From dde1d91c6e2a7877d091803207b4ce47432823d4 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 08:46:51 -0400 Subject: [PATCH 1/7] Reset the scanner's leftover token type between lines 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- src/scanner.c | 11 +++++++++++ tests/language/statements/rem_indented_line.bas | 14 ++++++++++++++ tests/language/statements/rem_indented_line.txt | 3 +++ 3 files changed, 28 insertions(+) create mode 100644 tests/language/statements/rem_indented_line.bas create mode 100644 tests/language/statements/rem_indented_line.txt diff --git a/src/scanner.c b/src/scanner.c index 2f7ed40..c49fc69 100644 --- a/src/scanner.c +++ b/src/scanner.c @@ -23,6 +23,7 @@ akerr_ErrorContext *akbasic_scanner_zero(akbasic_Runtime *obj) obj->current = 0; obj->start = 0; obj->hasError = false; + obj->tokentype = AKBASIC_TOK_UNDEFINED; SUCCEED_RETURN(errctx); } @@ -409,6 +410,16 @@ akerr_ErrorContext *akbasic_scanner_scan(akbasic_Runtime *obj, const char *line, obj->current = 0; obj->start = 0; obj->hasError = false; + /* + * The `REM` early-exit below leaves `tokentype` holding AKBASIC_TOK_REM, + * and the loop's post-switch check reads it before the first character of + * the *next* line has assigned anything. A line whose first character + * carries no token of its own -- leading whitespace -- then re-triggered + * the REM break and scanned to nothing: every indented line after a REM + * was silently skipped. A numbered program never saw it, because the line + * number is the first token and overwrites the leftover. + */ + obj->tokentype = AKBASIC_TOK_UNDEFINED; /* * Cleared here rather than by each caller, so the flag always describes the * line this call just scanned. It used to be cleared only in diff --git a/tests/language/statements/rem_indented_line.bas b/tests/language/statements/rem_indented_line.bas new file mode 100644 index 0000000..5628d03 --- /dev/null +++ b/tests/language/statements/rem_indented_line.bas @@ -0,0 +1,14 @@ +REM The line after this comment is indented, and it must still run: the +REM scanner's REM early-exit used to leave TOK_REM armed, and the next +REM line's leading whitespace re-triggered it -- every indented line +REM after a REM was silently skipped. Unnumbered on purpose: a numbered +REM line's first token overwrites the leftover and hides the defect. +PRINT 1 +REM an indented statement follows + PRINT 2 +REM an indented multi-line DEF body, the shape that found it +DEF F(N#) + REM a comment inside the body + RETURN N# + 5 +PRINT F(10) +END diff --git a/tests/language/statements/rem_indented_line.txt b/tests/language/statements/rem_indented_line.txt new file mode 100644 index 0000000..4b5aa34 --- /dev/null +++ b/tests/language/statements/rem_indented_line.txt @@ -0,0 +1,3 @@ +1 +2 +15 -- 2.43.0 From 743e610f8f5f00cb9c58175c76b2a447db6931d2 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 08:47:05 -0400 Subject: [PATCH 2/7] Reset scratch per line and unwind dead scopes in host function calls 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- include/akbasic/runtime.h | 21 ++++++++ src/runtime.c | 39 ++++++++++++-- tests/user_functions.c | 109 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 166 insertions(+), 3 deletions(-) diff --git a/include/akbasic/runtime.h b/include/akbasic/runtime.h index 8de41fa..592acc5 100644 --- a/include/akbasic/runtime.h +++ b/include/akbasic/runtime.h @@ -632,6 +632,27 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_println(akbasic_Runtime *obj, */ akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_set_mode(akbasic_Runtime *obj, int mode); +/** + * @brief Forgive the last BASIC-level error, so a host may call again. + * + * A program run latches its first runtime error and ends -- deliberately, and + * a host cannot un-decide that with akbasic_runtime_set_mode() alone: the + * latch survives the mode change, every later line is skipped, and every + * later akbasic_runtime_call_function() answers a stale value after walking + * the whole source table doing nothing. + * + * A host that absorbed a script error -- reported through the sink, actor + * marked dumb, frame preserved -- calls this beside + * `akbasic_runtime_set_mode(obj, AKBASIC_MODE_RUN)` to put the runtime back + * in service. It is for hosts between calls, not for verbs during a run: a + * running program's first error still ends it, exactly once, with one line. + * + * @param obj Object to initialize, inspect, or modify. + * @return `NULL` on success, otherwise an error context owned by the caller. + * @throws AKERR_NULLPOINTER When `obj` is NULL. + */ +akerr_ErrorContext AKERR_NOIGNORE *akbasic_runtime_clear_error(akbasic_Runtime *obj); + /** * @brief Evaluate one AST leaf, drawing scratch values from the environment. * @param obj Object to initialize, inspect, or modify. diff --git a/src/runtime.c b/src/runtime.c index 0b61e0f..3a34754 100644 --- a/src/runtime.c +++ b/src/runtime.c @@ -1114,9 +1114,33 @@ akerr_ErrorContext *akbasic_runtime_call_function(akbasic_Runtime *obj, const ch * answering wrongly -- which is worse. The fix wants the REPL's own line * cycle, and that is a larger change than a condition. */ - while ( obj->environment != targetenv && obj->mode == AKBASIC_MODE_RUN ) { - PASS(errctx, akbasic_runtime_process_line_run(obj)); - } + ATTEMPT { + while ( obj->environment != targetenv && obj->mode == AKBASIC_MODE_RUN ) { + /* + * The same per-line prologue akbasic_runtime_step() runs. Without + * it the call environment's value scratch accumulates across the + * whole body, and a body of ten real lines dies with "Maximum + * values per line reached" -- a limit that is supposed to be per + * line, not per call. step() cannot do this for us: this loop + * drives process_line_run() directly. + */ + CATCH(errctx, akbasic_runtime_zero(obj)); + CATCH(errctx, akbasic_scanner_zero(obj)); + CATCH(errctx, akbasic_runtime_process_line_run(obj)); + } + } CLEANUP { + /* + * A body that died mid-line -- a runtime error set run_finished_mode, + * or a scanner error escaped (issue #4) -- left its scopes active. + * Give them back, or a host absorbing script errors drains the + * twelve-slot environment pool after twelve dead calls and every + * call after that fails for a reason nobody can see in the script. + */ + while ( obj->environment != targetenv && obj->environment->parent != NULL ) { + IGNORE(akbasic_runtime_prev_environment(obj)); + } + } PROCESS(errctx) { + } FINISH(errctx, true); PASS(errctx, akbasic_environment_new_value(targetenv, &out)); PASS(errctx, akbasic_value_clone(&targetenv->returnValue, out)); *dest = out; @@ -1918,6 +1942,15 @@ akerr_ErrorContext *akbasic_runtime_step(akbasic_Runtime *obj) SUCCEED_RETURN(errctx); } +akerr_ErrorContext *akbasic_runtime_clear_error(akbasic_Runtime *obj) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, (obj != NULL), AKERR_NULLPOINTER, "NULL runtime in clear_error"); + obj->errclass = AKBASIC_ERRCLASS_NONE; + SUCCEED_RETURN(errctx); +} + akerr_ErrorContext *akbasic_runtime_run(akbasic_Runtime *obj, int maxsteps) { PREPARE_ERROR(errctx); diff --git a/tests/user_functions.c b/tests/user_functions.c index d2d60d5..3bc0414 100644 --- a/tests/user_functions.c +++ b/tests/user_functions.c @@ -337,6 +337,113 @@ static void test_call_from_c(void) harness_stop(); } +/** + * @brief A long multi-line body called from C completes. + * + * The value scratch is a *per line* limit, and the call loop has to reset it + * per line the way akbasic_runtime_step() does. It did not: the scratch + * accumulated across the whole body, and any body past about ten real lines + * died with "Maximum values per line reached" -- silently, from the caller's + * point of view, because a BASIC-level error inside the loop reports through + * the sink and comes back as a zero (issue #7's shape). Found by the galaga + * example, whose enemy functions are all longer than ten lines. + * + * The set_mode(RUN) between the load and the call is the issue #8 workaround: + * the body only runs in RUN mode, and the program has already ended. + */ +static void test_long_body_called_from_c(void) +{ + akbasic_Value arg; + akbasic_Value *argp[1]; + akbasic_Value *result = NULL; + + TEST_REQUIRE_OK(run_program("10 DEF LONGB(N#)\n" + "20 A# = N# + 1\n" + "30 B# = A# + 1\n" + "40 C# = B# + 1\n" + "50 D# = C# + 1\n" + "60 E# = D# + 1\n" + "70 F# = E# + 1\n" + "80 G# = F# + 1\n" + "90 H# = G# + 1\n" + "100 I# = H# + 1\n" + "110 J# = I# + 1\n" + "120 K# = J# + 1\n" + "130 L# = K# + 1\n" + "140 M# = L# + 1\n" + "150 P# = M# + 1\n" + "160 Q# = P# + 1\n" + "170 R# = Q# + 1\n" + "180 RETURN R#\n")); + TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN)); + + memset(&arg, 0, sizeof(arg)); + arg.valuetype = AKBASIC_TYPE_INTEGER; + arg.intval = 1; + argp[0] = &arg; + TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "LONGB", argp, 1, &result)); + TEST_REQUIRE(result != NULL, "a call should have produced a result"); + TEST_REQUIRE_INT(result->intval, 17); + TEST_REQUIRE_STR(HARNESS_OUTPUT, ""); + harness_stop(); +} + +/** + * @brief A body that dies leaves the environment stack balanced. + * + * A runtime error inside a called body reports through the sink and ends the + * run -- that part is unchanged, and the caller still gets the zeroed slot + * (issue #7 tracks whether it should). What must NOT happen is what did: the + * call's environment was never given back, so a host that absorbed script + * errors and kept calling drained the twelve-slot pool after twelve dead + * calls, and every later call failed with "Environment pool exhausted" -- an + * exhaustion nothing in the script explains. + * + * The revival dance after each death is two calls: clear_error(), because a + * run's first error latches and every later line is skipped while it stands, + * and set_mode(RUN), the issue #8 workaround the boot already needed -- + * the error dropped the runtime out of RUN mode. + */ +static void test_dead_body_releases_environments(void) +{ + akbasic_Value arg; + akbasic_Value *argp[1]; + akbasic_Value *result = NULL; + akbasic_Environment *root = NULL; + int i = 0; + + TEST_REQUIRE_OK(run_program("10 DEF DIE(N#)\n" + "20 X# = NOSUCH(N#)\n" + "30 RETURN X#\n" + "40 DEF FINE(N#)\n" + "50 Y# = N# * 2\n" + "60 RETURN Y#\n")); + TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN)); + root = HARNESS_RUNTIME.environment; + + memset(&arg, 0, sizeof(arg)); + arg.valuetype = AKBASIC_TYPE_INTEGER; + arg.intval = 7; + argp[0] = &arg; + + /* Fifteen deaths: more than the pool holds, so a single leaked scope + * fails this loop even if the first twelve limp through. */ + for ( i = 0; i < 15; i++ ) { + TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "DIE", argp, 1, &result)); + TEST_REQUIRE(HARNESS_RUNTIME.environment == root, + "a dead call must unwind back to the caller's environment"); + TEST_REQUIRE_OK(akbasic_runtime_clear_error(&HARNESS_RUNTIME)); + TEST_REQUIRE_OK(akbasic_runtime_set_mode(&HARNESS_RUNTIME, AKBASIC_MODE_RUN)); + } + + /* And the runtime is still whole: a healthy function runs to the right + * answer after every one of those deaths. */ + TEST_REQUIRE_OK(akbasic_runtime_call_function(&HARNESS_RUNTIME, "FINE", argp, 1, &result)); + TEST_REQUIRE(result != NULL, "a call should have produced a result"); + TEST_REQUIRE_INT(result->intval, 14); + harness_stop(); +} + int main(void) { TEST_REQUIRE_OK(akbasic_error_register()); @@ -351,6 +458,8 @@ int main(void) test_call_scopes_are_reclaimed(); test_calls_do_not_leak_value_slots(); test_call_from_c(); + test_long_body_called_from_c(); + test_dead_body_releases_environments(); return akbasic_test_failures; } -- 2.43.0 From 27837aeabc4a7cee2b38ebb918993f665a991414 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 08:47:21 -0400 Subject: [PATCH 3/7] 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- CMakeLists.txt | 63 ++ docs/images/galaga-title.png | Bin 0 -> 5504 bytes docs/images/galaga-wave.png | Bin 0 -> 58428 bytes examples/galaga/README.md | 63 ++ examples/galaga/assets/art/License.txt | 14 + examples/galaga/assets/art/PROVENANCE.md | 39 + examples/galaga/assets/art/enemyBlack3.png | Bin 0 -> 3548 bytes examples/galaga/assets/art/enemyBlue1.png | Bin 0 -> 3095 bytes examples/galaga/assets/art/enemyGreen3.png | Bin 0 -> 3609 bytes examples/galaga/assets/art/enemyRed2.png | Bin 0 -> 3055 bytes examples/galaga/assets/art/laserBlue01.png | Bin 0 -> 744 bytes examples/galaga/assets/art/laserBlue08.png | Bin 0 -> 882 bytes examples/galaga/assets/art/laserRed01.png | Bin 0 -> 735 bytes .../galaga/assets/art/playerShip1_blue.png | Bin 0 -> 2698 bytes .../galaga/assets/character_galaga_bee.json | 16 + .../galaga/assets/character_galaga_boom.json | 16 + .../galaga/assets/character_galaga_boss.json | 23 + .../assets/character_galaga_butterfly.json | 16 + .../assets/character_galaga_enemyshot.json | 16 + .../assets/character_galaga_player.json | 16 + .../assets/character_galaga_playershot.json | 16 + examples/galaga/assets/sprite_galaga_bee.json | 16 + .../galaga/assets/sprite_galaga_boom.json | 16 + .../galaga/assets/sprite_galaga_boss.json | 16 + .../assets/sprite_galaga_boss_hurt.json | 16 + .../assets/sprite_galaga_butterfly.json | 16 + .../assets/sprite_galaga_enemyshot.json | 16 + .../galaga/assets/sprite_galaga_player.json | 16 + .../assets/sprite_galaga_playershot.json | 16 + examples/galaga/enemies.c | 314 ++++++++ examples/galaga/galaga.bas | 119 +++ examples/galaga/galaga.h | 155 ++++ examples/galaga/interop_test.c | 132 ++++ examples/galaga/main.c | 698 ++++++++++++++++++ examples/galaga/player.c | 407 ++++++++++ examples/galaga/script.c | 281 +++++++ 36 files changed, 2532 insertions(+) create mode 100644 docs/images/galaga-title.png create mode 100644 docs/images/galaga-wave.png create mode 100644 examples/galaga/README.md create mode 100644 examples/galaga/assets/art/License.txt create mode 100644 examples/galaga/assets/art/PROVENANCE.md create mode 100644 examples/galaga/assets/art/enemyBlack3.png create mode 100644 examples/galaga/assets/art/enemyBlue1.png create mode 100644 examples/galaga/assets/art/enemyGreen3.png create mode 100644 examples/galaga/assets/art/enemyRed2.png create mode 100644 examples/galaga/assets/art/laserBlue01.png create mode 100644 examples/galaga/assets/art/laserBlue08.png create mode 100644 examples/galaga/assets/art/laserRed01.png create mode 100644 examples/galaga/assets/art/playerShip1_blue.png create mode 100644 examples/galaga/assets/character_galaga_bee.json create mode 100644 examples/galaga/assets/character_galaga_boom.json create mode 100644 examples/galaga/assets/character_galaga_boss.json create mode 100644 examples/galaga/assets/character_galaga_butterfly.json create mode 100644 examples/galaga/assets/character_galaga_enemyshot.json create mode 100644 examples/galaga/assets/character_galaga_player.json create mode 100644 examples/galaga/assets/character_galaga_playershot.json create mode 100644 examples/galaga/assets/sprite_galaga_bee.json create mode 100644 examples/galaga/assets/sprite_galaga_boom.json create mode 100644 examples/galaga/assets/sprite_galaga_boss.json create mode 100644 examples/galaga/assets/sprite_galaga_boss_hurt.json create mode 100644 examples/galaga/assets/sprite_galaga_butterfly.json create mode 100644 examples/galaga/assets/sprite_galaga_enemyshot.json create mode 100644 examples/galaga/assets/sprite_galaga_player.json create mode 100644 examples/galaga/assets/sprite_galaga_playershot.json create mode 100644 examples/galaga/enemies.c create mode 100644 examples/galaga/galaga.bas create mode 100644 examples/galaga/galaga.h create mode 100644 examples/galaga/interop_test.c create mode 100644 examples/galaga/main.c create mode 100644 examples/galaga/player.c create mode 100644 examples/galaga/script.c diff --git a/CMakeLists.txt b/CMakeLists.txt index 21229cf..f4ae118 100644 --- a/CMakeLists.txt +++ b/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 + $ --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 + $ --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. # diff --git a/docs/images/galaga-title.png b/docs/images/galaga-title.png new file mode 100644 index 0000000000000000000000000000000000000000..7a71b8668401e7e19d1d00ef4091d2741522baaa GIT binary patch literal 5504 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 literal 0 HcmV?d00001 diff --git a/docs/images/galaga-wave.png b/docs/images/galaga-wave.png new file mode 100644 index 0000000000000000000000000000000000000000..daf87f169e10744633fd5d58e867162d0d762159 GIT binary patch literal 58428 zcmdSBWmr{R*EWm=A}JwA3P_hqw<4uLkQ@TSJ@EEU!~NUf z*K*x!CIo~h2ycX5DcHwtO*@&Zt-e1!_o*atf7(E3kNrwMOur<;WTJREGlI7`G?&@0 zynw}4jvDH^=y;_&2~modm>IX>U3>$LA2r}vk5$pM!}=emG`{bU6%oDZnTu#@x_OUHG!bIsK>_UxgF0YuC$@a`KS=I ztYmJuWNvW#rjs6psU$d_$0{=~dxq7=7G1a*Ee#A!Tvk_iJ-!pSe_4NXqbrbkx!>_z zoL?6$dy|(7T)hdd?z^IwF|xs+?~rG9!`@7b%XBF_smo`oe)+dlLU$21ix(1jPWNRU zYBqp0arrDCO=x$lm#cwBtJWiP>!AgW~l&C7xbl1o!T|Y8!FG^0I12J->3<$Lz0G1_gOej-EL0ZsBbjXsysxI`ADq~a~n~I zm%C84X`MzEE;x1b7xls%rZ< z%>^Cp>_eyTP+4qc<;QhJHiUs`$~>pKzRHfg$WF8Qk|)72_M-LKBXz_qk-ZDqoS)nc zhS6WA)lzT4M%}Ko;cAKCPHtRwL06d8caH!rnnFs23-mpzlX;&H(TN3>+8MC-qxry# zLzmi14}r7UV$xJA90VPo8eJ&JtYSVfA9(DF*uuJzk~3cgzveu2*D!Slc%YFaDt#q0sctYsse=I42JB4w~C zww_)hj=JXvPg1n5vPo`6mINws-Ab(AomNF=k!*e{%Po!6zOK#9yor?gGGNP*U(Le( zST8lMY9r@=DB@=>NYX81TJSv(X8mpVjwBRTxEQp=Q~p;3_`d*&f1d)s<^R8rsLj6b zuZNl7ZUP()c<=st^FLoR#Xo%b@aM$;`S<_(Zw#l$#*}~A$Y0kK8kq0Gz19DB$03^n z6x^+|tgLL>s+aH1ojWad=grKn`*2w5*B>et9DaVlN*o*$zv*9`1en|r0PHS*ubMvx8sjk>) zl!@%;S7IKfswFHB9x5!q{{DV*P6ki=<6$K?*dnQwrr5WPd%i>JOUMZK`VkP_yVp5f z7ddun4yDLEC%0#+tn|#x3X*AB>@+nrNJvQ&qoTyplRKx(DJOE0J4hO8W3l`nx4IyCN!;lb^jqMqTSBa`mrM)Nzk;$Pd(Qc(MR^Y#Kgq( z^z?$hnm5OqyPKPYgoJ8pY9-lIW&XU9qNyw7(g@GK0xwnQK;v)ON^CdfdburlKe4yM znhVw&dHHa3bUw;QzzD=L((>bJMIh2trM#Tb~FbX_H> zLV-$ISy>7C0!h>RFIaQ4L5a95msSOC&Nns;WvR2dfA3O*5RiFN!q#NPZqUtH5E}-N zb9D4$6*LngBSL)qzAsl+oJ6km^_kddgX`z#4&5FlB_$bB@&3))g1#doBU@a$qN1X^ z^*7haQVNjYJLz79e+L!8CZ(k0Q2ORb8drFIV`F1&P2T{1M90R)Mn(CyF4{t`fV8)F zckMWdVu<6VGCG&(Hq_D3(8fR9)M%LL>FIIDYiMYE6-nvWw>CF_hIzj&L@1?yWJIxG z^m0VaEc}?4-s_LZiP5wWGBGp?PI+d}r8G4YXLoluHY}^u+jR~+F!-ZlVpKIXch}b+ zlaQDi8V*d4E?a)I(`29t7E2v8==NZb%_}P#UOi-FVgkb*uJ(3LRCO*NIMxP>>5S$> z^m-HcEEa@lrHeoR-Wde?KCm+vdx2)oi{6B$=Fn*u7Z>(e6K(Bl0gDW-BaLtoCEH!rPZ)*-P6?tzTsK7=Eg_WupR$+Pw7$tC(U!hoG$z= zRj32|-sP2vi3!m4fPjF*!^1``8QCxey0W^uIe<6$|Xl-ZbR67Ii z=|kd}=^3i{k1-L$Cp}oBvHKy2kIM7@-P_T){5;&;o|wU6KieJ>5WJ1so1G(ms)BkP zL*J;?r&}^@Jt%oP<78%#QI7s+PPD)7LgI2HTR%HHHAQs)?h6d=cqw2>)zvZe^~nl? z(qipx+fT?m)p-;kgyoal0FVTIFL&$RX6szi;-|^~=wlk7r7yP~=RP5M`}jZlA zNRIFaPCcZnVpkv9e&XOmN5S&3=QRf3(D=BD>MaS;gmelyt6*vb7jhcea7YL9oI zyXE7?ljSCz`B4{Ft`_r(60V558*6mRWKvY2IXO8bLDWuN?}5-~cTX>`f_M*nM>iR( zP<6?q2OnltwP7RBxx;Uk+}POo+6Nt(tQrcn(Q{^Vt!+^amZnI!apHv!= z^eS0KQuQmML>~1lsoQqSzMZAX%HjEvb9oToiSn{2Vo1jNUtk?BbO#^7uninnr?bqS z`1ts3Y=n}mbtgyjyIy$dih~bj*KB2?%jRJf9!puH0}si52AB!NX9xlfh>4B8a=mdo zXTC{`JHQF}Gr>YE>JB7?sCrJ{Ogg3>CY@^z`)R=H{Ip z)4wrC{psRw1aR+wa~`(F&12V9p4s)y&BMzp2n15aez|&@cvBI26LbEqhz)8y1MZ=I zg&HrV*QjE05YVi>xw%<=V{>t|E=2x3lrtO)nM{Z-9;UP4(Rm??6G`p#A+~#DYz*H| z$aZ@I?k};arNZR1{~(WhHk@<~c>*26jk~uBBt0W=?R^nkrXaLLjIFHuPI+lZHu^Cd zzNTh7FTS`?qT8Zqf8{mtQ(@Vq5+3WdZ^I>v-~QSRKRNZXTtMU1#d#l!rG^44U8~yHv^IlmQ7;em?{i>>}6B83K z*Bf9xI@4R6f9qUwwe8N73Wz|{o-IQOf&P5!O$p*RJf=lNLLzlNdru~0W@eV(==A;E zin;DMbgNa5V$}=NAp)^mAj60|o~bfjKmVe%2C1y@MX1SL zo134Tdl8P_Jf6uz)n{5k@1N|{B}86SUS3{PLj<;`C~AsRsaeT1iA?lPLc*oJg-zq4 zEbFB=Ub-h{V-ImP($VD=0M$r!%QxKd{EkPNJM3v>(pHB!LLK5qpC`Jo5&VULhG(x! zUoT06)dGL#Wq31u3IxaQv2ob zvJ~F(SJu@fh&|OVQl<+p9ygA8=x&ME9UR)elqH|xiP@?*1JTqBYF+SO7*X)0ZlZRX z8R;3B*`oefG9D8Xv$DEsw>xtM5KBs0dXxVY>sv;Z!vpeVN;=QXdEQ$|%5Vao?Evr) zsMn%3x091i_LqS}Gnm+ns;u}^tbkz3bE~HWkGNXyW@j|LNs|MF2L%NMyhb|~PF!3# zGCT?pA`cdON)Wg~^7M5AQ}LsSdaBU&X5XG%UVsWmLSk+kN>xVzm;UuNKG~i;JuYyY)-8cpwo_KM+^X9fk(P?PR6f)q4~|NN z+S}1YsBfEHm4V@ESu=s%a>wu6J3BaVIrYtLb-_@2YY#>UMdjPA&1Re5DG#h$lLz~X zqyQ5;*!fm%$^cG2k217{%uy>P6 zi^w4+Hsgt$Mlu~+6g5JaHvnseM&J=E>aR?MWgQ(Ifn=>K9CpWoD?~AjNF*`_gT0!q zx$|6~^+q)e4-YFdq>o=m?z+H2>+N^UZZ=4z662y`Aw*YuKM8MOwlAU$O%9!E@Ghl+ zr1V*1B&bG5N7*(%cl5jKJ-X(LP=9A;Rx!z15hS<1ly%t3L|QrWezYoYXl$&qre+G* z*!Z}^Qrp96qAyRR+jDvE1#2{jD`b~}?bLyjxB=jADS~(hMn_jqFRg6u!SrGAN;8*} zTdk|Qt0mMH;U8|-Y81@wDhVV=Wek^%4G)(^-prSgy4{$$TAbxojcZQJSaQYz!;h8- zBo#PpnYT-)%7}H5%-g}$d5mtPgAV&DvckO9xA zQNV%ahl++4&*yaV6Zxtq^gLM4n--|uyLn2wVTA+)8FaWCF_^s=smO=!a92#av{Oc| znPSEWoR)C7#l1B$sts;S-g+68mvfFqCX`=&yx$+n%zN4qbX{Lha;f8NV)A-bM1`;i zMv#!;w5xfuJ;>p&hqPgo2+C`Mf!2@gsD`#P;i1dxjlLD64pEzDT4}vN%u0 zcE`-jym_U1K7jK(Na#fT&i1aZ8mF{NuM!ARWK0u2i*YPasv3bXgbVI%g{K`><2A1j zB2CyQK@h^ac$(S=tAZn*)4i~?W=ct6_SavLzcgzDZgq9Gu`%IvbI}Q88Li}cGBJ+4 zUCJGj&dwk_s@;0y0@DntAx%gyGCAeAWIq~1^=SgM3}EQQbjtJQ6n%6;jVS-zu1!T> zz)Uc;ZES1++Z4DQ?=4n(-0i_zQo&3u{VKIa$cP764K|$S#svol3&5HLa0HJ|Pdn+7 zM1b>zF}tQhZ+9FVyiK5}aBxybZ(cpj!h3bzt_hn)aXXc^Tn|&XHfoZ45go%#=(yR| z-&sH)r{qgbMWtOdHr`xRCe%aGy6Cs{PVNVae3jxGK=jlBiM8i#YHDJxJJU|MofG^w zh^S5iDV-}LA|ueH0*4DM{Gp(=jSU++`-bTuaN-{e+_8dMS?H6N$alLKm`s(UbXNCH z1_GQuEm-7Gf9Z~+9Ibsq8!f@au*NWWurMhd6n_OWe_GGhthrCO#t$3rVBpi@J3NpF zkV@w{N2%K6aNC_0zAIk52W=Ft^?+YhR8(x5?)^{`=!e``z1PT4&H4^yUF(@|ltXdq zpOd-q#ug?Q^j#hkq=O`lYLh4UuI1xgj7SR}t`?I52l5x|bUB^AJlUpKes&Pn)gh0$ zey>J|BQ8_-;4XqZoG-nt1f0|dP8b1+uh>Dnfn6VxCJyuz#zoN{ zDa)%(8zR5yI0-C!PjUMBMY2)*3N$LUM7 zz6xHEnHQr3?brxig1}qQ%?D`0k}{?pR< zm9n|0*s1NenoFIZ9S3je!Uz8N_cPU#6GleH?(S~a`WvgnOZ62v$24H4kS^0c91>17 zTo!$sV3=MbbgKaejuu!E5fPr4Dy(S2NuW6hxnXJ2E#V?U_sA&JmeAr#xkZ`L8NTW!z<<0`?|c-r zA*v&kl9KXWhNk!HQdZ6qK*kk-j6)(ItbYVY9AvYaeQ!+Qu6{1=cX{{(UArV?7pB^W z!3cGfpHmff^}Bj=1Av7>EVcsMTE&tMACgI(c-s<4QRCj(RVej|dv??>i? zLHdYr_x`;*UYl9>j6x0R_kEw4NoeKwyB{!!RHEU`tePBilz(&$Kd(8NFuG^=R2o9L zO6$vtq>;=PLX8mh8SYtpx3FkMp>JH`y^NY{p|w#=!Mb0OhidU~By)d;Q~cPZ0^9c?c5m zN2Z>CS`I>Fl{<)^wEgI+p{$IFr;9=7%WD%J2i8Mm??)i;c^K>*4Jmx*zRA$Aa&yx$ zeQ^l2MN?NY7hU{t`$PM%zP50bwP+@gkZDDyF8!WT%eKN$+56}(HD-#K4jabuA^=7a+{yV(1+W0#?YEM4XKPlU5*P2laYa>Wo9Hp9o9MYckehsTzbYLTNh{6qMb*UYQDHM1Cg4#+P|L;744v`}YEJhMq(J8lx(M213zG*LlP%kn! zv*+7VmaHzAddVIZTcuO8Mlym76RxQ%P~`n5;!Vl3M){SZNXzOz=V zZsG8vzC&WE=2go-o=w#QOg#EaPYDLXv*yi$de^iMs!+hAplhRse$0E+(rIUdhJ^F8ChWkrA^R>S3 zhIqFcbSbD^`iH!yrBdkK9)+m~Q4aJg(4|#T97XqTpW5SAOs3e!91QtYU>xsOZ^#`} z6qhVyXO+D_e%1yEk=RozYM|!4DnGur$w$S2xsu&w?kDI0JKTsrcN=5^`u~if@b2=q z2X&8&@d)k6z{3nluL5jKq1q-1iypa zBOrSDn6ZNaxnIaV_w2)&XAaMA7BO7)PBZdL$G816`c3Wblc`R??5=tfZv<`% zX4~^0fPf=aj@C-_&P7dLd|qv|CQ80{NX9XJTge$O3b~vW1*P=hpRsU3o=(T!-rm4~ z)(WcIS`Jy*&gkZ@+lgxUGGcp!w|fq&i!HcZXDN`7l-h+l^y&#z2#kKut;9>!Kw=Aj z+rDnTr2Z<6thcKd?qk9t^-Wfh5h&qt>bt!Oqk?I-n=1enAOUdjuz7jB->FIkLcSdJ zk}M2B9#H(UnY#Rfs~M#SBpraC9B6!tqs-J{_X=zCZ zknPsRXe5t#9tmFIYaYRtXpqeS7!gnQF{AGV&+8Dq6(#utcw|&set6eC1fI>@_=eq( zN$vga6pKMq-$HIJ5ShWB2n}EQrvwpN<%h*S(P(!tEYT8ebT~jN6nnpj_UcF)gfMvW zM8T)#7J2KBH`guYFU5mYS_LdFqG&E{zfHNgI_T0C8%q_j_grBIiVUtFfqWwk4&7nl zUtvcU=I6-F$GJ{^w_hT|QO2eXSqr#8xh#d1SI1&iA>F+qEkTKX3=Cb&UL}!;jQ%yT zI57fFy0ERIDsu(`=1Or_(~RVNG-d{d`($5K;FG_D%wM9!g1gCV2jC{n zs@K!g($XYMDoe^nS4|-5@f`M^Ixote5voK5FmyqP&NwWb9WRV^bhY1K8x~#q*8=)k zTU+aZ9ufec!P9=HzP@zk+t!xZB>NbdXB55wwWoPiJfq3=*Pim^?B)%pSAYgS3Xqfn zF@Qs{=fX#d|2dK1!G_G%yAQ~0jiIos#d{I0LwR?l<73byMbdk_(&aY~g8TbrWm}?N zRxO^L*|QSh3Q9O*#hg7IT2gYfyIcL)BE%bN#2FeMO&fhN%v&YH$DbQV`pb)!0+HW zh1XvZ!`^LtSr$7QbHZ+&iEVqwXbPv}vDO%sDW{grHbpHA)E;aWY&Zuvx&=(HQ~%yl zN_b&=*m|ig7>xKw$lD6qe)_tx%B*$I@S>5s^YYZ4e>RYVQte;80Os#?&$rs6`=YDH zRA2P&_r`IRfZYE;%iWI2S1}XjBI&AA4~^F+R(4U#AMEEC7EPNP8Ju>;6glE`XJ-_% zGw30{K=~bt;tlD7z=;9woFsu7On{VGePty+JQun%R=&9?zuS>0zo9M%DP0^SYD;>>%)@o4$$dGQ+0VMIom%D zt1CCMYDTTk_U4n{zQc5Q^p1|gw=`1@S13U^`~iXl+`VS6|K(mmk~>SG1F!)kyKKWI zbSUJ0Q89jOLKKf3c@2@@3U5RLi(Zd!2v{owa779(g1-AIjMt|Xz1GJSb|>dfh!gTz zrD_)KH)y3tXM~e42s``T)9t*U_G+UjVg^4_D}=R`jD5c4UZso#29=OPrr<$(yWt?e zJXc+{?)70;5=Ra9k)VW>RELdd0E9rnjy37w`q0JDS=Sm*#&SV)r$@MhZv^}Qhe3;if5bMn8A<{hW4u_CM<8c+RAL!4}=YSpAcB zR(Ob}m6YCpF-?w6%I`cV$&sbRG+ty9X@6;OZdFoXVPKJ#2mNU1obKsC%IA2*d~?7I z5c|2hf{90@H@Qy)c>UVF#Ve^~S0eC>Bmcf&3M1&k3G|zs<|f zm-+<<1If4l&Ltuv4FA9fRFa?T`4?RYt#m|{>!^kYgI^G>d2o*{lMW0z9NZZMf9KT| zP~fz)?icL@j(=g_ex*@@RPZ>eVI!yp0k&b@B%4PQO@ZjU) zd;R(~1qH=HFm<9cyo%OVAF1-&sQ#C#GA_shDE`%V8Fa&2KKlBCUJ-}fYdHdr$xvGzG-s^H*vNu{e^AL=z@1TCW(Un&* zbD>s$tOjH+=-b}jPI|rP1J7QRp?EErKLqEGkg1h?ds;ZWm+wP>rqz%MZfE9t7<(`X zvab)wu>3qRwJj|VCTFitkVu_nmJb>cn38SUM!0p19);X3Czv^I6S;#=W2~dIG~={8 zU7{C+`D5K0@%E>Ph(}~UfBX>SB#KB(HLJfm36Hflz>fRKb;}({{6s9!OrFq@~%qsn@05E(S?qb4bo1iudsP!Lo>p z*-+lxRzur$#0NNEnVFZj{gr2@a<}esso>MghPjN47}!%ZpQeLR_+klVr38dOMG4hWSsc^4h}91745FwjP1wMKpwR`{^>`J|GHo~ z1zgZ(fSp)hygBiSoy=3Z2$_t4knu)aIzcdDXW~LRork zzfI>dF~l{fiR$Ep{>LsPYi^upLX8J0jH6e`r#i;j|0*p=PgiLHm-mM1-=kA4h@%=a z*1C>Dpin4`BysX&omit@TiTw-3)8e>aznmTK2_bdUi;<m{Ak!4GZz_Oq3Q>Bma0p&3=yPJV@-=giwIkD3vZpPID_ZaRa zYIxj=uI(1jI?&AbZ!;~{xz-u<80;03&!2BpwpriWU$ zXO5qN9sy(AL}K(QXO#?0?aU^wfyEwY_jKY2H^=N|msjT=gEP+t7D+bDACQ^WD9v{~)Px~01@i3Hpd78IsW}Ti!oW}#9Qb7`fEKiHtUxg6pCRJM zCJs{VRF^A#C49VYVaH)+KTcg6FL=Lx*39O)wX}tSPv>g6%QIYPaxb2~?R7VF70Vz8 zMK1CmHF^;V@X2Yn)(&t8!TTA5kMG|FTV%?1F+_Kk5Yg%k2sP&+P!qlPsHW zTRI)}iv}9EKuJdC(VwwborsLOTwZ|v2`YJSR-b&1kmsM;nQ>hP9WScT+~*{$h9z8{ z99M9>$QBCtXIE?jzkG2%h0eMx_)&ur(T9@p+n*Zx`o0-oJs<-!0M>E)lY6)BWQkrc zT+Y+Gu948jOuU-S_n>M&*5wT)*qxZ(w%~CwoeaD~Qm;K~{H+}7g=q^tu?T3xPMhNI zUUY4CU370!BIs^zZFQMmAl~MNJZHH{GexwswN+JOPjUtWuz>+e zm*mzhM?48DoQ6uMbe`7Sk`1<5O68@toFFuv+6iW%FC26H54|w7wzcIyoAc=9zsyZv zkIkUes+eT!p3_ToIcY>9O?~`j;wO{@_vIb@*l&(mM>&q_6nwbxwBM8Lt)7j#1s+uv zY*-*aQd=cg_50i91cGAWC8(~A>m~Bp?X z8TOgu%%}~!ETpb94Z5pp{TO3mre8LPqDbn0m;9Eq~UTryqe%-YHFIlgmrs) z5fbzk;7H6$sb8%}-oa)=^4U~5Skm~S2xB}FTvsZe6^GJ#gqN~*}LHt-JpTOaN?8r9i=1Ov!CrF z!#YaLkCbwS$Ym$KBDR|`9Uju3)LwNU$rr6JFYu#XPV(7p?>HQ2Qi(Ihp94#P2o+OK zCM!^?g)mUJUtOM}klp_D@)mtSnZJiiuVC;bO_ae!|@zfT4zUc2ZsxX<7?6ikT$UP2o{9=3lvs>_jm zwH>=zz3TmWTctI%iY~tx#C-PR+D7VP+J7);$y{j>xDa7sMD7mxsp6baF9}&;;C`Q5 zfBH3p2?qPiJJkGfn1VF^$*!;>feR}ND3s5e?t$iIZGnz!Pn`Z_qnY!;8Q;BAwlg7i z%HK1LU`){Aj<4J9*m-H5k*Rfu6LZR8GFQ3IOe-p~Fg5MT80$f?*nSz?yXd%{vVJ$*USTA{ zWi;hr?RH>H`6KcBWZLb?H|VVgCju5_)~8d>pw%n8jX=ZZq)VY_wZm+~SnSGZ#k!Vb zcGGaZr{u$RMpC`_{;PKgctteA_k_!Z$<)qYdzDbWSyW8U>d#t6RPz815Q8S(wNvya z+orT)hg61${rS+a^=Mh`c3^rpXJDSUor|nt$w7HlKZ1xP&qEDtK?%m6{?pHI5Wak3 z=3U!kZSU>#&!eEulIGa+LOL{7`GJr1c*rMIQPNYHfJs}{zuH$v4X5}W9z}1&imrGF zB4d7YkR)@f+z;Rb9DPO$#;|9kWP?9_J;0%joGlm=sBPM`ngr+!!146L;7$ro&1QgH z>~DjLT?FlY^oTjg33fXLS@n#YZEulxYAS<0{6lTpI16JM=Y*JQC`Gz7LFQxT$f2sc3ArD{# z8)-81BM1@yC%-%9Y(Gk8E%kUR?=wLIfD#Yy{n8%xfhDnB$& zv~HoNT5ljKJbJG?_h6xvSUdkImEF6Z_IZk}!$=%7Uw*@C{Mc3@iH> zYk}7R@q*^MTy;d^dCge6iGDbm5}jaTG}~Ze4|QT)s^5Ygt9mNG9@N9sokvB?Zn4dN znnp}mP4u@zKcJMhfjjig2@_KvN%j8K%Y%d&m^}6^f|||1%>9l@s+QHqh7fW_4L){y z&nQ)2N~_~9{V7mP2j_WbOB0prss4UI5P!@UURZT+9;;Vf9vt{P_b)3!vJ-@#5d?ZS zfrc3;C#dt&s&XPtPP4+js;7gSmI&=Rt-3~5Gg3_2uP8NziWz;4h0B0mL+Ja5>LtN0 zZ<6RW&A6sPt1eKio)SR;sXJYJD`!qht}x4-s=X^aH&UshdhXfFFX^J|KV z`lLTI^eYv^W$}JmiXW6Ql0jjVGD!asXGB%~C#<8&S0|Qq+@GK=;whVMgm!CsJRD*%W)wq{HaW&V0WA36C&j5t670 zQJ7(;CuqpTC?JV_DCqgveFLW!Fz~8_mH?(xPk{~%olBg;vQ|5(?iXs##N)q-($}~62*z%&9GC#=d?<` zzc|>Lb-bWEJQ^RUWwWtxYO7IDQCrIw{?<#7@R2i*d1qZnKupnY`sPr*x8QdLy5)WQ zC635(uXY+kEUzptWkU#2q6R-6t!b3xvc*Fy+8go^6DA#cLn^fp96_LeMeE^vmU8zk z-US(@W+V@)dY0aCd8YczK%R!j zuj;ML>K6+AzUQYy^S3{WJ^PXggI@a^dAnT-+_XBmUIv`PPVjzxpwEBIt}&r{4fFKN z7FfKk^)2q*jdwip>Lcw)8$y@$mO(+5(zh&@DH$29i~G6x`6A>Gk0qiiruU;sZz}ZO zGHutzayWZ{Zn>p_?F}Z@aj%EMQe?_@C975sOQLNawzCrg#p|?Xp?nNc;f96o)*c_$ zGo2LjS8QjKD4ir}qHz%^m5gQCEcu0~d~j!*sD;xJ=8T0OyH%^BRx?Z^HoCUkX+asA z%LTYya_x3543D6@eUT8;NOaFmtedlGtu6ccfzF2cyIuIVEsy)Ao(yoCaPXKYA-RXy>1+5862n1yXuvW^5SX8 zWB~w#LSJNWcokQKj4QW^mX#Y6RTfx+#~I%P8ajj7(yos$?IIP$rjd^(Cnsw)%o4Qk zlgW9n_6byA24sxjDQX{c!q-#00JcP^T+T!n8XdwAv9DSj99snEcqfKThCkFA{Oztl zOB@h&xyj_n=qO0-Ji){#AdstYWqEM}8uFMPPn|RuxbC3b3^GdcZ#z{n@e90v01!if z*@XxTpjaSN9!d8FPyE$3B%k)UU{=X`nRfKC?fgE*!C#EAr#?+*&kx}-Ro&*|{uwCJjg3VOt}Af3 z9OlNF{EB-n-F7(yoXj=TAFGQdCen~Xl4RX_gctO5M=vJ%Laq8gp-VSzFJ^g*w0cWV zZjGbBT-}_UF1NOfX>c|`T*m8qbv1mSJR-$g(r*$FcTvo{@ zNcH>ei>EkK6`8bd2=51=uAmvp+M4yy67BA7kc@Gds3j9%PDl77al&Ry;AWt+?Il zON2}K4N9B}?|L+LgE&T$(F|-D_h?WjYU=48F!?YiQ*tnQxVLd2P8O?kOG9jr8^PPj{w^AMc^y$uIG z+0Wz40yeo+fM`Y|(!K8xC_)W8s4rKt&byxj82CF`Dh{D`mH$In%m267A#VqKBWrk1?(qYkVs)6!P9l`1q{Vs|vwZGu_Z=S^DVSZR6O z>bUrov{i~!!uIl|C)LrI3NW?x^~G4|W*GdFK@ze(ks??O;_R9Xa)`36{87p;ICETI z81Y|iaiMx*0#;E_AbtNiTiN#ni@6BGIH`&i&6AxN;8I>)TwGX3cK6{t31?DIYwJq5 zY5Xa7&A560&jPNf#s|isCDUY{&nj~RVodS0p#x!6yL4*b0|UKRieCiq#v41KkX@L% zHRQ8?G*cA3(RU7M%Libd`!ze-r>IzyJF1_1IHO>2l_v1DTtZ2BfY zb*mGo(dry5L|$kVtjcp}tXfwM->~u+QuTqx*J2dO69lYjc{~`R1$HlRcz>rrl^z++6~C6+S(#X2tE3@uuRI`WCF0 zrPE^k{P2n;_=nmDqi5Io0&IzA%jZ#j&6U^`tncUu@@qA zQBERsM2~3xL?Dok=}0_isytH_w-e}L>=X?#>fHA_JU^rp_yIHD)9?b%tr z01K2rL&{dO45CnYYs+Ml>yWv(esBp!dJ}5<)EUjyHJKHt#;L}I{lzsQlCBa~Jb&b9 zxD`8Wi#cyJz2zs{1QK{O4YV3@5+y`M$&AK1URHyjFOh~I9e#iQ^wQ?Ca9tw#TZL}n zx?V3xZv9nH$(nuYk(a-J{!`AGuM~gRq<>vLkG^c?n;43oB6UsK;Rj39!ohV^M32SA z#bUI$@wsvy{tt?Gln2Mv%3WRHp@3-mvvDWN0rGcU2y=bfya}p_UvmSc3c_TSjRntV zkJ}Y4hPqUr#$XAa;lzS{a&KvAsjA{i)aGISd3kfzwE^pLJDaUfV`bN4&+P7%4s&Pf z%XC828`i`_i}|=}O)c|K@b2wfvE7dXnpsf{@bUbFK+Ar&ZfNKO-N88S1iHfXh4jS# z*r)u^nwm~Z&-;um{;KPur~DfOSpni-I*{#IjR-32N;Mq13myxIGsX1GL}O>^UCH86 zrDRUl7wM?lUOOL;fgquIC43c9k0t41=}L(u$z`m4<36xn;e1q}D(bX(eXIFBc4E!p zhNknT8=rtH!=WbYPI}MpUVyUmb3f3k(W0wmuISROx%08Men;?rWaseI6hrZf%yX%o zF;Gu2N_XwfI#i-9Z`(TmlO8#a)e%i8$?1h}zh5G0$l}z4XLq7vV+SQ3XbZ6t#K*>B3!YuMPM=?tNXNLLwm*vg*A@&? z`m1BnCXA?{zF}Fh1$`Ohn^b#!dr6IKfmQ|vhr6IL>&lnctNJ(=f=?#oSnJEv5S~uJbOGC(7*UyUzPRfcR^q?Pa93E-N0;YvH*NnR2EKp)wo-8jv$bi0cHxK24FL@1 zX#uKP4s9yO@|)T(>@c{y@y4nv(3gCf&uf7~h7ixAhIHzJ_{@lVwPMMI9#VX=fnpndB|=49b`;zAI;ByNu@u};r6^FnRor>-XR-m5!rWyu zS|tu~Xdu|xS=lI%3AHv+KF|GKyogv>NNiCgH=>mdO-y|D74aE6E>}Nn>#a6h{_N^o z7A=a=yL839lkK6@&0gWpP(uhiiEVg#J|?n`;)gKu{D)HqKCyqxc0%ZyY05C`*gI_J zhZLPuMhO(Ermmb$vv_d@4U8j?-PsTYPuj-l#kgqleYC%o3T!KaU+`5EBoO4R%Xzkd zZMEDA((KRo3Hw#;aOxTE@1m3rvowmlKA}G$MB?SIV5BuROVEgq3W~frcUbEqWAXnY z2lhW*&YUsOra$RikQ>Zd&=)*{3R=G(Yl^*QiiJNMdJQ}8dd13`A)ad0^S%D#e**UA zQzUL2*-VrQRo2Y}!;`#G^-VHJeZd;LdH!(FlCj!(KrloBVtwst!LegpyWL?LG&#O% zH&r>El5jvrF^}f!&v2Vz`S1LObmD9#x zs<5Eh8$90${zl%~_Po0$rphtQWPkkdPrYM<<4t1g@RAfmtK8oa$Y8TPTHseS$>puA zjQ=eHX_U`gR=vv1$Pg__>p@j+K|~ll#}?r;lRecX(p8rDktJ8th z9e6covIeZLxv8_=-tuEo(_*1!O{_8sP#@4P!cNGQbKMJaQtfrsE>drjn{c^-!oS@PBx#m)cPn2B(V-n_2- zr`#?~1vxM4yQ5}CF~t`}V=FZCT%Y2j_Vn~5@YqRBBaje~Og-A-;(2fVbyGcu)Ij9M zU!6tkapfI#qdV9#u@i)l3iX-(FFsU?{PGX9{3C@e-xI^8aecjszwxaPMkpn80%NT8nCtM_>-5R z6g6>iQ2`nwkjfDfN#yRrRv@l%v^i=1bD?~n)P&5F21X9pSv}u}HI-%MEAW_W+w+!~ z+d6myzN&;#?hni-e$F(G7$HsgPxr5uLxvYSNRD#Id=|Nha19IFuqjJg5R6Klwt?+~ z4a57ezE!ltp*iAk_%Xhk=K&eW)YTsCv+f3OfO=Oq2>M=YPGF-lwg6fCNUHS)WH2jo z7V|j1k;-5R7DGixCjpI8YqD2w6s_C$RjY|tSu+OX1;5==c&w=Tv#6*@z0=6-BA|`% zCuoX@xR5L!Tt#PWiTuC?HO~Q>=3)-+)<3(`Pwa~;|Bh3xe|Ze%V3%`3Z!Rp0 zQeS}S>S0I)Gxn_LSY!urou!J+H(m|r&lE#%7`!QQFik8l;r`&F)lEueP z+my{^pMF)&cxyn;=2zv+i8k`TDrb+ge^t&hw}(GJ`0z;IST(wgRr}4h=7;WC%V{W5 zvG;RUR)sBxWu|Jj47Tlo;0ZcmhG<=c@ITdFae%#jT59Tngeq9H(Pj7{J67OH=U)vx zSy^ZvuJG7*aD4>UIRh!V2<8<7&-U+dOUK+!9UxcHzm+<%&Kp#%f zpTv-y@xXdsF(93Q7u|$;ZObd(nLn{}8T^L<@NXYB){{=Bo#SzWP*=%owtInr`mQ*gT7a#)SozMw!`AM`pZ3L&zAO` z9_$$H`6Z12nd(M}1)Nfob8KyKvX$6=)GWEEAIf3gIN`9WQeP0nc)l2*r{kE_KF!81 z5g+m{?b|8ZOrq~I_qTz6qNe;%=k>+)OEV&x%BOO+#EvG066z@~g+)dEyQe-)^L~EF zHg_s33Ua{D++jylR21efTFI4fqubDNnXR=>5vB!UeLCHq(P+xB)4=)Z5l+nRJyxCxy+UtyXm)&W$~#A%%z$gj|# zm-~yaBFslo0ggzqTVBiGb2C~aI>MYK)hu)5CthtDy6ZM)?E{6JzYS|HT?CBpO|B+BH|<4Z<#b0&-=Dx~1a2v`6c=8h#k2u*lv;V15&&LY5W+ z(!vL1slh4nda{Mq!f7M*V@{2BY|n2E2)qm|TG@HRQ-K$aoZD)?KSMj-`JV!p4W16D zcAcA*K4H!6B)#a-WHebN!fKo!)6=?~+K05E5}AOXZwh9LuTje76BtbY0WGi?O5lFg{=kxS2|xn^6V{M zdRA4oeZI%fR&G@`9GPxP^iECDVUTGJy5X+6BiD;!@O!9IaZEfhNyA-Oa zx^PtO=E>gdt3d%ZPhhRKo|{9;Qm?xmU!>C19OO^L(gm(+V9WC=RcDuf1@UkXfooxp z6N;Hu=hfR+fs*sm1cc2w=!1lEGG!F$%;IszvPv-@$@wGX>2OoGQg+^DcG#uPZXe6{ zZcVIjeKPNJa*vweHSasDsddfauxravu;(*p@8Bbkh^~s>9*x}oi9g|}6J;6&v5Z_n zrV;U_qEHh-Ja3ClGg3oT6PbaC{5a=56GOqs&9_&>ukrWTRao6Gi0IoDe6f+ck3X_A zeZ@V4<50LMTx=_2)6kU2ljv08uZK!*IL^ZQtfcU(dIgf2SLG(OCnJ6KJ)(}dl-F_p34MWH@o{=Uzi(iwW^zIe@}dk^Zh&PLXI zA8F{fgXS8$N)KmewTXw=C>N3ulx3q!{5W2QjgGh1bXfs*i41h!;e%jC-4ARsgN|e_ zBs${{Z2egMhygRNM+Vah=O`G=dDOH-T1@Uqe~u5%QW>5j<1{~tq8o#yjnkMy0N=G*d2atIRZ4-~5#qV%QB zXsZcla_0krbRF09xt6Wv@ZP4UQ$viB2g?G5PfE|GYDU_G-Ly|1Oeui~4rq6UKbAQy zG#0@U=b@2iEu<+Q(-0*m#A4; ztVX`%dr4XmtHdEYRoTOx) z%pM#k?rPc`H0;d_&a=S!78W43}PwePc97U3@1hhd`w@=ud5(CRI2CumRH-?i3}33@Q&9bHUdD%oGSgTS=gf`a4+Dr`er zG6pOFtj6hHIj*2ZJ@UnONuk_}$E0DMWuRy*HraM&f1v zn4@sRg||YY#`*Aag}G$5@nl<0cJ}xe>VS-awaSJgmKk@lU4zCL-O*FZ!Hw+kr4h*l zJe&-#_k~{XS=jh_q}2)5r~PJ6U&&V@7i?ge#O3hs@)k~J*A*SPHXI}`wnaqi8`MYL zl-q%NMXEdEDY<{i4rBGBYVO%FV%gQNwxYFtsw85Jd?B=sc7kK7Cq@7nf+Vzsn1m#j z{QKUUOuhNuSIkPT*8H`if%L~rl+O*W89f>&Tk(`iRlo8yEe}fmJgdwbu6xV#t5kfo z6jz+@&8**hSNj}!%7!s|7(cS@gEpL`>pR=r0MY3|2EfLm{+kUpr?R0;c z#K1E$2#0)7OKfc>=i1E;$DtHDkmP>v5k&i0kgW9MNaEDfk=GrUUy2;(q}KdOcesmX zU6UG%Bi?BM*PoJX}*}3yBN_DqYk&?{L^3=00ZStwL z`(G*; z5*a6^K;`SmoS2k2qw6gvjX7$_Q@s7ti?y}272$D;q;D1T!Q3v6XBIu)jc~(9y;S=%m_0pcM3OzplSd=o#gR z64$v5!UmoOq!W{dEB~bz$h5y3l$68F|AlmE6TLwj8FO73_cC#zM*fnB+jnBAW>jX2 zwq`N4<;axRH76)$=a+88dMFEt_YB@~FdFf_0P1GOUCNx&y`;fK9q#P}iWeDsat96d z7`%o*^&{ROUU~>#{ag&Q6TR~g1|`7UxF*TJvM)TReYDxUA+K5#UJtEAPEylAP`@TI zU?v12-(A%ZCI3-enw2GC6S<2vuwb3itddob79B|^U9Upm+$$$yY)ooqLlPA1sZlfM zYaz;V>mgV^rY@shP&&)KoeogS5D<>t_dDpxX5P}3J?zvV=C-hYYAm64PwfPgp?FLd z3MvaLc3|~y>vhGeAIy;E6y$;5Q9MJ(Dt)>?fL*Gn8euycJ2dSukaB8+Agq%EXP&NK zZ9uc$LDqnKf3lww`f6s82**4?O}Nk31Xe?s+W4|$rQU5H;>f6>D42C|tmcZ5K`xdS z%RlISnb=7*uG)$jeWsR;5Ce}m7>nW*+o>?76irtIodu>^6&W7n21ww^AM3L}_4ISA zk*r{H@;dq6z=VEQYml<Tlfc9=wUu;eUE1X4VjD?#hCJw4-ze`dyh zuX3tq<*tUk@8`&xapBWJ-TQ!c#DCEa+u^xYSWq0nMqX6swfUy^?QX`3ccATej$}%+ z@>Y~13H*A2BqU3RX+pjbd=mk`p1r)c^^~67?Q58`#8YeHw2UbOqrUlZJ23hFese#b09HSY{x z=XqBNq8SENsm~VE%S~|QcmKuo7Vj{lt)YZ+(w$LKolo2E)$cZI3V$vx?z;#dZ#^S7 zY+;S5CB|&AkYVH@NK?1($$1tBWwZ#PUJv(TP%t&n)>ansK2AqNY0f{(^s0uR;d?~O z46UnSzYkS?#OSNa>UB8k2|tVL*IYxm!KvkxU}mwDg*;@+RDX!-xxXZRz;8sR!G=@- zf1%ClMJQ`btCJgj8YRVNfV4St`8?VgG)tvBn4=zvH2G|FqoGD`eaHG>8$Jd^#Ow2NpnR+HrpFc(g+yjGyJ`?=n|-{Xtqha83&Xd0493ZdY?@ z+X<`EW&OA2>h69w&pM8-@Dxv%6}FKl>Y^gU40F}?zMmE0i>Xdv`DDu=XjP)-Qtfkh z2Tr4hEIn_z0Qp@-1*hG$wI8npqG(zc_dt|!e-St3JPlq`+?kGR6VHwp(PpZ3{0pmb zGVDmbiG2+r^Kby?^{*r496UU9lH261xC<^Wpv9{zwg#m5JrpPIwX-Tz?(%256Kx{k zVqtw)M<_?ip;K>C_PGollr)^d98+&_F{6p=J#l%3L~+FOfnEA#wka%oUH|A!v*9C9 zsZvzb+tD*84GeASLbMb+#Vi(JOb+nA4GCC+Jd~jnMr^I|i+h;0m2eYlM&A@$~_Uj27?!Jla6$6WcUZQU8 zk-u8@cZRt8P#U5T1}~JllK--u>gBSbIMQ^cXj-o1%#e-s_23qx3q?kKd*$_(; z4G;)H+X9Fp?c9Rv$+E}hPVzJ{czr5Q`=t&04N0;`g*tYQDhWpE% zvK=#uh#XJ>2hd(vSVqPW&AJRKDl36zn!#4BEfPY!n-$@5ALuVqLnEWtK{vQ{5Gv!b859OVE%9Oq<63aHkLvjA8tvRnvejxQwst7l=r62+#pNh;nk6BhiP*7 z&PH}Fi`VedJ?=(5GAgEEryY@9PXUcA|8oPh-GO+c#06>+e`AUE}$6A@RoaHM=FNQKrIfqmBNf@N~F7QqjD>_5O4s?z?{t2PUr>#fP^I_%1q#Ii zh^d>(>Z$uO=>v6f_y{ar`H#-2sMB+GF>6k)*l@h|PgJL*qBsQwlY7hn90e%v2);u< zZC7rvPK4nv3uEmlt8?AeZ=4h6=FTQZ6}-Mk6*o9#Tc#{Wm1HkAc=B11Sx-xKNqK8LUaB5Kv?Jqn`F@dV!Bgw9O^RQCc|7GOVhBJ| ztM5BGgMKb|cfRP3`-1KCH6%jLUJx;p2Zgo(@7z@SlFnzk`zbV*w z9^*p#V}IXKfZ{r|@n@(?jy#Yr&@(*V?br{nPd7&L^HeuRGz>12=T4Kst2_Falywgt z@?W2fbqcS965ct&ovZD#RG(j8;3W2$eGV?A?*)~WCl{v&saJou`9577y`QF8dX@72v4?-H$3+d3XeDM#ni1)bnd=@( z*V&ia6>N*a@UyE{D{iKhRPS{3V4l9_#$Q;ZGK~; zFe*Yp`0}v4PpE5jGw|&9eU_--5!+tHIds+;A^;C0w3tzV^3v5l6` znFFb-F$15=M9^?ac{xB?QMp;CKx=S)HkSHoAs93V&jKg3Iqghmt)l3!`tp`R&x3Y6OqdrOf;J@%A_3pc_XW%W4_<#cyuVBaPd_v2k$| zr+0f2dDsjZE*3)BqJoJ^LTE!)oa{`P>Aq!s{2&$DcVX4M)D) zH%J|7_&PkSDwKK+z?#`PI8=s;K;Yndqxeb&@9o~+i|uk)M{pn0;3rb?pO$YiQm(nz)k&)z zwEC$pWIvg;G---(3|2Aq(^CjSdiQRw^Vk;c*7C+>5gW{-5pEX4^6jN#uw84}+U1Te zuzWNZ4o=6rqrt{z46=1ylp3TbMn+8AShaD(F-d|VNoYDq_CMj=(|(Ik=rKQuf!{Ld zR+^?SF2l9WT`N%N#T%-3qBFfQF6$JLU?n*@0ipwUWmmhx0?9GJS+nDWrqe8SMktQRkOi7}q-%VDH1bh6X>ZcwzTjD+XXI>>Lewm*Daz=oa0kzVd!3IU zc=%AzlL{{g3R#BbGq}=N(jk;fH1MWE=jW1f$PIlHZp)ty4>a6)pa&hEe@PJeIsCq> z4T+5_2=@p%e^O{#t|j{Y5Vn6z>as@?(^h{fqh_Qe32ogpEG@E^8}glKt?@ED!qC)d zMAVB{)gkwxJK?8wO*Sg}K?TbANa)7eD#oz_&F_4 zx@&#D5L`b`Rmnx~%J)0%CRe`@4VYLTf^nJCw?Fk~P8XmO$T5T#Dt z%ydQLtLtree;wL(eiER)p;99BgjM%1B>C?!Tc6cn*D7l+`naX6wxnx5V zy{40(KfZG@6-EGI^5U$`R{3=Mm#Ng9aM#M`aOwRV6I68PJkaa)W-nWt?K!#$3T*M} zxdF`*P{fi7IC5AOQ}rii0lzC0TZiY4VL=%WrL_p8dC_^xRZEdUFRQt?q>b?|%-mU!264}O=m7R=|a_pd<+riQJAE$%ap5?|vA(WL}aYgCrK5p4WaN%o~ z1}9j_w&cohY1A||*RTwKh~gg1K!`ChgEgbKwR`OJD%qYTSQ0`mxc$Ya`csvMI^DP5 ztcvg4wU4UZT_aM1l&eK+chx7A2j*Slf}~`aNy-xKd=mF*Sz)qxZ#{*C`S|!aIE<@8 z0Xz+a0Ht}^F)xMDgeU8pqg&2$8we86f)I?a)t9Gzr)YuaqTY?)t9-_D&MvHjUgwCN z8vE3qUp-GXa5(h805_mrssCff=HIt+Jj4`1qg1=#<22zBddjtQ+lR>Qpe#8o z40|RAFkH9LwT|q9XcUFe`XTlyN}1{%BObv|$+i$yDrXSz+`<`*-o?elt-q9l_Q( zHtW8AhmD+8UtzN0S{71`RKN_J-1e%EJ- zZClz!qNyCxFndkU1Aq(P(QRmHVY`MP#&jpi>3XfO^cmOs4?f{X-*2B{WuLUq;y@g0 zE7$pq_!(dE!|jQ2s&*)kFBhYr)YtYt7P;Aa)9*|Tsy>5=)luaj3V78v)W`dL^^r7l z288WH?kVm4Mgiz0yuz1=2`GF`{hhr#ySxOCe>U}RSigK|eL2FII+iN-1+#WfSFe4w z#%KIwG^(mhYbtQUVf?yf5xMU|#^*f|8#u;rOrs@d_XpAqjSTN|jszmpTd?pAUwWS* zbAqUNdTeQ5;~m$Lvmv3e^QZ%e02$;owQ=NyuhXH@y&@(#Q^Gn+a@);gK{gC1nb zPcONIpL}^S@2HFSpm>N(djC?~PoQu$7>mU$2qE!ch%!wY7752 zkC|LimOc2L&G8Ijz^oUM(?Y1n@VVAJZ!m@~9oY@Z4ef_dN`%Kx%q|I=*6Q9I0UUS zecn?)D(J4M`B8sAQ^cFZ0OGLBQag!sE}uXKaIHS?@=Iu}s708wPprF|_iWMPadKtR zCw8173yr+t&GGp@Z7l0^{VbMbB~&#dt_JPhZ^~K3R}V=nEj`w>MF2n8KVjEDL@f~4 zjqe<-S1_)_G+RxtO8B~iboUu*n$oVM|1Q8`-X zDRpat>TL|^(Ql6!mbC87q`iMG_vtBhQ-aM@j<85HAfEO_*a-8@b*F8h>2=lJE_{ky z*%;=9VyAOYM54Mj(q|t{?Q?-K1|H@{=WD%9&A9oh;g5qap1$MCb98^uk#P4aLnMW3 zpy$rLQD`DHQbEUOuYYqzJv$kFh9+NXCy|x=^YkT#xWiNoa)BQ8Mnj@&RZ73)vMs+OE*uG0jh)~c#xY|?Ps5vwOnK~fD|NGy`n3=I1HE@jYpAR zF@{zhd6#dUBn$1FCjM{UGNMUa!&i4I=9djNR~KJUAAi*J;_=rXU~P`>B(OHt z!OhzDMh>6>W~v={hzX^asaFU+2!JVCmP4JMvr9l_ZHKV>jl2oeEmE_>Wu zk^dtHU95Os)}Vp+9Y7*U;p-%*`5?3`HPGIG$n1BOK8lV--SMd@}C zrmY3gbY#Vv9G}TdiW*x7EGj2=EWW;*&*203X~XJ98RT?BOdpi4|BD`pod><$=i@jS=DD1Op2T8IEuMO694TixC}%;qKlJjEN{AFHN>0 zQ&AtnHY`%F#P096Ly8)$_~R1RgTDbgNZaG)5Nuef5U|+c-j!C# zPU$$y26!bsMJ291GcZSF_r#n%-o&vBBZPPrN${0j7xs4(_V^AHi%oO}TVp3OU2zUV z;imr|A1%JY5R%59#=uo;x`TbLsT}r(&;3Gih6w-D5$<@RBn1B{9wS$#%o}Geg+1i^ zBv~~Pm`18)K$A$*Zr<>`vX>h~EQ^mF>MPT8u#Vf$u!iuJHG?_CaG$mYIfPwjw+;sz zdtDux>%pp+b%q8IymJTNF=CI72(;ij=*Daau?8u1bOKEgTW}2&lg!a_FjnkFJ02n< zS0B)LncyC;?K+Beg0RRqb}T6}R4=`+SWNrODnyMg>fUL#DMMJerEj*~x&Rd5yCWbe>~-KI6(9K9J zwNW7gNB7S+t>HPauWAQCL_3HfuGgGq@d#JEo-BWomO(QZ$yWSrGxd?A1`&90?#lHV zcbc+_8hccC2xSRg0!BFI-V@fK$S29OQc+bmmw*Ycf{D~9IJw~%z|2!vfYHLZ#X;sK zDQKl<=2owz5JLs>dw?0^!~{w5T0=a*9xC+t?ovC!oVkJB&#g>yPH&J9%Jck&!2fK> ze7?umR3dwm&AhN|ROB1cZ=0-?5b|0q< zOuLe{e$-ZaJ~NBUK}I%)_W<`ufFgoMdhb;oXji)U`DRrp7rvY0xQ4vgNx8UJ#oPtr z`rJyF!>5`WK4IbF3-oES^(nG-jyX7(I0eD*7X=vm=LNl_ch$^~w!ST({q9|$j8{BD zA$8%87RQ%aQdGkp*1P>C2#jk;lFwlX0cW>D`-hx|;P+(BKb&0cO{UQ-6q0K;Y16w- zm`M+bXd9ZHl}~7S)NRaWV{d=*N}z@;*G10@qraEM+xKq<+{|s@G?$Cxf8wxp()jY@ z)H7W%C}?4?3J!UF5A>2zMBGtgAlyIooW%abUnqoXu}XX+r+;NT{$r=^0N)ECvN{9Z zKT51Z`{T}&T!1Hyj+C#j*k)^ZOt74oo9m*@tj6S5G89VrciWf*++yE}ImGe56}swF zbSdFQf-nY{Y$Tl!f*#Nb^l{gOPF}7Hqk044H0hr>V+!ao2TZ0ADwsw3z9PejV`$BZ z@5C_qudJ~)Oz{6tInLMllKCRz(!2Qed#z;PC#uge-p6RF zb4i>OY8U_MZE?Zdel`@x?>aqVvB zne<#9@x6I-)OWE620*t9X#7@D5abdNuyGvYv7dd{ws->{-xw@ob=*ssW+Z)0;gJ6) zzGDSBZ{Ki|B5_JVUT}kX@C(@GoEb|nM)f&w?rPO%Q3Xr=D`?^l%4ND>M;cxITzq^o zL=qx-E;+SGCe|c>;AT5t@e%|lRko0{`|dQW+@MBeo7)C`sHsV$u-1%ifE%G7aI{8qEiBd1>_641kxUWnX)%V_vtwgQ-A;OE7<_`=5 z!|(qa3bn}eAp1bXk!z`p0tziKUOSRh7rykwXc<%%W#(~){Y`<1Ak_wV3>gk;m0DxoYt z`q-`9643;D*>0*8HhoYSUDBs3G#MmRl&d3afkpDaA$&w_0&v)^MwZe#gil#{m!>F# z)Ityec=g~-O~ptTLZ^=G%{BXNFzS@N;@0nxBBW0=fSAt)SV9zwB&cZPFel_jWOZ3d z68kv#_^ixGY&ibASRvmp_c)`;UfN-X1zOQv3NX_ z(`Wa*zPj>0hK;BlVb3h*Sw~w}wmvb%2si3@3RO-IT0ndIw;d6K9f@GGJ}dM(9yer8 z9uuPdmEM04netER{c;u2J!A+tACzCo_+UjpF`t|Na8k>KL zP>_?0uSV<^07!c^{&#-G(L7boe{N(~3AW(gpmPEkSw}J#)yf$+-72yFPP(Gs)Q$ZA z;Zu@dO*(^6G6pK>KnE1S?jW1NGX@o3S;`NS<#}qTTi?UU-!r-f4dY0~fbk*QB0H%CB(dT`9ka}G=z%mFL0Vv#-BH6swWkDN2{4=4` zrRbiCUiObxXdgStAr;8V%b0GYqR=q^i&N1QPwKv!bmZx>h9CZHo|l^jBq&egmO+C0 zSBC#`$CXXL?n8$O=?otv1C+Wbc<)CWoDIT6)A8`#>Om)N@EViBX=iu$vrL^F+`LIY z5BSi~5Ww=iuT!v(irQ<{Z9_>o=m4WBUfKSp`XXZzF%QrSn>wRa^a^B*L7rXw=dCKP z?enlc)Gzf{SLx?qt{@q1GL}0kWO95Q%oA9i61~Bh9a0b`50j`Ye+~`=%n%$0_gZlK z`b`b5i?g#EsBNn$t2(A{yf|92CXp?>@3C6AT&X|P8xZfOy6vl4E%wnx1P&Gy3(75h zFKo~r4Gs{WuZe}hb8YqtH_7SrO)^?IzEc0S! zE{L2;N=HR?m@pF?58Wy1>?bz zux>*cA(L>~<8yhTdwp31Jl@9-qA;fuRnh*5%@kPs5$(8^pW^#nJs(k#y!9o*XGzoE zBkdxHxeL@&J3Ghr+|kt3{Mn4_{bMNgDyD1e6fhiE{tyg#dj4__xW!<8B7gz1JJ^^W zjJ|f@WwGTw4|Sw|u|3xFNF)O*51h7RpcJ4#V6y-`C1YxzhWF+ZAS!R?6-KbsfeH>F z%V$CLXG-vX8hT+`+vQKm@MO|^ih@N++)buoj-R>7&piOn%=-FsF!p26=;|Ccd)Wb? zwqYGh5ygxA0nNZ}2&8!rxw8 zwnPR65h|%?sxvI>pyXg6!h6Yy4-k}rP+5-v%2^xdx&LK(Vq7AYXQGamwl&j{)#H-h zXQ&C0UTOp=0DkD-CFwqIrJIi-3C!ciuoh(h1Xrz*F=&lm!>sY@E9O9q`^B5SRkHi{ z2~nsCF~Y*>c&9)G-d{5U!bfM~08&1l5&(5O4#2~|T-uHo_S{+C&_KmUy>-GXs1NI- z^*F6!~(6SvF1${>UkA}~F={01=sQ*Yx13*e716PBeDYqe3WE33Na6laG z;k-!O%P)7y$TBfVT4P&295>6n{rtYz+&2i4BP7b|I>_sH_N0vLbEb?P8OfeF#dXeLgh^#?uoFj2d6&K?*Ro6ZMBGzpq1BQ+=q4;Gw zzB@^}w2d#+&iSF^#)IS7ZV9+^qZ*M^#ZDz0C35sqU5#p_W=;m&4W73l@bkhdkt^rM zSk@)26PsYsR80^AV8@k8G<4XO-JA)n>WSbu+12u9%7n$5&S{D?L%F44gI zbor+41#7xyTlJ(Wh@D%+$oNdg;?*?+Q<?w%cV0ZMvTTi^2DoaI~Q5wqHoH=6{ zF~`5<+5iSGOxSSaq2F|w1K0um;<07;!Qp!vO8^GV3S$Cx1wkx8i~^029Shr12c{lrmGFEXMU%b6bYs2O06yk}IN!T&{=o>azt&h9(-6ECO} z120~5Jm{N=Hb(`=@F)`3tDAD?g?pXt1GM|SR-vy*mPM&yk;=iId}_=~d8!b{DlhNt zIK&q!`qf&@#Gu>_3`!fXb73M0U;tCWOTl27%*+QA5vz{X;KQ`Hm0eI?8Z*hzQN|p6 z+HLkYmF;GK`Da86IG=+{i4=4sgP!#kz`kib)JT1VYAY za`0YwK1wpBmab2xA8}TC@>akZojifkd4tEaQ1Ve*aIPvdv7?qHNBrFMd)iV}X2z5# z!Dg3{V{=g_PDPrGl#~=Ok%!;jz-E*U3j!i9pq&m(G|gbx!F{j#ainmhJ;aeZb)s%a zw3`#CV9p>I4R2PCPwAF)*kI%decIijEPsyEBKnj#Uyphj zk%0B76w7QuaWa-Nix|8oi4nr`HF)w<9;B~K#to9e9!^r`*4~H(6WF&o70Ay$p5fz6 z6sdv*c?x>O;u3!=s47hfE-aDFIO8WgaP95%#`Q-9gOEWmeZ1DyK2}2uR2bn>2t48B zghC}>4`)|R$7~NMF%mgyJ+4mC(!p1e=51WY`K9bXozz(QtHvroMzZCIA{kS^1y3gB zK@^swYuq4^<>_n z=`)@&Th&AF-W*gcrx-lw6BfM{Ew%!YTbx?w9sJlAbvGKxv}&p1J-q>TUpa=8uPb47 ziT5HoB#MX$KGJFU#bItPis~ zpdNCqw_m}eT?H7RCjoj>|r4UR;F^|D~=%`*S`WbGnv60BV z^ZJ`DMq%obzPWkSsK8&3(u)55QN?I(`z=g;>+6<9+cl^_mvpuq2#aJR?dYCA+= z;>jKNZ?=otd#xG?-Yb?7(h{sKeE^<$1oWi)}EI(xXR-2=_%lR+*~v#+zx<3|E>9XKO?&B+kQR1 z@CK~78d-i%ouOdo9#YRE!L%Lj5*?$hL;um#!v%yI2NF5&L8qDiC~(Mhh1Slee~QA$$4BAgc`zs_ z22%;93SZLI@o-$*UyoczN}KoaSiUk?GPs=bNk3NwrS&H4Mv-x}5D1LwXRW(q$E(No zRv*57j{SeDZtbh)0C?Hf*6zxle%8JrtpBn#aRWql4J(K-4nDcY6=OgqV=URl%9sH* z&$`_;$@MA+mmU$+>7~njaq3xLjY3af-<<)qmM1uYL+f)x+sCIpbqBw#bb9P z0gA6mtCqhQ){%P%Y$uP*y-e)-KhEdIQtf$`{wQZ^dlw8cczvAbJGYDFvNn6a=CE_Q zMkiK2Kh(8!N;F(i6VIvD5dF%xm_ygJ=7Jmc|0wh~6Z|$fmn5b1N0oiMn_Dh5PV#LJ zkms*|_?PDhIea*@!wDn5Us$W8H{%f_Ts9?YS9#7uDRA1B>YY|8XU_b#Yw^hS=*dww zL;vyrwFnwmL_b#axoFAERB7A%FmI=UQ0aAq@PSA_6DTYQ{Q7*mCmpo9em^{Ei|F?2 zehRC^1|e&+%fqrFhgD&Zi%LFG*N_O>=ni1TR!(^>e7gsTC?*^f^vW7um*OGFJc8%JpKO zK>t*OY1{>fVu6euH#aw!>J<>MGyId!`Rv z${{Iv;?IBequRi7?%NcFV-2b$hjbPJSCI|X|K-9}BAKQ?g0*dKZjF-TJcSPQ6l}nO zHQLqH1wdMX0S)F0A|oSrYCoUf5rn_M;d)+<1afgh>!8wI!pFzwkp(=i@;mO68Bx|! zI&*F^HEz6r^3|gGyAkbBmqnk`kX-21#};9%bS{vd%Yr!tFBV%D769Su9G5#m(Y{8O zx~A8-Z93?K1+p2O@e`nw0%4RLEDRafh%-{t-z0b|QdP`gmiP3}9MI*S(&8DOtBpN% zRw4k9#AobIiaPJC=3oFH`*mSboPs+4$OnzpxCsLQw8s!~(|ZGEGBsWu6<;42Tyv@A z5~)+V=rF{}T%M+0pPnA9rn+zBfpQ9&EXV33IBjfhj? zC|rZdVDuSa+Eu} z(ZcCaoy8`cCorbcfBeA~2D3sq&wUc5cDv3APJCL@v*zGGiPF(BXk#F9$HiBAba!iO zYw3u#WPj7(7(Ed_x$m}cG3>9Frqi}ESeMjQ<9Vg)*)lewVcNwcYfUNm2nq$>Sp2gU z&@J%;Br!cUZl=I^{`_%qA;4c=s5naux#=x07o4^Fn$e8fZHGx~-y79!UL@-Er<)g$ zUGNgEQvr0L>eaf0$)bdJN$23Qbfr13md|)V%P-;X_M&2_g4xP*8Euax=NiqKjXS z6Rv3&Cjf;E;9;|d@j5O^oo>zB?g~K~hv`6XNJq$ny2H1G53q?%`l79}}UO=Sz!C z(ifc%_gxg_upZqfiL7l57bvq@dEt8JOD&#y@$aEH$rS&~xg(vYXE#MVtx{Ndi=aiSS~3Z>uKcyzF;YM5-*$AO1lBL1$6yUNJe)w<{4 zqrKX%5?YQ^d$w!pjNY`$qLL8@Z%026M}F?Af`#c{e>Pj#eA}k#OQ~_&mbEeff1n`% z@L3cQfk8#gMOj%^2Qyu!%^$;@&$ZR={7LBe7{BEn3rwggCxZ4zFb>x`1-Vxh+D;Iu z>NGyaE%rpXS_G|X`2#DVi|LE7Akd>bwiyP6056}rLQ0U;sKZbf$`SWRLxHKW{K?8Y zl`uE=`q};ahC9QHsXfbXsrIp#AEL=75L-_>P>GwZo(4~Brq6pRvrBO5o0bCw3qtX9 z8R6mKU}ho+kY4-<6#kScXfy5K5xw79At5)}R8TfM6f^-R%jd|EwEmh*%-;COog=0&ALZ|odCgd6loIq! z6npM%S$q@Ma^4m~qtB3GRk7QAO0P)2fpyBsX-1`Yf!D=Lxu@}O4~8H>FW=G82qVJC zFN=2!s{&IsA3tucr@fhe*l}3nfX#-f{-=n!+O%d5!GN+T=XF%(4j25fLf}{G5U#B+ zA4}i3Duub7$qu4O&fi7~xaNt0bQD%@H)b+XM|5X6& z3{vKz%*i=Z>3gsLda<~8(dWy47+byAC*p%3+yv5Xs80AdEgIy0#GnW3G;0fN3 z8#oW6M9^`F{8iOBWqH35w2E7UOGJ^mbfS@j&e)Bgk$(Q-69V~n_100%=%^8S$&oem z25W$XNW45aUfiJZ!m^6)A*R`_KggS!u7PwhO?i}Vh~0-Pg7JD8t`#kP%(MAEuY#-3 zv)r#VC`Ue+S6|pSNIA0H@y#TQqJgPLO@NM-GaX%`-e0-S&Tc{srn!4JwnNbnvb%=| zfIFwcbEwvZI+>PE);Pe+3_%jJE}?m*SFR$S`nPnN!OXAX0J|VMrppfx(F;1urx9^n zcX{1+1=Y2uM)Ajoh~N+V98V44dz%KoYJiJ<^0!+cNvY0aXjLshCXY9!3rp{Si#$@w z#K|e9t7xJMJvz2o)wCJFQCEFxrsL-vp$q&ii|9iXDs5?Hs=_*=NYL@@siA2Km=ZgU zCIsq%iAiN$cPX<;513)sS)>|G;7A;Uv(>ptqRkp9igA1U&cHpfaP!i*6RZ4uuj>`u zbfK~Fdp#<|-86sD%lXE04hd|*CfQUajD3!1uP(k@XjGN&WJ^e#<;4laF8hRLkv1T* z!i36>HVtmAntK7`@P!$Mf8I)4d5Hd~*U|&Z7k?Q7gGS!m>ZM4p4gllc{)4jFuwwbO z%nqOCyV&@q#gnc4zexAu()?V8(sKTy065`=eI<(HHZ~6uI`Ja=R_~z9gK^NKu6&Ol zKV4}R=Ty^rbnqv^FB*-K3PAN!bL-qswp$ul4BW^Mv=-z5(ymw~)b9e7P`|Y>e z&*PovHgDHkb?Vfq6Mu)rbGlGRPcI=kd1iDpON}ZoyW{B)>J zim{!Kde=yEkqanfF6L+!9f2*`pTVFH{dc00wI}C5XAWSk9c<2U$$cH7amH*C`ritD z40S?X?C2&K>t5RtCFyS1BV@H5spD4q2jU9cP+TA)epwPZIkn*^e5E>+GqSLAie*=U z={f+WCi>Rkiwc(**{gm?Ze?X79XaY$R}B7@$QAM5dJf zK~B>gpVoN?HK83;D3=dt>`rfGha?QBGxyq~2YMN*yj`4}xXD8i2n2}E#U#g7i|<-s zPSmUIX?}5A5=ZM|rWT2n*SKyF0EJva{4g|jrs@;@NcV2A$U%8e_Kx+4RHkJrj%Z~J zB7GOAi41j*9fb>g9sGuYS7a*nJQ965R$}P@f6QrqZCio8T3iI_<*(G^R6}0|A`QY& zM!IK=oHO||AxhyRq$}6w`XkvJKp48a^sblUKkdrk4_Dvyu3t!|c&=UXxPpg7Ln%<@ zqAA_G8=ufJ8xq^!OoH$~>%({@B>X`N-Thx3)<*9wbYjjL(CSlMfvzHriTdyTQ8Ep= zKJ)hI)!xEsy#)P78R??lFytbt!o36cO|YeqwWtw4WBVq1ddO0CsPjb8Q7L&(Z(Isa zt?tLuz-P&4`8(lN8qm6}Y2Z1lFd){UJ82QdJ9zQ(Fq#4Q;7k1v*W4-s8UNvEbqn%T zEPj#IiXU-JkW=7?h`rs1fWt7L5LTT>9|o{svY zWmvmc*Kqp&z!ogvC&<;F<2lGx&cr(Us8s^(9y?v_ff^6Rc;uh11@P>1)fB||Vd9&l>jzj{PeqvNsQNL)MHZM5F-Jh=OTA5l63MP)U`L_JE!i6LXRfQ^rDq8V_t+qwX{qnJz&3X|b zp|ODh9&zykpVOJsUW_>Xqbz;^$>!^~iP^FD8)5jUF8ajE3M56i&eZ$Lyr%sv`~&wG zn7->1Tm3k%?Y8mefYlzGp{wl?5m$$=0O%kA&CO+;!SpvCb&!^J(Nq6^76mtXtb5QO6i5h${>hh(F5wg#NV`3^4 zj>S&;aGuV>&-&|6=aNP9Pb2E&n6CF9_>}`RA=A+lj#%-Bo9_4z@F~y7I`a6Y^ENn@ z#`wKvP|V8&pZBWTgk$^4?fMo(W-S0Ge=uVTZzb~7Y}bz zBVuOy97bLag%dQZxk!GPz?hES`2#-aJ|8IIJOb^r$Cfl90e3>>md)7#J_y$r=b=Z? z1=FCJy7Z`o$4Nw2!m{~S|AhhMXeRanzt>k~tYJuaFOXy4<-c;%B`xyv!hW1ACfM{{ zFbH0pzdjXaMiHg9&vA~402ZQnwazdgap8qEo1qBL^+$^!>lH2!m5XCeD|s~FQg{rI zeJBZD03?&e#YKQcR~J!V7a_izANLd5XN6rYaR`O?alFQiNhqd=6kAl$Re2%q!pn2G zGzdf>kL4OkcdIj;pDjXiT!&ZdgpVC4H*+q+QmP6pQPnh*0E{N}wlHV_mUNDb6JyE> z*XMY5Ho)24Orv&0kq654&MEHUWo9mRUfv(kt~I8>*X#Cgh@C{6Hr%&OG9z2yexfT;H+210Q>`f4OmuVZUS23x^Q%aO&qEJzZ~MtZ!*^%2Qos9)R|= z53XsirwZ3!GUrmQ4|!#k*{oK6Q5FCT4g5R?r^q`YOm=4l@ES@okVthO20&syWCxjM z>751FCDcWO-xx0x`h%)lT#$c$zTnehP&gh!&Px1TlcOT<U4IiV?it*c9 zd@=N*rGfwgF{=EHIYKGS1#Bt)u`9t=Oj`t3WXh2yXDKfoC8fIUkKHrO`jn>w?MUJ* z%5Vx_<@V$k0Hf;h`0WF_x9qx=t<~(0He%9aPIjukA&2?hCQGNjA)mCu%EShENJ=YW zOUDoLm~{tME9yABbxMXxm<>5ri(KPu9I)q+FNF$yU51Z%t-3V{Jb?X))DsM8=2rnsX-PnagAVukZu3j7Z>o-Y| z%0E_~<<>rpAEKpS{QBtg7^*!Qw`hCA&cb3b-oD;*w_AXim{@?1FaKmHLKX&__Sx<3 z=~1fsLf8l%eQKmBM)rtd3{NuU!f5yF6Y)7an~_rFLVQiJZ>w)|v2YoD3wjOGI6bU? zJ=^GOHrx=0pMH8{w0N%lRx-$92Wu+(rQK8wmINAJ(}}pXr6)m@$@y@|v12NORVeP_ zOB6hLOj4D}^+L1Cf2vGHf^ zjMR$}a@-K_w4iw7DPHlz_-y=e7v*N|d{=|Y(xSF5tMBgmM+rLXmy3cuM3VqwEO;|W zd7%@jIM#b?{UwG0lOW3kas~W^mlg~wS5A9%YxhX#N+!=|Vd9w7UZGQ%`Uugx{_#s! z6#v0eS~$I+!+n^6_j)dg0dJ2 zlEM)Y9v;#VmI~ew4daF1_@jHZiHq)orLzt zF<<9KI>nEhkDm$L@af+>{{W@+_-HQN{`Th}2EU{CLG;&2fd8ZO>*&Bh6qV=PU?s+B zneD3*ydg`x0Vjt=+PbN^K8ODShKA1!PEn8J@Tn{5!Tn$^#+Fo3p8X<=URxzx%z-yP-Y;&`N2ZC!k@SGjg&pO*886Am{iewUNeEMd?4)dO>OC_+mV z)TH{R1+%!Etfyb|hVIP5WHEu|a=OFIS#|aHyd2`NW~C%UZAUL2uwz$n??P&xpl35( z^haFJOoBxCNEGL38t8d+GLroU!4mBj72Pww?CUV`CAjI$45(`94h#+gU+@hn$0|K7 zeb=FL45f++A|fJ|>mm79@<7Xa0Nga0d^VQ6K2h1b?848>3o?4a|9+g>2;4?u_M!v~ zJr>Bimz{(X2^V{9&5U9n{$xr-hNBC=r<9B=g-qKftH&>EZm--QOYTOyll#OreS4Rf zIOKX(Gjq049Y_|{Qg!su>EKixd6!5o_w`e%qVG@4pmB<3PRjK0eS1UoEut=M98K3O zA#ToFnBy1Q-z<{7lDEHAv>I@WCmb2tm#}2yf88r!o0#_fLY9?1uymVSat!~SJG)M42IxbwKDjhf^wdP*DIi5`w>8l>mM3ohJwPl`uchRY`;+LfPWxj zU%Q(qfG5R7gZL7p{HiTGSu{FH$Z#WTSo-JszJB#s-`Mi@j<4fvCDVVuV6iK-k2mu| zCYaNI{hR;cUIzfiviDrnP=1p&}wz=EES+$iEn=)U3gaygoZds?suQ|%yeAeL-{BwD(>&^ zqv$fex2IuTY>c3h_90i3+oUW8wo&R5$H}Rz89^FM+;VtE_InQMHY|ws;>uNPAN{NK zbgmQ}A%o=FUhM~c77e9N^m!2x5vJUzttR3^c8t7|NgX4KVjt&0EI+c^(q;{%ZEnNK zliVhX?kq;6n?GB6qZ@XSGGJ;AQ;4zjIqGkyz3a8oQ;2Rm+UmieA6OfYUl(IIawy8? z>l>!CVbi1AR`FKHa0KZ}e)0*;$=UYs@$wq?cyDQAvjz}}kG>K6TXyi$lz4X$hv3S}c}6!YxW& z#xZe($7a4xq)C#q7Zjm+5Hx9Ai*u#XF3$cW%d*yDK<^#Kh_-C? zOn%b#v%?uobfM2e-+RdxCMtkd4t5c>KrY1;(SFuYnB=h*+t8lt1dGc)y-_9O7hE@|_rkoMC+C6XCq*OC=cZ4h|` zS3fiYz$y1z-eX2s462l}4~oQU3JD9uK5omhV9Yj5N@C-Xl1i1d6C*H!xD7aTo>gb8 z#2xpQ<0BrYU^cXHq&wGo(bGW2e4eRI+pUh5`mj;rE+jS$KWxt)56x^LMNYz}@;fKM zJpkMtw{LL2)SwghIntdu)@+X`tEli>U^4_BuE=;JJ z7kS9(uhMBgr~w@u<||!Lmyi78PX3(7n-fRBGD;(ao;#H^QvA^3`y0RlXsFnJH9?@1 zyXwUY&P7^FpCRdh;M@GwT?KDi(AoWltp^J;bVfoP*%9ry%qaYUnZV*0FJN7%_fAX3 zQg!iyZXQv-sGi;24wdDq0eYh^$M5dl)3Hr42{JC)+Y5&$A|fJU^vZ&?)1?;5?ZuNG za|q~lf)_eEIx#c+^;_%qiRjKuL;BZw&L)DRV{?1Qdg%Kju9Y#ga(8}S2ftZSpYgq? zk};{*AEHAAg=V+EkG{2cat3vpZzGutXUVv?zK1r+Xtkt5%7wHwYO_bS6?iWF=)1}B z@B&~p7d{J{SDY;|_CN_Mu@rGBm(bWG7|io=w}dxEj2cQDj^{{lqnnIDh8{D%39WTP zW+NLTY53XB`qRpnnhP#f*6tf*5nDY;;|Cj&&&F>5JQwehr0q?#MCTi8(tm9@A#xo(%0yirw0PVPP%kUBk+mkBB(z+OI%^Cc}Amc}+H z@?1%tr>ad6+R)OD^?+`}2cRY1!gZ~_!0onGyAMB6>e~<7M(dcUJo?3ldB` zmfw)4Lhy_P;v#t}PDy8dLWkZXZ5h)t39cw~<=KGVhft?6v)E|b{y-dj*axE)*`{jA zOoB_}Zgx|$tUnk2_7;M#TmLbf0V#**wP;xc9hJDB@jN!6L9N?oXx)9y_eyMF;GLtF zKb_Br4^(~nh5z!KnDf`>MDkVmTu1;r!5d}kvN!0IJKe`;mkW}Q3(GvhE<9zFOu~41NV*f^d(mzz7B-t#t`@QfAol%|Jbxg$(;Zu8 zjzb^MRG--6(S6k+J2s+*$Y*egFT;83Qks=^(lV`tz2yachE|aytFFR{-yA-cm%9Ql zNZO*_+||^;ZTN)s&nsEL{IBay=e{bHkpGL| zLI`w5B3IqsSF2X3g;C~_iYdP*H-t^4jDF#T)bu+Endo}qdlWaX^eLExB{_Nd1|q_f zI&}BNpmS%*Us=B1ofhYwhOwR&AQavg>s869{Z!MR^2WVT(7c!g!6}MAb&`3dIciMY znelpZb@I!NP@K7lRkunCUN2F4IDE5qx97T&$9!9a0!!&JWzJB+uoUaeIZw!olU3k) zd9-KhyylJZ$+>7+GOvyd1((=5JE!}Hr57A-Ma%u_o@_IW!oJ6Q6ZQ>LAbDbFXn$GR zzxugzPghs%(f3e*Do+#?YaIUyc#0()u9{JS?KebumRqEJmR|T|dipy4Ym*!!MWSL> zm%q~;tUcscVIeg_sAH3|TCFP};nh)eDwe9pDRB4hU4DKRC=mU*oX=Il#>U1#vUV)U zuHX9B)B;76gj~?@Y>~|w?Yr+`(ffI@=0}iUX*($aa&l}g`zqWMuWRK|mcqYY*ZuQ# zhyuNjx>dZFbh6*73dCznOw&z|F~-x2MGM@$=RCD>0B-nk>%wN^dmz09;J<^!gGc!< zia29C`2+<8#l+6QU3Iv(M=R_i3wz1Pl9#cReHDMaT0JVwHmKlrGL5Qwdv^jtfu*JQ z5>0&iD;^_F!-r^LxOzz z(@&rh0AKR`o8Cp|D*0Mr)6%h*FY&;9CC)#VX9} zLE6=%Np+eYX$z^n`@VChZT62sRh}!n8er&3U?2@jv*Iz*0dvneo^f>c5_~eBs{RDY zdl@V7F0Xl37Gzgv_{~0J;3k;0@ZWmdA4x52?&^}hT8%yn%plJk(W>!oXsQ~fMaSjb zUN+?yPk!`;kNH+L=XZw_9Ja$N=H!FB7JQ0?c+Y}}=(t%LN4v;?r`|G-oZ!XE$_lV* z2bTBR+S(dztRCo_E!v1?2Im(zae=Ef1kGyQ#DKV0h)L^b2)W+XO7|YS%0MP zey^sCRw}p?=zL{hOoPsS>xO3UFOu~0DavJ*5cW?#ROmK$QPe$P9MUCa9mTX1>5&Y= zKBT8F>~wOua~ebo_~Vk1G|bHO^#Mq49%NU2iYXtm-h7kfGOYGZJN>Y0kF%c&+q(F)D9Tts-6q$ttggr ziTf!LpDyl4Uzx7No=6MnY_b?iERC6Or(&o-I&1fMLiAG{Tt=CSqDK#!gy_v3D=Wx% ztJM6murESU7-|sYll8dz3<|Ar2X~|Q;f|PM)zeqOBdfM{c1j>VsFBmjWssSm%l}5c z{lk!r*8&xpBU99NL{xQ-hBMv{|5&UF@`$c?LV@@e!V}Dq zDT+mB^^PdSMh4sq{8AJqot4^jI?GQL^P%7Em$j#}Ox2L1dfZOaAKeOk@i;17P*%J0 zQ8Id*Bj~de(0+JW&?;)u?hss6)ipIz^D2lz&Kgdxa0{~Pf)DD*B|WDfJ}mTbXNoD- zgUYhdwvPDk&A&$JurLoL1};cUDx6cy2Sxm7>RQjqTr$=mkApg5z&Fcx;ck1iu5EAAg3cEBctTGcQHt7 z15h6kp#>?ObB~`DWXrQgB*iQBB=oX;kIM-TF1bb;v8Q*Zljn_`qvwa}za4Yg7iM2! z?9VPW+Lfid1`z626t?xH*~iBh8@zbkF=zmZ zOuQbk{Hap@$clTJU?_Vx!m20W@$bB>etrZ?S-nrAI!TQn6=|jj4v9;`K%F&B4^5;a zA>oKuT0N4jaa2<;w>ndwb>x3M$%ONU=_N~ z5!)Y~$3CsjbrtDyYz?OME6YB!28&;7a~RMJv9?oIRbDYi_rtF)C26oXkP(U?~jGCn|z0HB(kH(ZJ29iG@PzjvEHnXdELvU z5N5}X$DJ+Y@;}DO_@eRzGp}}jP45~=jUc-Dl>>$}zG|x$&1;3QeiKWLG`YKxNORaP zKqEN>NbO)Abs3QQZz9b^`bzYHGA9sf6YXXQ#r`j&I~(Z5Yqo9;5$^uWikPASc9&d}-$%A97=W-=Fs=Yf6yZ1S9JQeA3MdZK$=)Tml z7g8O`;m8y@v`G@}hY_s$HKTw*mSs`7j&UgQLg#-N;9ND~X-KH()q=26~ggse%!OIl(WE+%5tM`s(S-=AKe=q&U5^{4eF zoA$WP^hFAGdevAJmr46vziu_xyx~$kl@zBUl*$?@pmB?+RXUt?;5hK7bM04z`OPS@ z&$iebwxZeHm#nU+ng6a}i8@tO$eMG1ku_wXZAP5dRc6 zTOc-Ny%~k!tmK-_a<@n=rHOl#=Cg|b)9m^~#{$M+MY^S?j0*q2GkZR|H6Ab{LH%ah z??i(~4}Y86MTXVNm|9uo)YMF@8!S9@__4R-e|m_K;f`Px|BxuAk3mbI8sis)$qhcQ+McpLlT(Ge8XFrAoncNesH2yh$xtUZkG1%4^jVGsH60yUL}l#NBPYSc zz?bHg5-MHD&g#DqI!7pqOzjM7%+QoNUSMx7yuIXbM57}bX!KyWkOBq+DA-!BKOFZT z`g^%~vosXVp&v;cWN|`=mYz! z$EtnHZur!?di1>=47fNKEEK15+#_a=hKeK8Ll9g&=R_I#t2(;qaEYVBjwGpi*MC(B7?Dv&xRn%KmugOu+DPqtmRsrmYVD;4Q6& ziF4DA1odG!NR_VJ6xnI^o}SRD=}5T~J3?V;<5+OO8D-P`H|EjAo(Wxku7D9e)joC7 zogqHKgxpg`4DdVEAH6>uJ`x26JJ3qmHlZ^&Mw$5$u z@dh>cV7f=vt#mz81{MxR1Zrwu7*?D8jhS?Ev)WrBMj}=xTNbp_DH)w(4QI-lt!m_B zFSMr$IwuX1o7P>uYAJN+i0rebY4Y@|{1GE(3>(!O6=x#59On%O*dt`i%FBf)xGL$x zZ`~-M6Bg3zdPwMrP~1;m!8BEGePw+C+7Z~;bgjD?`tA<_Okr59-3X#CkY7+`oZ5|-x!%NU$V4QY zcw|rF`lneb$q!*Ct-$e-6gr3MBlGr(TS4zE8y1L$aNTgL78`q!wN!1h{crZe-=R>UU-1GW<~MotEZ`~ zfi1(2^u@2@%<;4Y!Jv*SgV_M9U2y;p53eUdsI(>ZY5Khl25iGFV`FGkJIJy%cX8p3 z?=}cFg_g7wbB5mZJYK_ITuZVK|e z&ha)5K*#|k^52Qo)+pj_Ih*qkMYl1A`+y`JpS^wn3v3BuEtvzj5qhr*tgW~?b!+}| zyxTs&feCBm&6A-$SVF~Ie*Bcc6Gc-A5X)cyhAzqX;4ujmEv?VVdZl7*sLiB=ALxSc zb=id*>2tc>if}WbghQkJXp{zj<^s^X{xU2sY3?Rp;q$kXnX3Z9Y2?pj?JsSDMkX07 z9t+ThFmnr$Was9RMgY^A8TpdoMdK#>_{>epGA0*2D42YtSCB}ZF81m^sbh%q9!gp3}L zvq%rQbSw~mu;@LZanCDWZ2Zz?dr~9Cbb|oY#l+iHFYhf6w1i`$dBEQCad8>^c*(A1 z=cEnE4%Wc6noq!g~f1IDk9QufY%oyw%w+2FHVFv{dHmkA@ll%r28& zqM#F*$U8cE8{yH|(4L&Jvd-0pK|6KA>~Ba*W#`e&LvPU}9DE`Gfo;0;S%D1O8UkAc z5>NB)UI42<#sko1%o3&r=SwWH`s)t1=eLs1%702AhwwAf#Dkkn55u|B93{t@{3wl< zVER`bcL@CW^O;Gf0R!}}bGp$O{ZxnpViS39+1Sg=XMKv`rRo%L5t<=7C^O9T^3Cdm znE2rBQWjFC!(Z8M|M`r~lLLthiN9-CQ&5vS%VxnDX3X8f2Rx-8eQuUlQ~)Ful#h7f z2pbd}ypS~=Qj_@+;;xn-9TY>=KmBIsyirLB&e5n;KN|s2STDF#7eFDkzP>(inVY@J za)1nd5yr`4HT(O5r2s=6sLsE7ippjOrss!*rmQd?3ZWO$Qu#pb`90Q1@YRx>`#ez5 zC>}k3!wO)@m8;`xV=$x!oAtpG-Cnxzt z7aE1Z9q1r<9e78iK4fIHEW5-k6I6rfse_>2DFH!r#lH`3g&@MZi@GL%;5LW?!7hYd z74+K68oCM54!UxVy#U!Qt>*K(`-7t1kKwT+{hHBmD zGVBf0tzGa4Z_|Eo)1T0Do%s@*!{3O(Aqj}#rrrgJL892gVKAVj{tMnSPj(jl*`zqyf@ao!A>b{ zwqY9ClEOYW&JM-8%4s9X>i3-JG>Rm|M5v&(kGOUFt*bim6P9HgwOmMf|>nSqaAjaZs4>j1SUqkC0sE29$(NI=csQilNemUZA>K8j3mSp*VkW3H5 zZ_*6Od8G8d_@5svglgUp73aq~j<~r&Muy_)kL~Sk;N#O~uV}gcbmGb1*u}}|F&zYw z62{A{)!)lEJjR%ja68O+5t%CH*uFUPyH^*5l@2kZ!MeUorP z;qZxgpCLqGAXaIbR@$rejNE--=`XZH8lGX#OmZOp)Lk3+OK2*B@~y>Ltr^#J37_B@8<- zHMO$yxa(&JQ$)Ib)61@?t0}N{*I%@Yl`tw3tP{8Yc#lUUJ$D7U=>HL+sq*We8}3J z&u&_xfITPZ({2$f9k66^e&g)~1c0&WnM%4Z+im_M2ww`Gcg1|}FZ9CpTl}v-Dn^!; zZ7bLQub)o|dlwBh{r}dd@%s5K4jCnHF#IomsBx2={l9qZ|LaHC0se!j>wg0ax4U)g)jZ>y(v0(eJK9+-5>v#71urh+kkO`2BS#)&yPSVNPo!xhd=$l z@U>?D%#8j2IgtY%IcfurY^2_ZDL9z%6?7Q8ITxO-jzfysB{B2r8qWgL>IeeDGbe)a zTJ`q`LyvJcF8eOU*R}gwie9XCsw&`tg@qDfAY5?A#lJF$I|XH}>~vH8vMlfR+pJk` z8X(DS!ptFXpxFCPKZRTCXbzOPSJt2bBAuO;E2X~;dbTy6=qeC}dXt*?5J*wLf5@}~ zBfKR9IbbQ&LM1uH26yZ(`Xei1I9QUQ=8Db!CozKb+^{YD6utPiZ|`*0nfop`Q*STRD-dN^0H(>u3u>R`S z`D;%}jTE^ovmIo@>C3T$75$v_*W8sC|61mdY-hd)zF?&oh=Kt^gX{}PPXAYKS)D(x zQ*Yxo=90EHU?TiwK!euePCM-u-n3V2aLaazMf_#Z9s3Vzw%L(5l4kK9kmgVp}-V^K(4(9+s>K} z{J(}^)AL?mDSCfy*)$$B`I4s4p6~B+71r@>cOH|*u?d#PW1g+QtU?45HXuWmPpFu% zjJ2F)3Q2hguDbhtYR+utfj#$*r~nPH9veUuQ>`4$KkYp5diu0UTkA3VmXgBK!nd?7_X%c^H|XB9im-;W2U*TpW{Gl&W^ZPjP9H?(;WkV3om z8ZBOnDnOktw5az^!hKCUQN!74hUisy;p(!hR6dT zs+&;G*xa@=gcu?XOuZs$Vg>wX0uHiAfvT41j&o{pmxG<1Qig2S)&VR8 z7kd(zx#b^+x0a@~%_Qks$o6kmWYdSszzV8Ya$4!V^JX(O8o-+f0fIe5CDrGGPfoB< zz7liu?Ep|&Q-y;)dSpN(q`+F{dt0t88B==Gi+U7=-2?O1qdxxwXl@Pz(LNR9GpYTT z*I%EyJQi_VyKQd@W|#}a8RYGE5Y#XESfct+-{0Sa!2|(4lM2%ftg?}!TWa#>W{4+`{W<`n4jJ3YY}fjcRd655<7^}KyJTK{X$JD!gb@` zrSZ{Q4cFBkoBV5*Hvq6mbo0{#4X3kPjo6=IrQ+{D%RN7T&tJtDUh%MeJYg{NdKjhzv11cVw`QnQulKc_`9^*M&9-3yyJUwr6s9FwY=n=oX4SAHrZErmcN0#8azFlZqYuwSdG5B!^(SEHd=RLFjNUc5Ib(G9Hgqvm`_ib< z+7sGldD(xDd)p9UQPrFmXnOa6_cb?51h}L}<*{sYm4|$1ADchLs=9W~5<95oLqIp( zaB%mjq#_Ce%TE9FP0?>72HyGXF(s1i#^KxtU9sIDS%Xu?2JAvC)~_~7X+q9s!pBG= zm(@%Z*t7YBwo_Ca%pw%aV*EeiR%ZaZ#ILq%+9v*UqfH}qt$U;3r^B;Y)v2+9#LmiV z$xz&!p7EE`hWa1pORKCOq8)riMd~(HX6hw<8;()R$!8lF z3Iwbx6zH)=WLS4t-rNd}{c+c#IHn-CfII^DHK%IaUNn6>sHRSy*qg@Uiu!a_%d&iUx2bv)m@KAsd^U{tMAsd9N=* za%6i!#oAG6!^dy0Yih*}CH1Fz3O0WHFpuqIh9v*7mM1!TKbl7HIe78aYsZjWsy-bSv(Yxulb=Y(j z;g@WW*+@DQ6BFv+6r?N+{cRV2 z+IQXC;~uEJd3$*iVjqDcZqPU|+Cqhr$>jx|y-9fpOgpTB5@TqV-(+1zv$D$R+Ju#mB~eq=H?77|iQ zI%i%-xn?)DP_ts_G2snk;t_r0gSyk6Aumn?#7N-P$qIakM#h#ThTmby7bU?OGCIk4 zW|jB$R+hk|;|Sd$#z0YD7B;S{bFjH_Pu`HEJ$ps(_~8Yr9Z#Y%-dAl5r{kXDHGz-X zi3-u~T2@deCole_b}Ga^I$*^0H<+4|>NFKq(z_(`2pBs$ltJw5lt&q4i6GEYdam79 zi5Xl+1{ZYIZ~!96?g)(-uwIHtfu`12VWH8Gk53#b>*K`Ee7$!4a8B9IW>5}nDDhct zkgi)|URg!~`eCs>8 zR&B2omVAjw%|`WdE~+(8h>DD7k@J-a=C(VmPe)s*@OHazCxMAub4u{iAnJXsvdm;o z7(`DS=)klr8cx1!wUajcM0k%Z@QqAzLa)|%P1OfP%7p|+29r6n0}|Z>f^_s?uzg^o zlZXvjHbLQVa`9WwRKGLh`x*(cLxE)dllz4;m~Y{}J7SgfhOkM_k)#b!WJ4D_?m1?n za~V|&brNNPav!bRd-Wu+^ABUTj<(?2TZ+AU#z6b@{`hwvRE*(_(Y|l*sw=Zk_!Mn z)A#q5md4sc4kwS%Yz6gh>lDwxfXBjz!g_WlTczxsK=foeO#p2e(wLL5pIVT!2r&xpfF%*h=4|DRU^4tYaxl+b1O|?%ClG3zSb&?)^2qg1@>vuW2%y$a$%;F#rJV#IG%N6oVi>H~BPs5(Hb zVUHBL4%}(0Co`7dzCE{2j3(4?DTT@k^EcGSh?Nv(@(GBLA;}}K)W!b$6gY=M7I3bv zY*^Y(^;OOX-8q@0kS10%=cmoF0CnViCp(Mn6pgPk7PKDf=$Z)n_|AOW&dydhp)k18 zgQbm%M>Z&TT4WpArINX<9MEe)E6um=S_R|Gd;Y;H?uHhGMp#Ezmzt(m zNg*MTQXpsMxZ1(QSG{qQqCI&Z8ryOG52e3oec5?YiYZ=Cdq49+LqlnPX?iwuw8Gkk zWrGUTZjUX-w@2avXCPyu-o9vD{jjKZ?#{=lSXX!Vva+x+uxkCBae>&BsYO4-^c(0 zyS<^JzZNmc{Nq!OxwKN)DUepI*zdt7ivXw@M))gVo{-43{>Uf#@SXC{BL&7OY12KF zVw8YD?gJ&Kk$$gg7aF-hH%k_lK#2nSAN)1YMAq&jx`TrYxaS;iGTxH*1J6dEM|@PS z-y>1w&MtQ!;1!E1l}t=%zY~{HSQj2~m5~R$+YW2gy^~B7U9Vp&ij=GI4dinhcw5!A zwz^w@^S$8kqaJ-_=enCGs6We1wGUyH0k6RhbBiSK{wnzVs86g5Sdd@UlZlyP-U!@5vT&O%-|lXk>w$}W5Y98fX4*j|%u zTxg~CDm6y8uq{Vb0kk7;8p77{jF%Z1$1QvvvkSH39=>*|;)gtQ;jg!b?xgc1t|vrW zySi6;RCiJqb7wNo*u5dWd1iXQXSrV>CUqx&H`P8VCno|m)}}ZA;<81xbx=dWd(q;H zjr_wiGyZ!^s<~+pc5IA@|GiQId4!9NIQ#Wv+W1#BcGj9@ZF@d0_37E^H}x9&N%=dh zp@kuwvF(gaJDE*i4PRz){Q|(>_QDr1lw(J<2u<{8oLJcwYGWhtf7vD}Ep|(E_G$bP96A{vL zA2C-NQgM#Nr-A=P@*EoGnmQ2!zDGDUaayDFqM+eu?JlGpFZeQ+V662IkFcvPpx zaNTijTJU=K8?sG}-h!sh++yy*G(N&UAO9txbk4rVg&FX&R8iv(&o)@A}KbO1A%OFRRl z$a4df&1S)SYU|#o?d&_~M(MdaMAJdvOC%Ixw12&pm7gtCTbg#0@>+!dw!CW8qr$zY zRSgp4qm0*ybcV7_C1ZIaXfLgKF3pXq)bCS}!vX+Ti4^1*(|F>D)giFH)6rMlt{KnM zrm3s5YS)(EOxuBlP8SgFJMhON0Qk4I&GfqPH6r=DMJSblepGvLKaBqtw7la5wJQ&q zeIQ~Q*pQG4toXalE6Uk4w=<{3d0Lz)Iqo%WwQ<>HW7-w7&Jf&e{LMj-^2+eXz30{6 zB4B)+`mpoH7!w1NTXlejY{#d**BgK$@0g4XELJ*x_!?r;|dzvXA>7P6_bw zl>=M!WMZ#Dtn%B%BQ(E03}m0e=244DXDbv9mR^luD!Je3j3AA8Aeg`Dk2wKW1*lS} zszUMD3n?=TINYgX&%zwCl_8NxfNqJ9-mE*EHsyX?ZwaJQjI$2#iyMi^v7Gl}ftlLb zfi(8Bc1~N#AWS0tL0dbikY#|-&cOMfz+TUdV#9(l_Lcp%{7l|Vd*%_wktBmpEnlI4w!;o46Uf_`TBwUPNSUBf)$K>QB9fy~ptf9$b z{Tn}-P;mi)%-bEHPY!sZ!VJp~^XI;iJuUxzE$H +* Downloaded: 2026-08-04, `kenney_space-shooter-remastered.zip` +* Author: Kenney () +* Licence: CC0 1.0. Crediting is not required; it is here because it should be. + +The files are the pack's `PNG/` versions, byte for byte — nothing is resized, +recoloured or re-encoded, so the checksum of any of them still matches the +distributed archive. `playerShip1_blue.png` sits at the top of `PNG/`; the enemies +are from `PNG/Enemies/` and the lasers from `PNG/Lasers/`. + +| File | Size | Used for | +|---|---|---| +| `playerShip1_blue.png` | 99x75 | the player's ship | +| `enemyBlue1.png` | 93x84 | the bee | +| `enemyRed2.png` | 104x84 | the butterfly | +| `enemyGreen3.png` | 103x84 | the boss, at full health | +| `enemyBlack3.png` | 103x84 | the boss at one hit point — same silhouette, drained colour | +| `laserBlue01.png` | 9x54 | the player's shot | +| `laserRed01.png` | 9x54 | an enemy's shot | +| `laserBlue08.png` | 48x46 | the explosion burst | + +The sprites are used at their distributed size: libakgl draws a sprite at the +sprite's own dimensions (`akgl_Actor.scale` is overwritten every frame — libakgl +docs/12-actors.md), so there is no way to draw these smaller, and the game's +1280x960 view is sized to fit a ten-column formation of them instead. The boss's +damage state is the same shape in a different colour deliberately: the swap has to +read at a glance from the top of the screen. + +Everything else on screen — the starfield and the HUD — is drawn by the program +with `akgl_draw_point()` and the UI layer. See `../../README.md` for the run +instructions and the two tutorial chapters (docs/20, docs/21) for why only the +things that move are artwork. diff --git a/examples/galaga/assets/art/enemyBlack3.png b/examples/galaga/assets/art/enemyBlack3.png new file mode 100644 index 0000000000000000000000000000000000000000..dafec1b16c6ad444ded47cdf3435c9beedd824fd GIT binary patch literal 3548 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 WWMy)w27m4V00004-GCp+ko{05bV>{P^*}znb;x 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 literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/art/enemyGreen3.png b/examples/galaga/assets/art/enemyGreen3.png new file mode 100644 index 0000000000000000000000000000000000000000..74e2bca68229314e2a6b074850c0f309ac547cc1 GIT binary patch literal 3609 zcmV+!4(9QRP)%3F73ClJCs37d`9!5qs8l6o5*Lfhi6hp4mhcEz4mOLh*=%eh76V3+Be4d7#4`w7 z0-`7ZOhsU!0#QUPLC6YVR#9xlR`3%#b0)ek{aU@w^o*V`Q+3PugJ!1tbl-FO+l>&yDUg=Z13K^1kj6M78SqhZTl29I_R`+0_Mbt6YT2M ztL(;&8|?Ap$Fab%@t&BK zfeOscqCI=|bhov&=~Q3k@#Du|4z3D7DORbcj*bp?@ZiB*$Dosta%8~t_4UOD2QyE0 zZ<=uzN* zW5;p;9XN1+UAuNI@4e5TKOX`Vw5xW=0)wfK5r&3fHt?hzq_JEFpfiZ@b%DS00S;!M z=~+;QG>i7_+ZX;n{XG=pnKNf-24#k7I?JK~7->(RJ`Eez)6)|+7L7(aL!(U{MFBGR z0nVK}cdVZYrAUJa1B%ol)=d4g=LPt5NC5-V#LHuZQKw$Nex331*tUZx;>u`IPTK|) zBk>{tqWfIAa)kiu8!`d`BZ-I;Ihq=C`SRsl8gm84hf?FylIydPc1hmz_qurTA_3Go zBzT4d0EkqSv6RkSJLl%jo8G{Y$!SwStl-^)w&mRm>6-Ybv$M0R(9>Bc0KhG>j-ge# zjR5d1qxlYX1&0(IX1{DEQl`MNp-=@tttbG*z{o=*O|m&D8Eqq{WkH;y;yqp za+>&N*H?|~)9n?k^WVp;?vG^z353-7CwS;+8XY#(Ndg89TwTA=iFbU;XbPlB7rxoL z>(Al4y8whV*q`1y2F+=seNE&1Fg@F>r_P=| zo1TNMa+-C~(*9K*FbIr9Ti)?4qbZOsZTSYXoqvA-)OYWul~t6QK#)1jxnm(zVT+Dscy!UufE_JI?iXN*m?MJHBN!1=6J}-^c*6c@{a?i7Zfg zrx{YwMlxgSs~S~VJv~=GF!7E{3EBln(^`l4X6@$XY}w|S%C>+{ZJx(1P+Pt7jLKtAX}YBhB5;{Q_UtFIK(#ydf)dx zpR5JQMq&#N_UO0*Aat4`32g+x_LlX^mq%)#h9WQ`O}ry2HM|430v+#Ka*(aZOnigc z&A;=!^;4DYL-c%q-b%v9cCcwnlgVjTtz|@D-d!~zub~JN?;t&qXQfkDUH>}AHms^; zpDtRX5|y!XMfq4W#_uo8%T8b=J`hU-bl}?_Ezs% zYLwWK9cX%9h9$49d`6^8(X<-{Qy8r;846%@*&Ia_?ms!(`($b zCgU41kf!5GY$pes-_m3f05)qGUE@UFQO%OQ*=ANzvOo)p4LB4?dFxixu|R`r_o~VG zMh4KwTW7@rh;y*jTda7e*N!^L??YnK z7AvWP?dmk^fLXdJV+{;q-KNi!yn|Vj6gZecI=-2+dWv-$-d{IG%e%0$B0JbF0w9WH z)&)kWigzH9lL7}qLB%(i%`R>5A+dRZklSKK6-^tbS!Vz9lGzm)1V*TicVw!}2RIN1 zD!##Nc5Me@VNIzPAXAxPz!ob?XQqXwNiv(1SsJ|K0*(*9k%dkm*hp-upoab%RDwwa zz?RSf<0=A@;vHLXeDVz+Fi1`P1dGd39At6@G}YE7lVs-8T2yd+@s2GxzWIg%%Lh|G z=_EF2g%mTTwPG?iUG0AtHy{n(u>~gyzA?E5Hf09loIKBs&=M=0I%TG-)eIKz*n*P; z-#`qx^c6xB2xN%n)qBXY5!W~-5g-Q0Fe*6JTUN*B9b1P$$2apnFNyU2Iw`F(NX3~$ zQaaDdq5T13K@G^dj)thI?US1Mv3bV^939`(H*8BKrO9}Q3ULr<0~`WMZQ@!-=LW>_ z)WpDujmtYW;OO`Uvo|U@It$0fHQ;{6m{tDpN!-AptJT<4JY51KHxBREfTQCZ%-%=? z%TOVeEl4#RK#G-npG6BNN@|1N9}M0xfs+*9=!$PPDGfr5GM9GylT1>BywXT*ae2oC zPEvg1n$kq4nzLbW# zUm%JJ8kcuW;3UB}SlhYuOZHIhfXtNV3Yd1>$V$|%sV!=3Zmf>XJ34Soe6zBCUMlSq zQyP`3t#;z5B(I2H#nUG&uYllr_wf=D?k$3Y8NQE z1>%+{-NtmEfe}n6NlAGpm;sZ=&0=r=veXG28Q(d8-gY8g%|LZr(ZBTTCWLkV9ma4g}xmlOZ>)o;f zoU0L<1n=;H*}#LugQDA(I~aT;Gdj70jqHzQA-6y*z(JoE0`JI#0#X-k!?pUGl=%j0 zMO9%f(vPKNZb4e9O~*SvB5l4AQ<{}4U~&t@0-UQ6niTKEjWqd2W^{7DG{{5&Co3z! zMKMC7#Ame&tav9%5Z~-<*pW(GWP1jvuomezI^-6}B(-aeCrXqqeA9_{T!Q$fx^5k- z+)$EuTg2K8N$6NdAgkPhBvaemwZCI!i^j8G&-@vy+ftJV?-1WCuA0jx&Uu|xteC)- z)MZjjX-=+y$t@5Ia8Zm!^f76tQ=QX)Xl%gZ{PVjo3Zq**g%O!Cl%JLT>+C@Ad}RtH6AS>rA4jd zN=9Wyj`>mE?^DouzIliE245Nx+dFRBPezO_E2s1edE(k*z9Zx1*UTnWy!F*^Cen%ARMWCb{}#v=m+ zBhM8O{t7xV#BQj0a7sdInze?WqifYcE8+4ydo zFW%w!CiVe!NXJOa;7bCCPj#}|4R=6M#wR#g)tLl5IJ1_&ol{&s4@SaQp?vTT$2Z}j1_z#E|$IW%)TgVRdq#rm-B4jIk#8Q5TObzT#2OFr4n~yE=l6fe zwIgo${(vhI#_L0`Ayi;hGjBjM8 zbx>g~(U&2&Kqjf7>wieRqv9LY(UGZqI!xsjkP%AW8kw6fD>!3Iema_JK$tmj-DO5+ zBCdeREr3r1?!kZY0^fEVlh$TlR&YZ5M)21@sHzCF3VryMFRZ2VMJoR2FEOUQH~xRl zb6HU>3_?>mV8{ysloe2@Lp>@0>dS3w2mf=){71n1|6K{tUYZYT$KYfrG6*OBW8+be zDgG~f^d^{WK3#7B001p?MObuGZ)S9NVRB^vVtFoNY;SL5WO*)Qa(QrcZ!T$VVP|D7 fP)Z)9b1s0M%T00000NkvXXu0mjf`V7Zs literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/art/enemyRed2.png b/examples/galaga/assets/art/enemyRed2.png new file mode 100644 index 0000000000000000000000000000000000000000..3ee96c571bcedfc0ac27639fb2db78fd3ebd0e39 GIT binary patch literal 3055 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 literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/art/laserBlue01.png b/examples/galaga/assets/art/laserBlue01.png new file mode 100644 index 0000000000000000000000000000000000000000..b76aaf7a042d56165a0d3cbadd2ce85216838081 GIT binary patch literal 744 zcmVP)GD7{~FaQA^V4-p+a6a;lBi0I%Uq9}@r@K6vKkr2_rLqv!N z1J|A16e|l2EsZTqwlLAKH22T^-<_F#dSC2E55c_fVd49}?ECW0EK8(DL%O&#m9=_O z*~-{IR*&v_o_6&Yx3*>Nf{}B=|LLyhDP>w$4b$?H=y__*S&ONhRn~6hJ$JeohL>ht z2TjkD+J6<6oG1$8I+ubtmYv#6XBqsc&LBIf!!3Xv)){112QSYk{dI~uC^<`h6N{PkX?V%C=~3NL3V1*S{azD#0;{lgWJy` zUyc}L*HoB++GRUqU%Vii?sxin;t)_DUo-NiG zWY<^F1y8=$7-XmBjCB_J7HSN#Q*+ij4UfOo7-T0SPDe5{ aMQ&qnWMy)w27m4V0000@18(EFBQ2g`r3cEJ!dgz<>|~14|JJ zl+sc{J~vLU7pG0rTz*cnWVx|@XWxDIwJ7%q=X|-WN2p<*SyX34J|2f7+Zag!=3~ z{P+T(UkEi)$m213`PTIXKwpo$LLTN=fRBb|^tILV1wcRdb^z6&2F%G9;M{u8l^Q|s z6;li{IjuLCUvTHRDp$!AaZC;iZR_ScAOOb9zQKN8IkVSNWgZ*yQwLNYJavY2pA&w= zHxyQhac`%0@{IYD*RC@uVGb7pYl|`uCq$XwxNbR*R?mq`n2R;2U5Gk5s`D_)QR)(v zum&}7F_={_Nv?aElQ-SOaO5h0P88!|h)EOHq^gu?{;*uL%BCPKX`<*f6)LHu#AO;+ ziP(jnejLP!gG`>ItAYpcGS;}gG_VrpoOH7~e_{e)?NNJs>1idPUMh|!rySM*dD28- zHLT%weDAGJo;fBgvUAr~hIP~YRV{4-GGSk2bi4QMfMC9%Lz1MiU5dER@Na=imc?mD zCGbXh9l#`0A*c@!0TU#RHY(HL1!}}qXvoW&VtO7T(>zy-um|?y`2%M@kQ4!D73PmY zfJ|Z3%c;lu1a%{IYacnT%5yVwWc~g7&eYnB9bV8-Leduuh1Tu?CL2l<8& z7r=!}`HNsqU{^(|&eRrg-ANcU)<`WYqqd+!>uGKRb9sUqkCb z!P5l+S{BLuJ2Cgv;x$j{ppTw@Vg4_{A3@NUdc61tU*aO@PZQXW0000jbVXQnQ*UN; zcVTj60AhJAVr*}3WMp|RV{&KQKGBibQV{c?-a;OG>?f?J)07*qo IM6N<$f_6BF2mk;8 literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/art/laserRed01.png b/examples/galaga/assets/art/laserRed01.png new file mode 100644 index 0000000000000000000000000000000000000000..5e467b65ba82babe205a227f0ba2ef5912d6839b GIT binary patch literal 735 zcmV<50wDc~P)0D5BJyC%g?&H zexk`bMJ;O|O8NYslX97V6^kdjlQW%%^6@c)?lP2x-=z|R?lQCk&S@BQCp!?>f}=u# zL3g>k4LID}W6+)AmbD6{T#i9^a&~qZeq^%@x|1CYrr;oxVbEPJd=9>EZ!_pFTQCdX z(rE_WW#~Q>Ha8h`m!WC+y0*rkyWHJ9__Dgnpu2q1D12U7VbGnN$8{L;OG^y8%g`Oj zrBV#Klk>pehTZvj2HnZ|W%R?RWRgL5`C5A5qdRKcshJ_g-srn1rxFME0zbf;;r z_cFZb?q<-PqF(PMc;4B`pgToE++0ek? zI`p`{p22nKQC%H_>(Im6S_aplL`_ZcK`6w+btqm{)tjiUW_i{9F9;-mPg1X)a{vGU zEp$a#bW?9;ba!ELWdLG%E@EtNZ)9Y7E@N_eaCC1jX>DO=WiC)oM=~@;Zewp`Wpbzn Rf9?PP002ovPDHLkV1hx$V`BgS literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/art/playerShip1_blue.png b/examples/galaga/assets/art/playerShip1_blue.png new file mode 100644 index 0000000000000000000000000000000000000000..cecbbed97ab05b70d3acf45529935a3f9f974249 GIT binary patch literal 2698 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 Ef&*|u*#H0l literal 0 HcmV?d00001 diff --git a/examples/galaga/assets/character_galaga_bee.json b/examples/galaga/assets/character_galaga_bee.json new file mode 100644 index 0000000..0b82825 --- /dev/null +++ b/examples/galaga/assets/character_galaga_bee.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_bee", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_bee" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_boom.json b/examples/galaga/assets/character_galaga_boom.json new file mode 100644 index 0000000..fa39a92 --- /dev/null +++ b/examples/galaga/assets/character_galaga_boom.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_boom", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_boom" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_boss.json b/examples/galaga/assets/character_galaga_boss.json new file mode 100644 index 0000000..13ff200 --- /dev/null +++ b/examples/galaga/assets/character_galaga_boss.json @@ -0,0 +1,23 @@ +{ + "name": "galaga_boss", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_boss" + }, + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE", + "AKGL_ACTOR_STATE_UNDEFINED_13" + ], + "sprite": "galaga_boss_hurt" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_butterfly.json b/examples/galaga/assets/character_galaga_butterfly.json new file mode 100644 index 0000000..e2a53be --- /dev/null +++ b/examples/galaga/assets/character_galaga_butterfly.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_butterfly", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_butterfly" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_enemyshot.json b/examples/galaga/assets/character_galaga_enemyshot.json new file mode 100644 index 0000000..9827180 --- /dev/null +++ b/examples/galaga/assets/character_galaga_enemyshot.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_enemyshot", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_enemyshot" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_player.json b/examples/galaga/assets/character_galaga_player.json new file mode 100644 index 0000000..54639be --- /dev/null +++ b/examples/galaga/assets/character_galaga_player.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_player", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_player" + } + ] +} diff --git a/examples/galaga/assets/character_galaga_playershot.json b/examples/galaga/assets/character_galaga_playershot.json new file mode 100644 index 0000000..37a0fef --- /dev/null +++ b/examples/galaga/assets/character_galaga_playershot.json @@ -0,0 +1,16 @@ +{ + "name": "galaga_playershot", + "speedtime": 200, + "speed_x": 0.0, + "speed_y": 0.0, + "acceleration_x": 0.0, + "acceleration_y": 0.0, + "sprite_mappings": [ + { + "state": [ + "AKGL_ACTOR_STATE_ALIVE" + ], + "sprite": "galaga_playershot" + } + ] +} diff --git a/examples/galaga/assets/sprite_galaga_bee.json b/examples/galaga/assets/sprite_galaga_bee.json new file mode 100644 index 0000000..30397ed --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_bee.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/enemyBlue1.png", + "frame_width": 93, + "frame_height": 84 + }, + "name": "galaga_bee", + "width": 93, + "height": 84, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_boom.json b/examples/galaga/assets/sprite_galaga_boom.json new file mode 100644 index 0000000..4575076 --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_boom.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/laserBlue08.png", + "frame_width": 48, + "frame_height": 46 + }, + "name": "galaga_boom", + "width": 48, + "height": 46, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_boss.json b/examples/galaga/assets/sprite_galaga_boss.json new file mode 100644 index 0000000..62e9a8e --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_boss.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/enemyGreen3.png", + "frame_width": 103, + "frame_height": 84 + }, + "name": "galaga_boss", + "width": 103, + "height": 84, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_boss_hurt.json b/examples/galaga/assets/sprite_galaga_boss_hurt.json new file mode 100644 index 0000000..3f3537c --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_boss_hurt.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/enemyBlack3.png", + "frame_width": 103, + "frame_height": 84 + }, + "name": "galaga_boss_hurt", + "width": 103, + "height": 84, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_butterfly.json b/examples/galaga/assets/sprite_galaga_butterfly.json new file mode 100644 index 0000000..a86909b --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_butterfly.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/enemyRed2.png", + "frame_width": 104, + "frame_height": 84 + }, + "name": "galaga_butterfly", + "width": 104, + "height": 84, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_enemyshot.json b/examples/galaga/assets/sprite_galaga_enemyshot.json new file mode 100644 index 0000000..87da91f --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_enemyshot.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/laserRed01.png", + "frame_width": 9, + "frame_height": 54 + }, + "name": "galaga_enemyshot", + "width": 9, + "height": 54, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_player.json b/examples/galaga/assets/sprite_galaga_player.json new file mode 100644 index 0000000..fcfe452 --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_player.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/playerShip1_blue.png", + "frame_width": 99, + "frame_height": 75 + }, + "name": "galaga_player", + "width": 99, + "height": 75, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/assets/sprite_galaga_playershot.json b/examples/galaga/assets/sprite_galaga_playershot.json new file mode 100644 index 0000000..05ed19f --- /dev/null +++ b/examples/galaga/assets/sprite_galaga_playershot.json @@ -0,0 +1,16 @@ +{ + "spritesheet": { + "filename": "art/laserBlue01.png", + "frame_width": 9, + "frame_height": 54 + }, + "name": "galaga_playershot", + "width": 9, + "height": 54, + "speed": 200, + "loop": false, + "loopReverse": false, + "frames": [ + 0 + ] +} diff --git a/examples/galaga/enemies.c b/examples/galaga/enemies.c new file mode 100644 index 0000000..aca8580 --- /dev/null +++ b/examples/galaga/enemies.c @@ -0,0 +1,314 @@ +/** + * @file enemies.c + * @brief The formation, the wave, and the hook that hands each enemy to BASIC. + * + * C owns the grid, the wave table and the spawn timing; BASIC owns everything + * an enemy does after it exists. The formation slot arrives in SELF@.HOMEX% / + * HOMEY%, so even the idle breathing of the grid is the script's, computed + * relative to home. + */ + +#include +#include +#include +#include + +#include + +#include +#include + +#include +#include +#include +#include + +#include "galaga.h" + +galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES]; +akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES]; + +/* Explosion lifetimes, indexed by heap slot. An explosion is an actor with + * nothing to decide, so its whole state is one countdown. */ +static float BOOM_TTL[AKGL_MAX_HEAP_ACTOR]; + +/* A spawn serial per shot so registry names never collide while two shots + * with the same slot number are briefly both alive. */ +static uint32_t SHOT_SERIAL = 0; +static uint32_t BOOM_SERIAL = 0; + +/* + * The wave, one row per formation row. Columns are 0..9 at GALAGA_COL_PITCH; + * `first` and `count` say which columns the row fills. 40 enemies: 4 bosses, + * 16 butterflies, 20 bees -- 59 of the 64 actor heap slots at peak, counting + * the player, two player shots, eight enemy shots and eight explosions. + */ +static const struct +{ + int32_t kind; /* GALAGA_ENEMY_* */ + int row; /* formation row */ + int first; /* first column filled */ + int count; /* columns filled */ + int32_t hp; +} +WAVE_ROWS[] = { + /* kind row first count hp */ + { GALAGA_ENEMY_BOSS, 0, 3, 4, 2 }, + { GALAGA_ENEMY_BUTTERFLY, 1, 1, 8, 1 }, + { GALAGA_ENEMY_BUTTERFLY, 2, 1, 8, 1 }, + { GALAGA_ENEMY_BEE, 3, 0, 10, 1 }, + { GALAGA_ENEMY_BEE, 4, 0, 10, 1 } +}; +#define WAVE_ROW_COUNT ((int)(sizeof(WAVE_ROWS) / sizeof(WAVE_ROWS[0]))) + +/* Enemy kind -> character name, the render half of the dispatch table. */ +static char *ENEMY_CHARACTER[GALAGA_ENEMY_KINDS] = { + "galaga_bee", + "galaga_butterfly", + "galaga_boss" +}; + +/* --------------------------------------------------------------- random --- */ + +/* + * No RND verb exists (issue #16), so the engine is the script's only source + * of randomness: it refreshes GAME@.RND% each frame and SELF@.RND% each call + * from this PRNG. A hand-rolled LCG rather than rand() so a headless run is + * the same game on every libc. + */ +static uint32_t PRNG_STATE = 0x12345678u; + +float galaga_random(void) +{ + PRNG_STATE = PRNG_STATE * 1664525u + 1013904223u; + return (float)(PRNG_STATE >> 8) / (float)0x01000000u; +} + +/* -------------------------------------------------------------- helpers --- */ + +static akerr_ErrorContext *release_actor(akgl_Actor *actor) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "actor"); + PASS(errctx, akgl_heap_release_actor(actor)); + SUCCEED_RETURN(errctx); +} + +/* ---------------------------------------------------------------- shots --- */ + +/** + * @brief Move an enemy shot; release it once it has left the screen. + */ +static akerr_ErrorContext *enemy_shot_update(akgl_Actor *obj) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + obj->y += 380.0f * galaga_game.dt; + if ( obj->y > (float)GALAGA_VIEW_HEIGHT + 60.0f ) { + galaga_game.enemy_shots_live -= 1; + PASS(errctx, release_actor(obj)); + } + SUCCEED_RETURN(errctx); +} + +/** + * @brief Consume an enemy's fire flag: take an actor and aim it downward. + * + * The script only raises a flag. Spawning takes a slot from the actor heap, + * and pool exhaustion must be a C-side refusal with the house error context -- + * so C consumes the flag and does the spawn. The engine also enforces the + * eight-shot cap by simply not consuming the flag's wish. + */ +static akerr_ErrorContext *enemy_fire(galaga_Enemy *enemy, akgl_Actor *from) +{ + akgl_Actor *shot = NULL; + char name[32]; + int count = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "enemy"); + FAIL_ZERO_RETURN(errctx, from, AKERR_NULLPOINTER, "from"); + + enemy->fire = 0; + if ( galaga_game.enemy_shots_live >= GALAGA_MAX_ENEMY_SHOTS ) { + SUCCEED_RETURN(errctx); + } + + SHOT_SERIAL += 1; + PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "eshot%u", SHOT_SERIAL)); + PASS(errctx, akgl_heap_next_actor(&shot)); + PASS(errctx, akgl_actor_initialize(shot, name)); + PASS(errctx, akgl_actor_set_character(shot, "galaga_enemyshot")); + /* AFTER initialize: it resets all seven hooks. */ + shot->updatefunc = &enemy_shot_update; + shot->movement_controls_face = false; + shot->state = AKGL_ACTOR_STATE_ALIVE; + /* akgl_actor_initialize() does not raise `visible`; a hand-spawned actor + * that skips this line exists, moves and collides -- invisibly. */ + shot->visible = true; + /* Actor x/y is a sprite's top-left corner; the shot leaves the enemy's + * midline. Enemy sprites run 93..104 wide, the shot is 9. */ + shot->x = from->x + 46.0f; + shot->y = from->y + 60.0f; + + galaga_game.enemy_shots_live += 1; + galaga_game.shots[enemy->kind] += 1; + SUCCEED_RETURN(errctx); +} + +/* ----------------------------------------------------------- explosions --- */ + +static akerr_ErrorContext *boom_update(akgl_Actor *obj) +{ + ptrdiff_t slot = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + slot = obj - akgl_heap_actors; + BOOM_TTL[slot] -= galaga_game.dt; + if ( BOOM_TTL[slot] <= 0.0f ) { + PASS(errctx, release_actor(obj)); + } + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_boom_spawn(float x, float y) +{ + akgl_Actor *boom = NULL; + char name[32]; + int count = 0; + PREPARE_ERROR(errctx); + + ATTEMPT { + CATCH(errctx, akgl_heap_next_actor(&boom)); + BOOM_SERIAL += 1; + CATCH(errctx, aksl_snprintf(&count, name, sizeof(name), "boom%u", BOOM_SERIAL)); + CATCH(errctx, akgl_actor_initialize(boom, name)); + CATCH(errctx, akgl_actor_set_character(boom, "galaga_boom")); + boom->updatefunc = &boom_update; + boom->movement_controls_face = false; + boom->state = AKGL_ACTOR_STATE_ALIVE; + boom->visible = true; + boom->x = x; + boom->y = y; + BOOM_TTL[boom - akgl_heap_actors] = 0.25f; + } CLEANUP { + } PROCESS(errctx) { + } HANDLE(errctx, AKGL_ERR_HEAP) { + /* Explosions are decoration. When the heap is momentarily full the + * right outcome is no explosion, not a dead frame -- this is the one + * spawn that absorbs exhaustion. */ + } FINISH(errctx, true); + SUCCEED_RETURN(errctx); +} + +/* --------------------------------------------------------------- enemies --- */ + +/** + * @brief The custom update hook: one enemy, once per frame, thought in BASIC. + * + * The whole body is the protocol from docs/20: refresh the inbox, hand the + * pair to the script, consume the outbox. akgl_game_update() calls this in + * place of akgl_actor_update() because spawn replaced the hook. + */ +static akerr_ErrorContext *enemy_update(akgl_Actor *obj) +{ + galaga_Enemy *enemy = NULL; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + enemy = (galaga_Enemy *)obj->actorData; + FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "an enemy actor with no galaga_Enemy attached"); + + enemy->rnd = galaga_random(); + PASS(errctx, galaga_script_update_enemy(enemy, obj, galaga_game.dt)); + if ( enemy->fire != 0 ) { + PASS(errctx, enemy_fire(enemy, obj)); + } + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_wave_spawn(void) +{ + akgl_Actor *actor = NULL; + galaga_Enemy *enemy = NULL; + char name[32]; + int row = 0; + int col = 0; + int index = 0; + int count = 0; + PREPARE_ERROR(errctx); + + for ( row = 0; row < WAVE_ROW_COUNT; row++ ) { + for ( col = 0; col < WAVE_ROWS[row].count; col++ ) { + FAIL_NONZERO_RETURN(errctx, (index >= GALAGA_MAX_ENEMIES), AKERR_OUTOFBOUNDS, + "The wave table places more than %d enemies", GALAGA_MAX_ENEMIES); + enemy = &galaga_enemies[index]; + memset(enemy, 0, sizeof(*enemy)); + enemy->kind = WAVE_ROWS[row].kind; + enemy->state = GALAGA_ES_ENTERING; + enemy->homex = (float)(GALAGA_FORM_LEFT + + (WAVE_ROWS[row].first + col) * GALAGA_COL_PITCH); + enemy->homey = (float)(GALAGA_FORM_TOP + WAVE_ROWS[row].row * GALAGA_ROW_PITCH); + enemy->hp = WAVE_ROWS[row].hp; + /* Stagger the entries: each enemy's clock starts in the past, and + * the script holds still until its own t crosses zero. */ + enemy->t = -0.08f * (float)index; + + PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "enemy%02d", index)); + PASS(errctx, akgl_heap_next_actor(&actor)); + PASS(errctx, akgl_actor_initialize(actor, name)); + PASS(errctx, akgl_actor_set_character(actor, ENEMY_CHARACTER[enemy->kind])); + /* AFTER initialize: it resets all seven hooks. */ + actor->updatefunc = &enemy_update; + actor->actorData = enemy; + /* Nothing here moves by state bits, and an actor whose state word + * matches no character mapping is silently not drawn -- so facing + * stays entirely out of the state word. */ + actor->movement_controls_face = false; + actor->state = AKGL_ACTOR_STATE_ALIVE; + /* akgl_actor_initialize() does not raise `visible` -- the map + * loader copies it from map data, and there is no map here. Skip + * this and the whole wave exists, moves, fires and dies without + * ever being drawn. */ + actor->visible = true; + /* Off screen above, pouring in from whichever side is closer. */ + actor->x = (enemy->homex < (float)GALAGA_VIEW_WIDTH / 2.0f) + ? -80.0f : (float)GALAGA_VIEW_WIDTH + 80.0f; + actor->y = -80.0f; + + galaga_enemy_actors[index] = actor; + index += 1; + } + } + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_wave_release(void) +{ + int i = 0; + PREPARE_ERROR(errctx); + + for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) { + if ( galaga_enemy_actors[i] != NULL ) { + PASS(errctx, release_actor(galaga_enemy_actors[i])); + galaga_enemy_actors[i] = NULL; + } + } + SUCCEED_RETURN(errctx); +} + +int galaga_enemies_alive(void) +{ + int i = 0; + int alive = 0; + + for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) { + if ( galaga_enemy_actors[i] != NULL ) { + alive += 1; + } + } + return alive; +} diff --git a/examples/galaga/galaga.bas b/examples/galaga/galaga.bas new file mode 100644 index 0000000..8105f5b --- /dev/null +++ b/examples/galaga/galaga.bas @@ -0,0 +1,119 @@ +REM GALAGA enemy behavior. The C engine loads this file, runs it once so the +REM definitions exist, and then calls one UPDATE function per enemy per frame. +REM There is no top-level code: definitions, then END. +REM +REM Names the engine binds before every call: +REM SELF@ - this enemy's record (ENEMY): the state machine's memory +REM ACTOR@ - the engine's live actor (ACTOR): position is the real thing +REM GAME@ - shared frame state (GAME): player position, wave, randomness +REM +REM SELF@.STATE# bits: 1 = entering 2 = in formation 4 = diving +REM +REM Two rules of this dialect that bite here, both from docs/03: +REM - the LEFT operand decides integer or float arithmetic, so a float +REM always goes first: SELF@.T% * 150 + 260, never 260 + 150 * SELF@.T% +REM - RETURN at the start of a line ends the DEF body, so every early +REM return rides an IF ... THEN, and only the last RETURN starts a line + +REM Ease toward the formation slot, with a little entry swirl. +REM Answers 1 once the slot is reached, else 0. +DEF GLIDEHOME(DT%) + DX% = SELF@.HOMEX% - ACTOR@.X% + DY% = SELF@.HOMEY% - ACTOR@.Y% + K% = DT% * 4.5 + IF K% > 1 THEN K% = 1 + ACTOR@.X% = ACTOR@.X% + DX% * K% + SIN(SELF@.T% * 6) * 90 * DT% + ACTOR@.Y% = ACTOR@.Y% + DY% * K% + IF ABS(DX%) < 3 AND ABS(DY%) < 3 THEN RETURN 1 + RETURN 0 + +REM One frame of a dive: accelerate downward, weave, lean toward the +REM player's column, and glide back in from the top after falling out. +DEF DIVESTEP(DT%, WEAVE%, LEAD%) + SPD% = SELF@.T% * 150 + 260 + ACTOR@.Y% = ACTOR@.Y% + SPD% * DT% + ACTOR@.X% = ACTOR@.X% + SIN(SELF@.T% * 4) * WEAVE% * DT% + DX% = GAME@.PLAYERX% - ACTOR@.X% + IF DX% > 220 THEN DX% = 220 + IF DX% < -220 THEN DX% = -220 + ACTOR@.X% = ACTOR@.X% + DX% * LEAD% * DT% + IF ACTOR@.Y% > 1040 THEN BEGIN + ACTOR@.Y% = 0.0 - 90 + SELF@.STATE# = 1 + SELF@.T% = 0 + BEND + RETURN 0 + +REM Raise the fire flag when diving roughly above the player. The engine +REM consumes FIRE# and does the spawning; the script only wishes. +DEF DECIDEFIRE(DT%) + DX% = GAME@.PLAYERX% - ACTOR@.X% + IF ABS(DX%) > 140 THEN RETURN 0 + IF ACTOR@.Y% > GAME@.PLAYERY% THEN RETURN 0 + IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1 + RETURN 0 + +REM Bee: enter, breathe in formation, occasionally dive nearly straight. +DEF UPDATEBEE(DT%) + SELF@.T% = SELF@.T% + DT% + IF SELF@.T% < 0 THEN RETURN 0 + S# = SELF@.STATE# + IF (S# AND 1) > 0 THEN BEGIN + R# = GLIDEHOME(DT%) + IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0 + BEND + IF (S# AND 2) > 0 THEN BEGIN + ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16 + ACTOR@.Y% = SELF@.HOMEY% + IF SELF@.RND% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0 + BEND + IF (S# AND 4) > 0 THEN BEGIN + R# = DIVESTEP(DT%, 130, 0.2) + R# = DECIDEFIRE(DT%) + BEND + RETURN 0 + +REM Butterfly: the same machine with a wide lateral weave on the dive. +DEF UPDATEBFLY(DT%) + SELF@.T% = SELF@.T% + DT% + IF SELF@.T% < 0 THEN RETURN 0 + S# = SELF@.STATE# + IF (S# AND 1) > 0 THEN BEGIN + R# = GLIDEHOME(DT%) + IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0 + BEND + IF (S# AND 2) > 0 THEN BEGIN + ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 2.1) * 24 + ACTOR@.Y% = SELF@.HOMEY% + IF SELF@.RND% < DT% * 0.05 THEN SELF@.STATE# = 4 : SELF@.T% = 0 + BEND + IF (S# AND 4) > 0 THEN BEGIN + R# = DIVESTEP(DT%, 260, 0.1) + R# = DECIDEFIRE(DT%) + BEND + RETURN 0 + +REM Boss: two hit points, a slow sway, and a dive that leads the player. +REM At one hit point it raises actor state bit 13 (8192), and the engine's +REM character mapping swaps the sprite - the boundary crossed the other way. +DEF UPDATEBOSS(DT%) + SELF@.T% = SELF@.T% + DT% + IF SELF@.T% < 0 THEN RETURN 0 + IF SELF@.HP# = 1 THEN ACTOR@.STATE# = ACTOR@.STATE# OR 8192 + S# = SELF@.STATE# + IF (S# AND 1) > 0 THEN BEGIN + R# = GLIDEHOME(DT%) + IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0 + BEND + IF (S# AND 2) > 0 THEN BEGIN + ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.1) * 10 + ACTOR@.Y% = SELF@.HOMEY% + IF SELF@.RND% < DT% * 0.03 THEN SELF@.STATE# = 4 : SELF@.T% = 0 + BEND + IF (S# AND 4) > 0 THEN BEGIN + R# = DIVESTEP(DT%, 60, 0.9) + R# = DECIDEFIRE(DT%) + BEND + RETURN 0 + +END diff --git a/examples/galaga/galaga.h b/examples/galaga/galaga.h new file mode 100644 index 0000000..ff324f5 --- /dev/null +++ b/examples/galaga/galaga.h @@ -0,0 +1,155 @@ +/** + * @file galaga.h + * @brief Shared declarations for the GALAGA embedding example. + * + * The engine is C on libakgl; the enemies think in BASIC. Everything the two + * sides share crosses in exactly one place: the three structures below, which + * script.c registers as host types so a script reads and writes them directly. + * docs/20-tutorial-galaga.md and docs/21-tutorial-galaga-enemies.md build this + * program from an empty file; the split between files follows the split + * between chapters. + */ + +#ifndef _GALAGA_H_ +#define _GALAGA_H_ + +#include +#include + +#include + +#include + +/* ------------------------------------------------------------- geometry --- */ + +/* + * The view is sized to the artwork rather than the other way round: the Kenney + * sprites are ~100 pixels wide, libakgl has no way to draw a sprite smaller + * than it is (akgl_Actor.scale is overwritten every frame -- libakgl + * docs/12-actors.md), and a ten-column formation of them needs 1120 pixels. + */ +#define GALAGA_VIEW_WIDTH 1280 +#define GALAGA_VIEW_HEIGHT 960 + +#define GALAGA_FORM_COLUMNS 10 /* formation width, in slots */ +#define GALAGA_FORM_LEFT 136 /* x of column 0, map pixels */ +#define GALAGA_FORM_TOP 120 /* y of row 0, map pixels */ +#define GALAGA_COL_PITCH 112 +#define GALAGA_ROW_PITCH 100 + +#define GALAGA_PLAYER_Y 860.0f +#define GALAGA_PLAYER_SPEED 420.0f /* map pixels per second */ +#define GALAGA_PLAYER_MARGIN 60.0f /* how close to the edge it may go */ + +/* ------------------------------------------------------------- entities --- */ + +#define GALAGA_ENEMY_BEE 0 +#define GALAGA_ENEMY_BUTTERFLY 1 +#define GALAGA_ENEMY_BOSS 2 +#define GALAGA_ENEMY_KINDS 3 + +#define GALAGA_MAX_ENEMIES 40 +#define GALAGA_MAX_PLAYER_SHOTS 2 /* the classic two-on-screen rule */ +#define GALAGA_MAX_ENEMY_SHOTS 8 + +/* + * galaga_Enemy.state bits. The script owns these transitions; the engine only + * writes the word at spawn and when a script error forces an enemy dumb. + * galaga.bas spells the same three values as literals, with a REM naming them. + * + * 8 0 + * 0 0 0 0 0 1 1 1 + * | | `-- ENTERING: flying its entry path toward the formation slot + * | `---- FORMATION: holding (and breathing around) homex/homey + * `------ DIVING: attacking, off the grid until it leaves the screen + */ +#define GALAGA_ES_ENTERING (1 << 0) +#define GALAGA_ES_FORMATION (1 << 1) +#define GALAGA_ES_DIVING (1 << 2) + +/** @brief One enemy, as both sides see it. Hangs off akgl_Actor.actorData. */ +typedef struct galaga_Enemy +{ + int32_t kind; /* GALAGA_ENEMY_BEE / BUTTERFLY / BOSS */ + int32_t state; /* GALAGA_ES_* bit flags */ + float homex; /* formation slot, in map pixels */ + float homey; + float t; /* parametric clock for the current maneuver */ + int32_t hp; + int32_t fire; /* outbox: script sets 1, engine consumes */ + float rnd; /* inbox: engine writes fresh 0..1 each call */ +} galaga_Enemy; + +/** @brief Frame state every enemy may read. Bound once as GAME@. */ +typedef struct galaga_Shared +{ + float playerx; /* the player actor's position, this frame */ + float playery; + int32_t wave; + float rnd; /* fresh 0..1 each frame; the issue #16 route */ +} galaga_Shared; + +/* --------------------------------------------------------------- screens --- */ + +typedef enum +{ + GALAGA_SCREEN_TITLE = 0, + GALAGA_SCREEN_PLAY, + GALAGA_SCREEN_GAMEOVER, + GALAGA_SCREEN_VICTORY +} galaga_Screen; + +/* ------------------------------------------------------------ game state --- */ + +typedef struct galaga_Game +{ + galaga_Screen screen; + int frame; + float dt; /* seconds, clamped; see main.c */ + bool autoplay; + + int score; + int lives; + int kills[GALAGA_ENEMY_KINDS]; + int shots[GALAGA_ENEMY_KINDS]; /* shots each kind fired */ + int script_errors; + + akgl_Actor *player; + float fire_cooldown; + float respawn_timer; /* > 0 while the player is invulnerable */ + bool firing; + bool moveleft; + bool moveright; + + int player_shots_live; + int enemy_shots_live; +} galaga_Game; + +extern galaga_Game galaga_game; +extern galaga_Shared galaga_shared; + +extern galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES]; +extern akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES]; + +/* ---------------------------------------------------------------- script --- */ + +akerr_ErrorContext AKERR_NOIGNORE *galaga_script_boot(char *path); +akerr_ErrorContext AKERR_NOIGNORE *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt); + +/* --------------------------------------------------------------- enemies --- */ + +akerr_ErrorContext AKERR_NOIGNORE *galaga_wave_spawn(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_wave_release(void); +int galaga_enemies_alive(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_boom_spawn(float x, float y); + +/* ---------------------------------------------------------------- player --- */ + +akerr_ErrorContext AKERR_NOIGNORE *galaga_player_spawn(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_player_controls(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_player_autoplay(int frame); + +/** @brief A 0..1 random draw from the engine's own PRNG (see enemies.c). */ +float galaga_random(void); + +#endif // _GALAGA_H_ diff --git a/examples/galaga/interop_test.c b/examples/galaga/interop_test.c new file mode 100644 index 0000000..775d1c9 --- /dev/null +++ b/examples/galaga/interop_test.c @@ -0,0 +1,132 @@ +/** + * @file interop_test.c + * @brief Round-trip test for the galaga boundary, hoststruct.c-style. + * + * Links the real script.c and the real galaga.bas -- not copies -- so this + * fails the moment the boundary and the script disagree. The four claims it + * pins: + * + * 1. The script writes the engine's actor memory: a formation enemy's sway + * lands in akgl_Actor.x with no marshalling step. + * 2. The outbox works: a diving enemy above the player raises FIRE# and the + * C side reads it. + * 3. The boss flips actor state bit 13 at one hit point -- the boundary + * crossed engine-ward. + * 4. Sustained calling holds: 24000 calls through the per-call + * akbasic_environment_zero() regime, the load a 40-enemy wave puts on + * the runtime in ten seconds. + * + * Exit status equals the number of failed claims. + */ + +#include +#include +#include +#include +#include + +#include + +#include + +#include "galaga.h" + +#ifndef GALAGA_SCRIPT_PATH +#define GALAGA_SCRIPT_PATH "galaga.bas" +#endif + +/* script.c reads these; main.c usually defines them. This test is the host. */ +galaga_Game galaga_game; +galaga_Shared galaga_shared; + +static int FAILURES = 0; + +#define CLAIM(__cond, __text) \ + if ( !(__cond) ) { \ + fprintf(stderr, "FAILED: %s\n", __text); \ + FAILURES += 1; \ + } else { \ + printf("ok: %s\n", __text); \ + } + +static akerr_ErrorContext *run_claims(void) +{ + galaga_Enemy enemy; + akgl_Actor actor; + int i = 0; + PREPARE_ERROR(errctx); + + PASS(errctx, galaga_script_boot((char *)GALAGA_SCRIPT_PATH)); + + /* --- 1: formation sway lands in the actor ---------------------------- */ + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BEE; + enemy.state = GALAGA_ES_FORMATION; + enemy.homex = 400.0f; + enemy.homey = 300.0f; + enemy.hp = 1; + actor.x = 0.0f; + actor.y = 0.0f; + PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f)); + CLAIM((fabsf(actor.x - enemy.homex) <= 16.5f) && (actor.y == enemy.homey), + "a formation bee's sway is written into akgl_Actor.x/y by the script"); + + /* --- 2: the fire outbox ---------------------------------------------- */ + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BEE; + enemy.state = GALAGA_ES_DIVING; + enemy.rnd = 0.0f; /* 0.0 < DT% * 1.5: always willing */ + actor.x = 600.0f; + actor.y = 200.0f; + galaga_shared.playerx = 610.0f; /* just off the shot's column */ + galaga_shared.playery = 860.0f; /* well below */ + PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f)); + CLAIM(enemy.fire == 1, + "a diving bee above the player raises FIRE# for the engine to consume"); + + /* --- 3: the boss's hurt bit ------------------------------------------ */ + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BOSS; + enemy.state = GALAGA_ES_FORMATION; + enemy.homex = 500.0f; + enemy.homey = 120.0f; + enemy.hp = 1; + actor.state = AKGL_ACTOR_STATE_ALIVE; + PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f)); + CLAIM((actor.state & AKGL_ACTOR_STATE_UNDEFINED_13) != 0, + "a boss at one hit point raises actor state bit 13 from BASIC"); + + /* --- 4: sustained calling --------------------------------------------- */ + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BEE; + enemy.state = GALAGA_ES_FORMATION; + enemy.homex = 400.0f; + enemy.homey = 300.0f; + for ( i = 0; i < 24000; i++ ) { + enemy.rnd = 0.9f; /* never dive: keep the state put */ + PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f)); + } + CLAIM(galaga_game.script_errors == 0, + "24000 calls survive the per-call akbasic_environment_zero() regime"); + SUCCEED_RETURN(errctx); +} + +int main(void) +{ + PREPARE_ERROR(errctx); + + ATTEMPT { + CATCH(errctx, run_claims()); + } CLEANUP { + } PROCESS(errctx) { + } HANDLE_DEFAULT(errctx) { + LOG_ERROR_WITH_MESSAGE(errctx, "the interop test could not run"); + FAILURES += 1; + } FINISH_NORETURN(errctx); + + return FAILURES; +} diff --git a/examples/galaga/main.c b/examples/galaga/main.c new file mode 100644 index 0000000..25de084 --- /dev/null +++ b/examples/galaga/main.c @@ -0,0 +1,698 @@ +/** + * @file main.c + * @brief Startup, the frame loop, the screens, and teardown. + * + * The startup order is libakgl's one sequence that works (deps/libakgl + * include/akgl/game.h): metadata, akgl_game_init(), screen properties, + * akgl_render_2d_init(), a physics backend -- and then, new in this example, + * the interpreter. The scripts compute, the engine draws; the interpreter is + * lent no devices at all, so a script that tries SPRITE is refused by name. + */ + +#include +#include +#include + +#include +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "galaga.h" + +/** @brief Where the example's assets live. CMake defines it; `--assets` overrides. */ +#ifndef GALAGA_ASSET_DIR +#define GALAGA_ASSET_DIR "." +#endif + +/** @brief The enemy script. CMake defines it; `--script` overrides. */ +#ifndef GALAGA_SCRIPT_PATH +#define GALAGA_SCRIPT_PATH "galaga.bas" +#endif + +/** @brief The HUD font. CMake defines it; headless runs still need it for the UI. */ +#ifndef GALAGA_FONT_PATH +#define GALAGA_FONT_PATH "font.ttf" +#endif + +#define GALAGA_PATH_MAX 1024 + +galaga_Game galaga_game; +galaga_Shared galaga_shared; + +/** @brief Where `--screenshot` writes, and on which frame. NULL means never. */ +static char *SHOTPATH = NULL; +static int SHOTFRAME = 0; + +/** @brief Set in HANDLE_DEFAULT and read after FINISH; see the note in main. */ +static int FAILED = 0; + +/* ------------------------------------------------------------- starfield --- */ + +/* + * No parallax facility exists in libakgl and none is needed: a fixed array of + * stars advanced per frame and drawn with akgl_draw_point() between + * frame_start and akgl_game_update(). Two speed bands give the depth for + * free -- the slow band reads as far away. + */ +#define GALAGA_STARS 96 + +static struct +{ + float x; + float y; + float speed; + Uint8 bright; +} STARS[GALAGA_STARS]; + +static void starfield_seed(void) +{ + int i = 0; + + for ( i = 0; i < GALAGA_STARS; i++ ) { + STARS[i].x = galaga_random() * (float)GALAGA_VIEW_WIDTH; + STARS[i].y = galaga_random() * (float)GALAGA_VIEW_HEIGHT; + if ( (i % 2) == 0 ) { + STARS[i].speed = 40.0f; /* the far band */ + STARS[i].bright = 110; + } else { + STARS[i].speed = 110.0f; /* the near band */ + STARS[i].bright = 220; + } + } +} + +static akerr_ErrorContext *starfield_draw(void) +{ + SDL_Color color = { 255, 255, 255, 255 }; + int i = 0; + PREPARE_ERROR(errctx); + + for ( i = 0; i < GALAGA_STARS; i++ ) { + STARS[i].y += STARS[i].speed * galaga_game.dt; + if ( STARS[i].y > (float)GALAGA_VIEW_HEIGHT ) { + STARS[i].y -= (float)GALAGA_VIEW_HEIGHT; + STARS[i].x = galaga_random() * (float)GALAGA_VIEW_WIDTH; + } + color.r = STARS[i].bright; + color.g = STARS[i].bright; + color.b = STARS[i].bright; + PASS(errctx, akgl_draw_point(akgl_renderer, STARS[i].x, STARS[i].y, color)); + } + SUCCEED_RETURN(errctx); +} + +/* ------------------------------------------------------------ screenshots --- */ + +/** + * @brief Read the render target back and write it out as a PNG. + * + * Called after everything has drawn and before the frame is presented, + * because SDL_RenderPresent is where the target stops being readable. The + * figures in docs/20 and docs/21 are output from this program rather than + * pictures somebody took once, so they cannot show a game that no longer + * exists. + */ +static akerr_ErrorContext *save_screenshot(char *path) +{ + SDL_Surface *shot = NULL; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path"); + shot = SDL_RenderReadPixels(akgl_renderer->sdl_renderer, NULL); + FAIL_ZERO_RETURN(errctx, shot, AKGL_ERR_SDL, "SDL_RenderReadPixels: %s", SDL_GetError()); + ATTEMPT { + FAIL_ZERO_BREAK(errctx, IMG_SavePNG(shot, path), AKGL_ERR_SDL, + "IMG_SavePNG(%s): %s", path, SDL_GetError()); + } CLEANUP { + SDL_DestroySurface(shot); + } PROCESS(errctx) { + } FINISH(errctx, true); + SDL_Log("Wrote %s", path); + SUCCEED_RETURN(errctx); +} + +/* ---------------------------------------------------------------- assets --- */ + +static char *SPRITE_FILES[] = { + "sprite_galaga_player.json", + "sprite_galaga_bee.json", + "sprite_galaga_butterfly.json", + "sprite_galaga_boss.json", + "sprite_galaga_boss_hurt.json", + "sprite_galaga_playershot.json", + "sprite_galaga_enemyshot.json", + "sprite_galaga_boom.json", + NULL +}; + +static char *CHARACTER_FILES[] = { + "character_galaga_player.json", + "character_galaga_bee.json", + "character_galaga_butterfly.json", + "character_galaga_boss.json", + "character_galaga_playershot.json", + "character_galaga_enemyshot.json", + "character_galaga_boom.json", + NULL +}; + +static akerr_ErrorContext *asset_path(char *dir, char *name, char *dest, size_t size) +{ + int count = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, dir, AKERR_NULLPOINTER, "dir"); + FAIL_ZERO_RETURN(errctx, name, AKERR_NULLPOINTER, "name"); + FAIL_ZERO_RETURN(errctx, dest, AKERR_NULLPOINTER, "dest"); + PASS(errctx, aksl_snprintf(&count, dest, size, "%s/%s", dir, name)); + SUCCEED_RETURN(errctx); +} + +/** + * @brief Sprites first, characters second. Not a preference: a character's + * JSON names its sprites by registry name, so a character loaded first fails + * on the first sprite it cannot find. + */ +static akerr_ErrorContext *load_assets(char *assetdir) +{ + char path[GALAGA_PATH_MAX]; + int i = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, assetdir, AKERR_NULLPOINTER, "assetdir"); + for ( i = 0; SPRITE_FILES[i] != NULL; i++ ) { + PASS(errctx, asset_path(assetdir, SPRITE_FILES[i], (char *)&path, sizeof(path))); + PASS(errctx, akgl_sprite_load_json((char *)&path)); + } + for ( i = 0; CHARACTER_FILES[i] != NULL; i++ ) { + PASS(errctx, asset_path(assetdir, CHARACTER_FILES[i], (char *)&path, sizeof(path))); + PASS(errctx, akgl_character_load_json((char *)&path)); + } + SUCCEED_RETURN(errctx); +} + +/* --------------------------------------------------------------- startup --- */ + +/** @brief Replacement for akgl_game.lowfpsfunc, which logs a line per frame. */ +static void galaga_lowfps(void) +{ +} + +static akerr_ErrorContext *startup(void) +{ + PREPARE_ERROR(errctx); + + PASS(errctx, aksl_strncpy((char *)&akgl_game.name, sizeof(akgl_game.name), + "akbasic galaga tutorial", sizeof(akgl_game.name) - 1)); + PASS(errctx, aksl_strncpy((char *)&akgl_game.version, sizeof(akgl_game.version), + "1.0.0", sizeof(akgl_game.version) - 1)); + PASS(errctx, aksl_strncpy((char *)&akgl_game.uri, sizeof(akgl_game.uri), + "net.aklabs.akbasic.galaga", sizeof(akgl_game.uri) - 1)); + + PASS(errctx, akgl_game_init()); + akgl_game.lowfpsfunc = &galaga_lowfps; + + /* Properties before the renderer: akgl_render_2d_init reads both, and an + * unset one defaults to the string "0" -- a zero-sized window. */ + PASS(errctx, akgl_set_property("game.screenwidth", "1280")); + PASS(errctx, akgl_set_property("game.screenheight", "960")); + PASS(errctx, akgl_render_2d_init(akgl_renderer)); + + FAIL_ZERO_RETURN( + errctx, + SDL_SetRenderLogicalPresentation( + akgl_renderer->sdl_renderer, + GALAGA_VIEW_WIDTH, + GALAGA_VIEW_HEIGHT, + SDL_LOGICAL_PRESENTATION_INTEGER_SCALE), + AKGL_ERR_SDL, + "%s", + SDL_GetError() + ); + + /* The view is what the camera looks through, so it says the same thing. */ + akgl_camera->x = 0.0f; + akgl_camera->y = 0.0f; + akgl_camera->w = (float)GALAGA_VIEW_WIDTH; + akgl_camera->h = (float)GALAGA_VIEW_HEIGHT; + + /* + * akgl_game_init does NOT install a physics backend, whatever physics.h's + * file comment says (libakgl docs/14-physics.md). Null physics accepts + * every call and moves nothing: whatever writes x and y directly is the + * mover, and in this game that is BASIC writing through ACTOR@. + */ + PASS(errctx, akgl_physics_init_null(akgl_physics)); + SUCCEED_RETURN(errctx); +} + +/* ---------------------------------------------------------------- the UI --- */ + +static akgl_UiMenu TITLE_MENU = { + "titlemenu", { "START", "QUIT" }, 2, 0, false, NULL +}; +static akgl_UiMenu AGAIN_MENU = { + "againmenu", { "PLAY AGAIN", "QUIT" }, 2, 0, false, NULL +}; + +/* Clay borrows label text until frame_end, so these cannot be locals. */ +static char HUD_SCORE[64]; +static char HUD_LIVES[64]; + +/** + * @brief Draw a headline centred above the menu, in the banner font. + * + * Direct text rather than a ui label: the menu owns AKGL_UI_ANCHOR_CENTER, + * and a label anchored there disappears behind it -- there is no + * top-centre anchor to reach for. Drawn before the UI bracket, so the menu + * still paints over it if the two ever meet. + */ +static akerr_ErrorContext *draw_banner(char *text) +{ + SDL_Color ink = { 235, 235, 235, 255 }; + TTF_Font *font = NULL; + int w = 0; + int h = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, text, AKERR_NULLPOINTER, "text"); + font = SDL_GetPointerProperty(AKGL_REGISTRY_FONT, "banner", NULL); + FAIL_ZERO_RETURN(errctx, font, AKERR_KEY, "the banner font is not loaded"); + PASS(errctx, akgl_text_measure(font, text, &w, &h)); + PASS(errctx, akgl_text_rendertextat(font, text, ink, 0, + (GALAGA_VIEW_WIDTH - w) / 2, 280)); + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *declare_title(void) +{ + PREPARE_ERROR(errctx); + + PASS(errctx, akgl_ui_menu(&TITLE_MENU)); + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *declare_play(void) +{ + int count = 0; + PREPARE_ERROR(errctx); + + PASS(errctx, aksl_snprintf(&count, HUD_SCORE, sizeof(HUD_SCORE), + "SCORE %06d", galaga_game.score)); + PASS(errctx, aksl_snprintf(&count, HUD_LIVES, sizeof(HUD_LIVES), + "LIVES %d WAVE %d", galaga_game.lives, galaga_shared.wave)); + PASS(errctx, akgl_ui_label("score", HUD_SCORE, AKGL_UI_ANCHOR_TOP_LEFT, NULL)); + PASS(errctx, akgl_ui_label("lives", HUD_LIVES, AKGL_UI_ANCHOR_TOP_RIGHT, NULL)); + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *declare_end(void) +{ + PREPARE_ERROR(errctx); + + PASS(errctx, akgl_ui_menu(&AGAIN_MENU)); + SUCCEED_RETURN(errctx); +} + +/* ------------------------------------------------------------ transitions --- */ + +static akerr_ErrorContext *start_game(void) +{ + PREPARE_ERROR(errctx); + + galaga_game.score = 0; + galaga_game.lives = 3; + memset(galaga_game.kills, 0, sizeof(galaga_game.kills)); + memset(galaga_game.shots, 0, sizeof(galaga_game.shots)); + galaga_game.respawn_timer = 0.0f; + galaga_shared.wave = 1; + + galaga_game.player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f; + PASS(errctx, galaga_wave_spawn()); + galaga_game.screen = GALAGA_SCREEN_PLAY; + SUCCEED_RETURN(errctx); +} + +/** + * @brief End-of-round bookkeeping: notice a cleared wave or a spent ship. + */ +static akerr_ErrorContext *check_transitions(bool *running) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running"); + (void)running; + if ( galaga_game.screen != GALAGA_SCREEN_PLAY ) { + SUCCEED_RETURN(errctx); + } + if ( galaga_game.lives <= 0 ) { + PASS(errctx, galaga_wave_release()); + galaga_game.screen = GALAGA_SCREEN_GAMEOVER; + SUCCEED_RETURN(errctx); + } + if ( galaga_enemies_alive() == 0 ) { + galaga_game.screen = GALAGA_SCREEN_VICTORY; + } + SUCCEED_RETURN(errctx); +} + +/** + * @brief Consume a menu activation. The menu never clears `activated`; the + * state machine that acts on it does. + */ +static akerr_ErrorContext *consume_menus(bool *running) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running"); + if ( galaga_game.screen == GALAGA_SCREEN_TITLE && TITLE_MENU.activated ) { + TITLE_MENU.activated = false; + if ( TITLE_MENU.selected == 0 ) { + PASS(errctx, start_game()); + } else { + *running = false; + } + } + if ( (galaga_game.screen == GALAGA_SCREEN_GAMEOVER + || galaga_game.screen == GALAGA_SCREEN_VICTORY) + && AGAIN_MENU.activated ) { + AGAIN_MENU.activated = false; + if ( AGAIN_MENU.selected == 0 ) { + PASS(errctx, galaga_wave_release()); + PASS(errctx, start_game()); + } else { + *running = false; + } + } + SUCCEED_RETURN(errctx); +} + +/* ------------------------------------------------------------- the frame --- */ + +/** + * @brief Route one event: the UI gets first refusal, then the menus, then + * the controller. A consumed event goes no further. + */ +static akerr_ErrorContext *route_event(SDL_Event *event, bool *running) +{ + bool consumed = false; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, event, AKERR_NULLPOINTER, "event"); + FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running"); + + if ( event->type == SDL_EVENT_QUIT ) { + *running = false; + SUCCEED_RETURN(errctx); + } + PASS(errctx, akgl_ui_handle_event((void *)&akgl_game.state, event, &consumed)); + if ( consumed ) { + SUCCEED_RETURN(errctx); + } + if ( galaga_game.screen == GALAGA_SCREEN_TITLE ) { + PASS(errctx, akgl_ui_menu_handle_event(&TITLE_MENU, event, &consumed)); + } else if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER + || galaga_game.screen == GALAGA_SCREEN_VICTORY ) { + PASS(errctx, akgl_ui_menu_handle_event(&AGAIN_MENU, event, &consumed)); + } + if ( consumed ) { + SUCCEED_RETURN(errctx); + } + /* Every event, unconditionally: one that no control map binds is not an + * error, it is a call that did nothing. */ + PASS(errctx, akgl_controller_handle_event((void *)&akgl_game.state, event)); + SUCCEED_RETURN(errctx); +} + +/** @brief The previous frame's timestamp, for dt. Stamped once at loop start. */ +static uint64_t LAST_NS = 0; + +static akerr_ErrorContext *frame(bool *running) +{ + SDL_Event event; + uint64_t now = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, running, AKERR_NULLPOINTER, "running"); + + while ( SDL_PollEvent(&event) == true ) { + PASS(errctx, route_event(&event, running)); + } + + galaga_game.frame += 1; + if ( galaga_game.autoplay ) { + if ( galaga_game.screen == GALAGA_SCREEN_TITLE && galaga_game.frame >= 8 ) { + PASS(errctx, start_game()); + } + /* + * On an end screen the pilot presses Return, which drives the real + * menu path -- declare, handle, activate, restart -- so a headless + * run that dies keeps exercising the game instead of idling. + */ + if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER + || galaga_game.screen == GALAGA_SCREEN_VICTORY ) { + if ( (galaga_game.frame % 30) == 0 ) { + SDL_Event press; + memset(&press, 0, sizeof(press)); + press.type = SDL_EVENT_KEY_DOWN; + press.key.key = SDLK_RETURN; + PASS(errctx, route_event(&press, running)); + } + } + PASS(errctx, galaga_player_autoplay(galaga_game.frame)); + } + + /* + * dt from the wall clock, clamped: a debugger pause or a stalled runner + * must not become one frame of teleporting enemies. The clamp is a 30 Hz + * frame, the slowest game this is still worth playing at. + */ + now = SDL_GetTicksNS(); + galaga_game.dt = (float)(now - LAST_NS) / 1e9f; + LAST_NS = now; + if ( galaga_game.dt > (1.0f / 30.0f) ) { + galaga_game.dt = 1.0f / 30.0f; + } + + /* The shared frame state, refreshed before any enemy thinks. The engine + * filling GAME@.RND% is the issue #16 route: no RND verb exists. */ + galaga_shared.playerx = galaga_game.player->x + 50.0f; + galaga_shared.playery = galaga_game.player->y; + galaga_shared.rnd = galaga_random(); + + PASS(errctx, akgl_renderer->frame_start(akgl_renderer)); + PASS(errctx, starfield_draw()); + + /* + * akgl_game_update is update-every-actor, step-the-physics, draw-the- + * world. Updating every actor is where the forty scripts run: each + * enemy's updatefunc is the hook in enemies.c, and that hook is a BASIC + * call. Held back on the menu screens so the world stands still there. + */ + if ( galaga_game.screen == GALAGA_SCREEN_PLAY ) { + PASS(errctx, akgl_game_update(NULL)); + PASS(errctx, check_transitions(running)); + } + + /* The banner is direct text, drawn before the UI bracket. */ + if ( galaga_game.screen == GALAGA_SCREEN_TITLE ) { + PASS(errctx, draw_banner("GALAGA")); + } else if ( galaga_game.screen == GALAGA_SCREEN_GAMEOVER ) { + PASS(errctx, draw_banner("GAME OVER")); + } else if ( galaga_game.screen == GALAGA_SCREEN_VICTORY ) { + PASS(errctx, draw_banner("VICTORY")); + } + + /* The UI bracket sits between akgl_game_update and frame_end, exactly as + * libakgl docs/22-ui.md draws it. */ + PASS(errctx, akgl_ui_frame_begin()); + switch ( galaga_game.screen ) { + case GALAGA_SCREEN_TITLE: + PASS(errctx, declare_title()); + break; + case GALAGA_SCREEN_PLAY: + PASS(errctx, declare_play()); + break; + case GALAGA_SCREEN_GAMEOVER: + case GALAGA_SCREEN_VICTORY: + PASS(errctx, declare_end()); + break; + } + PASS(errctx, akgl_ui_frame_end(akgl_renderer)); + + PASS(errctx, consume_menus(running)); + + if ( (SHOTPATH != NULL) && (galaga_game.frame == SHOTFRAME) ) { + PASS(errctx, save_screenshot(SHOTPATH)); + } + PASS(errctx, akgl_renderer->frame_end(akgl_renderer)); + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *run(int frames) +{ + bool running = true; + PREPARE_ERROR(errctx); + + LAST_NS = SDL_GetTicksNS(); + while ( running == true ) { + PASS(errctx, frame(&running)); + if ( (frames > 0) && (galaga_game.frame >= frames) ) { + running = false; + } + /* A crude frame limiter. A game on a real display should ask SDL for + * vsync; this one has to work under the dummy video driver, where + * there is nothing to sync to. */ + SDL_Delay(16); + } + SUCCEED_RETURN(errctx); +} + +/* -------------------------------------------------------------- teardown --- */ + +/** + * @brief Give back what the process is holding. + * + * There is no akgl_game_shutdown; teardown is the application's. Fonts have + * to unload before TTF_Quit destroys them underneath the registry. IGNORE() + * on every call: a teardown failure must not mask whatever error is already + * being reported. + */ +static void shutdown_game(void) +{ + int i = 0; + + IGNORE(akgl_ui_shutdown()); + IGNORE(akgl_text_unloadallfonts()); + for ( i = 0; i < AKGL_MAX_HEAP_ACTOR; i++ ) { + if ( akgl_heap_actors[i].refcount > 0 ) { + IGNORE(akgl_heap_release_actor(&akgl_heap_actors[i])); + } + } + TTF_Quit(); + SDL_Quit(); +} + +/* ------------------------------------------------------------------ args --- */ + +static akerr_ErrorContext *parse_args(int argc, char *argv[], char **assetdir, + char **script, int *frames) +{ + int i = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, assetdir, AKERR_NULLPOINTER, "assetdir"); + FAIL_ZERO_RETURN(errctx, script, AKERR_NULLPOINTER, "script"); + FAIL_ZERO_RETURN(errctx, frames, AKERR_NULLPOINTER, "frames"); + + for ( i = 1; i < argc; i++ ) { + if ( strcmp(argv[i], "--autoplay") == 0 ) { + galaga_game.autoplay = true; + } else if ( strcmp(argv[i], "--frames") == 0 ) { + i += 1; + FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--frames needs a count"); + PASS(errctx, aksl_atoi(argv[i], frames)); + } else if ( strcmp(argv[i], "--assets") == 0 ) { + i += 1; + FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--assets needs a directory"); + *assetdir = argv[i]; + } else if ( strcmp(argv[i], "--script") == 0 ) { + i += 1; + FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--script needs a path"); + *script = argv[i]; + } else if ( strcmp(argv[i], "--screenshot") == 0 ) { + i += 1; + FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, "--screenshot needs a path"); + SHOTPATH = argv[i]; + } else if ( strcmp(argv[i], "--screenshot-frame") == 0 ) { + i += 1; + FAIL_NONZERO_RETURN(errctx, (i >= argc), AKERR_VALUE, + "--screenshot-frame needs a number"); + PASS(errctx, aksl_atoi(argv[i], &SHOTFRAME)); + } else { + FAIL_RETURN( + errctx, + AKERR_VALUE, + "usage: galaga [--assets DIR] [--script PATH] [--frames N]" + " [--autoplay] [--screenshot PATH] [--screenshot-frame N]" + ); + } + } + SUCCEED_RETURN(errctx); +} + +int main(int argc, char *argv[]) +{ + char *assetdir = GALAGA_ASSET_DIR; + char *script = GALAGA_SCRIPT_PATH; + int frames = 0; + uint16_t fontid = 0; + PREPARE_ERROR(errctx); + + ATTEMPT { + CATCH(errctx, parse_args(argc, argv, &assetdir, &script, &frames)); + CATCH(errctx, startup()); + CATCH(errctx, load_assets(assetdir)); + /* The engine refuses to start when the script will not boot: a game + * whose enemies cannot think is not a game missing a feature. */ + CATCH(errctx, galaga_script_boot(script)); + CATCH(errctx, akgl_ui_init(GALAGA_VIEW_WIDTH, GALAGA_VIEW_HEIGHT)); + CATCH(errctx, akgl_text_loadfont("hud", GALAGA_FONT_PATH, 28)); + CATCH(errctx, akgl_text_loadfont("banner", GALAGA_FONT_PATH, 84)); + CATCH(errctx, akgl_ui_font_register("hud", &fontid)); + CATCH(errctx, galaga_player_spawn()); + CATCH(errctx, galaga_player_controls()); + starfield_seed(); + galaga_game.screen = GALAGA_SCREEN_TITLE; + galaga_game.lives = 3; + CATCH(errctx, run(frames)); + } CLEANUP { + shutdown_game(); + } PROCESS(errctx) { + } HANDLE_DEFAULT(errctx) { + LOG_ERROR_WITH_MESSAGE(errctx, "galaga could not run"); + /* Set a flag rather than returning: leaving a HANDLE block early + * skips FINISH's RELEASE_ERROR and leaks the context's pool slot. */ + FAILED = 1; + /* FINISH_NORETURN rather than FINISH: FINISH expands a return that an + * int-returning function cannot compile. */ + } FINISH_NORETURN(errctx); + + /* + * The readout is the evidence: exiting 0 is not proof the wave flew. A + * headless CI log gets the same line a reader's terminal does, and the + * script-error count is the line's whole reason to exist -- a wave of + * dumb enemies still exits 0. + */ + SDL_Log( + "galaga: %d frames, screen %d, score %d, alive %d, kills bee %d bfly %d boss %d," + " shots bee %d bfly %d boss %d, script errors %d", + galaga_game.frame, + (int)galaga_game.screen, + galaga_game.score, + galaga_enemies_alive(), + galaga_game.kills[GALAGA_ENEMY_BEE], + galaga_game.kills[GALAGA_ENEMY_BUTTERFLY], + galaga_game.kills[GALAGA_ENEMY_BOSS], + galaga_game.shots[GALAGA_ENEMY_BEE], + galaga_game.shots[GALAGA_ENEMY_BUTTERFLY], + galaga_game.shots[GALAGA_ENEMY_BOSS], + galaga_game.script_errors); + return FAILED; +} diff --git a/examples/galaga/player.c b/examples/galaga/player.c new file mode 100644 index 0000000..f15ba65 --- /dev/null +++ b/examples/galaga/player.c @@ -0,0 +1,407 @@ +/** + * @file player.c + * @brief The player's ship, its shots, and every collision in the game. + * + * Bullets and collision are C forever -- they are engine, not behavior. The + * per-frame budget for the script is spent on the forty things that think; + * nothing here thinks, it just moves and intersects. + */ + +#include +#include +#include + +#include + +#include +#include + +#include +#include +#include +#include +#include +#include + +#include "galaga.h" + +/* Points per kill, indexed by enemy kind. */ +static const int KILL_SCORE[GALAGA_ENEMY_KINDS] = { + /* bee butterfly boss */ + 50, 80, 150 +}; + +static uint32_t PSHOT_SERIAL = 0; + +/* -------------------------------------------------------------- hitboxes --- */ + +/* + * Actor x/y is a sprite's top-left corner. Every box is inset from the + * artwork's rectangle, because the PNGs carry transparent margin and wing + * tips that should not kill anybody. + */ +static void player_box(akgl_Actor *actor, SDL_FRect *dest) +{ + dest->x = actor->x + 12.0f; + dest->y = actor->y + 8.0f; + dest->w = 75.0f; + dest->h = 60.0f; +} + +static void enemy_box(akgl_Actor *actor, SDL_FRect *dest) +{ + dest->x = actor->x + 8.0f; + dest->y = actor->y + 8.0f; + dest->w = 78.0f; + dest->h = 68.0f; +} + +static void shot_box(akgl_Actor *actor, SDL_FRect *dest) +{ + dest->x = actor->x; + dest->y = actor->y; + dest->w = 9.0f; + dest->h = 54.0f; +} + +/* ---------------------------------------------------------- player shots --- */ + +/** + * @brief Kill one enemy: score it, blow it up, free its slot. + */ +static akerr_ErrorContext *kill_enemy(int index) +{ + akgl_Actor *actor = NULL; + galaga_Enemy *enemy = NULL; + PREPARE_ERROR(errctx); + + FAIL_NONZERO_RETURN(errctx, (index < 0 || index >= GALAGA_MAX_ENEMIES), + AKERR_OUTOFBOUNDS, "enemy index %d", index); + actor = galaga_enemy_actors[index]; + FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "enemy %d is already gone", index); + enemy = &galaga_enemies[index]; + + galaga_game.score += KILL_SCORE[enemy->kind]; + galaga_game.kills[enemy->kind] += 1; + PASS(errctx, galaga_boom_spawn(actor->x + 20.0f, actor->y + 20.0f)); + PASS(errctx, akgl_heap_release_actor(actor)); + galaga_enemy_actors[index] = NULL; + SUCCEED_RETURN(errctx); +} + +/** + * @brief Move a player shot and test it against every live enemy. + * + * The classic O(shots x enemies) sweep: at most 2 x 40 rectangle tests a + * frame, which is noise. A hit costs the enemy a point of hp; the boss's + * second point is the script's business to survive, not this file's. + */ +static akerr_ErrorContext *player_shot_update(akgl_Actor *obj) +{ + SDL_FRect mine; + SDL_FRect theirs; + bool hit = false; + int i = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + obj->y -= 900.0f * galaga_game.dt; + if ( obj->y < -60.0f ) { + galaga_game.player_shots_live -= 1; + PASS(errctx, akgl_heap_release_actor(obj)); + SUCCEED_RETURN(errctx); + } + + shot_box(obj, &mine); + for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) { + if ( galaga_enemy_actors[i] == NULL ) { + continue; + } + enemy_box(galaga_enemy_actors[i], &theirs); + PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit)); + if ( !hit ) { + continue; + } + galaga_enemies[i].hp -= 1; + if ( galaga_enemies[i].hp <= 0 ) { + PASS(errctx, kill_enemy(i)); + } + galaga_game.player_shots_live -= 1; + PASS(errctx, akgl_heap_release_actor(obj)); + SUCCEED_RETURN(errctx); + } + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *player_fire(akgl_Actor *player) +{ + akgl_Actor *shot = NULL; + char name[32]; + int count = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, player, AKERR_NULLPOINTER, "player"); + + PSHOT_SERIAL += 1; + PASS(errctx, aksl_snprintf(&count, name, sizeof(name), "pshot%u", PSHOT_SERIAL)); + PASS(errctx, akgl_heap_next_actor(&shot)); + PASS(errctx, akgl_actor_initialize(shot, name)); + PASS(errctx, akgl_actor_set_character(shot, "galaga_playershot")); + /* AFTER initialize: it resets all seven hooks. */ + shot->updatefunc = &player_shot_update; + shot->movement_controls_face = false; + shot->state = AKGL_ACTOR_STATE_ALIVE; + shot->visible = true; + shot->x = player->x + 45.0f; + shot->y = player->y - 44.0f; + + galaga_game.player_shots_live += 1; + galaga_game.fire_cooldown = 0.22f; + SUCCEED_RETURN(errctx); +} + +/* ----------------------------------------------------------- player hit --- */ + +static akerr_ErrorContext *player_hit(akgl_Actor *player) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, player, AKERR_NULLPOINTER, "player"); + galaga_game.lives -= 1; + galaga_game.respawn_timer = 2.0f; + PASS(errctx, galaga_boom_spawn(player->x + 25.0f, player->y + 10.0f)); + player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f; + SUCCEED_RETURN(errctx); +} + +/** + * @brief The player's own update hook: motion, fire, and what can kill it. + */ +static akerr_ErrorContext *player_update(akgl_Actor *obj) +{ + SDL_FRect mine; + SDL_FRect theirs; + bool hit = false; + float dx = 0.0f; + int i = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + + dx = 0.0f; + if ( galaga_game.moveleft ) { + dx -= GALAGA_PLAYER_SPEED; + } + if ( galaga_game.moveright ) { + dx += GALAGA_PLAYER_SPEED; + } + obj->x += dx * galaga_game.dt; + if ( obj->x < GALAGA_PLAYER_MARGIN ) { + obj->x = GALAGA_PLAYER_MARGIN; + } + if ( obj->x > (float)GALAGA_VIEW_WIDTH - GALAGA_PLAYER_MARGIN - 99.0f ) { + obj->x = (float)GALAGA_VIEW_WIDTH - GALAGA_PLAYER_MARGIN - 99.0f; + } + + galaga_game.fire_cooldown -= galaga_game.dt; + if ( galaga_game.firing + && galaga_game.fire_cooldown <= 0.0f + && galaga_game.player_shots_live < GALAGA_MAX_PLAYER_SHOTS + && galaga_game.screen == GALAGA_SCREEN_PLAY ) { + PASS(errctx, player_fire(obj)); + } + + /* + * Respawn grace: two seconds of blinking invulnerability. The blink is + * the `visible` flag, which is deliberate hiding -- the actor still + * updates, it just is not drawn on the off frames. + */ + if ( galaga_game.respawn_timer > 0.0f ) { + galaga_game.respawn_timer -= galaga_game.dt; + obj->visible = ((galaga_game.frame / 6) % 2) == 0; + SUCCEED_RETURN(errctx); + } + obj->visible = true; + + player_box(obj, &mine); + + /* Enemy shots. */ + for ( i = 0; i < AKGL_MAX_HEAP_ACTOR; i++ ) { + if ( akgl_heap_actors[i].refcount == 0 ) { + continue; + } + if ( strncmp(akgl_heap_actors[i].name, "eshot", 5) != 0 ) { + continue; + } + shot_box(&akgl_heap_actors[i], &theirs); + PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit)); + if ( hit ) { + galaga_game.enemy_shots_live -= 1; + PASS(errctx, akgl_heap_release_actor(&akgl_heap_actors[i])); + PASS(errctx, player_hit(obj)); + SUCCEED_RETURN(errctx); + } + } + + /* Diving enemies. The formation never reaches this low, so testing all + * forty is the same answer as testing the divers, without a state read. */ + for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) { + if ( galaga_enemy_actors[i] == NULL ) { + continue; + } + enemy_box(galaga_enemy_actors[i], &theirs); + PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit)); + if ( hit ) { + PASS(errctx, kill_enemy(i)); + PASS(errctx, player_hit(obj)); + SUCCEED_RETURN(errctx); + } + } + SUCCEED_RETURN(errctx); +} + +/* -------------------------------------------------------------- controls --- */ + +static akerr_ErrorContext *left_on(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.moveleft = true; + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *left_off(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.moveleft = false; + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *right_on(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.moveright = true; + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *right_off(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.moveright = false; + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *fire_on(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.firing = true; + SUCCEED_RETURN(errctx); +} + +static akerr_ErrorContext *fire_off(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + galaga_game.firing = false; + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_player_controls(void) +{ + akgl_Control control; + PREPARE_ERROR(errctx); + + memset(&control, 0, sizeof(control)); + control.event_on = SDL_EVENT_KEY_DOWN; + control.event_off = SDL_EVENT_KEY_UP; + + control.key = SDLK_LEFT; + control.handler_on = &left_on; + control.handler_off = &left_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + control.key = SDLK_RIGHT; + control.handler_on = &right_on; + control.handler_off = &right_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + control.key = SDLK_SPACE; + control.handler_on = &fire_on; + control.handler_off = &fire_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + akgl_controlmaps[0].target = galaga_game.player; + SUCCEED_RETURN(errctx); +} + +/* ----------------------------------------------------------------- spawn --- */ + +akerr_ErrorContext *galaga_player_spawn(void) +{ + akgl_Actor *player = NULL; + PREPARE_ERROR(errctx); + + PASS(errctx, akgl_heap_next_actor(&player)); + PASS(errctx, akgl_actor_initialize(player, "player")); + PASS(errctx, akgl_actor_set_character(player, "galaga_player")); + /* AFTER initialize: it resets all seven hooks. */ + player->updatefunc = &player_update; + player->movement_controls_face = false; + player->state = AKGL_ACTOR_STATE_ALIVE; + player->visible = true; + player->x = (float)GALAGA_VIEW_WIDTH / 2.0f - 50.0f; + player->y = GALAGA_PLAYER_Y; + + galaga_game.player = player; + SUCCEED_RETURN(errctx); +} + +/* -------------------------------------------------------------- autoplay --- */ + +/** + * @brief Send one synthetic key event through the controller. + * + * Through akgl_controller_handle_event(), never the handlers directly: the + * point of autoplay is to exercise the same path a keyboard does. + */ +static akerr_ErrorContext *synth_key(SDL_Keycode key, bool down) +{ + SDL_Event event; + PREPARE_ERROR(errctx); + + memset(&event, 0, sizeof(event)); + event.type = (down ? SDL_EVENT_KEY_DOWN : SDL_EVENT_KEY_UP); + event.key.key = key; + PASS(errctx, akgl_controller_handle_event((void *)&akgl_game.state, &event)); + SUCCEED_RETURN(errctx); +} + +/** + * @brief The scripted pilot for headless runs: hold fire, sweep the floor. + */ +akerr_ErrorContext *galaga_player_autoplay(int frame) +{ + int phase = 0; + PREPARE_ERROR(errctx); + + /* Hold fire until the wave has mostly assembled: shooting the entry + * stream point-blank empties the formation before it exists, which makes + * both the game and its figure worse. */ + if ( frame == 300 ) { + PASS(errctx, synth_key(SDLK_SPACE, true)); + } + phase = frame % 240; + if ( phase == 30 ) { + PASS(errctx, synth_key(SDLK_LEFT, true)); + } else if ( phase == 90 ) { + PASS(errctx, synth_key(SDLK_LEFT, false)); + PASS(errctx, synth_key(SDLK_RIGHT, true)); + } else if ( phase == 210 ) { + PASS(errctx, synth_key(SDLK_RIGHT, false)); + } + SUCCEED_RETURN(errctx); +} diff --git a/examples/galaga/script.c b/examples/galaga/script.c new file mode 100644 index 0000000..b588430 --- /dev/null +++ b/examples/galaga/script.c @@ -0,0 +1,281 @@ +/** + * @file script.c + * @brief The boundary: everything that touches the interpreter lives here. + * + * One runtime, one script, three host types, three bindings. The engine calls + * exactly one thing per enemy per frame -- galaga_script_update_enemy() -- and + * that function is the whole protocol: rebind, call, recover, reset. + * + * The structure types are declared once, in C, right below. The script never + * declares a TYPE of its own; akbasic_host_register_type() makes these structs + * *be* the BASIC types, offsets taken from offsetof() so the two sides cannot + * drift (include/akbasic/host.h). + */ + +#include +#include +#include +#include +#include + +#include + +#include + +#include +#include +#include +#include +#include + +#include "galaga.h" + +/* The interpreter. Static because an akbasic_Runtime is far too big for a + * stack frame -- 2.40 MiB on this branch. */ +static akbasic_Runtime SCRIPT; +static akbasic_TextSink SINK; +static akbasic_StdioSink SINKSTATE; + +/** @brief Longest galaga.bas this loader will accept. */ +#define GALAGA_MAX_SCRIPT_BYTES 16384 + +static char SOURCE[GALAGA_MAX_SCRIPT_BYTES]; + +/* + * Enemy kind -> BASIC function name. Dispatch is a table, not a conditional: + * adding a kind is one row here and one DEF in galaga.bas. + */ +static const char *UPDATE_FUNCTION[GALAGA_ENEMY_KINDS] = { + "UPDATEBEE", /* GALAGA_ENEMY_BEE */ + "UPDATEBFLY", /* GALAGA_ENEMY_BUTTERFLY */ + "UPDATEBOSS" /* GALAGA_ENEMY_BOSS */ +}; + +/* ---------------------------------------------------------- host types --- */ + +static const akbasic_HostField ENEMY_FIELDS[] = { + /* struct member BASIC name C representation */ + AKBASIC_HOST_FIELD( galaga_Enemy, kind, "KIND#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, state, "STATE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, homex, "HOMEX%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, homey, "HOMEY%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, t, "T%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, hp, "HP#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, fire, "FIRE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, rnd, "RND%", AKBASIC_HOSTFIELD_FLOAT ) +}; +static const akbasic_HostType ENEMY_TYPE = { + "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8 +}; + +/* + * The live actor itself. This is the demonstrative point of the whole + * example: the script writes the engine's *real* actor memory -- the same x + * the renderer reads -- with no copy in either direction. + */ +static const akbasic_HostField ACTOR_FIELDS[] = { + AKBASIC_HOST_FIELD( akgl_Actor, x, "X%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( akgl_Actor, y, "Y%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( akgl_Actor, state, "STATE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( akgl_Actor, visible, "VISIBLE#", AKBASIC_HOSTFIELD_BOOL ) +}; +static const akbasic_HostType ACTOR_TYPE = { + "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 4 +}; + +static const akbasic_HostField GAME_FIELDS[] = { + AKBASIC_HOST_FIELD( galaga_Shared, playerx, "PLAYERX%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Shared, playery, "PLAYERY%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Shared, wave, "WAVE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Shared, rnd, "RND%", AKBASIC_HOSTFIELD_FLOAT ) +}; +static const akbasic_HostType GAME_TYPE = { + "GAME", sizeof(galaga_Shared), GAME_FIELDS, 4 +}; + +/* Placeholders the boot bindings point at until the first real rebind. A + * binding is borrowed, never copied, so these must be static storage. */ +static galaga_Enemy SCRATCH_ENEMY; +static akgl_Actor SCRATCH_ACTOR; + +/* ---------------------------------------------------------------- boot --- */ + +static akerr_ErrorContext *read_script(char *path) +{ + FILE *fp = NULL; + size_t got = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path"); + fp = fopen(path, "rb"); + FAIL_ZERO_RETURN(errctx, fp, AKERR_IO, "Cannot open the enemy script %s", path); + ATTEMPT { + got = fread(SOURCE, 1, sizeof(SOURCE) - 1, fp); + SOURCE[got] = '\0'; + FAIL_NONZERO_BREAK(errctx, (got >= sizeof(SOURCE) - 1), AKERR_OUTOFBOUNDS, + "%s does not fit in the %d byte script buffer", + path, GALAGA_MAX_SCRIPT_BYTES); + } CLEANUP { + fclose(fp); + } PROCESS(errctx) { + } FINISH(errctx, true); + SUCCEED_RETURN(errctx); +} + +/** + * @brief One dry call of every dispatch-table function, at boot. + * + * A missing or misspelled DEF fails here, at startup, with the function's name + * in the message -- not on frame one of the first wave. The scratch enemy's + * state word is zero, so no maneuver block runs and nothing moves. + */ +static akerr_ErrorContext *dry_run(void) +{ + akbasic_Value dt; + akbasic_Value *argp[1]; + akbasic_Value *result = NULL; + int i = 0; + PREPARE_ERROR(errctx); + + memset(&SCRATCH_ENEMY, 0, sizeof(SCRATCH_ENEMY)); + memset(&dt, 0, sizeof(dt)); + dt.valuetype = AKBASIC_TYPE_FLOAT; + dt.floatval = 0.0; + argp[0] = &dt; + + for ( i = 0; i < GALAGA_ENEMY_KINDS; i++ ) { + PASS(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", &SCRATCH_ENEMY)); + PASS(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", &SCRATCH_ACTOR)); + PASS(errctx, akbasic_runtime_call_function(&SCRIPT, (char *)UPDATE_FUNCTION[i], + argp, 1, &result)); + /* + * A body that died reports through the sink and answers zero; the + * dropped mode is the only signal C gets. At boot that must be fatal + * and must say which function -- not frame one of the first wave. + */ + FAIL_NONZERO_RETURN(errctx, (SCRIPT.mode != AKBASIC_MODE_RUN), AKERR_VALUE, + "%s died during the boot dry run; the interpreter's report" + " is above", UPDATE_FUNCTION[i]); + PASS(errctx, akbasic_environment_zero(SCRIPT.environment)); + } + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_script_boot(char *path) +{ + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, path, AKERR_NULLPOINTER, "path"); + + PASS(errctx, akbasic_error_register()); + PASS(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL)); + PASS(errctx, akbasic_runtime_init(&SCRIPT, &SINK)); + + PASS(errctx, akbasic_host_register_type(&SCRIPT, &ENEMY_TYPE)); + PASS(errctx, akbasic_host_register_type(&SCRIPT, &ACTOR_TYPE)); + PASS(errctx, akbasic_host_register_type(&SCRIPT, &GAME_TYPE)); + + PASS(errctx, akbasic_host_bind(&SCRIPT, "SELF@", "ENEMY", &SCRATCH_ENEMY)); + PASS(errctx, akbasic_host_bind(&SCRIPT, "ACTOR@", "ACTOR", &SCRATCH_ACTOR)); + PASS(errctx, akbasic_host_bind(&SCRIPT, "GAME@", "GAME", &galaga_shared)); + + PASS(errctx, read_script(path)); + PASS(errctx, akbasic_runtime_load(&SCRIPT, SOURCE)); + + /* + * A "no top level code" script still has to run once: executing the DEF + * statements is what files the functions. The run is bounded because a + * script that is all definitions has no business taking more than a step + * per line, and an accidental loop at boot should be a diagnosis, not a + * hang. + */ + PASS(errctx, akbasic_runtime_start(&SCRIPT, AKBASIC_MODE_RUN)); + PASS(errctx, akbasic_runtime_run(&SCRIPT, 4 * AKBASIC_MAX_SOURCE_LINES)); + + /* + * The program has now ended and the runtime sits in QUIT mode, where a + * multi-line DEF called from the host returns a silent zero. Forcing the + * mode back makes the bodies run, and it stays put because nothing here + * ever steps the runtime again. Issue #8 tracks making this unnecessary. + */ + PASS(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN)); + + PASS(errctx, dry_run()); + SUCCEED_RETURN(errctx); +} + +/* ------------------------------------------------------------ per frame --- */ + +akerr_ErrorContext *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt) +{ + akbasic_Value dtval; + akbasic_Value *argp[1]; + akbasic_Value *result = NULL; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "enemy"); + FAIL_ZERO_RETURN(errctx, actor, AKERR_NULLPOINTER, "actor"); + FAIL_NONZERO_RETURN(errctx, (enemy->kind < 0 || enemy->kind >= GALAGA_ENEMY_KINDS), + AKERR_VALUE, "Enemy kind %d has no update function", enemy->kind); + + PASS(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy)); + PASS(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor)); + + memset(&dtval, 0, sizeof(dtval)); + dtval.valuetype = AKBASIC_TYPE_FLOAT; + dtval.floatval = (double)dt; + argp[0] = &dtval; + + /* + * An error in an enemy's function is that script's problem, not the + * engine's: the enemy goes dumb -- cleared to a formation hold it will + * never leave -- and the frame lives. HANDLE_DEFAULT absorbs whatever the + * interpreter raised; the first failure is logged with the function's + * name, the rest are counted, because sixty a second of the same message + * is how a log stops being read. + */ + ATTEMPT { + CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, (char *)UPDATE_FUNCTION[enemy->kind], + argp, 1, &result)); + } CLEANUP { + } PROCESS(errctx) { + } HANDLE_DEFAULT(errctx) { + if ( galaga_game.script_errors == 0 ) { + LOG_ERROR_WITH_MESSAGE(errctx, "first script error; this enemy is now dumb"); + } + galaga_game.script_errors += 1; + enemy->state = GALAGA_ES_FORMATION; + enemy->fire = 0; + } FINISH(errctx, true); + + /* + * A BASIC-level error in the body is quieter than an interpreter error: + * it reports through the sink, the call answers a stale value, and the + * runtime falls out of RUN mode -- after which every later call is a + * silent no-op. The mode is the tell. Revival is two calls: + * clear_error(), because a run's first error latches and every line is + * skipped while it stands, and the same set_mode(RUN) the boot needed + * (issue #8's mechanics). The enemy is treated exactly like the + * interpreter-error case above. + */ + if ( SCRIPT.mode != AKBASIC_MODE_RUN ) { + if ( galaga_game.script_errors == 0 ) { + SDL_Log("first script error (reported by the interpreter above);" + " enemy %s is now dumb", UPDATE_FUNCTION[enemy->kind]); + } + galaga_game.script_errors += 1; + enemy->state = GALAGA_ES_FORMATION; + enemy->fire = 0; + PASS(errctx, akbasic_runtime_clear_error(&SCRIPT)); + PASS(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN)); + } + + /* + * Load-bearing: akbasic_runtime_call_function() parks every result in the + * caller environment's per-line value scratch, and a host calling in a + * loop never crosses the line boundary that would reset it. Without this + * the pool drains in under two frames of a 40-enemy wave. + */ + PASS(errctx, akbasic_environment_zero(SCRIPT.environment)); + SUCCEED_RETURN(errctx); +} -- 2.43.0 From 47c6be58c5e3c41b8d840c36c475efa064321693 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 08:47:42 -0400 Subject: [PATCH 4/7] Update the breakout chapter's scope-pool figure to this branch's 12 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- docs/17-tutorial-breakout.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/17-tutorial-breakout.md b/docs/17-tutorial-breakout.md index 547c4de..5ea37e6 100644 --- a/docs/17-tutorial-breakout.md +++ b/docs/17-tutorial-breakout.md @@ -685,9 +685,9 @@ seconds asks for fifty frames a second. ### Why `GOTO` rather than `DO ... LOOP` A `DO ... LOOP` around the frame would read better, and it is not usable here: **a `GOTO` -that jumps out of a `FOR` or a `DO` does not release the loop's scope.** There are 32 +that jumps out of a `FOR` or a `DO` does not release the loop's scope.** There are 12 scopes, so a game that leaves its main loop once per lost life stops on the -thirty-second one: +twelfth one: ```basic N# = 0 @@ -700,7 +700,7 @@ PRINT "SURVIVED " + N# ``` ```output -? 3 : PARSE ERROR Environment pool exhausted at line 3 (32 in use) +? 3 : PARSE ERROR Environment pool exhausted at line 3 (12 in use) ``` -- 2.43.0 From d5a0edd692ca9d3cd9b3ef8338a8a8e9f6394b5d Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 08:47:43 -0400 Subject: [PATCH 5/7] Write the GALAGA tutorial chapters and the repeated-host-calls guide 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- CLAUDE.md | 2 +- README.md | 2 +- docs/10-embedding.md | 44 ++ docs/20-tutorial-galaga.md | 619 +++++++++++++++++++++++++++ docs/21-tutorial-galaga-enemies.md | 515 ++++++++++++++++++++++ docs/README.md | 7 +- tests/docs_preludes/galagacalls.post | 8 + tests/docs_preludes/galagacalls.pre | 53 +++ tests/docs_preludes/galagagame.pre | 121 ++++++ tests/docs_preludes/galagahost.post | 6 + tests/docs_preludes/galagahost.pre | 55 +++ tests/docs_preludes/galagatypes.pre | 37 ++ tests/docs_preludes/hostcalls.post | 2 + tests/docs_preludes/hostcalls.pre | 3 + 14 files changed, 1471 insertions(+), 3 deletions(-) create mode 100644 docs/20-tutorial-galaga.md create mode 100644 docs/21-tutorial-galaga-enemies.md create mode 100644 tests/docs_preludes/galagacalls.post create mode 100644 tests/docs_preludes/galagacalls.pre create mode 100644 tests/docs_preludes/galagagame.pre create mode 100644 tests/docs_preludes/galagahost.post create mode 100644 tests/docs_preludes/galagahost.pre create mode 100644 tests/docs_preludes/galagatypes.pre diff --git a/CLAUDE.md b/CLAUDE.md index 7e6eaa1..167a58d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,7 @@ scripting engine for game authors. | [the issue tracker](https://source.starfort.tech/andrew/akbasic/issues) | **Outstanding defects and gaps.** Labelled by kind and blast radius; `status::grooming` means the scope is not settled yet | | [`TODO.md`](TODO.md) | The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on | | [`README.md`](README.md) | What the project is and why, for somebody who has not seen it | -| [`docs/`](docs/README.md) | The language itself: eighteen chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/` | +| [`docs/`](docs/README.md) | The language itself: twenty-one chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/`; [Chapters 20](docs/20-tutorial-galaga.md) and [21](docs/21-tutorial-galaga-enemies.md) build the embedding host in `examples/galaga/` | | `deps/libakerror/AGENTS.md` | The `ATTEMPT`/`CLEANUP`/`PROCESS`/`HANDLE`/`FINISH` protocol, authoritatively | | `deps/libakerror/UPGRADING.md` | 1.0.0's status registry. Required before writing an error code | | `deps//AGENTS.md` | Per-repo rules. Read the relevant one **before editing a submodule** | diff --git a/README.md b/README.md index 6dce36a..6f6819c 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ version are catalogued in [`TODO.md`](TODO.md) and summarised for a BASIC progra | | | |---|---| -| [`docs/`](docs/README.md) | The guide: eighteen chapters, the language then each hardware area then a reference section for every verb and function, [Chapter 14](docs/14-architecture.md) on the interpreter's own architecture, [Chapter 15](docs/15-error-codes.md) listing every error code, and [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) building a whole game twice | +| [`docs/`](docs/README.md) | The guide: twenty-one chapters, the language then each hardware area then a reference section for every verb and function, [Chapter 14](docs/14-architecture.md) on the interpreter's own architecture, [Chapter 15](docs/15-error-codes.md) listing every error code, [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) building a whole game twice, and [Chapters 20](docs/20-tutorial-galaga.md) and [21](docs/21-tutorial-galaga-enemies.md) building a C game that embeds the interpreter | | [`MAINTENANCE.md`](MAINTENANCE.md) | For contributors and maintainers: the documentation-example harness, the three test lists, mutation testing, error-code allocation, style | | [`TODO.md`](TODO.md) | Outstanding defects, with file, line and consequence | | [`tests/reference/README.md`](tests/reference/README.md) | Where the golden corpus came from, and the rule for changing it | diff --git a/docs/10-embedding.md b/docs/10-embedding.md index 236e1e4..422eef7 100644 --- a/docs/10-embedding.md +++ b/docs/10-embedding.md @@ -100,6 +100,50 @@ bounded run is usually inside a `FOR` or `GOSUB` body, and a variable created th dies when the body pops — silently, with the script reading it correctly right up until it stops. +## Calling a function every frame + +`akbasic_runtime_call_function()` calls a `DEF` by name with values you already +hold — the entry point a game loop wants. A host that calls it repeatedly signs +up for three rules the one-shot examples never meet: + +```c wrap=hostcalls +CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "THINK", argp, 1, &result)); +/* ...consume the result... */ +CATCH(errctx, akbasic_environment_zero(SCRIPT.environment)); +``` + +1. **Reset the value scratch after every call, once the result is consumed.** + Each call parks its result in the caller environment's per-line scratch + (`AKBASIC_MAX_VALUES` slots), and a host calling in a loop never crosses the + line boundary that would reset it. Skip the `akbasic_environment_zero()` and + the pool drains — measured at under two frames of forty calls — after which + every call fails with `Maximum values per line reached`. The reset also + invalidates `result`, which is why it comes after the consumption. +2. **Force RUN mode once after the boot run.** A multi-line `DEF` body only + runs while the runtime is in RUN mode, and by the time a host can call, the + program that filed the definitions has ended. One + `akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN)` after + `akbasic_runtime_run()` makes the bodies run, and the mode stays put because + nothing steps the runtime between calls. Issue #8 tracks making this + unnecessary. +3. **Revive after a script error, deliberately.** A BASIC-level error inside a + called body reports through the sink, answers a stale value, and latches: + the runtime leaves RUN mode and every later call does nothing. When your + policy is to absorb the error and keep calling — a game marking one actor + dumb rather than killing the frame — the revival is two calls: + `akbasic_runtime_clear_error()`, then `akbasic_runtime_set_mode(RUN)` again. + The latch is deliberate for *programs* — the first error ends a run, once, + with one line — so nothing clears it for you. + +Do not pass structures as per-frame arguments. A structure or pointer parameter +spends a value-pool slot on every call and the pool never reclaims, so the +interface dies after about a thousand calls — issue #36 has the measurements. +Bind the instance once with `akbasic_host_bind()` and point it at each object +with `akbasic_host_rebind()` ([Chapter 16](16-structures.md)), which spends +nothing per call. The GALAGA tutorial ([Chapters 20](20-tutorial-galaga.md) +and [21](21-tutorial-galaga-enemies.md)) is this whole recipe as a working +game, forty calls a frame. + ## Where the output goes `PRINT` writes through an `akbasic_TextSink`, which is a record of function pointers plus diff --git a/docs/20-tutorial-galaga.md b/docs/20-tutorial-galaga.md new file mode 100644 index 0000000..a799c4e --- /dev/null +++ b/docs/20-tutorial-galaga.md @@ -0,0 +1,619 @@ +# 20. Tutorial: GALAGA — a C engine with a BASIC brain + +This chapter and [Chapter 21](21-tutorial-galaga-enemies.md) build a GALAGA-style +fixed shooter from an empty file. The engine — window, starfield, bullets, +collision, score, screens — is C on libakgl. The enemies think in BASIC: one +script of `DEF` functions is called once per enemy per frame, and it reads and +writes the engine's own structures with no marshalling in either direction. +This chapter builds the engine and proves the boundary works; the next one +fills in the data structures and the AI. + +The split is the point. Everything mechanical stays compiled, and everything an +enemy *decides* is a text file you can edit and re-run without rebuilding. It is +an academic exercise in *how* such an embed is done, not a claim that it is the +best way to write a GALAGA. + +This is what the two chapters build: + +![A full wave: four green bosses, two rows of butterflies, bees still streaming into the grid, the player firing](images/galaga-wave.png) + +The finished program is [`examples/galaga/`](../examples/galaga/): four C files, +one `galaga.bas`, and the assets. You do not need it to follow along, but it is +the same program assembled. + +```sh norun +$ cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON +$ cmake --build build-akgl --target akbasic_example_galaga +$ ./build-akgl/akbasic_example_galaga +``` + +| Key | Does | +|---|---| +| left / right | move the ship | +| space | fire — two shots on screen at a time, the classic rule | +| return | choose a menu entry | + +## What you will do + +- **[Step 1](#step-1-open-a-window)** — open a window, in the one startup order + that works +- **[Step 2](#step-2-scatter-a-starfield)** — scatter a starfield and scroll it, + with no parallax machinery at all +- **[Step 3](#step-3-put-a-ship-on-screen)** — put a ship on screen from a + sprite and a character file, and drive it from the keyboard +- **[Step 4](#step-4-shots-and-collision)** — spawn shots from the actor heap + and collide them by hand +- **[Step 5](#step-5-boot-the-interpreter)** — link the interpreter in, load a + script of definitions, and call one from C +- **[Step 6](#step-6-the-update-hook)** — replace an actor's update hook so its + every frame is a BASIC call +- **[Step 7](#step-7-first-light)** — watch one enemy move under BASIC control, + and read the same numbers from both sides +- **[Step 8](#step-8-screens)** — add the title, game over and victory screens +- **[Step 9](#step-9-run-it-headless)** — run the whole game headless, so CI can + play it every night + +Each step compiles and runs. The C fragments quote the finished example; the +file layout there — `main.c` for the harness, `script.c` for the boundary, +`enemies.c` and `player.c` for the actors — is a good one to copy. + +--- + +## Step 1: Open a window + +**Goal: a black window with a title, from the canonical startup order.** + +libakgl has one startup sequence that works, documented at the top of its +`include/akgl/game.h` and walked through in its own tutorial (libakgl +docs/20-tutorial-sidescroller.md). The order matters twice: the screen +properties are read by the renderer, so they must be set before it exists, and +`akgl_game_init()` does **not** install a physics backend, so the application +must. + +```c wrap=galagatypes requires=akgl +static akerr_ErrorContext *startup(void) +{ + PREPARE_ERROR(errctx); + + PASS(errctx, aksl_strncpy((char *)&akgl_game.name, sizeof(akgl_game.name), + "akbasic galaga tutorial", sizeof(akgl_game.name) - 1)); + PASS(errctx, aksl_strncpy((char *)&akgl_game.version, sizeof(akgl_game.version), + "1.0.0", sizeof(akgl_game.version) - 1)); + PASS(errctx, aksl_strncpy((char *)&akgl_game.uri, sizeof(akgl_game.uri), + "net.aklabs.akbasic.galaga", sizeof(akgl_game.uri) - 1)); + + PASS(errctx, akgl_game_init()); + + PASS(errctx, akgl_set_property("game.screenwidth", "1280")); + PASS(errctx, akgl_set_property("game.screenheight", "960")); + PASS(errctx, akgl_render_2d_init(akgl_renderer)); + + FAIL_ZERO_RETURN( + errctx, + SDL_SetRenderLogicalPresentation( + akgl_renderer->sdl_renderer, + 1280, + 960, + SDL_LOGICAL_PRESENTATION_INTEGER_SCALE), + AKGL_ERR_SDL, + "%s", + SDL_GetError() + ); + akgl_camera->x = 0.0f; + akgl_camera->y = 0.0f; + akgl_camera->w = 1280.0f; + akgl_camera->h = 960.0f; + + PASS(errctx, akgl_physics_init_null(akgl_physics)); + SUCCEED_RETURN(errctx); +} +``` + +Three of those lines deserve their reasons. + +**The view is 1280x960 because the artwork is ~100 pixels wide.** libakgl draws +a sprite at the sprite's own size — `akgl_Actor.scale` is overwritten every +frame, so there is no way to draw one smaller (libakgl docs/12-actors.md) — and +a ten-column formation of 100-pixel ships needs 1120 pixels plus margins. The +view is sized to the art rather than the art resized to a view. + +**`akgl_physics_init_null()` is not optional.** Skip it and the first +`akgl_game_update()` calls through a NULL `simulate` pointer. Null physics +accepts every call and moves nothing, which is exactly right here: whatever +writes `x` and `y` directly is the mover, and in this game that will be BASIC. + +**Error handling is the house protocol.** Every function returns +`akerr_ErrorContext *`, `PASS` propagates, `ATTEMPT`/`CATCH`/`CLEANUP` brackets +anything that must unwind. libakgl's docs/04-errors.md teaches it; this chapter +just uses it. + +The frame loop is the standard bracket, with one addition you will meet in +Step 6 — for now, events in, world drawn, frame out: + +```c wrap=galagahost requires=akgl +while ( SDL_PollEvent(&event) == true ) { + CATCH(errctx, akgl_controller_handle_event((void *)&akgl_game.state, &event)); +} +CATCH(errctx, akgl_renderer->frame_start(akgl_renderer)); +CATCH(errctx, akgl_game_update(NULL)); +CATCH(errctx, akgl_renderer->frame_end(akgl_renderer)); +``` + +`akgl_game_update(NULL)` is update-every-actor, step-the-physics, +draw-the-world. It neither clears nor presents; the `frame_start` and +`frame_end` calls own that. + +## Step 2: Scatter a starfield + +**Goal: a scrolling two-depth starfield, from an array and one draw call.** + +No parallax facility exists in libakgl and none is needed. A fixed array of +stars, advanced per frame and drawn with `akgl_draw_point()` between +`frame_start` and `akgl_game_update()`, is the whole feature. Two speed bands +give the depth for free — the slow band reads as far away: + +```c wrap=galagatypes requires=akgl +#define GALAGA_STARS 96 + +static struct +{ + float x; + float y; + float speed; + Uint8 bright; +} STARS[GALAGA_STARS]; + +static akerr_ErrorContext *starfield_draw(float dt) +{ + SDL_Color color = { 255, 255, 255, 255 }; + int i = 0; + PREPARE_ERROR(errctx); + + for ( i = 0; i < GALAGA_STARS; i++ ) { + STARS[i].y += STARS[i].speed * dt; + if ( STARS[i].y > 960.0f ) { + STARS[i].y -= 960.0f; + } + color.r = STARS[i].bright; + color.g = STARS[i].bright; + color.b = STARS[i].bright; + PASS(errctx, akgl_draw_point(akgl_renderer, STARS[i].x, STARS[i].y, color)); + } + SUCCEED_RETURN(errctx); +} +``` + +Seed the array once at startup — even indexes slow and dim (speed 40, bright +110), odd indexes fast and bright (speed 110, bright 220) — and the effect is +done. A point is exactly one pixel (libakgl docs/09-drawing.md). + +## Step 3: Put a ship on screen + +**Goal: a player actor, drawn from a character file, moving on key input.** + +The art is Kenney's Space Shooter pack, CC0, used byte for byte — see +[`examples/galaga/assets/art/PROVENANCE.md`](../examples/galaga/assets/art/PROVENANCE.md) +for what each file is. An actor gets its looks from a **character**, which maps +actor state words to **sprites** (libakgl docs/10 and 12). Both are JSON; load +sprites first, because a character names its sprites and a character loaded +first fails on the first name it cannot find. + +The spawn is four decisions after the two boilerplate calls: + +```c wrap=galagagame requires=akgl +static akerr_ErrorContext *galaga_player_spawn(void) +{ + akgl_Actor *player = NULL; + PREPARE_ERROR(errctx); + + PASS(errctx, akgl_heap_next_actor(&player)); + PASS(errctx, akgl_actor_initialize(player, "player")); + PASS(errctx, akgl_actor_set_character(player, "galaga_player")); + /* AFTER initialize: it resets all seven hooks. */ + player->updatefunc = &player_update; + player->movement_controls_face = false; + player->state = AKGL_ACTOR_STATE_ALIVE; + player->visible = true; + player->x = 590.0f; + player->y = 860.0f; + + galaga_game.player = player; + SUCCEED_RETURN(errctx); +} +``` + +Each of the four lines under the comment closes a trap: + +- **`updatefunc` after `akgl_actor_initialize()`**, never before — initialize + installs all seven default hooks, and a hook set first is a hook reset. +- **`movement_controls_face = false`.** The default facing logic edits the + state word, a character mapping matches the **whole** word, and an actor + whose state matches no mapping is *silently not drawn*. Nothing here moves by + state bits, so facing stays out of the word entirely. +- **`state = AKGL_ACTOR_STATE_ALIVE`** — the word the character mapping names. +- **`visible = true`.** `akgl_actor_initialize()` does not raise it. In a + tilemap game the map loader copies visibility from map data; there is no map + here, so an actor that skips this line exists, moves, fires and collides — + invisibly. This one line cost this example its first screenshot. + +Input goes through a control map: push a control per key with handlers that set +flags, and let the actor's update hook read the flags. The full recipe is in +`examples/galaga/player.c` and libakgl docs/16-input.md; the shape is: + +```c wrap=galagagame requires=akgl +static akerr_ErrorContext *galaga_player_controls(void) +{ + akgl_Control control; + PREPARE_ERROR(errctx); + + memset(&control, 0, sizeof(control)); + control.event_on = SDL_EVENT_KEY_DOWN; + control.event_off = SDL_EVENT_KEY_UP; + + control.key = SDLK_LEFT; + control.handler_on = &left_on; + control.handler_off = &left_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + control.key = SDLK_RIGHT; + control.handler_on = &right_on; + control.handler_off = &right_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + control.key = SDLK_SPACE; + control.handler_on = &fire_on; + control.handler_off = &fire_off; + PASS(errctx, akgl_controller_pushmap(0, &control)); + + akgl_controlmaps[0].target = galaga_game.player; + SUCCEED_RETURN(errctx); +} +``` + +Hand **every** polled event to `akgl_controller_handle_event()` — one that no +control binds is not an error, it is a call that did nothing. + +## Step 4: Shots and collision + +**Goal: bullets that fly, hit, and give their actor slot back.** + +Bullets and collision are C forever — they are engine, not behavior. A shot is +an actor from the same 64-slot heap pool, with its own tiny update hook: move, +test, release. + +```c wrap=galagagame requires=akgl +static akerr_ErrorContext *player_shot_update(akgl_Actor *obj) +{ + SDL_FRect mine; + SDL_FRect theirs; + bool hit = false; + int i = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + obj->y -= 900.0f * galaga_game.dt; + if ( obj->y < -60.0f ) { + galaga_game.player_shots_live -= 1; + PASS(errctx, akgl_heap_release_actor(obj)); + SUCCEED_RETURN(errctx); + } + + shot_box(obj, &mine); + for ( i = 0; i < GALAGA_MAX_ENEMIES; i++ ) { + if ( galaga_enemy_actors[i] == NULL ) { + continue; + } + enemy_box(galaga_enemy_actors[i], &theirs); + PASS(errctx, akgl_collide_rectangles(&mine, &theirs, &hit)); + if ( !hit ) { + continue; + } + galaga_enemies[i].hp -= 1; + if ( galaga_enemies[i].hp <= 0 ) { + PASS(errctx, kill_enemy(i)); + } + galaga_game.player_shots_live -= 1; + PASS(errctx, akgl_heap_release_actor(obj)); + SUCCEED_RETURN(errctx); + } + SUCCEED_RETURN(errctx); +} +``` + +Four conventions worth keeping: + +- **`akgl_collide_rectangles()` is the whole collision system.** At most 2 + shots x 40 enemies of axis-aligned tests per frame is noise; the full + `akgl_CollisionWorld` machinery earns its keep on tilemaps, not here. The + `shot_box`/`enemy_box` helpers inset each box from the artwork's rectangle, + because the PNGs carry transparent margin that should not kill anybody. +- **Releasing is despawning.** `akgl_heap_release_actor()` unregisters the + actor and stops it drawing; releasing mid-sweep is safe because + `akgl_game_update()` re-reads each slot's refcount as it goes. +- **Names carry a serial** — `pshot17`, not `pshot1` reused — because the actor + registry is keyed by name, and two live actors with one name is a fight. +- **Spawn caps are C-side refusals.** Two player shots, eight enemy shots; the + spawn functions simply decline past the cap. + +Give the enemy shots the same shape falling downward, and the ship a sweep over +both — `examples/galaga/player.c` has all three loops. + +## Step 5: Boot the interpreter + +**Goal: the engine calls a BASIC function and prints its answer.** + +Everything so far was libakgl. Now link the interpreter into the same +executable. In CMake: + +```cmake +target_link_libraries(akbasic_example_galaga PRIVATE akbasic akgl + SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image) +``` + +Link `akbasic` — the interpreter only. Not `akbasic_akgl` (the device backends +that let a script draw), and not `akbasic_frontend` (the standalone program's +host). This game lends the script **no devices at all**: the scripts compute, +the engine draws, and a script that tries `SPRITE` is refused by name. That +refusal is enforced by the interpreter, not by convention — +[Chapter 10](10-embedding.md) explains the device-lending model this game +declines to use. + +The boot is the embedding host from Chapter 10, adapted to a script that only +defines. Keep every line that touches the interpreter in one file — the +example's `script.c` — so the boundary stays a place rather than a habit: + +```c wrap=galagacalls requires=akgl +CATCH(errctx, akbasic_error_register()); +CATCH(errctx, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL)); +CATCH(errctx, akbasic_runtime_init(&SCRIPT, &SINK)); + +CATCH(errctx, akbasic_runtime_load(&SCRIPT, SOURCE)); +CATCH(errctx, akbasic_runtime_start(&SCRIPT, AKBASIC_MODE_RUN)); +CATCH(errctx, akbasic_runtime_run(&SCRIPT, 4 * AKBASIC_MAX_SOURCE_LINES)); +CATCH(errctx, akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN)); +``` + +Two of those lines are the ones a first embedding gets wrong. + +**A "no top level code" script still has to run once.** The script is nothing +but `DEF` blocks and a final `END`, and executing the `DEF` statements is what +files the functions. The run is bounded — a script that is all definitions has +no business taking more than a few steps per line, and an accidental loop at +boot should be a diagnosis, not a hang. + +**The `set_mode` after the run is load-bearing.** The program has now ended and +the runtime sits in QUIT mode, where a multi-line `DEF` called from the host +returns a silent zero. Forcing the mode back to RUN makes the bodies run, and it +stays put because nothing here ever steps the runtime again. Issue #8 tracks +making this workaround unnecessary. + +`PRINT` inside the script goes through the stdio sink and lands on stdout — +that is the script's debug channel for the rest of both chapters. + +Prove the wiring with one function. Put this in the script: + +```basic +DEF ADDEM(A#, B#) = A# + B# +END +``` + +And call it from C, with values you already have: + +```c wrap=galagacalls requires=akgl +memset(&args[0], 0, sizeof(args[0])); +memset(&args[1], 0, sizeof(args[1])); +args[0].valuetype = AKBASIC_TYPE_INTEGER; +args[0].intval = 17; +args[1].valuetype = AKBASIC_TYPE_INTEGER; +args[1].intval = 25; +argp[0] = &args[0]; +argp[1] = &args[1]; +CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "ADDEM", argp, 2, &result)); +printf("ADDEM(17, 25) = %lld\n", (long long)result->intval); +``` + +```text +ADDEM(17, 25) = 42 +``` + +`akbasic_runtime_call_function()` is the host's entry point: a name and +already-evaluated values in, the function's result out. The engine refuses to +start when the script will not boot — a game whose enemies cannot think is not +a game missing a feature, it is a game that does not run. + +## Step 6: The update hook + +**Goal: one actor whose every frame is a BASIC call.** + +`akgl_game_update()` calls each live actor's `updatefunc` exactly once per +frame. Replacing that pointer is the whole integration: the actor's frame *is* +a script call. + +```c wrap=galagagame requires=akgl +static akerr_ErrorContext *enemy_update(akgl_Actor *obj) +{ + galaga_Enemy *enemy = NULL; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + enemy = (galaga_Enemy *)obj->actorData; + FAIL_ZERO_RETURN(errctx, enemy, AKERR_NULLPOINTER, "an enemy actor with no galaga_Enemy attached"); + + enemy->rnd = galaga_random(); + PASS(errctx, galaga_script_update_enemy(enemy, obj, galaga_game.dt)); + if ( enemy->fire != 0 ) { + PASS(errctx, enemy_fire(enemy, obj)); + } + SUCCEED_RETURN(errctx); +} +``` + +The hook's body is a protocol, and `galaga_script_update_enemy()` is its +middle: **rebind, call, recover, reset.** + +```c wrap=galagacalls requires=akgl +CATCH(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy)); +CATCH(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor)); + +memset(&dtval, 0, sizeof(dtval)); +dtval.valuetype = AKBASIC_TYPE_FLOAT; +dtval.floatval = (double)dt; +argp[0] = &dtval; +CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "UPDATEBEE", argp, 1, &result)); + +CATCH(errctx, akbasic_environment_zero(SCRIPT.environment)); +``` + +`SELF@` and `ACTOR@` are **host bindings** — the enemy's record and the +engine's live actor, shared with the script as structures it can read and +write directly. [Chapter 21](21-tutorial-galaga-enemies.md) builds them; for +this chapter, know that `akbasic_host_rebind()` points an existing binding at +a different instance, which is how forty enemies share one script: one name, +rebound per enemy, rather than forty names. + +**The `akbasic_environment_zero()` after every call is load-bearing.** Each +call parks its result in the caller environment's per-line value scratch, and a +host calling in a loop never crosses the line boundary that would reset it. +Without this line the scratch drains in under two frames of a 40-enemy wave and +every later call fails with `Maximum values per line reached`. Chapter 10's +["Calling a function every frame"](10-embedding.md#calling-a-function-every-frame) +section is the rule's home. + +## Step 7: First light + +**Goal: a C actor moving under BASIC control, and proof it is one memory.** + +Before any real AI, the smallest demonstration. One enemy, one function, a sine +drift written entirely in BASIC through the actor binding: + +```basic +DEF UPDATEBEE(DT%) + SELF@.T% = SELF@.T% + DT% + ACTOR@.X% = 590.0 + SIN(SELF@.T%) * 200 + ACTOR@.Y% = 300.0 + PRINT "BASIC SEES X = " + ACTOR@.X% + RETURN 0 +END +``` + +Spawn one enemy with the hook from Step 6, and have the engine print the same +actor's position each frame from C: + +```c wrap=galagahost requires=akgl +SDL_Log("C SEES X = %f", galaga_enemy_actors[0]->x); +``` + +```text +BASIC SEES X = 593.191094 +INFO: C SEES X = 593.191094 +BASIC SEES X = 596.378593 +INFO: C SEES X = 596.378593 +``` + +Same numbers, one memory. The script wrote `ACTOR@.X%`; the renderer read +`akgl_Actor.x`; nothing copied anything anywhere. The ship swings in a slow +arc, and the whole architecture is visible in that one motion: C owns the +frame, BASIC owns the decision, and the actor is the same bytes to both. + +## Step 8: Screens + +**Goal: title, playing, game over, victory — a state machine around the loop.** + +The screens are libakgl's UI layer, in the three-state pattern of its uidemo +example (libakgl docs/22-ui.md). A `galaga_Screen` enum, one `declare_*()` +function per screen, and the UI bracket between `akgl_game_update()` and +`frame_end` — exactly where the frame contract puts it: + +```c wrap=galagahost requires=akgl +CATCH(errctx, akgl_ui_frame_begin()); +switch ( galaga_game.screen ) { +case GALAGA_SCREEN_TITLE: + CATCH(errctx, declare_title()); + break; +case GALAGA_SCREEN_PLAY: + CATCH(errctx, declare_play()); + break; +case GALAGA_SCREEN_GAMEOVER: +case GALAGA_SCREEN_VICTORY: + CATCH(errctx, declare_end()); + break; +} +CATCH(errctx, akgl_ui_frame_end(akgl_renderer)); +``` + +The playing screen is two `akgl_ui_label()` calls — score top-left, lives and +wave top-right — formatted into `static` buffers, because the UI borrows label +text until `frame_end` and a local buffer would be dangling by the time it +draws. The title and end screens are an `akgl_ui_menu()` at the center. + +The big **GALAGA** headline is direct text rather than a label: + +```c wrap=galagagame requires=akgl +static akerr_ErrorContext *draw_banner(char *text) +{ + SDL_Color ink = { 235, 235, 235, 255 }; + TTF_Font *font = NULL; + int w = 0; + int h = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, text, AKERR_NULLPOINTER, "text"); + font = SDL_GetPointerProperty(AKGL_REGISTRY_FONT, "banner", NULL); + FAIL_ZERO_RETURN(errctx, font, AKERR_KEY, "the banner font is not loaded"); + PASS(errctx, akgl_text_measure(font, text, &w, &h)); + PASS(errctx, akgl_text_rendertextat(font, text, ink, 0, (1280 - w) / 2, 280)); + SUCCEED_RETURN(errctx); +} +``` + +The menu owns `AKGL_UI_ANCHOR_CENTER`, a label anchored there disappears +behind it, and there is no top-center anchor — so the headline measures itself +and draws at a coordinate, before the UI bracket so the menu still paints over +it if the two ever meet. + +![The title screen: the banner, the menu, the starfield](images/galaga-title.png) + +Screen transitions are three rules read after the world updates: lives spent is +GAME OVER, an empty wave is VICTORY, and a menu activation either restarts or +quits. The menu never clears its own `activated` flag — the state machine that +acts on it does. + +## Step 9: Run it headless + +**Goal: the same game, playable by a script, in CI every night.** + +The example takes five flags, in the pattern of libakgl's sidescroller: + +```sh norun +$ SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy SDL_RENDER_DRIVER=software \ + ./build-akgl/akbasic_example_galaga --frames 600 --autoplay +``` + +`--frames N` bounds the run; `--autoplay` is a scripted pilot that starts the +game, sweeps the floor and holds fire until the wave assembles; `--screenshot +PATH --screenshot-frame N` write a PNG from the render target — the figures in +this chapter are that flag's output, not pictures somebody took once. Synthetic +input goes through `akgl_controller_handle_event()` with constructed +`SDL_Event`s, never by calling the handlers directly — the point of autoplay is +to exercise the same path a keyboard does. + +The last line of every run is the evidence: + +```text +galaga: 600 frames, screen 1, score 1910, alive 9, kills bee 19 bfly 12 boss 0, shots bee 0 bfly 3 boss 0, script errors 0 +``` + +Exiting 0 is not proof the wave flew. The readout is: kills and shots counted +per kind say the enemies entered, thought and fired, and **`script errors 0`** +says every one of the ~24,000 BASIC calls in those ten seconds came back clean. +A wave of dumb enemies still exits 0, and that count is how you notice. The +CTest entry `example_galaga` runs exactly this under the dummy SDL drivers, +which is what keeps both chapters honest. + +--- + +That is the engine: a window, a starfield, a ship, bullets, screens, and an +interpreter that answers when called. Everything on screen so far is C. What +turns it into a GALAGA is [Chapter 21](21-tutorial-galaga-enemies.md) — the +three shared structures, the script that thinks through them, and a full wave +entering, breathing, diving and firing without another line of engine code. diff --git a/docs/21-tutorial-galaga-enemies.md b/docs/21-tutorial-galaga-enemies.md new file mode 100644 index 0000000..2ae4d76 --- /dev/null +++ b/docs/21-tutorial-galaga-enemies.md @@ -0,0 +1,515 @@ +# 21. Tutorial: GALAGA — the structures and the AI + +[Chapter 20](20-tutorial-galaga.md) built a C engine that boots the interpreter +and hands one actor to BASIC. This chapter builds everything that crosses the +boundary — the three shared structures — and then the script that thinks +through them: a full wave that enters, forms up, breathes, dives, fires and +dies, without another line of engine code. + +![The wave assembling: bosses, butterflies and bees under BASIC control](images/galaga-wave.png) + +The finished script is +[`examples/galaga/galaga.bas`](../examples/galaga/galaga.bas) — six `DEF` +functions and an `END`, nothing else. Editing it and re-running the game is the +whole development loop; the engine never rebuilds. + +## What you will do + +- **[Step 1](#step-1-declare-the-enemy-once-in-c)** — declare the enemy record + once, in C, and register it as a BASIC type +- **[Step 2](#step-2-bind-the-engines-own-actor)** — bind the engine's own + actor as the second type, which is the point of the whole exercise +- **[Step 3](#step-3-share-the-frame-and-the-dice)** — share the frame state, + and give the script randomness it cannot make itself +- **[Step 4](#step-4-why-bindings-and-not-arguments)** — see why the structures + are bindings rather than function arguments +- **[Step 5](#step-5-the-shape-of-the-script)** — learn the three language + rules that shape every enemy function +- **[Step 6](#step-6-the-shared-maneuvers)** — write the shared maneuvers: + glide home, dive, decide to fire +- **[Step 7](#step-7-the-three-kinds)** — write the bee, the butterfly and the + boss +- **[Step 8](#step-8-the-formation-c-or-basic)** — decide who owns the + formation, and lay it out +- **[Step 9](#step-9-when-a-script-dies)** — decide what a script error does to + the game, and make it do that +- **[Step 10](#step-10-prove-it)** — prove the boundary with a test that links + the real files + +--- + +## Step 1: Declare the enemy once, in C + +**Goal: one struct that both languages read and write, with one source of truth.** + +An enemy is what the state machine needs to remember between frames, plus one +inbox and one outbox: + +```c wrap=galagatypes requires=akgl +#define GALAGA_ENEMY_BEE 0 +#define GALAGA_ENEMY_BUTTERFLY 1 +#define GALAGA_ENEMY_BOSS 2 + +/* + * galaga_Enemy.state bits. The script owns these transitions; the engine only + * writes the word at spawn. + * + * 8 0 + * 0 0 0 0 0 1 1 1 + * | | `-- ENTERING: flying its entry path toward the formation slot + * | `---- FORMATION: holding (and breathing around) homex/homey + * `------ DIVING: attacking, off the grid until it leaves the screen + */ +#define GALAGA_ES_ENTERING (1 << 0) +#define GALAGA_ES_FORMATION (1 << 1) +#define GALAGA_ES_DIVING (1 << 2) + +typedef struct galaga_Enemy +{ + int32_t kind; /* GALAGA_ENEMY_BEE / BUTTERFLY / BOSS */ + int32_t state; /* GALAGA_ES_* bit flags */ + float homex; /* formation slot, in map pixels */ + float homey; + float t; /* parametric clock for the current maneuver */ + int32_t hp; + int32_t fire; /* outbox: script sets 1, engine consumes */ + float rnd; /* inbox: engine writes fresh 0..1 each call */ +} galaga_Enemy; +``` + +The C struct *is* the BASIC type. `akbasic_host_register_type()` takes a table +of field descriptors — the BASIC name with its suffix, the C representation, +and where the member sits — and after that the language's own machinery works +across the boundary with no second set of rules +([Chapter 16](16-structures.md)): + +```c wrap=galagatypes requires=akgl +typedef struct galaga_Enemy +{ + int32_t kind; + int32_t state; + float homex; + float homey; + float t; + int32_t hp; + int32_t fire; + float rnd; +} galaga_Enemy; + +static const akbasic_HostField ENEMY_FIELDS[] = { + /* struct member BASIC name C representation */ + AKBASIC_HOST_FIELD( galaga_Enemy, kind, "KIND#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, state, "STATE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, homex, "HOMEX%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, homey, "HOMEY%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, t, "T%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( galaga_Enemy, hp, "HP#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, fire, "FIRE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( galaga_Enemy, rnd, "RND%", AKBASIC_HOSTFIELD_FLOAT ) +}; +static const akbasic_HostType ENEMY_TYPE = { + "ENEMY", sizeof(galaga_Enemy), ENEMY_FIELDS, 8 +}; +``` + +Three decisions are load-bearing here: + +- **`AKBASIC_HOST_FIELD` takes the offset and the width from the member + itself**, via `offsetof` — so the two sides cannot drift. Writing them out by + hand is two chances to name the wrong member and no way to notice. +- **The script never declares a `TYPE`.** A host type and a script `TYPE` share + one namespace, and a script that tries to redeclare `ENEMY` is refused. The + "structure definitions" half of the boundary lives here, once. +- **The suffixes are the dialect's**: `#` is integer, `%` is float + ([Chapter 3](03-the-language.md)). `HOMEX%` because a formation slot is a + pixel coordinate the glide arithmetic must not truncate. + +The limits that shape the struct: a type may carry 16 fields and the runtime 16 +types ([Chapter 16](16-structures.md)). `ENEMY` spends 8 fields; the game +spends 3 types. + +## Step 2: Bind the engine's own actor + +**Goal: the script writes the same bytes the renderer reads.** + +The enemy record is the game's own invention. The second type is not — it is +libakgl's `akgl_Actor`, registered field-for-field over the engine's real +struct: + +```c wrap=galagatypes requires=akgl +static const akbasic_HostField ACTOR_FIELDS[] = { + AKBASIC_HOST_FIELD( akgl_Actor, x, "X%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( akgl_Actor, y, "Y%", AKBASIC_HOSTFIELD_FLOAT ), + AKBASIC_HOST_FIELD( akgl_Actor, state, "STATE#", AKBASIC_HOSTFIELD_INT32 ), + AKBASIC_HOST_FIELD( akgl_Actor, visible, "VISIBLE#", AKBASIC_HOSTFIELD_BOOL ) +}; +static const akbasic_HostType ACTOR_TYPE = { + "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 4 +}; +``` + +This is the demonstrative point of the whole exercise. When the script writes +`ACTOR@.X%`, it writes `akgl_Actor.x` — the same memory the renderer reads on +the same frame. There is no copy going in, no copy coming out, and no code +between the script's decision and the engine's pixel. Null physics +(Chapter 20, Step 1) is what makes that safe: nothing else is trying to move +the actor. + +The per-frame call binds both names to *this* enemy before dispatching — one +binding per name, pointed at forty enemies in turn, which is what +`akbasic_host_rebind()` is for: + +```c wrap=galagacalls requires=akgl +CATCH(errctx, akbasic_host_rebind(&SCRIPT, "SELF@", enemy)); +CATCH(errctx, akbasic_host_rebind(&SCRIPT, "ACTOR@", actor)); +``` + +## Step 3: Share the frame, and the dice + +**Goal: everything a diving enemy needs to know about the world, in one record.** + +```c wrap=galagatypes requires=akgl +typedef struct galaga_Shared +{ + float playerx; /* the player actor's position, this frame */ + float playery; + int32_t wave; + float rnd; /* fresh 0..1 each frame; the issue #16 route */ +} galaga_Shared; +``` + +`GAME@` is bound once at boot to this one global instance and never rebound; +the engine refreshes it at the top of every frame. The boss reads +`GAME@.PLAYERX%` to lead its dive; the fire decision reads it to know whether +anything is worth shooting at. + +The `rnd` fields — one here per frame, one on each enemy per call — exist +because the engine's PRNG is the script's **only** source of randomness: write +`SELF@.RND% < DT% * 1.5` and an enemy's trigger finger is a dice roll. There +is no `RND` verb in this dialect; issue #16 tracks adding one, and Chapter +17's breakout hand-rolls a linear congruential generator in BASIC as the other +route. Here the engine fills the field, which also keeps a headless run the +same game on every machine — the PRNG is the example's own, not libc's. + +## Step 4: Why bindings, and not arguments + +**Goal: know why `SELF@` is a bound global rather than a parameter.** + +The language can pass structures to functions — by value with `E@ AS ENEMY`, +by reference with `E@ AS PTR TO ENEMY` ([Chapter 16](16-structures.md)) — and +a host can construct those argument values, so the obvious alternative +interface is honest functions: + +```basic norun +DEF UPDATEBEE(E@ AS PTR TO ENEMY, A@ AS PTR TO ACTOR, G@ AS PTR TO GAME, DT%) +``` + +It was measured before this chapter chose. Pointer arguments work — writes +through `E@->X%` land in the host struct, the type check refuses a wrong type, +by-value copies exactly as documented. What rules them out is the pool math: + +| | bound globals | pointer arguments | +|---|---|---| +| value-pool slots per call | 0 | 1 per structure parameter, never returned | +| calls before exhaustion | unbounded | 1,015 measured (2,048-slot pool, 2 pointer args) | +| at 40 enemies per frame | unbounded | 25 frames | +| per-call cost | 148 us | 251 us | + +A `@`-suffixed name always takes value-pool storage, and that pool never +reclaims — a documented property of structures, because a pointer may outlive +the scope that `DIM`med it. A *parameter* is a local that dies with the call, +but it pays the storage price of a `DIM` that must survive one; the pool +drains, and the wave stops thinking mid-flight. Issue #36 tracks it, with the +reduction for whoever fixes it. Until then: **bind and rebind for per-frame +host calls; pass structures only to functions called a bounded number of +times.** + +## Step 5: The shape of the script + +**Goal: the three rules every enemy function is written under.** + +`galaga.bas` is definitions and an `END` — no top-level code, no line numbers, +no `LABEL`s. Three rules of the dialect shape every body in it. + +**Rule 1: the left operand decides integer or float arithmetic** +([Chapter 3](03-the-language.md)). This will bite every enemy script exactly +once, so meet it now. The natural spelling of "move by speed times dt" moves +nothing: + +```basic norun +ACTOR@.Y% = ACTOR@.Y% + 260 * DT% +``` + +`260` is an integer, it is on the left of `*`, so `DT%` — a float around +0.016 — is converted to integer **zero** before the multiply. Nothing fails; +the enemy simply does not move. The working spelling puts the float first: + +```basic norun +ACTOR@.Y% = ACTOR@.Y% + SPD% * DT% +SPD% = SELF@.T% * 150 + 260 +``` + +Every expression in the finished script is written float-first. When an enemy +of yours will not move, this is the first thing to check. + +**Rule 2: only the last `RETURN` may start a line.** A multi-line `DEF` body +runs until `RETURN` — and the *definition* is scanned the same way, ending at +the first line that begins with one. An early return therefore always rides an +`IF ... THEN RETURN 0` on one line, and exactly one line-leading `RETURN` ends +each function. The stagger guard at the top of every update function is the +idiom: + +```basic norun +DEF UPDATEBEE(DT%) + SELF@.T% = SELF@.T% + DT% + IF SELF@.T% < 0 THEN RETURN 0 +``` + +**Rule 3: the budgets are small and named.** Eight function slots exist +(`AKBASIC_MAX_FUNCTIONS`), each a measured 36 KiB of the runtime's 2.40 MiB. +This game defines six: three update functions, two shared maneuvers, one fire +decision. Nesting draws from the twelve-slot environment pool exactly as +`GOSUB` does; the deepest chain here is three (update → maneuver → nothing). +If a design needs a ninth function, raising the limit is one `#define` and ++36 KiB per slot — weighed, not assumed. + +## Step 6: The shared maneuvers + +**Goal: three helpers that make the three kinds one page each.** + +Ease toward the formation slot, with a little entry swirl. Answers 1 once the +slot is reached — the caller flips the state on that answer: + +```basic +DEF GLIDEHOME(DT%) + DX% = SELF@.HOMEX% - ACTOR@.X% + DY% = SELF@.HOMEY% - ACTOR@.Y% + K% = DT% * 4.5 + IF K% > 1 THEN K% = 1 + ACTOR@.X% = ACTOR@.X% + DX% * K% + SIN(SELF@.T% * 6) * 90 * DT% + ACTOR@.Y% = ACTOR@.Y% + DY% * K% + IF ABS(DX%) < 3 AND ABS(DY%) < 3 THEN RETURN 1 + RETURN 0 +END +``` + +One frame of a dive: accelerate downward, weave, lean toward the player's +column, and glide back in from the top after falling out the bottom. The +weave and the lean are parameters, which is what makes three kinds out of one +maneuver: + +```basic +DEF DIVESTEP(DT%, WEAVE%, LEAD%) + SPD% = SELF@.T% * 150 + 260 + ACTOR@.Y% = ACTOR@.Y% + SPD% * DT% + ACTOR@.X% = ACTOR@.X% + SIN(SELF@.T% * 4) * WEAVE% * DT% + DX% = GAME@.PLAYERX% - ACTOR@.X% + IF DX% > 220 THEN DX% = 220 + IF DX% < -220 THEN DX% = -220 + ACTOR@.X% = ACTOR@.X% + DX% * LEAD% * DT% + IF ACTOR@.Y% > 1040 THEN BEGIN + ACTOR@.Y% = 0.0 - 90 + SELF@.STATE# = 1 + SELF@.T% = 0 + BEND + RETURN 0 +END +``` + +Note the off-screen exit: state back to `1` (ENTERING), clock to zero, and the +glide brings it home — a dive that misses rejoins the formation, which is the +classic loop. `0.0 - 90` rather than `0 - 90` is Rule 1 again: the float goes +first even to make a negative. + +The fire decision raises the flag when diving roughly above the player. The +engine consumes `FIRE#` and does the spawning — the script only wishes, +because spawning takes an actor from a bounded pool and pool exhaustion must +be a C-side refusal with the house error context, not a script mystery: + +```basic +DEF DECIDEFIRE(DT%) + DX% = GAME@.PLAYERX% - ACTOR@.X% + IF ABS(DX%) > 140 THEN RETURN 0 + IF ACTOR@.Y% > GAME@.PLAYERY% THEN RETURN 0 + IF SELF@.RND% < DT% * 1.5 THEN SELF@.FIRE# = 1 + RETURN 0 +END +``` + +## Step 7: The three kinds + +**Goal: bee, butterfly, boss — one state machine, three characters.** + +Every kind is the same three-state machine, dispatched by the bits of +`SELF@.STATE#`. The bee is the reference implementation: + +```basic +DEF GLIDEHOME(DT%) + ACTOR@.X% = SELF@.HOMEX% + ACTOR@.Y% = SELF@.HOMEY% + RETURN 1 + +DEF DIVESTEP(DT%, WEAVE%, LEAD%) + RETURN 0 + +DEF DECIDEFIRE(DT%) + RETURN 0 + +DEF UPDATEBEE(DT%) + SELF@.T% = SELF@.T% + DT% + IF SELF@.T% < 0 THEN RETURN 0 + S# = SELF@.STATE# + IF (S# AND 1) > 0 THEN BEGIN + R# = GLIDEHOME(DT%) + IF R# = 1 THEN SELF@.STATE# = 2 : SELF@.T% = 0 + BEND + IF (S# AND 2) > 0 THEN BEGIN + ACTOR@.X% = SELF@.HOMEX% + SIN(SELF@.T% * 1.7) * 16 + ACTOR@.Y% = SELF@.HOMEY% + IF SELF@.RND% < DT% * 0.04 THEN SELF@.STATE# = 4 : SELF@.T% = 0 + BEND + IF (S# AND 4) > 0 THEN BEGIN + R# = DIVESTEP(DT%, 130, 0.2) + R# = DECIDEFIRE(DT%) + BEND + RETURN 0 +END +``` + +(The three helpers above are stubs so this listing runs alone; the real ones +are Step 6's. The listing in `galaga.bas` is this function verbatim.) + +The shape to notice: `S#` is read **once**, so a state flipped this frame does +not also run its new state's block this frame — transitions are frame-atomic. +Each block is one `IF ... BEGIN`/`BEND`, never nested. The formation block +computes position *relative to home* every frame — `HOMEX% + SIN(...)` — so +the grid's idle breathing belongs to the script even though C placed the grid. + +The butterfly is the bee with a wide lateral weave — `DIVESTEP(DT%, 260, 0.1)` +— and a slightly itchier trigger. The boss differs three ways: two hit points +(C fills `HP#` at spawn), a dive that leads the player — +`DIVESTEP(DT%, 60, 0.9)` — and one line that crosses the boundary in the other +direction: + +```basic norun +IF SELF@.HP# = 1 THEN ACTOR@.STATE# = ACTOR@.STATE# OR 8192 +``` + +8192 is `AKGL_ACTOR_STATE_UNDEFINED_13`, one of the actor state bits libakgl +reserves for the game. The boss's character file maps the state word +`ALIVE` to the green sprite and `ALIVE`+bit-13 to the drained one — so when +the script raises the bit, the engine's own character machinery swaps the +sprite. BASIC decides *that* the boss looks hurt; C never hears about it. + +## Step 8: The formation: C or BASIC? + +**Goal: decide who owns the grid, from the trade-offs rather than taste.** + +Both can lay out the formation. The choice is argued, not asserted: + +| | C lays out the grid | BASIC lays out the grid | +|---|---|---| +| actor pool safety | refusal at spawn, house error path | script can ask for more than 64 exist | +| tuning without rebuild | no | yes | +| call budget | zero calls | one call per spawn | +| who knows the screen size | the engine owns it anyway | needs it exported through `GAME@` | + +**Decision: C owns the grid, the wave table and the spawn timing; BASIC owns +everything an enemy does after it exists.** The slot arrives in +`SELF@.HOMEX%`/`HOMEY%`, so the breathing stays the script's (Step 7), and the +pool stays behind a C-side refusal. The wave is the aligned table house style +already prescribes for tabular data — one row per formation row: + +```c wrap=galagagame requires=akgl +static const struct +{ + int32_t kind; /* GALAGA_ENEMY_* */ + int row; /* formation row */ + int first; /* first column filled */ + int count; /* columns filled */ + int32_t hp; +} +WAVE_ROWS[] = { + /* kind row first count hp */ + { GALAGA_ENEMY_BOSS, 0, 3, 4, 2 }, + { GALAGA_ENEMY_BUTTERFLY, 1, 1, 8, 1 }, + { GALAGA_ENEMY_BUTTERFLY, 2, 1, 8, 1 }, + { GALAGA_ENEMY_BEE, 3, 0, 10, 1 }, + { GALAGA_ENEMY_BEE, 4, 0, 10, 1 } +}; +``` + +Forty enemies: 4 bosses, 16 butterflies, 20 bees. The actor heap holds 64: + +```text +player 1 +player shots 2 /* the classic two-on-screen rule */ +enemies 40 /* 20 bees, 16 butterflies, 4 bosses */ +enemy shots 8 +explosions 8 /* short-lived actors, released on a timer */ + --- + 59 of 64 +``` + +The spawn walks the table, fills each `galaga_Enemy`, and staggers the entry +clocks — `t = -0.08 * index`, so each enemy holds still until its own clock +crosses zero and the wave pours in as a stream rather than a wall. The full +loop is `examples/galaga/enemies.c`. + +## Step 9: When a script dies + +**Goal: a script error costs one enemy's wits, never the frame.** + +A BASIC-level error in an enemy's function — a misspelled field, arithmetic on +the wrong type — reports through the sink and stops the script. The engine's +policy, implemented around the call in `script.c`: + +- **The enemy goes dumb**: state cleared to a formation hold it will never + leave, outbox cleared. The other thirty-nine keep thinking. +- **The runtime is revived**: a run's first error latches, and while it stands + every later call answers a stale value after doing nothing. Revival is two + calls — `akbasic_runtime_clear_error()`, then the same + `akbasic_runtime_set_mode(RUN)` the boot needed (issue #8's mechanics). +- **The first failure is logged, the rest are counted.** Sixty a second of the + same message is how a log stops being read; the count lands in the closing + readout as `script errors N`, where a headless run cannot miss it. + +The same detection runs at boot: every function in the dispatch table is +called once against a zeroed scratch enemy, so a script that cannot run fails +at startup with the function's name in the message — not on frame one of the +first wave. + +## Step 10: Prove it + +**Goal: a test that fails the moment the two sides disagree.** + +`examples/galaga/interop_test.c` links the real `script.c` and loads the real +`galaga.bas` — not copies — and pins the four claims this chapter made: + +```text +ok: a formation bee's sway is written into akgl_Actor.x/y by the script +ok: a diving bee above the player raises FIRE# for the engine to consume +ok: a boss at one hit point raises actor state bit 13 from BASIC +ok: 24000 calls survive the per-call akbasic_environment_zero() regime +``` + +That last claim is the per-frame contract from Chapter 20 Step 6 under a full +game's load — forty enemies at sixty frames a second for ten seconds. CTest +runs it as `example_galaga_interop` beside the headless game itself. + +And because the script is data, the proof extends to scripts nobody planned: +run the game with `--script` pointing at a variant — enemies that never dive, +enemies that always dive — and the engine neither knows nor cares. That +swap-a-brain-without-rebuilding property is what the two chapters were about; +the readout tells you how each brain did: + +```text +galaga: 3000 frames, screen 2, score 2350, alive 0, kills bee 20 bfly 15 boss 1, shots bee 1 bfly 1 boss 1, script errors 0 +``` + +--- + +Where to go from here: more waves are rows in the table; a new enemy kind is +one table row, one character file and one `DEF`; a smarter boss is edits to a +text file while the game is closed — or a different file handed to +`--script`. The engine is done. That is the point. diff --git a/docs/README.md b/docs/README.md index 347f71a..f35bc37 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,10 @@ embedding it, debugging it or changing it. **[Chapters 17](17-tutorial-breakout.md)** and **[18](18-tutorial-breakout-artwork.md)** are tutorials rather than reference: they build one complete game twice, two different ways, in numbered steps you can type in one at a time. Start with 17 — it needs nothing -but the earlier chapters, and 18 assumes it. +but the earlier chapters, and 18 assumes it. **[Chapters 20](20-tutorial-galaga.md)** and +**[21](21-tutorial-galaga-enemies.md)** are the third tutorial, from the other side of +the boundary: a C game on libakgl that embeds the interpreter as its enemy-behavior +engine, for anyone whose question is "how do I put this in *my* game". ## Chapters @@ -41,6 +44,8 @@ but the earlier chapters, and 18 assumes it. | **[17. Tutorial: Breakout](17-tutorial-breakout.md)** | Build a whole game out of the text grid and two `DATA` sprites, in sixteen steps | | **[18. Tutorial: Breakout with artwork](18-tutorial-breakout-artwork.md)** | Build it again out of loaded artwork, powerups and a drawn colour HUD, in thirteen | | **[19. Menus and dialogs](19-user-interface.md)** | `MENU`, `DIALOG`, `HUD` and `UISTYLE` — the widgets, and who owns the keyboard | +| **[20. Tutorial: GALAGA](20-tutorial-galaga.md)** | Build a C engine on libakgl that embeds the interpreter, boots a script and hands it an actor | +| **[21. Tutorial: GALAGA enemies](21-tutorial-galaga-enemies.md)** | Share three C structs with the script, then write the wave's whole brain in BASIC | ## The shortest possible start diff --git a/tests/docs_preludes/galagacalls.post b/tests/docs_preludes/galagacalls.post new file mode 100644 index 0000000..ce04880 --- /dev/null +++ b/tests/docs_preludes/galagacalls.post @@ -0,0 +1,8 @@ + } CLEANUP { + } PROCESS(errctx) { + } FINISH(errctx, true); + (void)SCRIPT; (void)SINK; (void)SINKSTATE; (void)SOURCE; + (void)args; (void)argp; (void)dtval; (void)result; + (void)enemy; (void)actor; (void)dt; + SUCCEED_RETURN(errctx); +} diff --git a/tests/docs_preludes/galagacalls.pre b/tests/docs_preludes/galagacalls.pre new file mode 100644 index 0000000..4ebab03 --- /dev/null +++ b/tests/docs_preludes/galagacalls.pre @@ -0,0 +1,53 @@ +/* + * Prelude for the interpreter-facing fragments in docs/20: the boot sequence, + * the ADDEM proof and the rebind-call-reset protocol, shown as runs of CATCH + * calls. The statics are the ones examples/galaga/script.c keeps; the locals + * are the superset every fragment draws from, void-cast in the postlude so an + * unused one is not a warning. + */ +#include +#include +#include +#include +#include + +#include + +#include +#include + +#include + +#include +#include +#include +#include +#include + +typedef struct galaga_docs_Enemy +{ + int32_t kind; + int32_t state; + float homex; + float homey; + float t; + int32_t hp; + int32_t fire; + float rnd; +} galaga_docs_Enemy; + +static akbasic_Runtime SCRIPT; +static akbasic_TextSink SINK; +static akbasic_StdioSink SINKSTATE; +static char SOURCE[16384]; + +akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt); +akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt) +{ + PREPARE_ERROR(errctx); + akbasic_Value args[2]; + akbasic_Value *argp[2]; + akbasic_Value dtval; + akbasic_Value *result = NULL; + + ATTEMPT { diff --git a/tests/docs_preludes/galagagame.pre b/tests/docs_preludes/galagagame.pre new file mode 100644 index 0000000..55e116f --- /dev/null +++ b/tests/docs_preludes/galagagame.pre @@ -0,0 +1,121 @@ +/* + * Prelude for file-scope fragments in docs/20 and docs/21 that assume the + * galaga example's own declarations already exist -- the shared structures + * from examples/galaga/galaga.h and the helpers a fragment calls but does not + * define. The types are copied rather than included so a fragment compiles + * against exactly what the chapter has shown so far; the helper declarations + * are invented prototypes, per the prelude policy in MAINTENANCE.md. + */ +#include +#include +#include +#include +#include + +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +#define GALAGA_ENEMY_BEE 0 +#define GALAGA_ENEMY_BUTTERFLY 1 +#define GALAGA_ENEMY_BOSS 2 +#define GALAGA_ENEMY_KINDS 3 +#define GALAGA_MAX_ENEMIES 40 +#define GALAGA_MAX_PLAYER_SHOTS 2 +#define GALAGA_MAX_ENEMY_SHOTS 8 +#define GALAGA_ES_ENTERING (1 << 0) +#define GALAGA_ES_FORMATION (1 << 1) +#define GALAGA_ES_DIVING (1 << 2) + +typedef struct galaga_Enemy +{ + int32_t kind; + int32_t state; + float homex; + float homey; + float t; + int32_t hp; + int32_t fire; + float rnd; +} galaga_Enemy; + +typedef struct galaga_Shared +{ + float playerx; + float playery; + int32_t wave; + float rnd; +} galaga_Shared; + +typedef enum +{ + GALAGA_SCREEN_TITLE = 0, + GALAGA_SCREEN_PLAY, + GALAGA_SCREEN_GAMEOVER, + GALAGA_SCREEN_VICTORY +} galaga_Screen; + +typedef struct galaga_Game +{ + galaga_Screen screen; + int frame; + float dt; + bool autoplay; + int score; + int lives; + int kills[GALAGA_ENEMY_KINDS]; + int shots[GALAGA_ENEMY_KINDS]; + int script_errors; + akgl_Actor *player; + float fire_cooldown; + float respawn_timer; + bool firing; + bool moveleft; + bool moveright; + int player_shots_live; + int enemy_shots_live; +} galaga_Game; + +extern galaga_Game galaga_game; +extern galaga_Shared galaga_shared; +extern galaga_Enemy galaga_enemies[GALAGA_MAX_ENEMIES]; +extern akgl_Actor *galaga_enemy_actors[GALAGA_MAX_ENEMIES]; + +float galaga_random(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_script_update_enemy(galaga_Enemy *enemy, akgl_Actor *actor, float dt); +akerr_ErrorContext AKERR_NOIGNORE *galaga_boom_spawn(float x, float y); +akerr_ErrorContext AKERR_NOIGNORE *enemy_fire(galaga_Enemy *enemy, akgl_Actor *from); +akerr_ErrorContext AKERR_NOIGNORE *kill_enemy(int index); +akerr_ErrorContext AKERR_NOIGNORE *player_update(akgl_Actor *obj); +akerr_ErrorContext AKERR_NOIGNORE *left_on(akgl_Actor *obj, SDL_Event *event); +akerr_ErrorContext AKERR_NOIGNORE *left_off(akgl_Actor *obj, SDL_Event *event); +akerr_ErrorContext AKERR_NOIGNORE *right_on(akgl_Actor *obj, SDL_Event *event); +akerr_ErrorContext AKERR_NOIGNORE *right_off(akgl_Actor *obj, SDL_Event *event); +akerr_ErrorContext AKERR_NOIGNORE *fire_on(akgl_Actor *obj, SDL_Event *event); +akerr_ErrorContext AKERR_NOIGNORE *fire_off(akgl_Actor *obj, SDL_Event *event); +void shot_box(akgl_Actor *actor, SDL_FRect *dest); +void enemy_box(akgl_Actor *actor, SDL_FRect *dest); +void player_box(akgl_Actor *actor, SDL_FRect *dest); diff --git a/tests/docs_preludes/galagahost.post b/tests/docs_preludes/galagahost.post new file mode 100644 index 0000000..2265d12 --- /dev/null +++ b/tests/docs_preludes/galagahost.post @@ -0,0 +1,6 @@ + } CLEANUP { + } PROCESS(errctx) { + } FINISH(errctx, true); + (void)event; + SUCCEED_RETURN(errctx); +} diff --git a/tests/docs_preludes/galagahost.pre b/tests/docs_preludes/galagahost.pre new file mode 100644 index 0000000..a9a298a --- /dev/null +++ b/tests/docs_preludes/galagahost.pre @@ -0,0 +1,55 @@ +/* + * Prelude for statement-context fragments in docs/20: runs of CATCH calls + * from the galaga frame loop, shown without their scaffolding because the + * ATTEMPT protocol is the scaffolding. Same policy as hostcalls.pre. + */ +#include +#include +#include +#include +#include + +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include +#include + +#include +#include + +typedef enum +{ + GALAGA_SCREEN_TITLE = 0, + GALAGA_SCREEN_PLAY, + GALAGA_SCREEN_GAMEOVER, + GALAGA_SCREEN_VICTORY +} galaga_Screen; + +struct galaga_docs_Game +{ + galaga_Screen screen; + float dt; + akgl_Actor *player; +}; +extern struct galaga_docs_Game galaga_game; +extern akgl_Actor *galaga_enemy_actors[40]; + +akerr_ErrorContext AKERR_NOIGNORE *declare_title(void); +akerr_ErrorContext AKERR_NOIGNORE *declare_play(void); +akerr_ErrorContext AKERR_NOIGNORE *declare_end(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(void); +akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(void) +{ + PREPARE_ERROR(errctx); + SDL_Event event; + + ATTEMPT { diff --git a/tests/docs_preludes/galagatypes.pre b/tests/docs_preludes/galagatypes.pre new file mode 100644 index 0000000..bb0506a --- /dev/null +++ b/tests/docs_preludes/galagatypes.pre @@ -0,0 +1,37 @@ +/* + * Prelude for the self-contained file-scope fragments in docs/20 and docs/21: + * blocks that define a struct, a table or a whole function from scratch need + * only the includes. Only compiled in the AKBASIC_WITH_AKGL build. + */ +#include +#include +#include +#include +#include + +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include +#include diff --git a/tests/docs_preludes/hostcalls.post b/tests/docs_preludes/hostcalls.post index 14fb300..0ffbc94 100644 --- a/tests/docs_preludes/hostcalls.post +++ b/tests/docs_preludes/hostcalls.post @@ -2,5 +2,7 @@ } PROCESS(errctx) { } FINISH(errctx, true); (void)score; + (void)argp; + (void)result; SUCCEED_RETURN(errctx); } diff --git a/tests/docs_preludes/hostcalls.pre b/tests/docs_preludes/hostcalls.pre index a79548d..bed87f9 100644 --- a/tests/docs_preludes/hostcalls.pre +++ b/tests/docs_preludes/hostcalls.pre @@ -7,6 +7,7 @@ * surrounding prose says exists but does not print. */ #include +#include #include #include #include @@ -23,5 +24,7 @@ akerr_ErrorContext AKERR_NOIGNORE *akbasic_docs_fragment(void) { PREPARE_ERROR(errctx); int64_t score = 0; + akbasic_Value *argp[4]; + akbasic_Value *result = NULL; ATTEMPT { -- 2.43.0 From 54ab85a27667c40c020e8cbaece332a7628c0084 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 09:01:59 -0400 Subject: [PATCH 6/7] Benchmark the boundary and close the cold read's tutorial gaps 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- CMakeLists.txt | 2 +- docs/20-tutorial-galaga.md | 140 ++++++++++++++++++++++++++++- docs/21-tutorial-galaga-enemies.md | 52 +++++++++++ examples/galaga/interop_test.c | 133 +++++++++++++++++++++++++++ 4 files changed, 322 insertions(+), 5 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index f4ae118..c739f0c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -304,7 +304,7 @@ if(AKBASIC_BUILD_EXAMPLES AND AKBASIC_WITH_AKGL) 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) + SDL3::SDL3 m) 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) diff --git a/docs/20-tutorial-galaga.md b/docs/20-tutorial-galaga.md index a799c4e..39561e3 100644 --- a/docs/20-tutorial-galaga.md +++ b/docs/20-tutorial-galaga.md @@ -125,7 +125,41 @@ writes `x` and `y` directly is the mover, and in this game that will be BASIC. **Error handling is the house protocol.** Every function returns `akerr_ErrorContext *`, `PASS` propagates, `ATTEMPT`/`CATCH`/`CLEANUP` brackets anything that must unwind. libakgl's docs/04-errors.md teaches it; this chapter -just uses it. +just uses it. The status codes this game raises are `AKERR_NULLPOINTER`, +`AKERR_VALUE`, `AKERR_KEY`, `AKERR_IO`, `AKERR_OUTOFBOUNDS`, `AKGL_ERR_SDL` +and `AKGL_ERR_HEAP` — there is no code this tutorial invents. + +The includes the engine files draw on, so nothing later has to be guessed — +the SDL satellites use their own prefixes (`SDL3_ttf/SDL_ttf.h`, not +`SDL3/SDL_ttf.h`): + +```c wrap=galagatypes requires=akgl +#include +#include +#include + +#include +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +``` The frame loop is the standard bracket, with one addition you will meet in Step 6 — for now, events in, world drawn, frame out: @@ -198,6 +232,20 @@ actor state words to **sprites** (libakgl docs/10 and 12). Both are JSON; load sprites first, because a character names its sprites and a character loaded first fails on the first name it cannot find. +These are the names, so the loading lists and every +`akgl_actor_set_character()` call in both chapters agree — each `sprite_*.json` +and `character_*.json` lives in `assets/`: + +| Character | Sprite(s) it maps | Worn by | +|---|---|---| +| `galaga_player` | `galaga_player` | the ship | +| `galaga_bee` | `galaga_bee` | bees | +| `galaga_butterfly` | `galaga_butterfly` | butterflies | +| `galaga_boss` | `galaga_boss`, and `galaga_boss_hurt` on state bit 13 | bosses | +| `galaga_playershot` | `galaga_playershot` | the ship's shots | +| `galaga_enemyshot` | `galaga_enemyshot` | enemy shots | +| `galaga_boom` | `galaga_boom` | explosions | + The spawn is four decisions after the two boilerplate calls: ```c wrap=galagagame requires=akgl @@ -338,18 +386,84 @@ Four conventions worth keeping: Give the enemy shots the same shape falling downward, and the ship a sweep over both — `examples/galaga/player.c` has all three loops. +Explosions are the fourth actor kind, and they carry the one place this game +*absorbs* an error instead of propagating it. `HANDLE` names the status it +forgives; everything else still travels: + +```c wrap=galagagame requires=akgl +static float BOOM_TTL[AKGL_MAX_HEAP_ACTOR]; +static uint32_t BOOM_SERIAL = 0; + +static akerr_ErrorContext *boom_update(akgl_Actor *obj) +{ + ptrdiff_t slot = 0; + PREPARE_ERROR(errctx); + + FAIL_ZERO_RETURN(errctx, obj, AKERR_NULLPOINTER, "obj"); + slot = obj - akgl_heap_actors; + BOOM_TTL[slot] -= galaga_game.dt; + if ( BOOM_TTL[slot] <= 0.0f ) { + PASS(errctx, akgl_heap_release_actor(obj)); + } + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *galaga_boom_spawn(float x, float y) +{ + akgl_Actor *boom = NULL; + char name[32]; + int count = 0; + PREPARE_ERROR(errctx); + + ATTEMPT { + CATCH(errctx, akgl_heap_next_actor(&boom)); + BOOM_SERIAL += 1; + CATCH(errctx, aksl_snprintf(&count, name, sizeof(name), "boom%u", BOOM_SERIAL)); + CATCH(errctx, akgl_actor_initialize(boom, name)); + CATCH(errctx, akgl_actor_set_character(boom, "galaga_boom")); + boom->updatefunc = &boom_update; + boom->movement_controls_face = false; + boom->state = AKGL_ACTOR_STATE_ALIVE; + boom->visible = true; + boom->x = x; + boom->y = y; + BOOM_TTL[boom - akgl_heap_actors] = 0.25f; + } CLEANUP { + } PROCESS(errctx) { + } HANDLE(errctx, AKGL_ERR_HEAP) { + /* Explosions are decoration. When the heap is momentarily full the + * right outcome is no explosion, not a dead frame. */ + } FINISH(errctx, true); + SUCCEED_RETURN(errctx); +} +``` + ## Step 5: Boot the interpreter **Goal: the engine calls a BASIC function and prints its answer.** Everything so far was libakgl. Now link the interpreter into the same -executable. In CMake: +executable. The whole CMake recipe, inside an akbasic checkout with +`AKBASIC_WITH_AKGL=ON`: ```cmake -target_link_libraries(akbasic_example_galaga PRIVATE akbasic akgl +add_executable(mygalaga + main.c + script.c + enemies.c + player.c) +target_compile_options(mygalaga PRIVATE -Wall -Wextra) +target_compile_definitions(mygalaga PRIVATE + GALAGA_ASSET_DIR="${CMAKE_CURRENT_SOURCE_DIR}/assets" + GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/galaga.bas" + GALAGA_FONT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/assets/fonts/C64_Pro_Mono-STYLE.ttf") +target_link_libraries(mygalaga PRIVATE akbasic akgl SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image) ``` +The three baked-in paths are what let the program launch from any working +directory; `--assets` and `--script` flags can override them at runtime. + Link `akbasic` — the interpreter only. Not `akbasic_akgl` (the device backends that let a script draw), and not `akbasic_frontend` (the standalone program's host). This game lends the script **no devices at all**: the scripts compute, @@ -360,7 +474,25 @@ declines to use. The boot is the embedding host from Chapter 10, adapted to a script that only defines. Keep every line that touches the interpreter in one file — the -example's `script.c` — so the boundary stays a place rather than a habit: +example's `script.c` — so the boundary stays a place rather than a habit. That +file's interpreter-facing includes and statics, exactly: + +```c wrap=galagatypes requires=akgl +#include +#include +#include +#include +#include + +/* Static because an akbasic_Runtime is far too big for a stack frame -- + * 2.40 MiB on this branch. */ +static akbasic_Runtime SCRIPT; +static akbasic_TextSink SINK; +static akbasic_StdioSink SINKSTATE; +static char SOURCE[16384]; +``` + +The boot itself: ```c wrap=galagacalls requires=akgl CATCH(errctx, akbasic_error_register()); diff --git a/docs/21-tutorial-galaga-enemies.md b/docs/21-tutorial-galaga-enemies.md index 2ae4d76..7a7df0b 100644 --- a/docs/21-tutorial-galaga-enemies.md +++ b/docs/21-tutorial-galaga-enemies.md @@ -35,6 +35,8 @@ whole development loop; the engine never rebuilds. the game, and make it do that - **[Step 10](#step-10-prove-it)** — prove the boundary with a test that links the real files +- **[Step 11](#step-11-the-cost-measured)** — measure what thinking in BASIC + costs, against the same logic in C --- @@ -507,6 +509,56 @@ the readout tells you how each brain did: galaga: 3000 frames, screen 2, score 2350, alive 0, kills bee 20 bfly 15 boss 1, shots bee 1 bfly 1 boss 1, script errors 0 ``` +## Step 11: The cost, measured + +**Goal: the real price of the boundary, in numbers, next to the same logic in C.** + +The interop test binary ends with a benchmark: 24,000 formation-hold updates — +forty enemies at sixty frames a second for ten seconds — once through +`galaga_script_update_enemy()` and once through a line-for-line C translation +of `UPDATEBEE` with its helpers inlined. Same guard, same branches, same +arithmetic; the difference is the interpreter. On this repository's build +machine (a two-core VM, the interpreter built `-O2`): + +```text +benchmark: 24000 formation-hold updates, dt 0.016 + BASIC through the boundary: 21.147 s 881.11 us/call 35.245 ms per 40-enemy frame + the same logic in C: 0.000 s 0.01 us/call 0.001 ms per 40-enemy frame + ratio: 61022x +``` + +The facts, without decoration: + +- **A BASIC-driven update costs about four orders of magnitude more than the + same logic compiled.** The C translation of the whole state machine costs + tens of *nano*seconds; the scripted call costs high hundreds of + *micro*seconds. +- **The cost is per line executed, not per call.** The interpreter scans and + parses each body line from source text on every call; a 3-line body measured + ~148 us on this class of machine, and this ~15-line body measures ~881 us. + Body length is the knob. +- **At this cost, forty thinking enemies spend ~35 ms per frame on this + hardware** — more than two 60 Hz frames. The shipped example visibly runs + below 60 fps on this machine while the whole wave is alive, and exactly at + its frame pace once the wave thins. A faster machine moves the numbers, not + the shape. + +This is the measured version of decisions the chapters already made on +architectural grounds. Bullets, collision and the starfield are C +([Chapter 20](20-tutorial-galaga.md), Steps 2 and 4) — at two shots and forty +tests a frame, scripting them would multiply the call count for things that +decide nothing. The fire decision is one flag rather than a per-bullet +callback (Step 6): the script's call budget is bounded by the enemy count and +nothing else. C owns the formation and the spawn timing (Step 8), so zero +calls happen for enemies that do not exist yet. And the 36 KiB function slots +and 2.40 MiB runtime (Step 5) are the memory half of the same bill. + +What the cost buys is the previous ten steps: behavior as data, edited and +swapped without a compiler. Whether ~900 us per thinking entity per frame is +acceptable is a per-project decision — fewer thinkers, shorter bodies, or a +lower think rate (every Nth frame) are the standard levers, and all three are +host-side choices this architecture leaves open. + --- Where to go from here: more waves are rows in the table; a new enemy kind is diff --git a/examples/galaga/interop_test.c b/examples/galaga/interop_test.c index 775d1c9..297947a 100644 --- a/examples/galaga/interop_test.c +++ b/examples/galaga/interop_test.c @@ -24,6 +24,7 @@ #include #include #include +#include #include @@ -115,12 +116,144 @@ static akerr_ErrorContext *run_claims(void) SUCCEED_RETURN(errctx); } +/* ------------------------------------------------------------ benchmark --- */ + +/** + * @brief UPDATEBEE's state machine, translated line for line into C. + * + * The native comparator for the benchmark below: the same guard, the same + * three branches, the same arithmetic as galaga.bas's UPDATEBEE with its + * helpers inlined. Nothing is simplified, so the timing difference is the + * interpreter's, not the algorithm's. + */ +static void native_updatebee(galaga_Enemy *enemy, akgl_Actor *actor, float dt) +{ + float dx = 0.0f; + float dy = 0.0f; + float k = 0.0f; + int32_t s = 0; + + enemy->t += dt; + if ( enemy->t < 0.0f ) { + return; + } + s = enemy->state; + if ( (s & GALAGA_ES_ENTERING) != 0 ) { + dx = enemy->homex - actor->x; + dy = enemy->homey - actor->y; + k = dt * 4.5f; + if ( k > 1.0f ) { + k = 1.0f; + } + actor->x += dx * k + sinf(enemy->t * 6.0f) * 90.0f * dt; + actor->y += dy * k; + if ( fabsf(dx) < 3.0f && fabsf(dy) < 3.0f ) { + enemy->state = GALAGA_ES_FORMATION; + enemy->t = 0.0f; + } + } + if ( (s & GALAGA_ES_FORMATION) != 0 ) { + actor->x = enemy->homex + sinf(enemy->t * 1.7f) * 16.0f; + actor->y = enemy->homey; + if ( enemy->rnd < dt * 0.04f ) { + enemy->state = GALAGA_ES_DIVING; + enemy->t = 0.0f; + } + } + if ( (s & GALAGA_ES_DIVING) != 0 ) { + actor->y += (enemy->t * 150.0f + 260.0f) * dt; + actor->x += sinf(enemy->t * 4.0f) * 130.0f * dt; + dx = galaga_shared.playerx - actor->x; + if ( dx > 220.0f ) { + dx = 220.0f; + } + if ( dx < -220.0f ) { + dx = -220.0f; + } + actor->x += dx * 0.2f * dt; + if ( actor->y > 1040.0f ) { + actor->y = -90.0f; + enemy->state = GALAGA_ES_ENTERING; + enemy->t = 0.0f; + } + dx = galaga_shared.playerx - actor->x; + if ( fabsf(dx) <= 140.0f && actor->y <= galaga_shared.playery + && enemy->rnd < dt * 1.5f ) { + enemy->fire = 1; + } + } +} + +static double seconds_since(const struct timespec *t0) +{ + struct timespec t1; + + clock_gettime(CLOCK_MONOTONIC, &t1); + return (double)(t1.tv_sec - t0->tv_sec) + (double)(t1.tv_nsec - t0->tv_nsec) / 1e9; +} + +/** + * @brief The cost of thinking in BASIC, measured against the same logic in C. + * + * Both loops run the identical formation-hold workload, 24,000 calls -- forty + * enemies at sixty frames a second for ten seconds. Informational: nothing + * asserts on the timing, because CI machines vary; the numbers print so the + * tutorial can quote a real measurement. + */ +static akerr_ErrorContext *run_benchmark(void) +{ + galaga_Enemy enemy; + akgl_Actor actor; + struct timespec t0; + double basic_s = 0.0; + double native_s = 0.0; + int i = 0; + PREPARE_ERROR(errctx); + + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BEE; + enemy.state = GALAGA_ES_FORMATION; + enemy.homex = 400.0f; + enemy.homey = 300.0f; + enemy.rnd = 0.9f; + + clock_gettime(CLOCK_MONOTONIC, &t0); + for ( i = 0; i < 24000; i++ ) { + PASS(errctx, galaga_script_update_enemy(&enemy, &actor, 0.016f)); + } + basic_s = seconds_since(&t0); + + memset(&enemy, 0, sizeof(enemy)); + memset(&actor, 0, sizeof(actor)); + enemy.kind = GALAGA_ENEMY_BEE; + enemy.state = GALAGA_ES_FORMATION; + enemy.homex = 400.0f; + enemy.homey = 300.0f; + enemy.rnd = 0.9f; + + clock_gettime(CLOCK_MONOTONIC, &t0); + for ( i = 0; i < 24000; i++ ) { + native_updatebee(&enemy, &actor, 0.016f); + } + native_s = seconds_since(&t0); + + printf("benchmark: 24000 formation-hold updates, dt 0.016\n"); + printf(" BASIC through the boundary: %8.3f s %7.2f us/call %6.3f ms per 40-enemy frame\n", + basic_s, basic_s / 24000.0 * 1e6, basic_s / 24000.0 * 40.0 * 1e3); + printf(" the same logic in C: %8.3f s %7.2f us/call %6.3f ms per 40-enemy frame\n", + native_s, native_s / 24000.0 * 1e6, native_s / 24000.0 * 40.0 * 1e3); + printf(" ratio: %.0fx\n", basic_s / native_s); + SUCCEED_RETURN(errctx); +} + int main(void) { PREPARE_ERROR(errctx); ATTEMPT { CATCH(errctx, run_claims()); + CATCH(errctx, run_benchmark()); } CLEANUP { } PROCESS(errctx) { } HANDLE_DEFAULT(errctx) { -- 2.43.0 From dd10dc143ace21b6b32a10cde07dd88677150e72 Mon Sep 17 00:00:00 2001 From: Tachikoma Date: Tue, 4 Aug 2026 09:22:43 -0400 Subject: [PATCH 7/7] Close the remaining cold-read gaps: bind, labels, menus and main's shape 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 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc --- docs/20-tutorial-galaga.md | 110 +++++++++++++++++++++++++-- docs/21-tutorial-galaga-enemies.md | 18 +++++ tests/docs_preludes/galagacalls.post | 2 + tests/docs_preludes/galagacalls.pre | 31 ++++++++ 4 files changed, 155 insertions(+), 6 deletions(-) diff --git a/docs/20-tutorial-galaga.md b/docs/20-tutorial-galaga.md index 39561e3..72f9e68 100644 --- a/docs/20-tutorial-galaga.md +++ b/docs/20-tutorial-galaga.md @@ -125,7 +125,38 @@ writes `x` and `y` directly is the mover, and in this game that will be BASIC. **Error handling is the house protocol.** Every function returns `akerr_ErrorContext *`, `PASS` propagates, `ATTEMPT`/`CATCH`/`CLEANUP` brackets anything that must unwind. libakgl's docs/04-errors.md teaches it; this chapter -just uses it. The status codes this game raises are `AKERR_NULLPOINTER`, +just uses it, with two rules that keep the fragments compiling: **`CATCH` is +only legal inside an `ATTEMPT` block, and `PASS` everywhere else** — swap them +and the compiler objects about a stray `break` — and `main()` alone ends its +block with `FINISH_NORETURN(errctx)` instead of `FINISH`, because `FINISH` +expands a `return` of the context that an `int`-returning function cannot +compile: + +```c wrap=galagatypes requires=akgl +static int FAILED = 0; + +int main(int argc, char *argv[]) +{ + PREPARE_ERROR(errctx); + + (void)argc; (void)argv; + ATTEMPT { + /* CATCH each stage in order: startup, assets, the script boot, + * the spawns, then the frame loop. */ + } CLEANUP { + /* ...teardown, every call wrapped in IGNORE()... */ + } PROCESS(errctx) { + } HANDLE_DEFAULT(errctx) { + LOG_ERROR_WITH_MESSAGE(errctx, "galaga could not run"); + /* Set a flag rather than returning: leaving a HANDLE block early + * skips FINISH's release and leaks the context's pool slot. */ + FAILED = 1; + } FINISH_NORETURN(errctx); + return FAILED; +} +``` + +The status codes this game raises are `AKERR_NULLPOINTER`, `AKERR_VALUE`, `AKERR_KEY`, `AKERR_IO`, `AKERR_OUTOFBOUNDS`, `AKGL_ERR_SDL` and `AKGL_ERR_HEAP` — there is no code this tutorial invents. @@ -285,8 +316,32 @@ Each of the four lines under the comment closes a trap: invisibly. This one line cost this example its first screenshot. Input goes through a control map: push a control per key with handlers that set -flags, and let the actor's update hook read the flags. The full recipe is in -`examples/galaga/player.c` and libakgl docs/16-input.md; the shape is: +flags, and let the actor's update hook read the flags. A handler receives the +map's target actor and the event, and returns through the error protocol like +everything else — this pair is the whole pattern, repeated per key: + +```c wrap=galagagame requires=akgl +static bool MOVELEFT = false; + +akerr_ErrorContext *left_on(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + MOVELEFT = true; + SUCCEED_RETURN(errctx); +} + +akerr_ErrorContext *left_off(akgl_Actor *obj, SDL_Event *event) +{ + PREPARE_ERROR(errctx); + (void)obj; (void)event; + MOVELEFT = false; + SUCCEED_RETURN(errctx); +} +``` + +(The example keeps the flags in its `galaga_Game` struct rather than statics; +either works.) The bindings themselves are pushes onto map 0: ```c wrap=galagagame requires=akgl static akerr_ErrorContext *galaga_player_controls(void) @@ -673,10 +728,53 @@ case GALAGA_SCREEN_VICTORY: CATCH(errctx, akgl_ui_frame_end(akgl_renderer)); ``` -The playing screen is two `akgl_ui_label()` calls — score top-left, lives and -wave top-right — formatted into `static` buffers, because the UI borrows label +The playing screen is two `akgl_ui_label()` calls — a widget call per label, +not a struct — formatted into `static` buffers, because the UI borrows label text until `frame_end` and a local buffer would be dangling by the time it -draws. The title and end screens are an `akgl_ui_menu()` at the center. +draws: + +```c wrap=galagagame requires=akgl +static char HUD_SCORE[64]; +static char HUD_LIVES[64]; + +static akerr_ErrorContext *declare_play(void) +{ + int count = 0; + PREPARE_ERROR(errctx); + + PASS(errctx, aksl_snprintf(&count, HUD_SCORE, sizeof(HUD_SCORE), + "SCORE %06d", galaga_game.score)); + PASS(errctx, aksl_snprintf(&count, HUD_LIVES, sizeof(HUD_LIVES), + "LIVES %d WAVE %d", galaga_game.lives, galaga_shared.wave)); + PASS(errctx, akgl_ui_label("score", HUD_SCORE, AKGL_UI_ANCHOR_TOP_LEFT, NULL)); + PASS(errctx, akgl_ui_label("lives", HUD_LIVES, AKGL_UI_ANCHOR_TOP_RIGHT, NULL)); + SUCCEED_RETURN(errctx); +} +``` + +The title and end screens are an `akgl_ui_menu()` at the center, fed an +`akgl_UiMenu` that lives in a `static` for the same borrowing reason. The +struct is an id, the item strings, a count, the selected index, the +`activated` output flag, and a style (`NULL` for the default): + +```c wrap=galagatypes requires=akgl +static akgl_UiMenu TITLE_MENU = { + "titlemenu", { "START", "QUIT" }, 2, 0, false, NULL +}; + +static akerr_ErrorContext *declare_title(void) +{ + PREPARE_ERROR(errctx); + + PASS(errctx, akgl_ui_menu(&TITLE_MENU)); + SUCCEED_RETURN(errctx); +} +``` + +Route events to the menu with +`akgl_ui_menu_handle_event(&TITLE_MENU, event, &consumed)` — the menu for +whichever screen is up, a `bool` out-parameter reporting whether the event was +taken. Up and down move `selected`, return sets `activated`. The big **GALAGA** headline is direct text rather than a label: diff --git a/docs/21-tutorial-galaga-enemies.md b/docs/21-tutorial-galaga-enemies.md index 7a7df0b..ff14dc7 100644 --- a/docs/21-tutorial-galaga-enemies.md +++ b/docs/21-tutorial-galaga-enemies.md @@ -157,6 +157,24 @@ between the script's decision and the engine's pixel. Null physics (Chapter 20, Step 1) is what makes that safe: nothing else is trying to move the actor. +Registration and the first binding happen at boot, before the script loads — +between `akbasic_runtime_init()` and `akbasic_runtime_load()` in Chapter 20's +boot sequence. A binding is **borrowed, never copied**, so the placeholders it +points at must be static storage: + +```c wrap=galagacalls requires=akgl +CATCH(errctx, akbasic_host_register_type(&SCRIPT, &ENEMY_TYPE)); +CATCH(errctx, akbasic_host_register_type(&SCRIPT, &ACTOR_TYPE)); +CATCH(errctx, akbasic_host_register_type(&SCRIPT, &GAME_TYPE)); + +CATCH(errctx, akbasic_host_bind(&SCRIPT, "SELF@", "ENEMY", &SCRATCH_ENEMY)); +CATCH(errctx, akbasic_host_bind(&SCRIPT, "ACTOR@", "ACTOR", &SCRATCH_ACTOR)); +CATCH(errctx, akbasic_host_bind(&SCRIPT, "GAME@", "GAME", &galaga_shared)); +``` + +`akbasic_host_bind()` takes the script name, the registered type's name, and +the instance; after that, `SELF@` and `ACTOR@` are only ever *re*bound. + The per-frame call binds both names to *this* enemy before dispatching — one binding per name, pointed at forty enemies in turn, which is what `akbasic_host_rebind()` is for: diff --git a/tests/docs_preludes/galagacalls.post b/tests/docs_preludes/galagacalls.post index ce04880..e6d321b 100644 --- a/tests/docs_preludes/galagacalls.post +++ b/tests/docs_preludes/galagacalls.post @@ -4,5 +4,7 @@ (void)SCRIPT; (void)SINK; (void)SINKSTATE; (void)SOURCE; (void)args; (void)argp; (void)dtval; (void)result; (void)enemy; (void)actor; (void)dt; + (void)SCRATCH_ENEMY; (void)SCRATCH_ACTOR; (void)galaga_shared; + (void)ENEMY_TYPE; (void)ACTOR_TYPE; (void)GAME_TYPE; SUCCEED_RETURN(errctx); } diff --git a/tests/docs_preludes/galagacalls.pre b/tests/docs_preludes/galagacalls.pre index 4ebab03..781efa5 100644 --- a/tests/docs_preludes/galagacalls.pre +++ b/tests/docs_preludes/galagacalls.pre @@ -36,11 +36,42 @@ typedef struct galaga_docs_Enemy float rnd; } galaga_docs_Enemy; +typedef struct galaga_docs_Shared +{ + float playerx; + float playery; + int32_t wave; + float rnd; +} galaga_docs_Shared; + static akbasic_Runtime SCRIPT; static akbasic_TextSink SINK; static akbasic_StdioSink SINKSTATE; static char SOURCE[16384]; +static galaga_docs_Enemy SCRATCH_ENEMY; +static akgl_Actor SCRATCH_ACTOR; +static galaga_docs_Shared galaga_shared; + +static const akbasic_HostField ENEMY_FIELDS[] = { + AKBASIC_HOST_FIELD( galaga_docs_Enemy, kind, "KIND#", AKBASIC_HOSTFIELD_INT32 ) +}; +static const akbasic_HostType ENEMY_TYPE = { + "ENEMY", sizeof(galaga_docs_Enemy), ENEMY_FIELDS, 1 +}; +static const akbasic_HostField ACTOR_FIELDS[] = { + AKBASIC_HOST_FIELD( akgl_Actor, x, "X%", AKBASIC_HOSTFIELD_FLOAT ) +}; +static const akbasic_HostType ACTOR_TYPE = { + "ACTOR", sizeof(akgl_Actor), ACTOR_FIELDS, 1 +}; +static const akbasic_HostField GAME_FIELDS[] = { + AKBASIC_HOST_FIELD( galaga_docs_Shared, wave, "WAVE#", AKBASIC_HOSTFIELD_INT32 ) +}; +static const akbasic_HostType GAME_TYPE = { + "GAME", sizeof(galaga_docs_Shared), GAME_FIELDS, 1 +}; + akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt); akerr_ErrorContext AKERR_NOIGNORE *galaga_docs_fragment(galaga_docs_Enemy *enemy, akgl_Actor *actor, float dt) { -- 2.43.0