Andrew Kesterson
8f848d80be
docs/22-ui.md covers the clay-backed UI: what clay owns against what libakgl owns, bring-up and the arena refusal contract, the frame bracket and where it sits in a real frame, the consumed-event rules (with the one-frame-stale hit test stated plainly), the three widgets, menus across keyboard, gamepad and mouse, writing raw CLAY() with an application-owned press edge, images and styles, and how layout errors surface from frame_end with a captured trace. Every listing is a checked block: one linked-and-run example with pinned output, eight excerpts quoting examples/uidemo and examples/jrpg/textbox.c, and the chapter figure is a frame out of uidemo via docs_game_figures. The chapter owes and pays the comparison the tutorials earn: the dialog widget's default style reproduces the JRPG textbox palette, the two listings sit side by side, and the trade is stated -- 125 lines you own completely against one call that costs you the subsystem. Neither is deprecated; chapter 21 keeps teaching the hand-rolled panel on purpose. The appendix moves to 23 (links in chapters 4, 5, 6, 7, 13 and the TOC updated) and gains the ui.h status cross-reference, the AKGL_UI_* limits table, and the new draw primitives' rows. Its status-band figures were stale at COUNT 5 / LIMIT 261 while the band already held six codes; now correct at 7 / 263. Chapter 4 gains AKGL_ERR_UI (262) in the excerpt, the table and the name list. Co-Authored-By: Claude Code (Claude Fable 5, claude-fable-5) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KzBDV2fqgnUAcqCKqKvc71
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 `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.
|