Archmage.Atlas

The base class of the generated ConfigAtlas, which Archmage.AtlasLoader.load_atlas() fills.

Inherits: RefCounted

For the code generator. ConfigAtlas extends Archmage.Atlas and implements the abstract methods below. A new ConfigAtlas has one empty object for each config source (a field such as var hero_table := HeroTable.new()) and one Archmage.AtlasItem that holds the object and its mapping. The loader fills the objects in place, so the fields keep pointing at them; an item that is skipped keeps its empty object.

The loader calls the methods in this order: set_data_version(), atlas_items(), the load_json and apply_keys methods of each loaded item (see Archmage.AtlasItem.cfg), bind_refs(), then on_loaded(). Loading stops at the first failure.

Threads. The asynchronous loader may call the load_json and apply_keys methods of the items on worker threads, for several items at a time; the other methods run on the main thread.

Freeing. When the atlas is freed, it calls unbind_refs() to remove the references between its entries. Godot frees a RefCounted object only when nothing references it, so without this, entries that reference each other would keep each other alive and never be freed. An entry that other code still holds stays alive, but its references to other entries are removed.

Methods

atlas_items()

@abstract func atlas_items() -> Dictionary[String, Archmage.AtlasItem]

Returns the items, keyed by their keys in atlas.json, such as "hero". Build the dictionary once and return the same one on every call, because the loader records the load state, such as Archmage.AtlasItem.ready, in its items.

set_data_version()

@abstract func set_data_version(version: Archmage.VersionInfo) -> void

Stores version, the version object of atlas.json, or null when atlas.json has none. The generated code keeps it in data_version.

bind_refs()

@abstract func bind_refs() -> String

Resolves the references between config entries, after all items are loaded.

Returns an empty string on success. A non-zero ID with no entry in the referenced table is a load failure: return a message that locates the reference and includes the table and the ID, such as hero[3].weapon: ItemTable: config entry not found for ID 999. The loader then returns ERR_INVALID_DATA.

on_loaded()

@abstract func on_loaded() -> String

Called after bind_refs(). The generated code calls extension.on_loaded(self), where extension is the AtlasExtension that the user edits. Returns an empty string on success. On failure, returns a message; the loader then returns FAILED, and Archmage.AtlasLoader.get_error_message() returns the message.

unbind_refs()

@abstract func unbind_refs() -> void

Removes the references between config entries: a reference field becomes null, an array or dictionary of references becomes empty, and a reference in an Archmage.WeightedPool or Archmage.Tuple becomes null.

The atlas calls this method while it is being freed. At that time, a call to any other method of the atlas fails, so the generated code calls only _unbind_refs() of the objects that the atlas holds, such as hero_table._unbind_refs().