Andrew Kesterson
bace818998
A pure rename plus link rewrite and nothing else. Collision is a pluggable subsystem with two implementations, shapes, a response hook and a tile binding; that is a chapter, and burying it inside the physics chapter is the shape this manual otherwise avoids -- rendering and drawing are 8 and 9, spritesheets and characters and actors are 10, 11 and 12. Kept separate from writing the chapter because **nothing validates a cross-reference target.** The example harness reads fenced blocks; it does not follow links. A rename mixed into five hundred lines of new prose is not reviewable, and a broken link would land silently. As its own commit it is reviewable as a rename, and a grep for dangling `](NN-` targets is clean. Co-Authored-By: Claude Code <noreply@anthropic.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
65 lines
4.9 KiB
Markdown
65 lines
4.9 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 five 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 six 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. Input](16-input.md)** | Control maps, push-not-poll dispatch, the keystroke ring, gamepads |
|
|
| **[16. Text and fonts](17-text-and-fonts.md)** | Loading, drawing, measuring, and the teardown order that matters |
|
|
| **[17. Audio](18-audio.md)** | The three-voice synthesizer, and the separate background-music path |
|
|
| **[18. Utilities](19-utilities.md)** | Collision helpers, path resolution, the JSON accessors, static strings |
|
|
| **[19. Tutorial: a 2D sidescroller](20-tutorial-sidescroller.md)** | Gravity, a jump, collision you write yourself, coins and hazards |
|
|
| **[20. Tutorial: a top-down JRPG](21-tutorial-jrpg.md)** | A town map, NPCs spawned from map objects, four-way animation, a text box, a follower |
|
|
| **[21. Appendix](22-appendix-limits.md)** | Every limit, every status, every configuration property |
|
|
|
|
Both tutorials 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.
|
|
|
|
## 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/`](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.
|