Andrew Kesterson
a3cb6ca79a
akgl_collision_test takes two proxies and fills in a contact: a unit normal, a depth, and a point. Three paths, cheapest first. The proxies' bounds reject most pairs in four comparisons and no arithmetic, which is free because the bounds were computed when the proxy was synced. A box against a box is answered in closed form. That is not only cheaper than the general solver, it is *exact*, and the difference shows up where it matters most: an actor resting on a floor wants a normal of precisely (0, -1, 0), and an iterative solver converges to something like (0.0001, -0.99999, 0), which accumulates into a slow sideways creep. A tile game is almost entirely boxes, so this is the path that runs. Everything else goes to ccdMPRPenetration. MPR rather than GJK+EPA because MPR allocates nothing at all, converges in fewer iterations, and its one weakness -- a coarser contact *point* -- is on a field the blocking resolver never reads. EPA stays compiled and available behind the arena for a caller who one day wants an accurate manifold. The header says the point is approximate so nobody builds a damage falloff on it. The normal points out of the second shape and toward the first, so a caller moving `a` along it by `depth` separates the pair. libccd hands back the opposite convention; converting once here saves every resolver from remembering the sign, and getting it backwards would compile, would pass any "do these collide" test, and would drag actors into walls. There is a test that asserts the direction, and inverting the conversion turns it red. AKGL_COLLISION_TEST_PLANAR flattens the normal into the xy plane. The extrusion the setters apply already makes z the most expensive axis, so this is a net for a caller who set a depth by hand -- and the failure it catches is silent: the narrowphase reports a contact, the resolver pushes the actor into the screen, and the actor does not move on screen while remaining inside the floor. It also rescues the degenerate case, two shapes at exactly the same centre, where there is no planar direction at all and a zero-length normal would be a wall that stops nothing. Level authors stack things constantly. Three things the tests found rather than assumed: - The guard has two copies, one per path, and the box one is where it earns its place. Removing both is caught; removing only the iterative one is not, because the iterative solver is seeded from the line between the two centres and so converges to a planar answer on its own for a planar offset. That is measured and written down in the test rather than papered over with a fixture contrived to force it. - A concentric pair has no preferred sign on the degenerate axis, so the test asserts the magnitude of the normal rather than its direction. The first version asserted -1 and failed against an equally correct +1. - The box fast path and the iterative solver are two implementations of one answer, so they are driven over the same arrangements and required to agree on the decision and the axis. A shortcut nothing cross-checks is a shortcut waiting to diverge. Co-Authored-By: Claude Code <noreply@anthropic.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
libakgl
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.
The manual
docs/ is the manual — twenty-one chapters covering every subsystem,
plus two complete tutorial games. Start at
Chapter 3, Getting started if you want a window on screen, or
Chapter 2, Design philosophy 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/:
| A 2D sidescroller | Gravity, a jump, collision you write yourself, coins and hazards |
| A top-down JRPG | 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 unbalancedPASS()calls, asprite->frameids = [0, 1, 2, 3];that is not C in any dialect, a stray9inside a bitmask expression, anint screenwidth = NULL, and — in the first snippet a reader ever saw — the exactstrncpycallAGENTS.mdforbids. 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 indocs/is now compiled, linked, run or matched against the source tree byctest, 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.
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
While editing one chapter, run it directly rather than the whole suite:
./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
The repository ships a pre-commit hook that keeps committed C sources in the
project's canonical format (Emacs cc-mode "stroustrup"; see AGENTS.md for the
full style guide). The hook lives in scripts/hooks/ and is version controlled,
but Git configuration is not cloned, so every clone has to be pointed at it
once:
git config core.hooksPath scripts/hooks
Confirm it took effect:
git rev-parse --git-path hooks # should print: scripts/hooks
That is the whole installation. The hook is already committed with its
executable bit set, so nothing needs chmod.
What the hook does
On each commit it looks at the staged content of any added, copied, modified,
or renamed .c/.h file under src/, include/, tests/, or util/, and
reindents it if it does not already match the canonical style. Checking the
staged content rather than the working tree means what lands in the commit is
what was actually verified.
When a file needs reindenting, the hook fixes it in the working tree and
re-stages it — but only when the index and working tree agree for that file. If
they differ, you have staged part of a file with git add -p, and re-staging
would sweep your unstaged work into the commit. Rather than do that silently the
hook stops and prints the commands to run yourself:
scripts/reindent.sh path/to/file.c
git add path/to/file.c
include/akgl/SDL_GameControllerDB.h is generated and always skipped.
Requirements
The hook drives Emacs in batch mode, because cc-mode's indentation engine is
the definition of the style and clang-format cannot reproduce it exactly. If
emacs is not on PATH the hook prints a warning and allows the commit — a
hook that refuses to run without an optional tool only teaches people to reach
for --no-verify. Install Emacs to get the check; without it, formatting is on
you.
Bypassing and uninstalling
Skip the hook for a single commit:
git commit --no-verify
Remove it entirely:
git config --unset core.hooksPath
If you already have local hooks
core.hooksPath replaces the hooks directory outright — once it is set, Git
stops reading .git/hooks/ altogether, so any hooks you keep there will silently
stop firing. If that matters, leave core.hooksPath unset and symlink just this
one hook instead:
ln -s ../../scripts/hooks/pre-commit .git/hooks/pre-commit
Formatting without the hook
The hook is a convenience, not the source of truth. The same check is available directly, and is what you would run in CI:
scripts/reindent.sh --check # list non-conforming files; exit 1 if any
scripts/reindent.sh # reindent every tracked C source in place
scripts/reindent.sh src/game.c # reindent specific files
--check exits 0 when everything conforms, 1 when a file needs reindenting,
and 2 if Emacs is missing or the script cannot run — so a CI job that treats
any non-zero status as failure will not mistake a broken toolchain for a clean
tree.
Mutation testing
The mutation harness makes one deliberate source-code change at a time in a scratch copy, then rebuilds and runs the passing CTest suite to measure whether tests detect the change. The known-failing character test is excluded by default.
cmake --build build --target mutation
scripts/mutation_test.py --target src/tilemap.c --list
scripts/mutation_test.py --target src/tilemap.c --max-mutants 10
scripts/mutation_test.py --threshold 40 --junit mutation-junit.xml
The default run covers all libakgl-owned files under src/. Use repeated --target options to narrow the scope. A surviving mutant identifies behavior that the current tests do not verify; the script prints its file, line, operator, and exact edit. The real working tree is never mutated.
Performance testing
tests/perf.c and tests/perf_render.c are benchmarks rather than unit tests: they drive the hot paths — pool acquire and release, the registry, the physics sweep, the per-actor update and render, the tilemap draw, text, and asset loading — and print what each one costs per operation.
ctest --test-dir build -L perf --output-on-failure # benchmarks only, about 30 seconds
ctest --test-dir build -LE perf # everything except the benchmarks
AKGL_BENCH_SCALE=0.1 ctest --test-dir build -L perf # a tenth of the iterations
Each measurement is the best of five runs and is held to a budget set at roughly ten times the recorded baseline, so a suite that turns red means an algorithmic regression rather than a busy machine. Budgets are enforced only in an optimized build at full scale; below AKGL_BENCH_SCALE=1.0, and in a coverage build, they are reported without failing.
PERFORMANCE.md carries the recorded baseline, the frame budget it adds up to, and what the numbers say — including the raw-SDL control rows that separate what libakgl costs from what the rasterizer costs. The six defects the stress tests turned up, and the targets the numbers are measured against, are in TODO.md under Performance.
Memory checking
memcheck runs the suites that already exist under valgrind rather than adding suites of its own. The perf binaries carry most of it: they are the only programs in the tree that load assets, draw a scene, and run a frame loop in one process, and tests/benchutil.h cuts their iteration counts by three orders of magnitude when it detects valgrind — a benchmark walks one path a hundred thousand times, a leak check wants every path walked once.
cmake --build build --target memcheck # everything, about 30 seconds
scripts/memcheck.sh -R tilemap # one suite; ctest selection flags pass through
scripts/memcheck.sh -LE perf # skip the benchmarks
The run forces SDL_VIDEO_DRIVER=dummy, SDL_RENDER_DRIVER=software and SDL_AUDIO_DRIVER=dummy so the vendor GPU stack is never loaded — that removes thousands of unfixable findings inside the driver without suppressing anything. Definite leaks, invalid accesses and uninitialised reads are counted and set the exit status; "still reachable" is not, because that is what SDL and FreeType keep for the process lifetime. Suppressions for genuine third-party findings are in scripts/valgrind.supp.
What it found the first time it ran is in TODO.md under Memory checking.