Andrew Kesterson
f06c53110d
`spr_collisions()` computed axis-aligned overlaps itself, because at libakgl 0.7.0 there was nothing to delegate to: `akgl_collide_rectangles()` has a documented corner-containment defect and the physics backend's `collide` slot raised "Not implemented". 0.8.0 brought a real narrowphase, and this moves onto it. The mask is bit-identical and every test from the previous commit passes **unmodified**, which was the gate this stage had to clear -- including the two that were written to be hard to satisfy. Edge-to-edge is still not a collision, so a tile-aligned program is unaffected. The cross-shaped overlap is still reported, which is the one that could have regressed: it is the case `akgl_collide_rectangles()` gets wrong and the reason the hand-written loop existed, and `akgl_collision_test()`'s box path gets it right. What it buys is the contact -- a normal, a penetration depth and a point -- which four comparisons cannot produce. Nothing consumes it yet; that is the next commit. It is here now because the mask and the contact come out of the same test, and computing them in two places would be two things to keep in step. **The first attempt was ten times slower and the benchmark caught it.** Syncing all eight proxies and running the narrowphase on all twenty-eight pairs measured 984 ns a scan against 96 ns for the loop it replaced -- 21% of a frame at 256 scans a frame -- to produce a mask that was bit-identical and a contact that was thrown away. Two changes fixed it, and both are what a broad phase *is* rather than workarounds for a slow library: - **Reject on the bounding boxes first.** The four comparisons that were always here now decide which pairs are worth an exact answer. The narrowphase still decides the bit -- the box test only says "maybe", which will matter the moment a shape is not the whole frame. - **Do not sync a proxy that has not moved.** The scan runs at the top of every interpreter step and a sprite moves at most once in that time, so almost every sync would rewrite a proxy with what it already holds. Compared against the last synced rectangle rather than flagged by the verbs, because a host game can move a BASIC sprite through the actor registry and a flag would miss that. Measured after: 54.9 ns at eight sprites spread out, which is *faster* than the 96.3 ns it replaced -- boxes are now built eight times a scan instead of fifty-six. The number that matters is the new benchmark row for the arrangement `examples/breakout/sprites/breakout.bas` actually has, which is 211.8 ns, or 4.5% of a frame. That game reaches it because two of its eight sprites are the screen -- a captured HUD strip and a captured play field -- so the field's box covers everything and those pairs can never be rejected. Roughly double the old cost, for contacts. Recorded in MAINTENANCE.md with the two synthetic extremes either side of it as a bracket. The eight proxies are claimed once at init and held, so exhaustion of the pool shared with an embedding host is an initialization failure that names the pool rather than a collision scan refusing halfway through somebody's game. The shape is built before the proxy is spawned from it and the acquire sits adjacent to the initialize, which are two traps libakgl hit itself and documents. `tests/akgl_backends.c` now tears the sprite backend down between cases. It never did, and got away with it while init claimed nothing; eight proxies apiece across twenty cases is a hundred and sixty against a pool of a hundred and twenty-eight. A host releases what it took, and so does the harness. Both games run forty seconds headless with no error line. 111 with akgl, 110 without. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
akbasic
A BASIC interpreter written in C, styled after Commodore BASIC 7.0
and the Dartmouth BASIC of 1964. It runs a
.bas file, it gives you a prompt, and — the point of the exercise — it links into a C program
as a scripting engine.
It is a rewrite of basicinterpreter, a Go
implementation that started from the Java Lox instructions in
craftinginterpreters.com and then struck off on its own. That
project is deprecated. It is vendored here as the behavioural spec to read when a question about
semantics comes up, and its acceptance corpus is checked in at
tests/reference/ and runs on every build — so nothing about
building or testing this project needs it.
Quickstart
git submodule update --init --recursive
cmake -S . -B build
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/basic # the REPL
./build/basic tests/reference/language/functions.bas # run a program
10 FOR I# = 1 TO 3
20 PRINT "HELLO " + I#
30 NEXT I#
HELLO 1
HELLO 2
HELLO 3
Two things in that program are not Commodore BASIC and will catch you out immediately: variables
carry a type suffix (I# is an integer), and + concatenates a string with a number.
Chapter 3 explains both; Chapter 13 is the
whole list of what differs from a C128.
Graphics, sound and sprites need the SDL build, which is off by default because the interpreter and its entire test suite build on a machine with no SDL installed at all:
cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
cmake --build build-akgl --parallel
That basic is a different program: it opens a window, draws BASIC output into it in the
Commodore font, and still puts every byte on stdout.
Why rewrite it in C?
Three reasons, in the order they matter.
The interpreter is meant to end up inside libakgl as a scripting engine for game authors, and libakgl is C. Embedding a Go runtime in a C game is not a thing anybody should do to themselves.
The Go version was already written against static pools and explicit state structs — a fixed source table, a fixed variable pool, a 32-leaf ceiling per line — so it ports across almost directly. It reads like C that happens to be spelled in Go.
And the port is a good excuse to find out what the original actually does, as opposed to what it looks like it does. It found five defects nobody knew about.
Design philosophy
A game engine cannot tolerate a scripting language that surprises it. Five rules follow from that, and between them they explain most of what looks unusual in this interpreter:
- Nothing in the library terminates the process. No
exit(), noabort(), nopanic. Errors come back asakerr_ErrorContext *for the host to handle.FINISH_NORETURNappears only in amain(). - Nothing calls
malloc. Every object comes from a fixed pool insideakbasic_Runtime. Exhausting one is a diagnosable error, not a crash and not a slow leak. - No file-scope mutable state. Interpreter state lives in an
akbasic_Runtimeyou own. Two of them in one process do not interfere. - The host owns the loop.
akbasic_runtime_run(rt, n)executes at mostnsteps and returns. A script containing10 GOTO 10costs younsteps per frame and nothing else. - Hardware is a record of function pointers. Graphics, audio, input and sprites attach as
backends, and any of them may be
NULL— that is how a host withholds a capability, and how a host that renders some other way never links libakgl at all.
Nothing is silently ignored, either. A verb that needs a device it was not given, or a capability nothing underneath can supply, refuses by name and says why.
Two ways to use it
As a program. basic is a REPL and a script runner, and the standalone driver owns the
things a library has no business owning: argv, QUIT, and the window in the SDL build.
The guide is written for this reader.
As a library. A host links akbasic::akbasic, hands the interpreter a script, and steps it a
frame at a time:
add_subdirectory(deps/akbasic EXCLUDE_FROM_ALL)
target_link_libraries(YOUR_GAME PRIVATE akbasic::akbasic)
Host and script exchange variables through the same pool the script itself uses — no marshalling
layer and no copy. PRINT goes through an akbasic_TextSink the host supplies, so a game draws
BASIC output into its own text layer. examples/embed.c and
examples/hostvars.c are complete and runnable, and both are built and
run by every build, so they cannot rot. Chapter 10 walks through the API.
What state it is in
Everything the Go version does, and by now a good deal more. All 41 .bas files of the
reference's corpus produce the expected output, including error messages, each as a separate
CTest case so a failure names the file.
What is still missing, what is refused deliberately, and the eleven defects inherited from the Go
version are catalogued in TODO.md and summarised for a BASIC programmer in
Chapter 13.
Where everything else lives
docs/ |
The guide: eighteen chapters, the language then each hardware area then a reference section for every verb and function, Chapter 14 on the interpreter's own architecture, Chapter 15 listing every error code, and Chapters 17 and 18 building a whole game twice |
MAINTENANCE.md |
For contributors and maintainers: the documentation-example harness, the three test lists, mutation testing, error-code allocation, style |
TODO.md |
Outstanding defects, with file, line and consequence |
tests/reference/README.md |
Where the golden corpus came from, and the rule for changing it |
API documentation builds with doxygen Doxyfile, into build/docs/html.
Dependencies
Everything is a submodule; git submodule update --init --recursive gets all of it. There is
nothing to install first.
- libakerror 2.0.1 — TRY/CATCH-style error contexts. Every function that can fail returns one. 2.0.0 made it thread safe and broke the ABI; anything built against a 1.x header must be rebuilt rather than relinked.
- libakstdlib 0.2.0 — libc wrappers that
report through
libakerror. String-to-number conversion goes straight to it, which is whyVAL("garbage")is an error rather than a silent0. - libakgl 0.8.0 — optional, only for
-DAKBASIC_WITH_AKGL=ON. Pulls in SDL3. Its soname carriesMAJOR.MINORwhile the major is 0, so rebuild rather than relink. - basicinterpret — the Go original. Not linked, not built, and safe to omit.