akbasic/docs/20-tutorial-galaga.md

# 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, 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.

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 <stdbool.h>
#include <stdint.h>
#include <string.h>

#include <SDL3/SDL.h>
#include <SDL3_image/SDL_image.h>
#include <SDL3_ttf/SDL_ttf.h>

#include <akerror.h>
#include <akstdlib.h>

#include <akgl/actor.h>
#include <akgl/character.h>
#include <akgl/controller.h>
#include <akgl/draw.h>
#include <akgl/error.h>
#include <akgl/game.h>
#include <akgl/heap.h>
#include <akgl/physics.h>
#include <akgl/registry.h>
#include <akgl/renderer.h>
#include <akgl/sprite.h>
#include <akgl/text.h>
#include <akgl/ui.h>
#include <akgl/util.h>
```

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.

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
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. 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)
{
    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.

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. The whole CMake recipe, inside an akbasic checkout with
`AKBASIC_WITH_AKGL=ON`:

```cmake
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.