andrew/libakgl
1
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

Add the manual: nineteen chapters and a corrected README

Browse Source 
docs/ is a narrative manual, not a second reference. Every header already
carries a substantial @file/@brief block and Doxyfile sets WARN_IF_UNDOCUMENTED
with WARN_AS_ERROR, so an undocumented symbol already fails CI. The gap was
navigation and worked examples. Chapters teach a task and link to the Doxygen
output; where a declaration or a constant table has to be in front of the
reader it arrives as a `c excerpt=` block, so the text *is* the header and
cannot diverge from it. That also preserves the hand-aligned bit-flag tables
scripts/reindent.el goes out of its way not to destroy.

The manual does not re-document its dependencies. libakerror owns the
ATTEMPT/CLEANUP/PROCESS/HANDLE/FINISH protocol, SDL3 owns renderers and events,
Tiled owns the map format, jansson owns json_t. A chapter that restated any of
them would be wrong the day upstream changed and nothing here would notice --
the same drift this work exists to fix, arriving from a different direction. So
each chapter says what libakgl adds or constrains and links out for the rest.

Chapter 4 is the exception and the reason for it: libakerror documents the
mechanism, but only libakgl can say which statuses its own functions raise and
what they mean here, and that was written down nowhere. It carries three tables
-- libakgl's five status codes, the libakerror statuses libakgl actually raises
with their meaning in this library, and the exit-status trap where
`exit(AKGL_ERR_SDL)` is a wait status of 0 because the band starts at 256.

Every chapter was written against src/ rather than against the header comments,
which is how 27 false claims in those comments came to light. Where a chapter
documents a known defect rather than a design decision it says so and points at
TODO.md.

README.md keeps the development process and hands the reader to docs/. Its
task-oriented FAQ is deleted rather than moved, because one source of truth per
topic is the whole point and that FAQ's examples did not compile.

Census: 39 compiled snippets, 89 verbatim header excerpts, 4 JSON documents run
through the real loaders, one linked-and-executed program with its output
compared byte for byte, one generated figure. 11 norun blocks, each justified.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Kesterson
2026-08-01 20:58:37 -04:00
parent 8ac291d2dd
commit b938460127
22 changed files with 6306 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
README.md
View File

@@ -1,274 +1,71 @@
## How do I initialize a game
# libakgl
Initialize the global game object with info about your game
A C library for building 2D games on SDL3. Not an engine: no editor, no scripting layer, no
inheritance, and no runtime `malloc`. Behaviour attaches to a struct as function pointers,
objects come from fixed pools, and every call reports failure through an error context the
caller cannot silently ignore.
```c
strncpy((char *)&game.name, "sdl3-gametest", 256);
strncpy((char *)&game.version, "0.0.1", 32);
strncpy((char *)&game.uri, "net.aklabs.games.sdl3-gametest", 256);
## The manual
**[`docs/`](docs/README.md) is the manual** — twenty-one chapters covering every subsystem,
plus two complete tutorial games. Start at
[Chapter 3, Getting started](docs/03-getting-started.md) if you want a window on screen, or
[Chapter 2, Design philosophy](docs/02-design-philosophy.md) if you want to know why the
library is shaped the way it is.
The two tutorials build real, running programs that live under [`examples/`](examples):
| | |
|---|---|
| [A 2D sidescroller](docs/19-tutorial-sidescroller.md) | Gravity, a jump, collision you write yourself, coins and hazards |
| [A top-down JRPG](docs/20-tutorial-jrpg.md) | A town map, NPCs spawned from map objects, four-way animation, a text box, a follower |
For per-function reference, build the Doxygen output with `doxygen Doxyfile`; it is a CI
gate, so an undocumented symbol fails the build.
This README covers the development process only — hooks, mutation testing, benchmarks and
memory checking. Everything about *using* the library is in `docs/`.
> **The task-oriented FAQ that used to live here has moved into `docs/`, corrected.** It was
> not merely incomplete: its examples did not compile. Two unbalanced `PASS()` calls, a
> `sprite->frameids = [0, 1, 2, 3];` that is not C in any dialect, a stray `9` inside a
> bitmask expression, an `int screenwidth = NULL`, and — in the first snippet a reader ever
> saw — the exact `strncpy` call `AGENTS.md` forbids. The prose had drifted with it: its
> claim that the engine "ONLY supports TilED TMJ tilemaps with tileset external references"
> is backwards, and the loader accepts only *embedded* tilesets. Writing the manual turned
> up twenty-seven such claims across the headers. Every example in `docs/` is now compiled,
> linked, run or matched against the source tree by `ctest`, so that class of drift fails a
> build instead of reaching a reader.
## Documentation examples
Every fenced example in `docs/` carries an info string saying what it is, and the
`docs_examples` test acts on it: `c` blocks are compiled, `c run=` blocks are linked against
the library and executed headless with their output compared byte for byte, `c excerpt=`
blocks must still appear verbatim in the file they quote, `json` blocks are loaded through
the real `akgl_*_load_json`, and `c screenshot=` blocks generate the figures in
`docs/images/`. A block with no info string is a hard error, because the failure mode the
harness exists to prevent is passing while checking nothing.
```sh
ctest --test-dir build -R docs_examples --output-on-failure
ctest --test-dir build -R docs_screenshots --output-on-failure
cmake --build build --target docs_screenshots # regenerate the figures
```
Call the game initialization routines and lock the game state for further initialization
While editing one chapter, run it directly rather than the whole suite:
```c
PASS(e, akgl_game_init());
PASS(e, akgl_game_state_lock());
```
If you have a registry properties file, load it. If you don't have a properties file, use `akgl_set_property("prop_name", "prop_value")` to populate the required game properties.
```c
PASS(e, akgl_registry_load_properties(YOUR_REGISTR_FILEPATH));
```
Initialize your physics engine and renderer of choice
```c
PASS(e, akgl_render_2d_init(akgl_renderer));
PASS(e, akgl_physics_init_arcade(akgl_physics));
```
Unlock the game state
```c
PASS(e, akgl_game_state_unlock());
```
## What is in a properties file (or, What properties must I set if I don't have one?)
```json
{
"properties": {
"game.screenwidth": "640",
"game.screenheight": "480",
"physics.gravity.y": "1024.0",
"physics.drag.y": "1.0"
}
}
```
Physics properties (gravity and drag along X, Y and Z) are optional and default to `0`.
## How do I update and render the game world in my main loop
In your game loop (or in your `SDL_AppIterate` method), lock the game state, call the game update function, and then unlock the game state
```c
PASS(e, akgl_game_state_lock());
PASS(e, akgl_renderer->frame_start(akgl_renderer));
SDL_RenderClear(akgl_renderer->sdl_renderer);
PASS(e, akgl_game_update(NULL));
PASS(e, akgl_renderer->frame_end(akgl_renderer));
PASS(e, akgl_game_state_unlock());
```
## How do I get an actor on screen
Load a sprite for a character. Sprites are JSON documents describing 2D sprites, frames, and looping. Sprites are named, and sprite names must be unique.
```c
PASS(e, akgl_sprite_load_json(SOME_FILENAME))
```
Load a character from a JSON file. Characters map sprites to actor states and define physics characteristics like movement speed. Each character is named, and character names must be unique.
```c
PASS(e, akgl_character_load_json(SOME_FILENAME))
```
You don't strictly have to load sprites and characters from json files, you can initialize them yourself, it's just tedious work. Here's an example of initializing a 32x32 sprite from a spritesheet that uses the first 4 frames in a looping animation.
```c
akgl_SpriteSheet *sheet;
akgl_Sprite *sprite;
akgl_Character *character;
PASS(e, akgl_heap_next_spritesheet(&sheet);
PASS(e, akgl_spritesheet_initialize(sheet, 32, 32, IMAGE_FILENAME));
PASS(e, akgl_heap_next_sprite(&sprite));
PASS(e, akgl_sprite_initialize(sprite, SPRITE_NAME, &sheet);
sprite->frames = 4;
sprite->frameids = [0, 1, 2, 3];
sprite->width = 32;
sprite->height = 32;
sprite->speed = 1000;
sprite->loop = true;
strncpy((char *)&sprite->name, "SPRITE NAME", AKGL_SPRITE_MAX_NAME_LENGTH);
PASS(e, akgl_heap_next_character(&character));
PASS(e, akgl_character_initialize(&character, "CHAR NAME"));
PASS(e, akgl_character_sprite_add(&character, &sprite, STATE_MASK));
// Set the character acceleration and scale if desired
character->ax = 64.0;
character->ay = 64.0;
character->sx = 2.0;
character->sy = 2.0;
```
Initialize an actor. Actors are named ("player", "Quest NPC", whatever) and names must be unique.
```c
akgl_Actor *myactor = NULL;
PASS(e, akgl_heap_next_actor(&myactor);
PASS(e, akgl_actor_initialize(&myactor, "ACTOR_NAME"));
```
Assign a character to the actor by looking up the `akgl_Character` from the AKGL registry and assign it.
```c
myactor->basechar = SDL_GetPointerProperty(
AKGL_REGISTRY_CHARACTER,
"CHARACTER_NAME",
NULL);
FAIL_ZERO_BREAK(e, myactor->basechar, AKERR_REGISTRY, "Character missing");
```
Give the actor a position and a state, and turn it visible.
```c
myactor->state = 9AKGL_ACTOR_STATE_ALIVE | AKGL_ACTOR_STATE_FACE_LEFT);
myactor->x = 320;
myactor->y = 240;
myactor->visible = true;
```
## What are in Sprite and Character files
Sprite files:
```json
{
"spritesheet": {
"filename": "RELATIVE_IMAGE_FILE_REFERENCE",
"frame_width": int,
"frame_height": int
},
"name": "UNIQUE_SPRITE_NAME",
"width": int,
"height": int,
"speed": int,
"loop": boolean,
"loopReverse": boolean,
"frames": [
int
]
}
```
* `frames` references the frame indexes in the spritesheet that should be used for this animation. Spritesheets are counted from the top left corner going to the right according to the spritesheet `frame_width` and `frame_height`.
* `loop` says whether or not we should loop the animation
* `loopReverse` says whether or not we should "bounce" the animation (when we reach the end of the frames, start counting back to the beginning, then count to the end, etc). Otherwise the frames are displayed from 0..n and then cycles back to 0.
* `speed` is the number of milliseconds each frame in the animation should appear on the screen
Character files:
```c
{
"name": "UNIQUE_CHARACTER_NAME",
"speedtime": 8,
"speed_x": 0,
"speed_y": 0,
"acceleration_x": 0,
"acceleration_y": 0,
"sprite_mappings": [
{
"state": [
"AKGL_ACTOR_STATE_ALIVE",
"AKGL_ACTOR_STATE_FACE_UP",
"AKGL_ACTOR_STATE_MOVING_UP"
],
"sprite": "menupointer"
}[, ...]
]
}
```
* `speedtime` appears to be legacy and unused.
* `speed_[xy]` and `acceleration_[xy]` are physics parameters that specify the top speed and acceleration rate (in pixels per nanosecond) of the character in physics simulations. The effect of acceleration depends on the physics simulation being used at the time (which may or may not account for gravity, drag, etc).
* `sprite_mappings` map a set of actor state flag bitmasks (assume everything in `state` is `OR`ed together) to a sprite name. The game engine uses this to automatically pick the correct sprite (by name) for a given set of state flags. You need one of these for every possible state the character may be used in.
## How do I load a tilemap from the filesystem and display it on screen with my actors
The engine ONLY supports TilED TMJ tilemaps with tileset external references. Load a tilemap into the global `akgl_Tilemap *gamemap` object.
```c
PASS(e, akgl_tilemap_load(PATHSTRING, akgl_gamemap));
```
Actors will be automatically populated from objects in the tilemap object layers. Actor state flags here must be expressed as an integer, you can't (yet) use the same array of strings that is used in character json files.
```json
"objects":[
{
"gid":147,
"height":16,
"id":1,
"name":"player",
"properties":[
{
"name":"character",
"type":"string",
"value":"little guy"
},
{
"name":"state",
"type":"int",
"value":24
}],
"rotation":0,
"type":"actor",
"visible":true,
"width":16,
"x":440.510088317656,
"y":140.347239175702
}[, ... ]
```
Check if the tilemap wants to use its own physics, and if you want to allow that, override the global physics simulation
```c
if ( akgl_gamemap->use_own_physics == true ) {
akgl_physics = &akgl_gamemap->physics;
}
```
Tilemap physics specification follows. A map can specify its own physics properties (drag, gravity) without specifying a custom model.
```json
"properties":[
{
"name":"physics.drag.y",
"type":"float",
"value":0
},
{
"name":"physics.gravity.y",
"type":"float",
"value":0
},
{
"name":"physics.model",
"type":"string",
"value":"arcade"
}],
```
The global `akgl_gamemap` object is automatically displayed if it is populated. Actors are drawn at the appropriate map layer depending on the actor's `layer` property (warning: this may be replaced with a `z` property soon.)
## How do I get the screen width and height
The most direct is to call `SDL_GetCurrentDisplayMode` to get the parameters from the returned `SDL_DisplayMode` structure (`->w` and `->h`).
The simplest way is to check the global `akgl_camera` object's `akgl_camera->w` and `akgl_camera->h` object. You may have more than one camera on a scene, and it's theoretically possible that the global camera object has been overriden and no longer represents the full screen.
The most reliable engine-centric way is to use `akgl_get_property` to get the property from the engine. Properties are read and stored as strings, so if you need to do these kinds of things a lot, cache the integer value somewhere.
```c
akgl_String *width = NULL;
int screenwidth = NULL;
PASS(e, akgl_get_property("game.screenwidth", &width, "0"));
PASS(e, aksl_atoi(width->data, &screenwidth));
PASS(e, akgl_heap_release_string(width));
```sh
./tests/docs_examples.sh --root . \
--cflags-file build/docs_cflags.txt \
--ldflags-file build/docs_ldflags.txt \
--checkjson build/akgl_docs_checkjson \
docs/14-physics.md
```
`docs/MAINTENANCE.md` is the reference for the info strings, the preludes and the fixtures.
There is deliberately no docs-path filter in CI: documentation goes stale because the *code*
moved, not because somebody edited a chapter.
## Git hooks