Tachikoma
ff4af80693
TODO.md carried two records in one file: what had been done, with the measurements behind it, and what was left. The second half is what a tracker is for, and keeping it here has already cost something -- AGENTS.md records a round where eleven entries described code that had already changed, and this file admitted to three more. Every open item is now an issue on source.starfort.tech/andrew/libakgl, labelled by kind and blast radius and milestoned by what it can land in: 0.9.x for anything that breaks no ABI, 0.10.0 for new or changed public symbols, 1.0.0 for the design work. Four are epics: the performance plan (#60), coverage (#61), actor rotation (#62), and the false header comments (#63). Verified against the tree before filing rather than transcribed. Three entries were already fixed and were not filed: the akgl_path_relative context leak, the akgl_draw_background test extension, and the SDL enumeration audit -- keyboards, gamepads and mappings are all freed in CLEANUP today. Two were reworded because the code had moved: the fonts item is a missing teardown entry point rather than a missing API, since akgl_text_unloadallfonts exists, and draw_world's tilemap call is already bounded by numlayers, so only the per-layer actor rescan remains. TODO.md keeps the part a tracker has no place for: why a decision went the way it did, what the measurement was, and which arguments turned out to be wrong. TODO.txt is deleted. Four of its eight entries had shipped -- actor-to-actor collision, actor-to-world collision, automatic facing, image layers -- and the four that had not are #74 through #77, with the GPU renderer's research links kept because that is the part that took the time. Every reference that named an item number or a moved section is repointed, in the manual, the headers, the tests and the examples. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
220 lines
11 KiB
C
220 lines
11 KiB
C
/**
|
|
* @file registry.h
|
|
* @brief The name-to-object lookup tables, and the string configuration store.
|
|
*
|
|
* Nothing in this library is passed around by pointer where a name will do. An
|
|
* actor names the character it instantiates, a character names the sprites it
|
|
* draws, a sprite names the sheet it cuts frames from -- all resolved at load
|
|
* time through these eight registries. That is what lets the whole asset graph
|
|
* be described in JSON files that reference each other by name.
|
|
*
|
|
* They are SDL property sets, not akgl types, so a caller can enumerate one with
|
|
* `SDL_EnumerateProperties` -- which is exactly what akgl_registry_iterate_actor
|
|
* and akgl_character_state_sprites_iterate are for.
|
|
*
|
|
* Every id starts at 0, which SDL treats as "no such property set": reads return
|
|
* the default and writes are silently dropped. So an uninitialized registry does
|
|
* not fail loudly, it fails quietly, and akgl_registry_init has to run first.
|
|
*
|
|
* @warning akgl_registry_init does *not* initialize
|
|
* #AKGL_REGISTRY_PROPERTIES -- akgl_registry_init_properties is a
|
|
* separate call, made by akgl_game_init but by nothing else. A program
|
|
* that builds its own startup path and skips it gets a silently
|
|
* no-op akgl_set_property and an akgl_get_property that always hands
|
|
* back the caller's default, which in turn means akgl_render_2d_init
|
|
* and akgl_physics_init_arcade quietly ignore their configuration.
|
|
* TODO.md, "Formatting and hygiene".
|
|
*/
|
|
|
|
#ifndef _AKGL_REGISTRY_H_
|
|
#define _AKGL_REGISTRY_H_
|
|
|
|
#include <SDL3/SDL.h>
|
|
#include <akgl/error.h>
|
|
#include <akgl/staticstring.h>
|
|
|
|
/** @brief Actor name -> `akgl_Actor *`. Written by akgl_actor_initialize, cleared when an actor's last reference goes. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR;
|
|
/** @brief Sprite name -> `akgl_Sprite *`. The `name` field from a sprite JSON. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_SPRITE;
|
|
/** @brief Resolved image path -> `akgl_SpriteSheet *`. Keyed by path so two sprites sharing an image share the texture. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_SPRITESHEET;
|
|
/** @brief Character name -> `akgl_Character *`. What akgl_actor_set_character resolves against. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_CHARACTER;
|
|
/** @brief Actor-state name -> its bit value, as a number. Lets character JSON say "AKGL_ACTOR_STATE_FACE_LEFT" instead of 2. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_ACTOR_STATE_STRINGS;
|
|
/** @brief Font name -> `TTF_Font *`. Names are chosen by the caller of akgl_text_loadfont, not derived from the file. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_FONT;
|
|
/** @brief Music name -> audio handle. Created but not yet populated by anything in the library. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_MUSIC;
|
|
/** @brief Configuration key -> string value. Read through akgl_get_property; everything is a string, including numbers. */
|
|
extern SDL_PropertiesID AKGL_REGISTRY_PROPERTIES;
|
|
|
|
/**
|
|
* @brief Create the seven asset registries, in dependency order.
|
|
*
|
|
* Spritesheet, sprite, character, actor, actor-state-strings, font, music. Call
|
|
* it once at startup, before loading anything.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate any one of the property sets;
|
|
* the message names which registry failed. The registries created before
|
|
* the failure are left in place rather than torn down.
|
|
*
|
|
* @warning This does not create #AKGL_REGISTRY_PROPERTIES -- see the warning on
|
|
* this file.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init(void);
|
|
/**
|
|
* @brief Create the music registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set, so calling it
|
|
* twice leaks the first one along with everything registered in it.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_music(void);
|
|
/**
|
|
* @brief Create the font registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_font(void);
|
|
/**
|
|
* @brief Create the actor registry, destroying any previous one first.
|
|
*
|
|
* The one initializer here that cleans up after itself, which is what makes it
|
|
* safe to call between levels: it destroys the old property set before creating
|
|
* the replacement, so the actors from the previous map are unregistered in one
|
|
* step. Note that it destroys the *registry*, not the actors -- releasing those
|
|
* is akgl_heap_release_actor's job.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set. The old one
|
|
* has already been destroyed at that point, so the registry is left at 0.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor(void);
|
|
/**
|
|
* @brief Create the sprite registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_sprite(void);
|
|
/**
|
|
* @brief Create the spritesheet registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_spritesheet(void);
|
|
/**
|
|
* @brief Create the character registry.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set. See
|
|
* akgl_registry_init_music.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_character(void);
|
|
/**
|
|
* @brief Create the configuration-property registry.
|
|
*
|
|
* Deliberately separate from akgl_registry_init, because configuration has to be
|
|
* in place before the subsystems that read it start up. akgl_game_init creates
|
|
* it; filling it in -- with akgl_registry_load_properties or akgl_set_property --
|
|
* is the caller's job, and has to happen before akgl_render_2d_init or
|
|
* akgl_physics_init_arcade run.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set.
|
|
* @note Overwrites the existing id without destroying the old set, so every
|
|
* property set before a second call is lost.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_properties(void);
|
|
/**
|
|
* @brief Load a JSON configuration file into the property registry.
|
|
*
|
|
* Expects a document with a top-level `properties` object whose members are all
|
|
* strings; each becomes one entry. Numbers are configured as strings here and
|
|
* parsed by whoever reads them -- `akgl_game.screenwidth` is `"800"`, not `800`.
|
|
*
|
|
* @param fname Path to the JSON document. Required. Used verbatim.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p fname is `NULL`, or if the file cannot be
|
|
* opened or does not parse. The message carries jansson's line number
|
|
* and text.
|
|
* @throws AKERR_KEY If the document has no top-level `properties` member.
|
|
* @throws AKERR_TYPE If `properties` is not an object, or if one of its members
|
|
* is not a string.
|
|
* @throws AKGL_ERR_HEAP If the string pool is exhausted.
|
|
*
|
|
* @note Writes into #AKGL_REGISTRY_PROPERTIES, so akgl_registry_init_properties
|
|
* has to have run -- otherwise every entry is silently dropped and this
|
|
* still returns success.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_load_properties(char *fname);
|
|
/**
|
|
* @brief Create the actor-state-name registry and fill it from the name table.
|
|
*
|
|
* Walks `AKGL_ACTOR_STATE_STRING_NAMES` and maps entry `i` to the value `1 << i`,
|
|
* which is what lets a character JSON write `"AKGL_ACTOR_STATE_FACE_LEFT"` and
|
|
* have akgl_character_load_json turn it into a bit.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If SDL cannot allocate the property set. The
|
|
* individual name registrations are not checked.
|
|
*
|
|
* @note The name table it reads disagrees with actor.h in two places: bits 11
|
|
* and 12 are named `UNDEFINED_11`/`UNDEFINED_12` rather than `MOVING_IN`
|
|
* and `MOVING_OUT`, so those two states cannot be named from JSON at all.
|
|
* TODO.md, "AKGL_ACTOR_STATE_STRING_NAMES".
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_registry_init_actor_state_strings(void);
|
|
/**
|
|
* @brief Set one configuration property.
|
|
*
|
|
* @param name Property key. Required.
|
|
* @param value Property value. Required. SDL copies it, so the caller's buffer
|
|
* can go away afterwards.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p name or @p value is `NULL`.
|
|
*
|
|
* @note The write itself is unchecked. If #AKGL_REGISTRY_PROPERTIES is still 0 --
|
|
* akgl_registry_init_properties never having run -- this discards the
|
|
* value and returns success.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_set_property(char *name, char *value);
|
|
/**
|
|
* @brief Read one configuration property into a pooled string, with a fallback.
|
|
*
|
|
* Absence is not an error: an unset property yields @p def, which is how every
|
|
* caller in the library gets a working default without checking first.
|
|
*
|
|
* @param name Property key. Required.
|
|
* @param dest Receives the value. Required. If `*dest` is `NULL` a string is
|
|
* claimed from the pool for you, so initialize it to `NULL` on the
|
|
* first call; either way the caller releases it with
|
|
* akgl_heap_release_string. If `*dest` is non-`NULL` it is written
|
|
* in place.
|
|
* @param def Value to use when @p name is not set. Effectively required --
|
|
* a `NULL` here on an unset property is an AKERR_NULLPOINTER rather
|
|
* than an empty result.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p name or @p dest is `NULL`, or if the property
|
|
* is unset and @p def is `NULL`.
|
|
* @throws AKERR_OUTOFBOUNDS If the stored value is #AKGL_MAX_STRING_LENGTH bytes
|
|
* or longer, which will not fit an akgl_String with its terminator.
|
|
* @throws AKERR_VALUE If the value and the destination overlap in memory.
|
|
* @throws AKGL_ERR_HEAP If `*dest` was `NULL` and the string pool is exhausted.
|
|
*
|
|
* @note Only the value and its terminator are copied. The rest of @p dest keeps
|
|
* whatever the previous holder left there, so read the result as a C
|
|
* string rather than as #AKGL_MAX_STRING_LENGTH bytes.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_get_property(char *name, akgl_String **dest, char *def);
|
|
|
|
#endif //_AKGL_REGISTRY_H_
|