Andrew Kesterson
b938460127
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>
4.9 KiB
The libakgl manual
libakgl is a C library for building 2D games on SDL3. It is not an engine: there is 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 you cannot silently ignore.
This manual teaches the library. It deliberately does not re-document its dependencies
— libakerror owns the error-handling protocol, SDL3 owns renderers and events, Tiled owns
the map format, jansson owns the JSON API. Each chapter says what libakgl adds or
constrains, shows what a caller actually writes, and links out for the rest. For
per-function reference, build the Doxygen output with doxygen Doxyfile.
| 1. Introduction | What libakgl is, what it refuses to be, the frame budget, and who owns which documentation |
| 2. Design philosophy | Bounded pools, pluggable backends, bit flags, name-based registries, one world at a time |
| 3. Getting started | Dependencies, add_subdirectory vs akgl.pc, and the smallest program that opens a window |
| 4. Errors and status codes | The status tables, what each code means here, and the traps that fail silently |
| 5. The heap | The five pools, akgl_heap_next_*, akgl_String, and why exhaustion usually means a missing release |
| 6. The registry | The eight registries, configuration properties, and the id-0 silent no-op |
| 7. The game and the frame | Startup order, akgl_game_update, the state lock, iterators, savegames |
| 8. Rendering | The backend vtable, the frame contract, cameras, and embedding a host's own SDL_Renderer |
| 9. Drawing | Points, lines, rectangles, circles, flood fill, and saving a region |
| 10. Spritesheets and sprites | One texture shared by path, the sprite JSON format, frame animation |
| 11. Characters | State-to-sprite mappings, movement constants, the character JSON format |
| 12. Actors | The state bitmask, the six behaviour hooks, parents and children, layers |
| 13. Tilemaps | Tiled TMJ, libakgl's three extensions, and the limits that bind a map |
| 14. Physics | Thrust, environment and velocity; the null and arcade backends; what is not implemented |
| 15. Input | Control maps, push-not-poll dispatch, the keystroke ring, gamepads |
| 16. Text and fonts | Loading, drawing, measuring, and the teardown order that matters |
| 17. Audio | The three-voice synthesizer, and the separate background-music path |
| 18. Utilities | Collision helpers, path resolution, the JSON accessors, static strings |
| 19. Tutorial: a 2D sidescroller | Gravity, a jump, collision you write yourself, coins and hazards |
| 20. Tutorial: a top-down JRPG | A town map, NPCs spawned from map objects, four-way animation, a text box, a follower |
| 21. Appendix | Every limit, every status, every configuration property |
Both tutorials are complete programs under examples/. They build with the
library and run headless in CI, and the chapters quote them rather than restating them — so
a tutorial cannot drift from a program that compiles.
Every example here is checked
The examples in these chapters are compiled, linked, run, and cross-checked against the
source tree by the test suite. A snippet that stops compiling, an excerpt that no longer
matches the header it quotes, or a JSON document the loader would reject turns
ctest -R docs_examples red.
This exists because the documentation it replaces had drifted badly: the previous FAQ's
examples did not compile — two unbalanced PASS() calls, a sprite->frameids = [0, 1, 2, 3];
that is not C in any dialect, and, in the first snippet a reader ever saw, the exact
strncpy call AGENTS.md forbids. The prose had drifted with it, and writing these
chapters turned up twenty-seven header claims that were false against src/.
Where a chapter documents behaviour that is a known defect rather than a design decision,
it says so and points at TODO.md. See MAINTENANCE.md if you are editing an example.
Assets
The tutorial art, tiles and music are CC0, vendored under
tutorials/assets/ with provenance recorded per file in
PROVENANCE.md and geometry documented in
README.md. CC0 specifically, not merely free: a reader who
copies a tutorial into their own game inherits no obligation.