Deliver GALAGA tutorial and akbasic enemy scripting example #39

logikoma · 2026-08-04T11:28:49-04:00

logikoma commented

2026-08-04 11:28:49 -04:00

Closes #34.

Branch 34 contains the implementation already present on origin/galaga-tutorial: the libakgl C engine example, BASIC enemy behavior script, host-call/runtime fixes and tests, tutorial chapters 20 and 21, docs/10 embedding guidance, assets, and validation report.

Validation: core build succeeds; 97/113 tests pass. The 16 failures are the pre-existing #32 79-character source-line-limit cases.

Closes #34. Branch 34 contains the implementation already present on origin/galaga-tutorial: the libakgl C engine example, BASIC enemy behavior script, host-call/runtime fixes and tests, tutorial chapters 20 and 21, docs/10 embedding guidance, assets, and validation report. Validation: core build succeeds; 97/113 tests pass. The 16 failures are the pre-existing #32 79-character source-line-limit cases.

logikoma added 7 commits 2026-08-04 11:28:50 -04:00

Reset the scanner's leftover token type between lines dde1d91c6e

The REM early-exit leaves tokentype holding AKBASIC_TOK_REM, and the scan
loop's post-switch check reads it before the next line's first character
has assigned anything. A line opening with whitespace then re-triggered
the REM break and scanned to nothing: every indented line after a REM was
silently skipped. Numbered programs never saw it -- the line number is the
first token and overwrites the leftover -- which is why the whole golden
corpus missed it and the unnumbered, indented galaga.bas found it.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Reset scratch per line and unwind dead scopes in host function calls 743e610f8f

akbasic_runtime_call_function()'s body loop drives process_line_run()
directly, skipping the per-line prologue akbasic_runtime_step() provides.
The call environment's value scratch therefore accumulated across the
whole body, and any body past about ten real lines died with 'Maximum
values per line reached' -- a limit that is supposed to be per line. The
loop now runs the same prologue step() does.

A body that died also left its call scopes active: nothing popped them,
so a host absorbing script errors drained the twelve-slot environment
pool after twelve dead calls. The loop now unwinds to the caller's
environment on every exit path.

New: akbasic_runtime_clear_error(), the missing half of host revival. A
run's first BASIC-level error latches deliberately, and set_mode(RUN)
alone cannot un-decide that; a host that absorbed the error calls this
beside it. Both defects and the revival dance are pinned in
tests/user_functions.c.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Add the galaga example: a C engine with akbasic as its enemy brain 27837aeabc

A GALAGA-style fixed shooter whose engine is C on libakgl (null physics)
with the interpreter embedded as the scripting engine that owns every
enemy's behavior. One DEF-only script is called per enemy per frame
through a custom akgl_Actor update hook; SELF@, ACTOR@ and GAME@ are host
bindings, so the script reads and writes the engine's real memory -- the
boss even swaps its own damage sprite by raising an actor state bit from
BASIC. Bullets, collision, scoring and screens stay C.

Structure arguments were measured and rejected for the per-frame path:
each pointer parameter spends a value-pool slot the pool never reclaims,
1,015 calls to exhaustion against an unbounded rebind (issue #36).

Built when AKBASIC_WITH_AKGL=ON. Two CTest entries: a 600-frame headless
autoplay run under the dummy SDL drivers, and an interop round-trip test
that links the real script.c and galaga.bas and pins the four boundary
claims, 24,000 sustained calls among them. docs_galaga_figures
regenerates the two checked-in figures. Art is Kenney CC0, byte for
byte, with provenance.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Update the breakout chapter's scope-pool figure to this branch's 12 47c6be58c5

The environment pool shrank from 32 to 12 in the memory-reduction work
and the chapter's exhaustion transcript still asserted the old number,
which is a docs_examples failure on every run of this branch.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Write the GALAGA tutorial chapters and the repeated-host-calls guide d5a0edd692

docs/20 builds the engine and the boundary: the startup order, the
starfield, actors and collision, booting a DEF-only script, the issue #8
mode workaround, the custom update hook, first light, screens, and the
headless harness. docs/21 builds the three shared structures and the AI:
the host type tables, the actor binding, the randomness route around
issue #16, the measured case against structure arguments (issue #36),
the three language rules that shape the script, the maneuvers, the
argued formation decision, the script-death policy, and the interop
proof. Every fenced block runs under tests/docs_examples.sh in both
build configurations; five new preludes carry the C fragments.

docs/10 gains the 'Calling a function every frame' section the chapters
lean on: the per-call akbasic_environment_zero() rule, the set_mode(RUN)
workaround, the clear_error() revival, and the case for rebinding over
structure arguments. Index rows and chapter counts updated.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Benchmark the boundary and close the cold read's tutorial gaps 54ab85a276

The interop test now ends with a measured comparison: 24,000 formation
updates through the script boundary against a line-for-line C
translation of the same state machine. 881 us against 0.01 us per call
on this machine, quoted verbatim in the new chapter 21 Step 11 with the
architectural decisions it prices.

A Haiku-class cold read of the chapters produced a build whose failures
were all mechanical -- invented include paths, never-shown sink statics,
guessed status codes and character names. The chapters now carry the
include lists, the script.c statics, the status-code roster, the
sprite/character table, the full CMake recipe and the explosion spawn's
HANDLE example, so none of those have to be guessed again.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

Close the remaining cold-read gaps: bind, labels, menus and main's shape

akbasic CI Build / cmake_build (push) Failing after 5m32s

Details

akbasic CI Build / sanitizers (push) Failing after 15m58s

Details

akbasic CI Build / coverage (push) Failing after 20m7s

Details

akbasic CI Build / mutation_test (push) Failing after 4m29s

Details

akbasic CI Build / akgl_build (push) Failing after 12m28s

Details

dd10dc143a

Three more Haiku-class cold reads of the chapters, each against the
amended text. What each surfaced is now shown rather than described: the
akbasic_host_register_type()/akbasic_host_bind() boot calls, the
declare_play() label listing, the akgl_UiMenu static and its
handle_event signature, one control-handler pair, and main()'s
ATTEMPT/HANDLE_DEFAULT/FINISH_NORETURN shape with the CATCH-inside-
ATTEMPT rule stated. By the fourth read the generated player.c and
enemies.c compiled untouched and every remaining guess was a tuning
value the chapters deliberately leave open.

Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc

logikoma requested review from andrew 2026-08-04 11:28:55 -04:00

logikoma referenced this pull request

2026-08-04 11:29:04 -04:00

Plan: a GALAGA tutorial — C/libakgl engine with akbasic embedded as the enemy-behavior scripting engine #34

tachikoma referenced this pull request

2026-08-04 11:30:22 -04:00

Plan: a GALAGA tutorial — C/libakgl engine with akbasic embedded as the enemy-behavior scripting engine #34

andrew closed this pull request

2026-08-04 13:22:38 -04:00

akbasic CI Build / cmake_build (push) Failing after 5m32s

Details

akbasic CI Build / sanitizers (push) Failing after 15m58s