c64-kb 0.17.0

package/templates/platformer/README.md

@@ -0,0 +1,277 @@
+# platformer: a side-scrolling platformer starter
+
+A small game that plays: a level 2,048 pixels wide scrolls through a
+38-column window as you run; you jump with 8.8 fixed-point physics, walk
+up 45-degree and 1-in-2 slopes, land on blocks and one-way ledges, stomp
+enemies that wake as they come near the screen, collect coins, and have
+three lives. A HUD sits under the playfield and an original two-voice tune
+plays. Title, fire to start, game over back to the title. PAL and NTSC,
+Oscar64 C with a KickAssembler part.
+
+Start a game from it in c64-kb:
+`npm run new-project -- platformer ~/c64/mygame`.
+
+## Playing
+
+`make run` opens VICE; give it a joystick device for port 2 ("Driving it
+headless" below says how). Left and right run,
+fire jumps, down + fire drops through a ledge. Land on an enemy from
+above to squash it (100); a coin is 10; the flag at the far end is 1,000
+and starts the level again.
+
+## Files
+
+| File | Holds |
+|---|---|
+| `src/main.c` | The frame loop, the states (title, play, dying, game over, level clear), lives |
+| `src/game.h` | Every shared constant, variable and function, in one place |
+| `src/level.c` | The level as ten lines of text, the 2 x 2 metatiles, cell lookups, the slope height table |
+| `src/art.c` | Every picture as text: playfield glyphs, sprite shapes, hit boxes |
+| `src/player.c` | The physics every body shares (walk, fall, land) and the player on top |
+| `src/actors.c` | Enemies: the activation window, five live slots, walker and hopper, hit boxes by group |
+| `src/view.c` | VIC-II: bank 3, the camera, the three-page scroll, sprite shadows |
+| `src/anim.c` | Animation sequences (frame, duration, loop or hold) |
+| `src/hud.c`, `src/sound.c` | Score digits and HUD text; sound effects on SID voice 3 |
+| `src/engine.asm` | KickAssembler: the slice copy for the scroll, the two raster IRQs, the tune and its player |
+| `src/autopilot.h`, `src/verdict.h` | AUTOPILOT builds only: the scripted joystick and the self-check |
+| `tools/tearcheck.py` | Renders the level from `src/` and proves no picture tears (`make tearcheck`) |
+| `expect.json`, `stage-expect.json`, `PLAN.md` | The screenshot checks, the crowded-level checks (`make stage`); the plan with the c64-kb tool output |
+
+## How a frame runs
+
+The main loop waits for the IRQ at raster line 251, then writes the
+sprites, plays the tune and the effects, runs the player, the enemies and
+the camera, and publishes the next picture's `$D018` and `$D016` as one
+pair. Two raster IRQs in `engine.asm` own those registers: at line 212,
+inside the blank character row 20, the HUD gets 40 columns, hires and its
+own screen page; at line 251 the playfield gets the published pair back.
+A frame whose work runs long therefore shows the last picture again,
+never a half-set one.
+
+The scroll never shifts or redraws the page on display; a taken coin's
+cells and the sprite pointers are the only writes to it, and a level
+restart redraws all three pages at a cut. XSCROLL moves the picture a
+pixel; a column crossing is only a `$D018` flip, because three pages are
+kept: the one on display, the one the camera just left, and one prepared
+for the next column in the direction of travel, five rows a frame, by a
+KickAssembler copy one column over plus the new column's cells from the
+level. The camera moves at most 2 pixels a frame, so the next crossing is
+at least 4 frames off and 4 slices are enough. A frame never carries a
+whole 20-row shift (an earlier draft of this starter did: 9,457 cycles in
+one frame, measured with `PROF=3`).
+
+Memory: VIC bank 3. Pages at `$C000`, `$C400` and `$E800`, the HUD page at
+`$C800`, sprites at `$CC00`, the character set at `$E000` (the ROM's
+glyphs 0-63 copied in, so text and the meter read). BASIC and KERNAL are
+banked out (`$01` = `$35`). Colour RAM is never scrolled: the playfield's
+four colours are `$D021`, `$D022`, `$D023` and the colour RAM's green.
+
+## The measured frame
+
+The harness meter (CIA2 timer A) over the first 255 play frames of the
+autopilot run, VICE x64sc 3.10, `make shot check`:
+
+| Model | Worst | Typical (median) | Frame |
+|---|---|---|---|
+| PAL | 11,758 | 6,212 | 19,656 |
+| NTSC | 12,216 | 6,573 | 17,095 |
+
+Per subsystem, built with `-dPROF=n` (worst / typical, PAL; NTSC within
+400 cycles of each):
+
+| n | Subsystem | Worst | Typical |
+|---|---|---|---|
+| 1 | player physics, coins | 4,237 | 1,686 |
+| 2 | enemies: window, AI, hit boxes | 3,682 | 2,269 |
+| 3 | camera and scroll slice | 4,001 | 240 |
+| 4 | sprites to the VIC, tune, effects | 925 | 706 |
+| 5 | HUD, sprite shadows, publish | 1,346 | 915 |
+
+The meter covers play frames 1-255 of about 835. A review of an earlier
+build metered two later windows (from frames 275 and 560): their worst was
+below the first window's, their typical about 1,000 cycles above it. Not
+re-measured on this build.
+
+The worst frames of the parts do not fall together: the whole frame's
+worst is 11,758, not their sum. Every figure is wall time, so badline and
+sprite DMA are in it, and so is the split IRQ when it lands inside the
+bracket (work past line 212; about 56 cycles by arithmetic). The IRQ at
+251 falls just before the bracket opens and is not counted: about 66
+cycles by arithmetic.
+
+Against `plan-budget` (PLAN.md): it gave 10,167 to 10,765 cycles plus
+1,432 fixed, 11,599 to 12,197 in all, verdict undetermined, with the
+scroll left out (its only figure was the old recipe's 74,041-cycle shift,
+issue #18) and six techniques unknown. The measured worst is 11,758 on PAL,
+inside that range, and 12,216 on NTSC, 19 cycles above its top (an earlier build, before the walker
+and HUD cuts below, was 356 and 785 cycles above its top). The parts disagree more than
+the total: the budget charges per-frame-hitbox 3,693 and decimal-print
+1,361 from their recipes, where this game tests a few box pairs and adds
+score digits without division. For the player physics it charges only
+slope_collision's 455, with no figure for fixed_point_8_8 or
+jump_arc_table; measured, the player is 4,237 worst. The measured typical
+frame, 6,212, is far under the budget's low end, because most frames have
+no column slice and no HUD change.
+
+## Enemies on screen
+
+The stock level never fills every slot, but a level an agent writes can. `make stage` builds the run with row 7 crowded (ten
+enemies in the first view, `STAGE_CROWD` in `src/level.c`), so every slot
+is live from the first play frame, and wants no late frame in the whole run
+and the meter's worst inside one frame on each model.
+
+| Build | NSLOT | Worst PAL | Worst NTSC | Late frames |
+|---|---|---|---|---|
+| walkers probing every step, HUD redrawn whole | 6 | 17,105 | 17,262 | yes |
+| walker judges the column ahead once; HUD figures only | 6 | 15,632 | 15,977 in frames 1-255; 17,618 from frame 400 | on NTSC |
+| the same | 5 | 14,523 | 14,829 in frames 1-255; 15,353 from frame 400 (measured once; no target re-measures that window) | none, either model |
+
+So `NSLOT` is 5: sprites 1-5 are enemies, sprite 6 is free. Six live
+enemies overran an NTSC frame by about 520 cycles; a sixth needs about
+1,000 more cycles cut from the enemy loop first (`-dPROF=2`). The walker
+cut: a walker judges the column 6 pixels ahead once, when it first reaches
+it (edge, step or wall), and each step is one ground snap; odd and even
+slots step on alternate frames.
+
+## Proving it
+
+| Command | What it proves | Last result |
+|---|---|---|
+| `make shot check` | 23 checks: the verdict, the HUD text (so the split's 40 columns and XSCROLL 0), the player sprite where arithmetic puts it, the hopper where the run leaves it, the scrolled playfield's brick, grass and pit at camera 576, the blank row 20, PAL and NTSC identical, the meter | 23 of 23 passed |
+| `make selftest` | FORCE_FAULT makes a coin worth 20: the verdict fails, the HUD score reads 000200 | check.py rejected the build |
+| `make tearcheck` | 16 shots a model mid-play, each matched pixel for pixel against a render of the level | 32 of 32 whole or two-frame composites; the TEAR_DEMO build: 2 of 32 torn (the count moves with the code; one is enough) |
+| `make stage` | Every enemy slot live from the first play frame: no late frame, the meter inside one frame | 4 of 4 passed (worst 14,523 PAL, 14,829 NTSC) |
+| `make claims` | Every store the run makes, title to verdict, against CLAIMS_ARGS | 0 violations |
+| `make disk` | `build/platformer.d64`; it boots to the title | |
+
+The self-check (`src/verdict.h`) grades the game's own state after the
+script: every event seen (jump, landing, slope, ledge, coin, stomp, hit,
+respawn, wake, sleep, both scroll directions, a wall), the score equal to
+coins x 10 + stomps x 100, the lives, the player stopped by the brick at
+x 716 and the camera at 576 (both arithmetic), every ready page equal to
+the level at its column, the activation window's rules, the player's
+sprite registers against the model, and no late frame.
+
+After every play frame it also checks four invariants, each with its own
+bit, so a fault that heals before the end still fails the run:
+
+| Bit | Invariant | Mutation that trips it (PAL run) |
+|---|---|---|
+| `0800` | no dormant, living enemy inside the view (a pop-in) | wake window cut to the middle 24 columns: `FAIL 0880` |
+| `1000` | every live enemy inside the drop window it was judged against | the drop never happens: `FAIL 1181` |
+| `2000` | a grounded player stands exactly on its cell's surface | `surface_walk` reads every slope at column 0: `FAIL 223D` (tearcheck still 32 of 32: only this bit sees it) |
+| `4000` | the page to show is the camera's column, and whole | left crossings ignored: `FAIL 4001`; tearcheck 28 of 32 |
+
+Hits use boxes per animation frame with a group and a mask (c64-kb
+`per_frame_hitbox`). The falling frame (`SH_FALL`, from the jump table's
+apex on) carries two boxes, the body and the feet; only the feet are in the
+stomp group, so a stomp is the feet reaching an enemy, not a height test.
+Boxes are bytes relative to the player's foot; an enemy more than 40 pixels
+away is not listed. Mutation: the feet box put in the player group turns
+the scripted stomp into a hit, and the run ends in GAME OVER with the
+verdict failed.
+
+How the tear check works: VICE's exit screenshot is taken mid-frame, so a
+shot can hold two frames, split at the beam. `tools/tearcheck.py` finds,
+line by line, the camera positions at which the level render matches the
+shot, and allows one seam between parts at most 2 pixels (one frame of
+camera) apart, and only if the lower part, the older frame, is exactly
+the camera the program printed on HUD row 23 ("CAM 0576") for that frame.
+The same number must match the playfield in every shot: a page flipped
+without its XSCROLL is 8 pixels off. A mid-picture XSCROLL write also
+splits a shot into parts 1-2 pixels apart; the review's mutation (XSCROLL
+written again at line 150) passed four shots as two frames until the
+lower-part rule was added, and is now caught. Rows that are all sky match
+every camera, so a tear inside them cannot be seen, by this check or by
+eye. The TEAR_DEMO build
+shifts the page on display in place, the old way; the check catches it
+(off by 8, or torn), so the check can see a tear.
+
+## Extending it
+
+1. **A second level, or longer ones.** Edit the text in `src/level.c`;
+   keep the metatile keys. For more than fits in memory, compress it with
+   c64-kb `level-rle-decoder` (`docs/recipes/oscar64/level-rle-decoder.md`)
+   or load levels from disk (`kernal_file_read_seq`,
+   `docs/techniques/file-io.md`). `tools/tearcheck.py` renders the
+   `LEVEL` text block, so a compressed level needs it changed too. Then re-time `src/autopilot.h` with
+   `-dDEBUG_AT=n` builds: the script is a timeline, so a changed level
+   changes the run.
+2. **More enemies on screen than five.** One sprite per live slot is the
+   limit here. A multiplexer lifts it: `sprite_multiplex_8`
+   (`docs/recipes/oscar64/sprite-multiplex-8.md`) or the game multiplexer
+   `sprite_multiplex_game` (`docs/recipes/kickassembler/sprite-multiplex-game.md`).
+   The activation window already hands out slots; raising `NSLOT` is the
+   easy part. The multiplexer's IRQs must join `engine.asm`'s `$FFFE`
+   chain around lines 212 and 251, and it replaces `view_apply`.
+3. **Parallax or a vertical component.** `charset_parallax`
+   (`docs/recipes/oscar64/charset-parallax.md`) moves reserved glyphs for
+   a background layer at no screen cost. Vertical scrolling needs
+   `eight_way_scroll_double_buffer` (`docs/recipes/kickassembler/eight-way-scroll.md`),
+   whose redraw and colour bands this three-page scheme would replace.
+
+Smaller steps: a high-score table on disk (`high-score-persist`,
+`docs/recipes/oscar64/high-score-persist.md`; the harness's `SHOT_DISK=1`
+attaches the image during `make shot`), a variable jump height (cut
+`pjump` to `JUMP_APEX` when fire is released while rising), more tiles
+(add a key, four glyphs and their art).
+
+## Driving it headless
+
+`make joy` builds the normal game with its port byte read from `$02FE`
+instead of `$DC00`; `tools/drive.py` (from the action-puzzle starter) plays
+it over VICE's binary monitor, at real speed (no warp; the monitor port is
+DRIVE_PORT or a free one), and reads the HUD page. Measured: title,
+fire, LIVES 3, holding right loses all three lives, GAME OVER, the title
+with HI 000030, fire, a new game at LIVES 3.
+
+```bash
+make joy
+python3 tools/drive.py build/platformer-joy.prg "until:PRESS FIRE" tap:fire \
+    "until:LIVES 3" hold:right "until:GAME OVER" "until:PRESS FIRE" print
+```
+
+`make run` starts the windowed VICE with no joystick device chosen: pick
+one for port 2 in its settings, or pass one, e.g.
+`make run X64SC_WINDOWED="x64sc -joydev2 1"` (1 is the numeric keypad,
+from `x64sc -help`; not tried here).
+
+## Which Oscar64
+
+It builds and passes on both the local build named in c64-kb's CLAUDE.md
+(1.32.271 plus c1270bc) and the released v1.32.273: `make shot check`,
+`selftest` and `stage` pass on each (v1.32.273: worst 11,756 PAL, 12,204
+NTSC). Two workarounds make that so, both for faults of the released
+compiler that the local build does not have:
+
+- `surface_at` (`src/level.c`) is `__noinline`. Inlined into
+  `surface_walk`, v1.32.273 and upstream 9a902f6 compile
+  `heights[((a & A_SLOPE) >> 1) | (x & 7)]` as `ORA heights,x` with X as
+  `cell_attr` left it, and never compute the index: the player stops a few
+  pixels up the first 45-degree slope and the run ends at LIVES 0. Issue
+  #30 holds the fault.
+- `hud_draw` writes the score through `put_digits`. A loop storing
+  `HUD22[6 + i]` kept only the first digit on v1.32.273 (the HUD read
+  `SCORE 0`); not reduced or filed.
+
+## Left out on purpose
+
+- The high score is not saved: it lives until power-off.
+- No sprite multiplexer: at most five enemies live (see "Enemies on screen").
+- No vertical scroll; the playfield is 20 rows, the level 10 tiles high.
+- Colour RAM does not scroll: four colours for the whole playfield.
+- NTSC runs the same per-frame steps at 60 Hz, so the game and the tune
+  are 6/5 as fast there (c64-kb `pal_ntsc_tempo_mismatch`), and the tune's
+  pitches, tabled for the PAL clock, about 4% sharp (arithmetic).
+- One effect at a time on voice 3; a new one cuts the last.
+
+## Not established
+
+- A real `$DC00` joystick: the normal game was played through `make joy`
+  (a RAM port byte), not through the CIA.
+- Real hardware: everything was measured in VICE x64sc 3.10.
+- The tune was never listened to; its note table is arithmetic.
+- The tear check samples 32 moments of one run; it does not prove every
+  frame. The three-page rule (the scroll never writes the page shown) is
+  the design reason; the self-check compares every ready page with the
+  level, and row 20 of every page with the sky.

package/templates/platformer/expect.json

@@ -0,0 +1,32 @@
+{
+  "checks": [
+    { "name": "own verdict (border)", "type": "verdict" },
+    { "name": "verdict line", "type": "text", "row": 21, "col": 0, "text": "RESULT 01 PASS" },
+    { "name": "HUD: score, coins, lives (40 columns, XSCROLL 0 after the split)", "type": "text", "row": 22, "col": 0, "text": "SCORE 000150  COINS 05  LIVES 2" },
+    { "name": "HUD: high score", "type": "text", "row": 23, "col": 0, "text": "HI 000000" },
+    {
+      "name": "player at the wall: x 716, feet on line 179 (sprite X 163, Y 157; stand art columns 3-13)",
+      "type": "sprite",
+      "colour": 1,
+      "vic_x": 166,
+      "line": 158,
+      "width": 11,
+      "height": 21
+    },
+    {
+      "name": "hopper where the scripted run leaves it (pinned from the run; the program checks its own sprite registers)",
+      "type": "sprite",
+      "colour": 3,
+      "vic_x": 32,
+      "line": 167,
+      "width": 14,
+      "height": 12
+    },
+    { "name": "scrolled playfield: brick tile 46 top row at camera 576 (VIC X 191, line 147)", "type": "rect", "colour": 7, "vic_x": 191, "line": 147, "width": 16, "height": 1 },
+    { "name": "scrolled playfield: grass on tiles 43-44 (VIC X 143-174, lines 179-180)", "type": "rect", "colour": 5, "vic_x": 143, "line": 179, "width": 32, "height": 2 },
+    { "name": "scrolled playfield: the pit at tiles 41-42 is sky (VIC X 111-142)", "type": "rect", "colour": 6, "vic_x": 111, "line": 179, "width": 32, "height": 16 },
+    { "name": "row 20, between playfield and HUD, is blank", "type": "rect", "colour": 6, "vic_x": 31, "line": 211, "width": 304, "height": 8 },
+    { "name": "display the same on both models", "type": "same", "cells": [0, 0, 23, 39] },
+    { "name": "frame meter, the first 255 play frames", "type": "meter", "row": 24, "col": 20, "frames": 255 }
+  ]
+}

package/templates/platformer/src/actors.c

@@ -0,0 +1,289 @@
+// actors.c: enemies placed in the level wake when they come within a
+// window around the view, and go back to the level table when they leave
+// it, so a patrol survives off screen and a stomped enemy stays dead
+// (c64-kb actor_activation_window). The live ones sit in NSLOT slots, one
+// sprite each (object_pool). Hits are tested box against box, each box
+// from the animation frame on show (per_frame_hitbox).
+#include "game.h"
+
+#define MARGIN 4                    // wake window: the view plus 4 columns each side
+#define HYST   2                    // live actors are kept 2 columns further out
+#define SCAN_K 8                    // level entries examined a frame, round robin
+#define HOP_WAIT 70                 // frames a hopper sits between hops
+#define HOP_START 8                 // vy_tab entry a hop starts from: a lower arc than a jump
+#define ENEMY_H 15                  // enemy feet to head
+
+char lvl_count;
+char lvl_col[NLVL], lvl_ty[NLVL], lvl_type[NLVL], lvl_flags[NLVL];
+
+char slot_lvl[NSLOT];
+unsigned slot_x[NSLOT], slot_y[NSLOT];
+char slot_type[NSLOT], slot_jump[NSLOT], slot_timer[NSLOT];
+static char slot_probe[NSLOT];      // the column ahead the walker last judged
+static bool slot_turn[NSLOT];       // and whether it turns there
+bool slot_left[NSLOT], slot_squashed[NSLOT];
+struct Anim slot_anim[NSLOT];
+
+static char scan_pos, win_lo, win_top, tick;
+char drop_lo, drop_top;             // this frame's drop window, in columns
+
+void actors_reset(void)
+{
+    for (char s = 0; s < NSLOT; s++)
+        slot_lvl[s] = NO_SLOT;
+    scan_pos = 0;
+}
+
+static void activate(char i)
+{
+    char s = 0;
+    while (slot_lvl[s] != NO_SLOT)
+        if (++s == NSLOT)
+            return;                         // every slot live: it wakes on a later scan
+    slot_lvl[s] = i;
+    slot_type[s] = lvl_type[i];
+    slot_x[s] = lvl_col[i] * 8 + 8;
+    slot_y[s] = (unsigned)((lvl_ty[i] + 1) * 16) << 8;
+    slot_jump[s] = JUMP_APEX;               // it drops onto whatever is under it
+    slot_left[s] = lvl_flags[i] & LF_LEFT;
+    slot_timer[s] = HOP_WAIT / 2 + (i & 15);
+    slot_squashed[s] = false;
+    slot_probe[s] = 0xff;
+    slot_anim[s].seq = nullptr;
+    anim_set(&slot_anim[s], lvl_type[i] == T_WALKER ? an_walk : an_hop_sit);
+    lvl_flags[i] |= LF_LIVE;
+    events |= EV_WAKE;
+}
+
+// Back to the table: where it is now, which way it faces, one tile row up
+// so a wake drops it onto the surface again.
+static void deactivate(char s)
+{
+    char i = slot_lvl[s];
+    lvl_col[i] = (slot_x[s] - 8) >> 3;
+    lvl_ty[i] = (char)((slot_y[s] >> 8) >> 4) - 1;
+    lvl_flags[i] = (lvl_flags[i] & ~(LF_LIVE | LF_LEFT)) | (slot_left[s] ? LF_LEFT : 0);
+    slot_lvl[s] = NO_SLOT;
+    events |= EV_SLEEP;
+}
+
+static void kill(char s)
+{
+    char i = slot_lvl[s];
+    lvl_flags[i] = (lvl_flags[i] & ~LF_LIVE) | LF_DEAD;
+    slot_lvl[s] = NO_SLOT;
+}
+
+// Both windows in columns, clamped to the level, so every compare is a byte.
+static void set_window(void)
+{
+    int cc = camx >> 3;
+    int lo = cc - MARGIN, hi = cc + 40 + MARGIN;
+    win_lo = lo < 0 ? 0 : lo;
+    win_top = hi > 255 ? 255 : hi;
+    drop_lo = lo - HYST < 0 ? 0 : lo - HYST;
+    drop_top = hi + HYST > 255 ? 255 : hi + HYST;
+}
+
+// Half a pixel a frame; odd and even slots take turns, so a crowd costs
+// half as much on any one frame. The column WALK_AHEAD pixels in front is
+// judged once, when the walker first reaches it: an edge, a step too high
+// or low, or a wall there turns the walker. Each step then costs one
+// surface_walk for the ground snap (about 300 cycles by the meter's PROF
+// runs, against about 1,100 when every step also probed walls and the
+// ground ahead; README, "Enemies on screen").
+#define WALK_AHEAD 6
+
+static void walker(char s)
+{
+    if ((tick ^ s) & 1)
+        return;
+    signed char dx = slot_left[s] ? -1 : 1;
+    char fy = slot_y[s] >> 8;
+    unsigned nx = slot_x[s] + dx;
+    unsigned probe = nx + dx * WALK_AHEAD;
+    char pc = probe >> 3;
+    if (pc != slot_probe[s])
+    {
+        slot_probe[s] = pc;
+        char ahead = surface_walk(probe, fy);
+        slot_turn[s] = ahead == 0xff || (ahead > fy && ahead - fy > MAX_SNAP) ||
+                       (ahead < fy && fy - ahead > MAX_RISE) || wall_at(probe, fy, ENEMY_H);
+    }
+    if (slot_turn[s])
+    {
+        slot_left[s] = !slot_left[s];
+        slot_probe[s] = 0xff;               // judge the other way afresh
+        return;
+    }
+    char sy = surface_walk(nx, fy);
+    slot_x[s] = nx;
+    if (sy != 0xff)
+        slot_y[s] = (unsigned)sy << 8;
+}
+
+static void hopper(char s)
+{
+    slot_left[s] = px < slot_x[s];          // it watches the player
+    if (--slot_timer[s] == 0)
+    {
+        slot_timer[s] = HOP_WAIT;
+        slot_jump[s] = HOP_START;
+        anim_set(&slot_anim[s], an_hop_up);
+    }
+}
+
+void actors_update(void)
+{
+    tick++;
+    set_window();
+    char i = scan_pos;
+    for (char k = 0; k < SCAN_K; k++)
+    {
+        if (i < lvl_count && !(lvl_flags[i] & (LF_LIVE | LF_DEAD)))
+        {
+            char c = lvl_col[i];
+            if (c >= win_lo && c <= win_top)
+                activate(i);
+        }
+        i = (i + 1) & (NLVL - 1);
+    }
+    scan_pos = i;
+
+    for (char s = 0; s < NSLOT; s++)
+    {
+        if (slot_lvl[s] == NO_SLOT)
+            continue;
+        struct Anim *a = &slot_anim[s];
+        anim_step(a);
+        if (slot_squashed[s])
+        {
+            if (anim_done(a))
+                slot_lvl[s] = NO_SLOT;      // already dead in the table
+            continue;
+        }
+        if (slot_jump[s] != 0xff)
+        {
+            if (air_step(slot_x[s], &slot_y[s], &slot_jump[s], ENEMY_H, false))
+            {
+                slot_jump[s] = 0xff;
+                if (slot_type[s] == T_HOPPER)
+                    anim_set(a, an_hop_sit);
+            }
+        }
+        else if (slot_type[s] == T_WALKER)
+            walker(s);
+        else
+            hopper(s);
+
+        char fy = slot_y[s] >> 8;
+        char c = slot_x[s] >> 3;
+        if (fy > 200 && fy < 240)
+            kill(s);                        // fell into a pit
+        else if (c < drop_lo || c > drop_top)
+            deactivate(s);
+    }
+}
+
+bool enemy_near(unsigned x, char dist)
+{
+    for (char s = 0; s < NSLOT; s++)
+    {
+        if (slot_lvl[s] != NO_SLOT && !slot_squashed[s])
+        {
+            unsigned e = slot_x[s];
+            if ((e > x ? e - x : x - e) < dist)
+                return true;
+        }
+    }
+    return false;
+}
+
+// ---- hits: boxes per animation frame, emitted where the sprites are ----
+// Coordinates are bytes relative to the player's foot, placed at (BOX_O,
+// BOX_O); an enemy is listed only within NEAR pixels each way, so every
+// compare in the pass is one byte (16-bit world X is taken apart once per
+// enemy, never per box pair). After c64-kb per_frame_hitbox.
+#define BOX_O 64
+#define NEAR  40
+#define MAXB  (2 + NSLOT)
+static char nbox;
+static char bl[MAXB], br[MAXB], bt[MAXB], bb[MAXB], bg[MAXB], bm[MAXB], bo[MAXB];
+
+static void emit_boxes(char owner, char shape, char left, char top)
+{
+    char k = hb_first[shape], e = k + hb_count[shape], i = nbox;
+    for (; k != e; k++, i++)
+    {
+        const struct HBox *h = &hbox[k];
+        bl[i] = left + h->x0;
+        br[i] = left + h->x1;
+        bt[i] = top + h->y0;
+        bb[i] = top + h->y1;
+        bg[i] = h->group;
+        bm[i] = h->mask;
+        bo[i] = owner;                      // 0 the player, 1 + slot an enemy
+    }
+    nbox = i;
+}
+
+// The slots the feet hit and the slots the body hit, as bit masks.
+char hit_stomp, hit_body;
+
+static void collide(void)
+{
+    hit_stomp = hit_body = 0;
+    for (char i = 0; i + 1 < nbox; i++)
+    {
+        char m = bm[i];
+        for (char j = i + 1; j < nbox; j++)
+        {
+            if (!(m & bg[j]))
+                continue;                   // a pair that cannot hurt each other
+            if (bl[i] <= br[j] && bl[j] <= br[i] && bt[i] <= bb[j] && bt[j] <= bb[i])
+            {
+                char p = bo[i] ? j : i, e = bo[i] ? bo[i] : bo[j];
+                char bit = 1 << (e - 1);
+                if (bg[p] == G_STOMP)
+                    hit_stomp |= bit;
+                else
+                    hit_body |= bit;
+            }
+        }
+    }
+}
+
+// Any enemy the feet reach is stomped; a body touch by any other hurts.
+void actors_collide(void)
+{
+    if (pinvuln)
+        return;
+    nbox = 0;
+    char fy = py >> 8;
+    emit_boxes(0, panim.shape + (pleft && panim.shape < SH_MIRROR ? SH_MIRROR : 0), BOX_O - 8, BOX_O - 21);
+    for (char s = 0; s < NSLOT; s++)
+    {
+        if (slot_lvl[s] == NO_SLOT || slot_squashed[s])
+            continue;
+        int dx = (int)slot_x[s] - (int)px;
+        signed char dy = (char)(slot_y[s] >> 8) - fy;
+        if (dx > -NEAR && dx < NEAR && dy > -NEAR && dy < NEAR)
+            emit_boxes(1 + s, slot_anim[s].shape, (char)dx + (BOX_O - 8), (char)dy + (BOX_O - 16));
+    }
+    collide();
+    for (char s = 0; s < NSLOT; s++)
+    {
+        if (!(hit_stomp & (1 << s)))
+            continue;
+        slot_squashed[s] = true;
+        anim_set(&slot_anim[s], an_squash);
+        lvl_flags[slot_lvl[s]] = (lvl_flags[slot_lvl[s]] & ~LF_LIVE) | LF_DEAD;
+        pjump = JUMP_BOUNCE;
+        stomps++;
+        score_add(1, 0);
+        events |= EV_STOMP;
+        sfx_play(SFX_STOMP);
+    }
+    if (hit_body & ~hit_stomp)
+        player_hurt();
+}

package/templates/platformer/src/anim.c

@@ -0,0 +1,51 @@
+// anim.c: sprite animation from tables (c64-kb sprite_animation_table).
+// A sequence is (shape, frames) pairs ending in AN_LOOP n (go to pair n)
+// or AN_HOLD (stay on the last pair). Facing is not in the tables: the
+// player adds SH_MIRROR to the shape when it faces left.
+#include "game.h"
+
+#define AN_LOOP 0xff
+#define AN_HOLD 0xfe
+
+const char an_stand[]   = { SH_STAND, 1, AN_HOLD };
+const char an_run[]     = { SH_RUN1, 6, SH_STAND, 4, SH_RUN2, 6, SH_STAND, 4, AN_LOOP, 0 };
+const char an_jump[]    = { SH_JUMP, 1, AN_HOLD };            // rising
+const char an_fall[]    = { SH_FALL, 1, AN_HOLD };            // falling: the stomp box
+const char an_hurt[]    = { SH_HURT, 1, AN_HOLD };
+const char an_walk[]    = { SH_WALK1, 8, SH_WALK2, 8, AN_LOOP, 0 };
+const char an_squash[]  = { SH_SQUASH, 24, AN_HOLD };
+const char an_hop_sit[] = { SH_HOP_SIT, 1, AN_HOLD };
+const char an_hop_up[]  = { SH_HOP_UP, 1, AN_HOLD };
+
+void anim_set(struct Anim *a, const char *seq)
+{
+    if (a->seq == seq)
+        return;
+    a->seq = seq;
+    a->pos = 0;
+    a->shape = seq[0];
+    a->count = seq[1];
+}
+
+void anim_step(struct Anim *a)
+{
+    if (a->count == 0 || --a->count)
+        return;                         // held (0), or the pair is not over
+    char p = a->pos + 2;
+    char op = a->seq[p];
+    if (op == AN_LOOP)
+        p = a->seq[p + 1] * 2;
+    else if (op == AN_HOLD)
+    {
+        a->count = 0;                   // stays on the last pair
+        return;
+    }
+    a->pos = p;
+    a->shape = a->seq[p];
+    a->count = a->seq[p + 1];
+}
+
+bool anim_done(struct Anim *a)
+{
+    return a->count == 0;
+}