Feature: Toroid vertical slice — first live flying enemy (slice 8)

[StarshipSuperjam]

Closes #65
Closes #66
Closes #57
Closes #58
Closes #59
Closes #61
Closes #62
Closes #63
Closes #64

A green mechanical check below shows this change conforms to the engine's rules — not that it is correct. What covers correctness is the behavioural steps in Review and your own read of the change; a green check is never a substitute for that. Your merge is the binding gate.

About those checks: only the one that runs when the change is proposed for merge can stop a risky merge — a check that ran while the change was still being written is early advice. Each check is itself proven against a deliberately broken example it must catch, so a passing check can't be one that quietly did nothing — but that proves the check works, not that this change is right. And a check that could not run leaves its area unverified.

Purpose

The first complete enemy, end to end — the Toroid vertical slice — turning the dormant entity/RNG/formation foundations into live combat.

• Formation spawn → aim-approach → lateral swing → flap → single aimed shot (shooting variant) → enemy bullets → blaster-to-air hit (+30, explosion) → player-collision death → cleanup.
• First live consumer of the shared RNG (record 004) and of the slice-7 formation state; retires the debug D/G death keys and the S scoring fixture that stood in for real combat since slice 4.

Impact: area 1 now fights back — the first live enemy the player can be killed by and can destroy for score.

Scope

Toroid (AIR-01) plus the eight integration leaves that ride on it — the live dispatch walk, collision, RNG draw, air-hit award, and air-collision death.

• AIR-01 Toroid (record 024) — spawns from the live formation, aim-approaches (1.5 px/frame), swings laterally by reversing its course (arcade toroid_toggle_dir bounce) when it draws level, flaps; culls off any field edge keeping its scroll position.
• AIR-12 standard bullets (record 026) — the shooting variant (type 0x0B) fires one aimed bullet at its swing commit; the bullet flies straight and culls off any edge.
• WPN-02 / SYS-03 / ECO-01 (record 025) — a shot overlapping an active Toroid resolves once, awards 30, and the enemy explodes and is freed.
• PLY-02 — a Toroid or an enemy bullet touching the craft raises the hit; the walk's death check (gated player hit == 1 AND invuln == 0) spends a craft and respawns or ends the game.
• SYS-02 / SYS-04 — the index-order dispatch walk and live occupants; AREA-02 / FORM-01 / DIF-01 — the formation now spawns live waves.

Change profile — the shape of this pull request at a glance:

• Size: 33 files changed, +32906 / −12287 lines (the bulk is the regenerated src/xevious/project.json, a single generated artifact whose block IDs re-flow on every build).
• Kinds of thing touched: generated game logic, tests, headless harness, mechanics records, two locked specs.
• Where: docs, harness, tests, tools, src, .engine.
• Shape: one slice of the roadmap; Part of #60 (see Out of scope).

Impact: the entity/formation/RNG scaffolding built dormant in slices 1–7 becomes a live, playable enemy loop.

Behaviors

The capabilities this change delivers, each with the check that exercises it.

• A live Toroid advances under its own velocity each tick — harness toroid-wave-spawns-and-moves.
• A drawing-level Toroid reverses its lateral course (bounce, not homing) — harness toroid-swing-reverses-away.
• A player shot destroys an overlapping Toroid and scores 30 once — harness blaster-kills-toroid-and-scores.
• The shot hit box spans the rendered Toroid width but no further — harness air-shot-hit-column-bounded.
• The craft dies only on a Toroid's exact cell, not the row/column near it — harness craft-collision-is-single-cell.
• A fired shot cannot step over a Toroid between frames (no collision tunneling) — Python invariant B8-no-tunnel.
• A Toroid or bullet touching the craft runs death → respawn / game-over — harness death-respawn, death-game-over.

Out of scope

Everything past the Toroid loop — recorded, deliberate deferrals.

• Fire-permission mask consumption (DIF-03.play) — the shooting Toroid fires once without consuming any mask; Part of #60, reassigned to slice 10 (mask-consuming families).
• The add_object flying branch (Torkan/Kapi/Terrazi, slice 10); radiating bullets + Bacura-vs-craft (slice 11).
• Dedicated enemy/bullet crops and the bullet colour pulse (a later art pass — the bullet renders as a small stand-in and the kill explosion reuses the player death-burst frames); the flying-enemy hit sound (slice 20 audio).

Impact: these are named follow-ups with their own slices, not silent gaps — the Toroid loop is complete on its own.

Risk

Two locked product specs are amended (needs guardrail-ack), and the collision windows deviate from the reference for playability.

• ⚠ Locked-spec amendments — needs guardrail-ack. docs/spec/core-game-systems.md (removes the temporary D/G debug death keys now that live combat is lethal) and docs/spec/player-craft-and-weapons.md (records the shot-vs-flying hit window and its doubling). The fail-closed product-lock-integrity check names both and blocks merge until the single global guardrail-ack label is applied.
• Shot hit window doubled from the reference (16,32,8,16) to (32,64,16,32) — a recorded deviation that (a) prevents collision tunneling (the shot's 2.5-cell/frame step exceeded the 2-cell reference window) and (b) matches the 36-px rendered Toroid. The craft hurtbox is left tight on purpose (forgiving offence, precise defence). Guarded by the B8-no-tunnel invariant.
• Timing/feel is not machine-verifiable. Nothing in the repo runs a real Scratch VM, and the headless harness runs threads to settling (no per-frame stepping) — so tunneling, swing feel, and hit feel rest on the operator playtest, not a check.

Impact: the guardrail-weakening is fenced to two named spec edits under your explicit label; the deviations are documented in records 025/026 and bounded by the invariant test.

Validation

Full automated suite green; feel confirmed by the operator playtest.

• 193 Python tests, 37 headless harness scenarios (each with a biting negative), both generator check()s, mechanics-record and roadmap validators — all green.
• Two builds byte-identical (build_hash 0c7c82db…); build→import round-trip holds.
• CI: functional checks (runtime-harness, CodeQL/Analyze, engine-guard, secret-scan, actionlint, overlay-disclosure) pass; the two red checks are the consent gates (engine-ci → guardrail-ack, xevious-project → playtest-approved + owner playtest comment).

Impact: an approver can rely on the logic layer being exercised and deterministic; the on-screen layer is the playtest's, recorded below.

Review

A Standard pre-submission review ran cold (five passes) at 515db05; the operator playtest then caught three defects the review missed, each fixed and re-verified — the merged build differs materially from the reviewed one.

• Depth: Standard. Passes that ran (plain checks): spec-conformance, an adversarial divergence hunt against the locked specs, technical-integrity, security-governance, and usability, plus a scoped re-audit. Findings were dispositioned: re-anchored an ENGINE-TODO marker; a generate-time formation/slot-capacity assert; a bullet-dispatch structural clause; disclosure of the two interim art stand-ins; stale-comment/estimate fixes. No blocking security/governance defect (the aiming.json extraction is instruction-derived; invuln is test-only with zero writers; D/G/S fully removed).

• Material change after review — re-verified. Between reviewed 515db05 and submitted 299dc37, 10 files changed, 5477 insertions / 3698 deletions (net +1779 — the large figure is the regenerated project.json; the source/logic change is the swing revert plus two collision fixes plus their tests/docs). The operator playtest (this project's terminal gate for feel, since nothing runs a real VM) drove three fixes the cold review got wrong or could not see: (1) the Toroid swing was flagged inverted by the review and "fixed" to home; the playtest showed the arcade Toroid reverses — reverted and grounded against the pinned disassembly (toroid_toggle_dir), guard flipped to toroid-swing-reverses-away. (2) both collision windows reused one axis-delta reporter across their two bounds, and a Scratch reporter attaches to only one parent, so the second bound stole it — the box degraded to a quadrant/row; rebuilt each delta fresh per compare, added off-target MISS scenarios. (3) the shot tunneled through Toroids (2.5-cell/frame step > 2-cell window); window doubled and guarded by B8-no-tunnel. Each fix re-ran the full suite green. These are validated by the playtest, not by a re-run of the cold review.

• Spec-derived acceptance steps (from spec_referent.py review-steps --doc docs/spec/aerial-enemies.md) — only the shared-rules and Toroid paragraphs are live this slice; the other families' steps are for their slices:

  Things you can confirm yourself

  • Each family plays its recorded pattern — approach, trigger, fire rule, exit: Play scheduled waves of each family in the built .sb3 against this document's descriptions
  • A Zakato that fires its shot self-destructs scoring nothing; one killed first scores: Play: let one fire, kill one early
  • A Garu Zakato left alone rings 16 bullets and releases four Brag Sparios: Play (or seeded fixture) the detonation
  • Sheonites cannot be killed and track the craft in the recorded pincer-and-dock pattern: Play the boss approach

  Things I checked for you

  • Every family's speeds, fuses, windows, and per-variant differences in the build's data match this document: Data-table comparison fixture over the build's generated family constants
  • All families share one blaster hit window and one explosion; Giddo Spario's short variant excepted: Structural fixture over the build's collision and animation data
  • Fire timing draws from the shared stream under the family mask (seeded waves repeat exactly): Seeded fixture: identical seeds reproduce identical wave behavior

Impact: the engine's account is that the logic conforms and was reviewed; the swing/collision/tunneling corrections rest on the operator playtest — your merge is the binding gate.

Demonstration

Open the delivered .sb3 in Scratch 3 / TurboWarp and play area 1 — the behaviors fail visibly if broken.

• Toroid waves appear after the first formation record and keep refilling until a reset row; a Toroid draws level and bounces away (not into you); the shooting variant fires one aimed bullet at its swing.
• Shoot a Toroid you're lined up under → it explodes and the score rises by exactly 30; held fire mows down a column of Toroids (the fix that this PR's last commit addressed — before it, shots passed through).
• Touch a Toroid or its bullet → death → respawn (craft remain) or GAME OVER (last craft), immediately vulnerable.
• Stop and green-flag with a wave on screen → no orphan clones survive.
• Interim art (note, don't fail): the enemy bullet is a small stand-in costume; the kill explosion reuses the player death-burst frames.

Impact: the operator can watch every claimed behavior work or fail; the full sweep is docs/PLAYTEST_CHECKLIST.md.

Files of interest

The generator, the two locked specs, the tests, and the four mechanics records.

• tools/game_director.py (spawn/aim/swing/cull, both collision windows, the walk) and the regenerated src/xevious/project.json.
• docs/spec/aerial-enemies.md (settled this slice), docs/spec/core-game-systems.md + docs/spec/player-craft-and-weapons.md (locked amendments — guardrail-ack).
• tests/test_scratch_project.py (structural contracts, B8-no-tunnel, pinned build_hash), harness/lib/catalog.js (live scenarios).
• docs/mechanics/023–026-*.md.

Impact: the generator and the two locked specs most determine whether this merge is sound.

AI involvement

Claude Code (Opus) authored the slice end to end under the operator's direction and playtest gate.

• AI drove: the block-DSL generation, the reference-grounded behavior port (aim/swing/cull/collision), the tests and harness scenarios, and the diagnosis of the three playtest defects (swing direction, reporter single-parent steal, collision tunneling).
• Operator-driven: the plan approval and review depth, the playtest verdicts (the authority on feel that overturned the review's swing finding), and every consent gate — the guardrail-ack and playtest-approved labels and the merge itself.

Impact: AI judgment is load-bearing on the reference port and the collision fixes; the operator's playtest and labels are the binding checks over it.

🤖 Generated with Claude Code

[github-actions]

These engine-internal files are regenerated by the update.

The engine rebuilds them from your project's own current state on each update. A change here that reflects a real change in your project — you edited what the file is generated from and regenerated it — is reproduced, not lost. But content typed directly into one of these files, with no matching change to the source it comes from, will not survive: it is rebuilt away on the next update. So if you meant to change what one of these records, edit the source it is generated from (for the settled-criteria record, your docs/spec/), not the file itself:

• .engine/product-spec-matrix.json

This is a heads-up only — it does not block your merge, and your merge is the decision.

[StarshipSuperjam]

Playtest record — approved

Tested head commit: 299dc376363bbbbe19ed20ec910fc092229fcadd (299dc37), built to dist/Xevious.sb3 sha256 0c7c82db73b670f15695af5e9b6a7568506b4a42cb19e58bdaa8f13f6bf8f519.

Played area 1 in Scratch 3 across the slice-8 behavior list (spawn → aim → swing → flap → shot → blaster-to-air kill/+30 → collision death → cleanup). After the three playtest-driven fixes (swing reversal, single-cell/bounded collision boxes, and the anti-tunneling shot-window widening) the Toroids behave and destroy correctly — not pixel-exact to the arcade, but a good faithful port. Approved to merge; further hit-feel tuning can follow as more mechanics come online.

Interim art stand-ins (enemy bullet costume, reused explosion frames) noted, not blocking — deferred to the art pass per the PR's Out of scope.

[StarshipSuperjam]

Follow-up: the reported seedAirKill "seeds inert slot 36" item — not a bug, closing

A work item was raised during this slice claiming harness/lib/catalog.js's seedAirKill seeds the player shot into slot 36 = SOLVALOU_SLOT (the craft's own slot), making the seed inert — so blaster-kills-toroid-and-scores would be scoring only via a stray shot rather than the controlled seed it claims to test. I checked this against both the director source and the running VM, and the premise doesn't hold up.

Root cause of the confusion: Scratch 1-based lists vs. JS 0-based arrays

tools/game_director.py numbers slots as Scratch item numbers (Scratch lists are 1-based): SOLVALOU_SLOT = 36, SHOT_SLOTS = (37, 39). The check air shot hit detector reads list_item("slot type", …, number(s)) for s in range(37, 40) — Scratch items 37/38/39.

readVar(...) in the harness returns a plain 0-based JS array, so Scratch item N lands at JS index N − 1:

• Detector shot slots (Scratch items 37/38/39) → JS indices 36/37/38
• SOLVALOU_SLOT (Scratch item 36) → JS index 35

So seedAirKill's default shotSlot = 36 is a JS index, i.e. the first real detector slot (Scratch item 37) — not the craft, and not inert.

Evidence (running VM: clear leftover shots, seed enemy + one controlled shot in each JS slot, step once)

seeded shot JS index	score delta	shot consumed?
enemy only (no shot)	0	—
35 (craft, Scratch item 36)	0	no
36 (Scratch item 37)	30	yes
37 (Scratch item 38)	30	yes
38 (Scratch item 39)	30	yes
39 (Scratch item 40)	0	no

In the scenario as it runs today, after the step it is slot 36's state that flips 1→0 while 37/38 stay active — the seeded shot is the one that resolves the hit. blaster-kills-toroid-and-scores scores via its controlled seed, for the right reason, and the neutralizeProc('check air shot hit') negative still bites (enemy-only → 0 delta). Two incidental corrections: reachPlaying does not deliberately fire a shot (it taps start precisely to avoid a held-space shot), and air-shot-hit-column-bounded's use of JS slot 37 is also a valid detector slot (Scratch item 38) — correct, just not because "37 is the first real detector slot."

Changing the default from JS 36 → 37 would swap one valid detector slot for another: it fixes nothing and would force a matching edit to the scenario's slot-state[36] read. No change made; no build_hash change.

One real (minor, deferred) weakness

There is a genuine fragility nearby, just misdiagnosed: seedAirKill does not clear reachPlaying's three stray active shots (JS 36/37/38), and it parks the enemy at an arbitrary absolute cell (5000, 4000). Those stray shots (on the craft column) happen not to overlap that cell today, so the delta is exactly 30 — but that's coincidental. A robust hardening (clear JS shot slots 36/37/38 before seeding + park the enemy a few columns off the craft column) would guarantee exactly one controlled shot with no contamination. That's an enhancement to a currently-correct test, not a bug fix — noted here for later, not done in this slice.

Resolution: closing as not-a-bug.