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>
70 lines
5.5 KiB
Markdown
70 lines
5.5 KiB
Markdown
# 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](01-introduction.md)** | What libakgl is, what it refuses to be, the frame budget, and who owns which documentation |
|
|
| **[2. Design philosophy](02-design-philosophy.md)** | Bounded pools, pluggable backends, bit flags, name-based registries, one world at a time |
|
|
| **[3. Getting started](03-getting-started.md)** | Dependencies, `add_subdirectory` vs `akgl.pc`, and the smallest program that opens a window |
|
|
| **[4. Errors and status codes](04-errors.md)** | The status tables, what each code means *here*, and the traps that fail silently |
|
|
| **[5. The heap](05-the-heap.md)** | The eight pools, `akgl_heap_next_*`, `akgl_String`, and why exhaustion usually means a missing release |
|
|
| **[6. The registry](06-the-registry.md)** | The eight registries, configuration properties, and the id-0 silent no-op |
|
|
| **[7. The game and the frame](07-the-game-and-the-frame.md)** | Startup order, `akgl_game_update`, the state lock, iterators, savegames |
|
|
| **[8. Rendering](08-rendering.md)** | The backend vtable, the frame contract, cameras, and embedding a host's own `SDL_Renderer` |
|
|
| **[9. Drawing](09-drawing.md)** | Points, lines, rectangles, circles, flood fill, and saving a region |
|
|
| **[10. Spritesheets and sprites](10-spritesheets-and-sprites.md)** | One texture shared by path, the sprite JSON format, frame animation |
|
|
| **[11. Characters](11-characters.md)** | State-to-sprite mappings, movement constants, the character JSON format |
|
|
| **[12. Actors](12-actors.md)** | The state bitmask, the seven behaviour hooks, parents and children, layers |
|
|
| **[13. Tilemaps](13-tilemaps.md)** | Tiled TMJ, libakgl's three extensions, and the limits that bind a map |
|
|
| **[14. Physics](14-physics.md)** | Thrust, environment and velocity; the `null` and `arcade` backends; what is not implemented |
|
|
| **[15. Collision](15-collision.md)** | Shapes, masks, tiles as geometry, the response hook, and the two partitioners |
|
|
| **[16. Input](16-input.md)** | Control maps, push-not-poll dispatch, the keystroke ring, gamepads |
|
|
| **[17. Text and fonts](17-text-and-fonts.md)** | Loading, drawing, measuring, and the teardown order that matters |
|
|
| **[18. Audio](18-audio.md)** | The three-voice synthesizer, and the separate background-music path |
|
|
| **[19. Utilities](19-utilities.md)** | Rectangle overlap, path resolution, the JSON accessors, static strings |
|
|
| **[20. Tutorial: a 2D sidescroller](20-tutorial-sidescroller.md)** | Thirteen steps from an empty directory to a game with gravity, a jump, coins and hazards. **Start here** |
|
|
| **[21. Tutorial: a top-down JRPG](21-tutorial-jrpg.md)** | Thirteen more, for four-way movement, NPCs, a text box, a follower, and freezing the world |
|
|
| **[22. User interfaces](22-ui.md)** | Menus, HUDs and dialogs on the clay layout engine: the widgets, the frame bracket, and writing `CLAY()` yourself |
|
|
| **[23. Appendix](23-appendix-limits.md)** | Every limit, every status, every configuration property |
|
|
|
|
**If you are new, read chapter 20 first and read it in order.** It builds a working game from
|
|
an empty directory and teaches the library as it needs each piece; chapter 21 assumes it.
|
|
Both are complete programs under [`examples/`](../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. The picture at the top of each chapter is a frame
|
|
out of the game itself, regenerated by `cmake --build build --target docs_game_figures`.
|
|
|
|
## 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 its issue. See `MAINTENANCE.md` if you are editing an example.
|
|
|
|
## Assets
|
|
|
|
The tutorial art, tiles and music are CC0, vendored under
|
|
[`tutorials/assets/`](tutorials/assets) with provenance recorded per file in
|
|
[`PROVENANCE.md`](tutorials/assets/PROVENANCE.md) and geometry documented in
|
|
[`README.md`](tutorials/assets/README.md). CC0 specifically, not merely free: a reader who
|
|
copies a tutorial into their own game inherits no obligation.
|