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

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

CMakeLists.txt

@@ -268,6 +268,69 @@ if(AKBASIC_BUILD_EXAMPLES)
   endforeach()
 endif()
 
+# The galaga example: a C game on libakgl with the interpreter embedded as its
+# enemy-behavior engine. Chapters 20 and 21 build it from an empty file, so it
+# is compiled and run by every AKGL build rather than rotting in a document.
+# The asset, script and font paths are baked in so the smoke test can launch
+# from any working directory; --assets and --script override them at runtime.
+if(AKBASIC_BUILD_EXAMPLES AND AKBASIC_WITH_AKGL)
+  add_executable(akbasic_example_galaga
+    examples/galaga/main.c
+    examples/galaga/script.c
+    examples/galaga/enemies.c
+    examples/galaga/player.c)
+  target_compile_options(akbasic_example_galaga PRIVATE -Wall -Wextra)
+  target_compile_definitions(akbasic_example_galaga PRIVATE
+    GALAGA_ASSET_DIR="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/assets"
+    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas"
+    GALAGA_FONT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/assets/fonts/C64_Pro_Mono-STYLE.ttf")
+  target_link_libraries(akbasic_example_galaga PRIVATE akbasic akgl
+    SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image)
+  akbasic_instrument(akbasic_example_galaga)
+  # Ten seconds of scripted play under the headless drivers: the script boots,
+  # a wave enters and forms, the autoplay pilot shoots at it, and the program
+  # tears down and exits 0. A tutorial that stops working fails here rather
+  # than in front of a reader.
+  _add_test(NAME example_galaga COMMAND akbasic_example_galaga --frames 600 --autoplay)
+  _set_tests_properties(example_galaga PROPERTIES TIMEOUT 120
+    ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software")
+
+  # The boundary's round-trip test: links the real script.c and the real
+  # galaga.bas, and fails the moment the two sides of the interop disagree.
+  add_executable(akbasic_example_galaga_interop
+    examples/galaga/interop_test.c
+    examples/galaga/script.c)
+  target_compile_options(akbasic_example_galaga_interop PRIVATE -Wall -Wextra)
+  target_compile_definitions(akbasic_example_galaga_interop PRIVATE
+    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas")
+  target_link_libraries(akbasic_example_galaga_interop PRIVATE akbasic akgl
+    SDL3::SDL3)
+  akbasic_instrument(akbasic_example_galaga_interop)
+  _add_test(NAME example_galaga_interop COMMAND akbasic_example_galaga_interop)
+  _set_tests_properties(example_galaga_interop PROPERTIES TIMEOUT 120)
+
+  # Regenerating the game figures in docs/ is a deliberate act, never part of
+  # a build, for the same reason docs_screenshots is: the PNGs are checked in.
+  # Wall-clock dt makes each regeneration differ by a few pixels of starfield,
+  # so expect a binary diff every time this runs; commit one only when the
+  # content changed on purpose. (docs_galaga_figures, not docs_game_figures:
+  # the libakgl submodule already owns that target name.)
+  add_custom_target(docs_galaga_figures
+    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy
+            SDL_RENDER_DRIVER=software
+            $<TARGET_FILE:akbasic_example_galaga> --frames 40
+            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/galaga-title.png"
+            --screenshot-frame 30
+    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy
+            SDL_RENDER_DRIVER=software
+            $<TARGET_FILE:akbasic_example_galaga> --autoplay --frames 370
+            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/galaga-wave.png"
+            --screenshot-frame 360
+    DEPENDS akbasic_example_galaga
+    COMMENT "Regenerating the galaga figures in docs/images"
+    VERBATIM)
+endif()
+
 # ---------------------------------------------------------------------------
 # Tests.
 #