libakgl/docs/06-the-registry.md

# 06. The registry

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 of it is resolved at load time through eight registries,
and that is what lets the whole asset graph be described in JSON files that reference each
other by name.

**The registries are SDL property sets, not akgl types.** They are `SDL_PropertiesID`
values with external linkage, so you can enumerate one with `SDL_EnumerateProperties`,
which is exactly what `akgl_registry_iterate_actor` and
`akgl_character_state_sprites_iterate` do.

## The eight registries

| Registry | Key | Value | Written by | Cleared by |
|---|---|---|---|---|
| `AKGL_REGISTRY_ACTOR` | actor name | `akgl_Actor *` | `akgl_actor_initialize` | `akgl_heap_release_actor` at refcount 0 |
| `AKGL_REGISTRY_SPRITE` | sprite name | `akgl_Sprite *` | `akgl_sprite_initialize` | `akgl_heap_release_sprite` at refcount 0 |
| `AKGL_REGISTRY_SPRITESHEET` | **resolved image path** | `akgl_SpriteSheet *` | `akgl_spritesheet_initialize` | `akgl_heap_release_spritesheet` at refcount 0 |
| `AKGL_REGISTRY_CHARACTER` | character name | `akgl_Character *` | `akgl_character_initialize` | `akgl_heap_release_character` at refcount 0 |
| `AKGL_REGISTRY_ACTOR_STATE_STRINGS` | state name | its bit value, as a number | `akgl_registry_init_actor_state_strings` | never |
| `AKGL_REGISTRY_FONT` | font name (yours) | `TTF_Font *` | `akgl_text_loadfont` | `akgl_text_unloadfont` |
| `AKGL_REGISTRY_MUSIC` | music name | audio handle | **nothing** — created but never populated | — |
| `AKGL_REGISTRY_PROPERTIES` | configuration key | string value | `akgl_set_property`, `akgl_registry_load_properties` | never |

Three of those rows are worth expanding.

**The spritesheet registry is keyed by path, not by name.** That is the sharing mechanism:
two sprites cutting frames out of the same image find the same `akgl_SpriteSheet` and the
same `SDL_Texture`, and the texture is loaded once.

**The actor-state-string registry exists so JSON can name a bit.**
`akgl_registry_init_actor_state_strings` walks `AKGL_ACTOR_STATE_STRING_NAMES` and maps
entry `i` to `1 << i`, which is what lets a character definition write
`"AKGL_ACTOR_STATE_FACE_LEFT"` instead of `2`. Two entries in that name table disagree with
`actor.h`: bits 11 and 12 are `UNDEFINED_11` and `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`"). The individual name registrations are not checked, either.

**The music registry is empty.** `akgl_registry_init_music` creates it and nothing in the
library ever writes to it. It is there for you.

## What actually runs at startup

`registry.h` documents `akgl_registry_init` as creating "the seven asset registries", with
a `@warning` that it does not create `AKGL_REGISTRY_PROPERTIES`. **Both halves of that are
now wrong**, and the correction matters because the warning is what a reader would design
around.

Read against `src/registry.c` and `src/game.c`, this is what is true:

- `akgl_registry_init` creates **eight**, including `AKGL_REGISTRY_PROPERTIES`. The
  properties call was added in 0.5.0 (`TODO.md`, "Formatting and hygiene"). Its order is spritesheet, sprite, character, actor, actor-state-strings, font,
  music, properties.
- **`akgl_game_init` never calls `akgl_registry_init`.** It calls the eight individual
  initializers itself, in a different order: actor, sprite, spritesheet, character, font,
  music, properties, actor-state-strings.

So there are two supported startup paths and they do not share code. If you call
`akgl_game_init`, you have all eight and need do nothing. If you are building your own
startup — an embedder binding an existing renderer, say — call `akgl_registry_init` and you
also have all eight. What you must not do is call some subset by hand and assume the rest
followed.

`akgl_registry_init_actor` is the one initializer that behaves differently in a way you
would notice: since 0.5.0 every initializer destroys the previous property set before
creating the replacement, so none of them leaks on a second call, but the *actor* one is
the one meant to be called again — between levels, paired with `akgl_heap_init_actor`. Note
that it destroys the **registry**, not the actors; releasing those is
`akgl_heap_release_actor`'s job.

## The id-0 trap

Every `SDL_PropertiesID` in `src/registry.c` starts at 0, and SDL treats 0 as "no such
property set". **Reads return the default and writes are refused.** An uninitialized
registry therefore does not fail the way you would want it to.

How loud that failure is depends entirely on whether libakgl checks SDL's return value, and
it does not check everywhere:

| Call | Behaviour against an id of 0 |
|---|---|
| `akgl_actor_initialize`, `akgl_sprite_initialize`, `akgl_spritesheet_initialize`, `akgl_character_initialize` | **Loud.** The `SDL_SetPointerProperty` result is checked; you get `AKERR_KEY`, "Unable to add … to registry" |
| `akgl_actor_set_character` | **Loud.** `SDL_GetPointerProperty` returns `NULL` and the result is checked; you get `AKERR_NULLPOINTER` |
| `akgl_set_property` | **Silent.** The `SDL_SetStringProperty` result is not checked. The value is discarded and the call returns success |
| `akgl_registry_load_properties` | **Silent, and worse.** Same unchecked write, and it logs `Set property x = y` for every entry it dropped, then logs `Properties loaded` |
| `akgl_get_property` | **Silent.** You get the default you passed, every time |
| `akgl_registry_init_actor_state_strings` | **Silent.** The `SDL_SetNumberProperty` results are not checked |

The consequence is the one `registry.h` warns about, and it is real even though the
attribution has moved: **a startup path that leaves `AKGL_REGISTRY_PROPERTIES` at 0 gives
you a no-op `akgl_set_property` and an `akgl_get_property` that always hands back your
default** — which in turn means `akgl_render_2d_init` builds a window from its fallback
size and `akgl_physics_init_arcade` runs with no gravity, both reporting success.

If you are debugging configuration that appears not to apply, check
`AKGL_REGISTRY_PROPERTIES != 0` before you check anything else.

## Truncated keys

Every name is copied into a fixed-width field with `aksl_strncpy` bounded to
`sizeof(field) - 1`, which is the "**truncated, not rejected**" contract those headers
document. The fields:

| Object | Field | Bytes |
|---|---|---|
| `akgl_Actor::name` | `AKGL_ACTOR_MAX_NAME_LENGTH` | 128 |
| `akgl_Sprite::name` | `AKGL_SPRITE_MAX_NAME_LENGTH` | 128 |
| `akgl_Character::name` | `AKGL_CHARACTER_MAX_NAME_LENGTH` | 128 |
| `akgl_SpriteSheet::name` | `AKGL_SPRITE_SHEET_MAX_FILENAME_LENGTH` | 512 |

**Two distinct names that agree on their first 127 bytes truncate to the same key**, and
the second `SDL_SetPointerProperty` silently replaces the first. The objects are different;
the registry cannot tell. That is issue #54, and it is not fixed yet because the fix is a contract change — refusing an
over-long name with `AKERR_OUTOFBOUNDS` — and every one of those headers currently promises
the opposite.

There is a second half that the issue understates. It says the truncated name *is*
the registry key. That is true for sprites and spritesheets, which register under their own
copied field. It is **not** true for actors and characters:

- `akgl_actor_initialize` and `akgl_character_initialize` register under the **caller's**
  string, untruncated.
- `akgl_heap_release_actor` and `akgl_heap_release_character` clear under the object's
  **truncated** field.

For any name of 127 bytes or fewer those are the same string and nothing happens. Over that,
the entry is written under one key and cleared under another, so **releasing the object
leaves a live registry entry pointing at a zeroed pool slot** — and the next lookup of that
name hands out a pointer to freed storage. Keep asset names short; 127 bytes is generous for
something a human types into a JSON file.

## Configuration properties

`AKGL_REGISTRY_PROPERTIES` is a string-to-string store. **Everything is a string, including
numbers** — `game.screenwidth` is `"800"`, not `800` — and whoever reads a property parses
it.

These are every property the library itself reads, with the default it falls back to and
where it is read:

| Property | Default | Read by | Meaning |
|---|---|---|---|
| `game.screenwidth` | `"0"` | `akgl_render_2d_init` | Window and camera width, in pixels |
| `game.screenheight` | `"0"` | `akgl_render_2d_init` | Window and camera height, in pixels |
| `physics.gravity.x` | `"0.0"` | `akgl_physics_init_arcade` | Constant acceleration on x, px/s² |
| `physics.gravity.y` | `"0.0"` | `akgl_physics_init_arcade` | Constant acceleration on y, px/s². Positive is down |
| `physics.gravity.z` | `"0.0"` | `akgl_physics_init_arcade` | Constant acceleration on z, px/s² |
| `physics.drag.x` | `"0.0"` | `akgl_physics_init_arcade` | Fraction of environmental velocity shed per second on x |
| `physics.drag.y` | `"0.0"` | `akgl_physics_init_arcade` | Same for y. **This is the only brake on falling** — there is no terminal velocity |
| `physics.drag.z` | `"0.0"` | `akgl_physics_init_arcade` | Same for z |
| `physics.max_timestep` | `"0.05"` | `akgl_physics_init_arcade` | Upper bound on a single simulation `dt`, in seconds |

That is the whole list. Two things follow from it:

**The screen size defaults to 0×0.** `akgl_render_2d_init` passes whatever it parsed
straight to `SDL_CreateWindowAndRenderer`, so a program that never sets those two asks SDL
for a zero-sized window. Set them before calling it.

**`physics.engine` is not a property.** `physics.h` says in two places that `akgl_game_init`
passes a `physics.engine` property to `akgl_physics_factory`. It does not — `akgl_game_init`
never calls the factory at all, and the string `physics.engine` does not appear anywhere in
`src/`. Choosing a backend is an explicit call you make yourself, with a name of `"null"` or
`"arcade"`; see [Chapter 14](14-physics.md). The header comment is a known-false claim left
alone deliberately, since correcting it is a source change rather than a documentation one.

### Setting properties

Two ways in, and both must happen **after** `akgl_game_init` (which creates the registry)
and **before** `akgl_render_2d_init` or `akgl_physics_init_arcade` (which read it).

`akgl_set_property(name, value)` sets one. SDL copies the value, so your buffer can go away
afterwards.

`akgl_registry_load_properties(fname)` loads a JSON document. It expects a top-level
`properties` object whose members are **all strings**:

```json kind=properties
{
    "properties": {
        "game.screenwidth": "800",
        "game.screenheight": "600",
        "physics.gravity.y": "400.0",
        "physics.drag.y": "0.9",
        "physics.max_timestep": "0.05"
    }
}
```

A member that is not a string is `AKERR_TYPE`; a document with no `properties` member is
`AKERR_KEY`; a file that will not open or will not parse is `AKERR_NULLPOINTER` with
jansson's line number and text in the message. Note that a failure part-way through leaks
one string-pool slot, because the per-property `CLEANUP` block is empty — a malformed
configuration file is worth failing on rather than retrying in a loop.

### Reading properties

`akgl_get_property(name, dest, def)` reads one into a pooled string. **Absence is not an
error**: an unset property yields `def`, which is how every caller inside the library gets a
working default without checking first.

Three details, all of which have caused a defect here before:

- **`*dest` decides who allocates.** `NULL` claims a slot from the string pool for you;
  non-`NULL` is written in place. Either way **you** release it with
  `akgl_heap_release_string`. Initialize your local to `NULL` on the first call.
- **`def` is effectively required.** A `NULL` default on an unset property is
  `AKERR_NULLPOINTER`, not an empty result.
- **Only the value and its terminator are copied.** The rest of the destination keeps
  whatever the previous holder left, so read the result as a C string and never as
  `AKGL_MAX_STRING_LENGTH` bytes. A value of `AKGL_MAX_STRING_LENGTH` bytes or more is
  `AKERR_OUTOFBOUNDS`; it will not fit an `akgl_String` with its terminator.

The full worked example — claim, read, parse, release in `CLEANUP` — is in
[Chapter 5](05-the-heap.md), because the ownership rule is the string pool's rather than the
registry's.

## Where to go next

- [Chapter 5](05-the-heap.md) — the pools the registries point into, and who releases what.
- [Chapter 7](07-the-game-and-the-frame.md) — where in startup the registries are created,
  and where configuration has to be in place by.
- [Chapter 14](14-physics.md) — choosing a backend, and what the `physics.*` properties do.
- [Chapter 23](23-appendix-limits.md) — the configuration table again, alongside every
  `AKGL_MAX_*`.