Archmage.AtlasOptions

The options of Archmage.AtlasLoader.load_atlas() and Archmage.AtlasLoader.load_atlas_async().

Inherits: RefCounted

Each with_* method returns this object, so calls can be chained:

var opts := Archmage.AtlasOptions.new() \
        .with_blacklist(["balance"]) \
        .with_override_root("user://override")

A method that gets an invalid argument records the error, and the load then fails with ERR_INVALID_PARAMETER and that message.

Methods

with_logger()

func with_logger(logger: Archmage.AtlasLogger) -> Archmage.AtlasOptions

Sets the logger, which receives the progress messages. The default prints them; Archmage.NullLogger discards them.

with_fs()

func with_fs(fs: Archmage.FS) -> Archmage.AtlasOptions

Sets the file system that atlas.json, the config files and the files in the override roots of with_override_root() are read from. The default is Archmage.FileAccessFS. The override sources added with with_override_fs() use their own file systems.

with_atlas_modifier()

func with_atlas_modifier(modifier: Callable) -> Archmage.AtlasOptions

Sets a function that receives the Archmage.AtlasJson after atlas.json is parsed and may change it before the items are loaded. Its signature is func(atlas_json: Archmage.AtlasJson) -> void.

with_whitelist()

func with_whitelist(keys: PackedStringArray) -> Archmage.AtlasOptions

Loads only the items whose keys are in keys. When the whitelist is not empty, the blacklist is ignored. A key that is not an item of the atlas makes the load fail.

with_blacklist()

func with_blacklist(keys: PackedStringArray) -> Archmage.AtlasOptions

Skips the items whose keys are in keys, unless a whitelist is set. A key that is not an item of the atlas makes the load fail.

with_variant()

func with_variant(key: String, variant: String) -> Archmage.AtlasOptions

Selects the variant to load for the variant-mapped item key. An item without a selected variant loads "/". A later call for the same key replaces the earlier one. An unknown key or an empty variant makes the load fail; so does a variant that atlas.json does not list for the key, unless the item is skipped.

with_override_root()

func with_override_root(dir: String) -> Archmage.AtlasOptions

Adds a directory of override files in the main file system. The override file of a config file has the same relative path under dir: <dir>/hero.json overrides hero.json. After the config files of an item are merged, its override files are merged into the result (see Archmage.AtlasLoader.merge_json()) in the order of the config files, and for each config file in the order in which the sources were added, so a later source overrides an earlier one. The load fails when the directory does not exist.

with_override_fs()

func with_override_fs(fs: Archmage.FS, root: String = "") -> Archmage.AtlasOptions

Adds a file system of override files, as with_override_root() does for a directory. The override files are looked up under root in fs, or at the root of fs when root is empty.

with_max_concurrency()

func with_max_concurrency(n: int) -> Archmage.AtlasOptions

Sets the maximum number of items that Archmage.AtlasLoader.load_atlas_async() loads at the same time. The default is 32. Archmage.AtlasLoader.load_atlas() loads one item at a time.

Inner Classes

OverrideConfig

Archmage.AtlasOptions.OverrideConfig

An override source: a directory in the main file system, or a file system with an optional root directory.

Inherits: RefCounted

Properties

fs

var fs: Archmage.FS

The file system of the override files; null for the main file system.

root

var root: String

The directory of the override files in fs; empty for the root of a separate file system.

Constructor

new()

Archmage.AtlasOptions.OverrideConfig.new(p_fs: Archmage.FS, p_root: String)