m3te

A match-3 game written entirely in the sx language, targeting iOS first.

• Game logic, rendering, input, and UI are all authored in sx.
• Art (palettes, sprite sheets) is produced as real assets.
• Verification gate: sx logic tests pass AND the iOS app builds & launches in the Simulator.

Development is driven by the multi-agent flow (Product Owner → Worker → Reviewer → Observer).

Verification gate

The gate has two halves. Both must pass. The sx compiler used below lives at /Users/agra/projects/sx/zig-out/bin/sx (override the runner's binary with the SX env var). Run everything from the repo root.

1. Logic tests

Pure-sx logic tests run under sx and have their stdout + exit code diffed against committed snapshots in tests/expected/. A failed assertion exits the process non-zero, so it fails the runner (and the gate).

bash tools/run_tests.sh

• A test is any tests/<name>.sx that has a tests/expected/<name>.exit marker; tests/test.sx (the expect assert helper) has no marker, so it is not itself run.
• Regenerate snapshots after an intentional change: bash tools/run_tests.sh --update.

2. iOS Simulator build + launch

Build the app for the simulator, then install/launch it on an available device and screenshot the rendered scene — the brighter candy match-3 board: a soft pink→lavender→blue gradient background, an 8×8 grid of glossy candy gems on cream cell tiles, and a grape candy HUD card (score / moves) above the grid.

# Build the .app bundle (sx-out/ios/M3te.app):
/Users/agra/projects/sx/zig-out/bin/sx build --target ios-sim main.sx

# Discover an available simulator — do NOT hardcode a udid:
xcrun simctl list devices available
# e.g. capture the first available device's UDID into $udid:
udid=$(xcrun simctl list devices available | grep -Eo '[0-9A-Fa-f-]{36}' | head -1)

# Boot it (skip if already "Booted") and bring the Simulator window up:
xcrun simctl boot "$udid" || true
open -a Simulator

# Install, launch (bundle id co.swipelab.m3te), wait for the board to render, then
# screenshot. The wait is REQUIRED: screenshotting immediately after `launch` grabs
# the blank white launch screen, before the scene has drawn. ~2 s is ample; poll the
# screenshot if you want it tighter.
xcrun simctl install booted sx-out/ios/M3te.app
xcrun simctl launch booted co.swipelab.m3te
sleep 2
xcrun simctl io booted screenshot /tmp/m3te.png

Render-readiness wait — applies to every sim capture recipe in this README. Each deterministic section below shows only the pinned launch command (it swaps a different scene in for the launch line above); capture it exactly as here — after the launch, wait for the first rendered frame (sleep 2, or poll the screenshot) before xcrun simctl io booted screenshot. Skipping the wait captures the white launch screen, not the board.

The screenshot should match goldens/p6_idle_t0.png (the resting candy board), modulo the status-bar clock — pixel-exact equality is not required; compare the board + HUD region, not the top status strip. A tap selects a cell; a swipe between two adjacent gems commits a swap (legal swaps cascade + score, illegal ones ping back). The deterministic capture hooks below pin a chosen scene so each golden reproduces from a clean checkout.

The earlier p0_* goldens (a pre-board orange quad over a blue clear, from the P0 foundation slice) were removed in P13.1: the app no longer renders that scene, so they could only ever mislead.

Deterministic animation capture (P6.3)

The per-gem idle loop (gem_anim.sx) is always-on, so a plain screenshot is time-dependent. Two environment variables pin the visual state so the board can be captured reproducibly. The simulator forwards any SIMCTL_CHILD_* variable to the launched app, so prefix them on the simctl launch:

• M3TE_ANIM_TIME=<seconds> freezes the animation clock at that phase. t=0 is the resting board — every gem sits at its static pose, so the pre-P6.3 goldens reproduce unchanged. A larger t (e.g. 1.0) shows the mid-breath idle deformation. The select/land reactions read this same pinned phase.
• M3TE_SELECT=<cellIndex 0..63> (= row*8 + col) force-selects a cell at startup, so the selection highlight + pop can be captured without a tap.

Every M3TE_* pin is read once, at app startup. A simctl launch against an already-running copy just foregrounds the existing process (the launch prints the same PID) and the new SIMCTL_CHILD_* value is ignored. So every multi-launch recipe below passes --terminate-running-process on each pinned launch — it kills the running copy first, so the fresh process re-reads the new pin. (xcrun simctl terminate booted co.swipelab.m3te before each relaunch does the same.) A changed PID between launches confirms the new pin took.

# Resting board (idle at rest): goldens/p6_idle_t0.png
SIMCTL_CHILD_M3TE_ANIM_TIME=0   xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Mid-breath idle: goldens/p6_idle_mid.png
SIMCTL_CHILD_M3TE_ANIM_TIME=1.0 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Selection pop on cell (3,3): goldens/p6_select.png
env SIMCTL_CHILD_M3TE_ANIM_TIME=0.17 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

With no variable set the game runs fully live (the clock advances by delta_time). tests/gem_pose.sx locks the t==0-rest invariant headlessly.

Level-state capture (P7.2)

The win/lose banner and restart button are driven by the model's level_status (score vs. goal vs. move budget). Three more env hooks force a terminal status (or a restart) so the banner / restart states can be screenshot deterministically without scripting a winning swipe — combine them with M3TE_ANIM_TIME to pin the idle clock:

• M3TE_TARGET=<n> overrides the per-level score goal. 0 makes the fresh board read won immediately (score 0 ≥ goal 0).
• M3TE_MOVE_LIMIT=<n> overrides the move budget. 0 makes it read lost (budget spent below the goal).
• M3TE_RESTART=<non-zero> runs board.restart after the overrides, capturing the fresh in_progress board the restart button produces.

# Win banner + restart over the board: goldens/p7_win.png
env SIMCTL_CHILD_M3TE_TARGET=0 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Lose banner ("OUT OF MOVES") + restart: goldens/p7_lose.png
env SIMCTL_CHILD_M3TE_MOVE_LIMIT=0 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Fresh in_progress board after restart: goldens/p7_restart.png
env SIMCTL_CHILD_M3TE_TARGET=0 SIMCTL_CHILD_M3TE_RESTART=1 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

While a banner is up the board freezes (only the restart button is live, per P7.1's finished-level rule); tests/banner_layout.sx locks the restart button's rect ↔ hit-test round-trip headlessly.

Match-FX capture (P11.1)

The match bursts + score popup (board_fx.sx) only spawn off a committed move, which the simulator can't script (there is no public touch injection). One more env hook forces a representative match at startup so the FX can be screenshot deterministically — combine it with M3TE_ANIM_TIME to freeze the phase:

• M3TE_FX=<n> commits the n-th currently-legal swap (1-based, clamped; =1 is the first) through the normal plan_and_commit path, then begins the move timeline + its burst/popup FX. While M3TE_ANIM_TIME is set the move/FX timelines are pinned at that phase (the frame loop holds them frozen), so the burst and floating +points render identically every run. A larger M3TE_ANIM_TIME lands past the timeline, capturing the settled board with the FX fully pruned. Startup-only and guarded by the var, so normal play is untouched.

The legal-swap order is the fixed enumeration in tests/expected/swap_legality.stdout (row-major, right-before-down). For seed 1337, M3TE_FX=3 is the vertical red 3-match used by the golden, and M3TE_FX=11 is a depth-5 cascade (the deepest on this seed) used to capture the escalated combo emphasis (next section).

# Punchy match burst + "+30" popup, pinned mid-clear: goldens/p6_fx_match.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same match, later phase — FX fully gone over the settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

Escalating combo emphasis (P11.2)

The combo FX escalates with cascade depth (mv.rounds.len), the SAME depth the cascade SFX (play_cascade) steps up on: a deeper cascade gets a bigger, hotter- gold +points popup topped by a COMBO xN label, and bursts that grow from the first round. The depth→emphasis clamp (fx_combo_level) mirrors the cascade cue's cascade_cue_index exactly (depth ≤ 1 → floor, depth ≥ 5 → ceiling); the equivalence is locked headlessly by tests/fx_combo.sx.

Capture it with the same M3TE_FX hook — M3TE_FX=11 is a depth-5 cascade on seed 1337, contrasted against the depth-1 single clear M3TE_FX=3:

# Escalated COMBO x5 + gold "+1050" + bigger burst: goldens/p11_combo_deep.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Single clear for contrast — plain white "+30", no COMBO label (goldens/p6_fx_match.png):
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Deep cascade at a later phase — all combo FX gone over the settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

The combo emphasis is purely visual and self-pruning: it never gates input (BoardAnim.active owns gating) and never touches board / score / move state.

Glossier gem & selection feel (P11.3)

The selection highlight (board_view.sx render_selection) is a candy-glossier overlay: two concentric stroked rings fake a soft outward glow, a warm wash tints the cell, a bright rim is doubled by a thin inner highlight for a glassy edge, and a wet sheen rides the selected gem's live pose. The engine can't tint a texture at draw time (issue 0002), so every layer is a rect/overlay — never a gem-texture tint. The selection-pop motion still comes from gem_anim, so the t==0 idle pose is byte-identical to the static sprite (locked by tests/gem_pose.sx); the gloss is selection-only, so the resting board (no selection) is unchanged.

Capture it with the same P6.3 hooks — no new env var:

# Glossy candy selection on cell (3,3), pinned mid-pop: goldens/p6_select.png
env SIMCTL_CHILD_M3TE_ANIM_TIME=0.17 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same selection at exact rest (no pop) — isolates the overlay:
env SIMCTL_CHILD_M3TE_ANIM_TIME=0 SIMCTL_CHILD_M3TE_SELECT=27 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

The selection gloss is purely visual: it never gates input (BoardAnim.active owns gating) and never touches board / score / move state.

Organic swap motion (P16.1)

A legal swap no longer slides flatly into place: render_swap drives the two gems with ease_out_back (the P15.1 overshoot curve), so they shoot a touch PAST their target cells then settle exactly onto them. The curve pins f(0)=0 and f(1)=1, so the swap stays purely visual — t==0 is the rest pose and t==1 lands byte-on-cell; the committed move and final board are unchanged. The reused SWAP_ANIM_DUR (0.16 s) is untouched, so the cascade-cue timing snapshots (tests/cascade_rounds.sx / cascade_cue.sx) don't churn.

Capture the overshoot with the same M3TE_FX hook, pinned near the peak (swap-phase t ≈ 0.625, where the gems are ~10 % past target):

# Swapped gems caught PAST their target cells (overshoot): goldens/p16_swap.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.10 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same swap at exact rest (t=0) — gems sit dead-on their pre-swap cells:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

M3TE_FX=3 is the top-row swap (5,0)↔(6,0) that completes the vertical red 3-match in column 5; at M3TE_ANIM_TIME=0.10 the red lands ~8 % left of col-5 and the green ~12 % right of col-6 (every unswapped gem stays centered).

Organic illegal swap (P16.2)

A rejected swap no longer pings flatly out and back: render_swap now drives the two gems with bad_swap_bounce (a P15.1 spring-based envelope), so they lunge toward each other then spring home, overshooting rest by a bounded amount before settling. The curve pins f(0)=0 and f(1)=0, so the move stays purely visual — both t=0 and t=1 are the rest pose, the board is byte-identical to pre-swap, no move or score is spent. The envelope (endpoints, single lunge peak + location, damped settle) is locked headlessly by tests/easing.sx.

The bounce only plays for an illegal swap, which the sim can't script, so one more env hook forces a known rejected pair at startup — combine it with M3TE_ANIM_TIME to freeze the phase:

• M3TE_BADSWAP=<n> commits the n-th currently-ILLEGAL orthogonally-adjacent pair — the complement of legal_swaps, enumerated in the SAME stable row-major order (right-before-down), 1-based + clamped — through the normal plan_and_commit path (which reverts the illegal swap), then begins the move timeline so the swap-segment bounce can be screenshot. No FX begins (a rejected swap clears nothing). Startup-only and guarded by the var, so normal play is byte-identical with it unset.

The lunge peak is at swap-phase t = BADSWAP_LUNGE_T (0.36), i.e. animation time 0.36 × SWAP_ANIM_DUR (0.16) ≈ 0.0576 s. For seed 1337, M3TE_BADSWAP=41 is the mid-board horizontal pair (2,3)↔(3,3):

# Springy lunge caught at its extreme (gems nudged toward each other): goldens/p16_badswap.png
env SIMCTL_CHILD_M3TE_BADSWAP=41 SIMCTL_CHILD_M3TE_ANIM_TIME=0.0576 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same rejected pair at exact rest (t=0) — gems sit dead-on their pre-swap cells:
env SIMCTL_CHILD_M3TE_BADSWAP=41 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

Organic fall — gravity accel (P17.1)

Falling gems no longer decelerate into place: render_fall now drives the per-round drop with ease_in_cubic (the P15.1 accelerate-from-rest curve) instead of ease_out_cubic, so gems start slow and accelerate down like gravity. The curve pins f(0)=0 and f(1)=1, so each gem still lands EXACTLY on its destination cell at the segment's end — the seam to the next round / settled board stays invisible and move.final is untouched (tests/anim_plan.sx contiguity stays green). FALL_ANIM_DUR (0.22 s) is unchanged, so the per-round cascade-cue timing snapshots (tests/cascade_rounds.sx / cascade_cue.sx) don't churn.

The visual tell of the accel: pinned mid-fall, gems are bunched HIGH near their sources (little distance covered) rather than spread out near landing. Capture it with the M3TE_FX hook; M3TE_FX=11 is the depth-5 cascade on seed 1337, pinned inside round 3's fall window [1.38, 1.60) s — at 1.51 we are ~59 % through that segment in time, yet ease_in_cubic(0.59) ≈ 0.20, so the gems have covered only ~20 % of their drop and hang caught in the upper rows over the filled lower board (the old ease_out_cubic(0.59) ≈ 0.93 would have them ~93 % down, all but landed):

# Gems caught bunched-high mid-fall under gravity accel: goldens/p17_fall.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.51 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — fully settled board (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

The round-k fall window is [0.30 + 0.36·k, 0.52 + 0.36·k) s on the swap→(clear,fall)* timeline (swap 0.16, then clear 0.14 + fall 0.22 per round), so 1.51 lands squarely in round 3's fall. The change is render-only — no board.sx model change, and normal play is byte-identical apart from the fall's motion curve.

Organic fall — per-column stagger (P17.2)

The fall no longer drops a whole row in lockstep: render_fall offsets each COLUMN's drop START by a small bounded delay (fall_stagger_t), so a refilled row pours in as a left-to-right cascade. Column col waits FALL_STAGGER_MAX·col/7 (FALL_STAGGER_MAX = 0.30) of the fall window, then falls over the remaining 1 - 0.30, feeding that local progress through ease_in_cubic so each column still accelerates under gravity within its own window. The LAST column lands EXACTLY at t=1 and every earlier column strictly before it, so NO gem is ever left mid-air at the segment end — the seam to the next round / settled board stays invisible and move.final is untouched (tests/anim_plan.sx contiguity stays green; tests/easing.sx pins fall_stagger_t's f(0)=0, f(1)=1, monotonicity, and the mid-fall cascade ordering). FALL_ANIM_DUR (0.22 s) is unchanged, so the per-round cascade-cue snapshots don't churn.

The cleanest tell is a round where several adjacent columns refill the SAME distance: in lockstep their gems share one height (a flat row); staggered, they form a diagonal. On seed 1337, M3TE_FX=11 round 4 refills columns 2–7 by one cell each (its fall window [1.74, 1.96) s); at 1.91 the leading column has just landed while the trailing column is still ~⅔ cell high, so the top row reads as a left-to-right staircase instead of a flat band:

# Refilled row pouring in as a staggered cascade: goldens/p17_stagger.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.91 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — every gem landed exactly on the model board:
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

The change is render-only — no board.sx model change, and normal play is byte-identical apart from the fall's per-column timing.

Organic fall — landing squash-&-settle (P17.3)

Each landing gem now flattens wide-and-short on impact then wobbles back to rest (P15.1's squash_envelope), applied WITHIN the fall so EVERY cascade round bounces, staggered per column — not only the final whole-move settle as before. render_fall ages a per-column bounce from each column's touch-down instant (fall_landing_frac · FALL_ANIM_DUR), so a gem still in the air is drawn unsquashed and only a gem that has reached its cell flattens; the squash carries across the fall→clear seam (render_clear continues the previous round's bounce) and across the final render_anim → render_gems seam (the settle stamp is back-dated per column so land_squash resumes exactly where the fall left it — ONE bounce, no double-pop). land_squash is now LAND_SQUASH_A · squash_envelope(tl/LAND_DUR), so the per-round fall bounce and the settle bounce are the same single envelope; amplitude is the tasteful ~13 % peak (LAND_SQUASH_A = 0.18). Durations are unchanged, so the cascade-cue snapshots don't churn; M3TE_ANIM_TIME=0 still reproduces goldens/p6_idle_t0.png exactly (a resting board carries no landing stamp).

The visual tell: pin a round's fall just before it ends and the leading columns sit landed-and-squashed (wide-short) while the trailing columns are still airborne — a staggered squash wave. On seed 1337, M3TE_FX=11 round 4 (the refill round) at 1.94 shows columns 2–4 landed and flattened with columns 5–7 still pouring in (every round behaves identically — round 2 [1.02,1.24) at 1.21 and round 3 [1.38,1.60) near 1.58 bounce the same way, so the bounce is NOT limited to the last settle):

# Staggered landing squash mid-pour (leading cols flattened, trailing airborne):
#   goldens/p17_land.png
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=1.94 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same cascade past the timeline — fully settled, bounce decayed to rest (no golden):
env SIMCTL_CHILD_M3TE_FX=11 SIMCTL_CHILD_M3TE_ANIM_TIME=3.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

All three fall goldens were re-captured in P19.2 to the final, fully-merged fall motion (gravity accel + per-column stagger + landing squash), each pinned to foreground a different tell of it: goldens/p17_fall.png (round 3 at 1.51) catches the columns bunched HIGH under the gravity accel before any has landed (so it carries no squash); goldens/p17_stagger.png (round 4 at 1.91) catches the left-to-right staircase as the leading column just touches down; and this golden (round 4 at 1.94) catches the squash wave once the leading columns have landed-and-flattened while the trailing ones still pour in. The change is render-only — no board.sx model change, and a resting board is untouched.

Organic combine — anticipation pop on clear (P18.1)

Matched gems no longer just pop-then-shrink flatly: clear_pop_scale now shapes the clear as a candy pop in three beats over its local 0..1 — a tiny anticipation squash dip (a "gather" ~8 % below rest), a snappy overshoot up to ~1.40× via P15.1's ease_out_back, then an accelerating collapse to nothing (ease_in_quad). The endpoints stay LOCKED — t==0 → 1.0 (rest) and t==1 → 0.0 (gone) — so the seam to the model board is clean and M3TE_ANIM_TIME=0 still reproduces the resting board; the soft particle burst / +points popup (board_fx.sx) compose on top. tests/gem_pose.sx pins the new envelope (locked rest endpoints, the anticipation dip below rest, the overshoot above 1, and the strictly monotonic post-peak collapse). CLEAR_ANIM_DUR (0.14 s) is unchanged, so the per-round cascade-cue timing snapshots (tests/cascade_rounds.sx / cascade_cue.sx) don't churn.

The pop peaks at clear-phase local t ≈ 0.37; for M3TE_FX=3 (the seed-1337 vertical red 3-match in column 5, rows 0–2) the clear window is [0.16, 0.30) s. Because P18.2 staggers each matched gem's pop START (see below), the 0.21 capture no longer catches the three gems together at this shared peak — it catches them at DIFFERENT points on this same curve, a ripple: the top gem collapsing, the middle rising toward its overshoot, and the bottom still at rest (full size), all composed with the burst and "+30" popup:

# Per-gem candy-pop shape, staggered across the match by P18.2 (composed w/ burst):
#   goldens/p18_pop.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.21 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Same match at exact rest (t=0) — board sits at its resting pose, no pop:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

goldens/p6_fx_match.png (the P11.1 burst+popup reference, pinned at 0.22) was refreshed for the new pop shape (and re-refreshed in P18.2 for the stagger — pinned mid-clear, the committed frame now shows the ripple, not a uniform pop). This step is the per-gem pop SHAPE only; the per-gem STAGGER of the explosions follows in P18.2. The change is render-only — no board.sx model change, and normal play is byte-identical apart from the clear's pop curve.

Organic combine — staggered clear ripple (P18.2)

The matched gems no longer all explode at once: within a clearing round each gem's pop (and its burst) START is offset by a small BOUNDED delay so the cells detonate as a RIPPLE. clear_ripple_t(t, u) mirrors fall_stagger_t's (t-delay)/window: a gem's normalized rank u ∈ [0,1] (its diagonal col+row position within the round's matched cells, lowest = 0) delays its pop START by CLEAR_STAGGER_MAX·u (0.45 of the clear window), then plays the P18.1 clear_pop_scale curve over the remaining 1 − CLEAR_STAGGER_MAX. The rank is normalized PER ROUND (not across the board) so even a 3-match ripples across the full stagger budget. It is BOUNDED: every matched gem still reaches local 1 (scale 0, fully cleared) by the clear segment's end — the last-to-start gem (u=1) lands exactly at t==1 — so no gem is left mid-pop at the seam to the fall. The bursts (board_fx.sx) carry the SAME per-gem delay so they ripple in lockstep with the pops. tests/easing.sx pins the envelope (locked f(0,·)=0 / f(1,·)=1 endpoints, bounded completion by t==1, monotonicity, and the rank ordering).

INTRA-ROUND VISUAL ONLY: the per-round cascade audio (P10.10) is untouched — one ascending cue per round at the round's clear, NOT per gem — and the model is unchanged (same cells cleared, same final board). CLEAR_ANIM_DUR (0.14 s) is unchanged, so the cascade-cue snapshots (tests/cascade_rounds.sx / cascade_cue.sx) don't churn and M3TE_ANIM_TIME=0 still reproduces the resting board.

For M3TE_FX=3 (the seed-1337 vertical red 3-match in column 5, rows 0–2) the clear window is [0.16, 0.30) s; at M3TE_ANIM_TIME=0.22 the ripple is at its clearest — the TOP gem is collapsing, the MIDDLE is mid-burst, and the BOTTOM is still full-size (not yet started):

# Staggered clear ripple (top collapsing / middle bursting / bottom not yet):
#   goldens/p18_stagger.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.22 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Past the timeline — all three cells cleared per the model, board continues:
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

goldens/p18_pop.png (M3TE_FX=3 at 0.21), goldens/p6_fx_match.png (M3TE_FX=3 at 0.22), and goldens/p11_combo_deep.png (M3TE_FX=11 at 0.22) were refreshed — each was pinned mid-clear, so each now shows the staggered ripple instead of the prior simultaneous pop.

FPS counter — dev overlay (P20.1)

A small FPS readout for gauging frame cost while tuning the animations. It is a dev overlay, OFF by default: only the M3TE_FPS env pin turns it on, so default play and every committed golden stay byte-identical (with M3TE_FPS unset the rendered scene is unchanged — goldens/p6_idle_t0.png reproduces exactly).

• M3TE_FPS=<non-zero> renders the FPS counter in the top-left corner (inside the safe area, clear of the centered notch / Dynamic Island and the centered HUD). The rate is computed from the per-frame delta_time as an exponential moving average (FPS_DT_SMOOTH = 0.9) so the digits don't jitter. Read once at startup like every other M3TE_* pin; =0 or unset leaves it off. Purely a render overlay — no board / score / move / animation state changes, and it never gates input. delta_time is real wall-clock even when M3TE_ANIM_TIME pins the animation, so the counter stays live while the rest of the scene is frozen.

# FPS counter over the resting board: goldens/p20_fps.png
# (the FPS digits are DYNAMIC — only the FPS text varies run-to-run; the rest of the
#  scene is pinned at M3TE_ANIM_TIME=0, byte-identical to goldens/p6_idle_t0.png)
env SIMCTL_CHILD_M3TE_FPS=1 SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# On device, pass the same flag through devicectl's environment instead:
#   xcrun devicectl device process launch --environment M3TE_FPS=1 ... co.swipelab.m3te

goldens/p20_fps.png is the only golden that captures this overlay; because the FPS digits are dynamic, compare the FPS text's PRESENCE in the top-left corner, not its exact value. Every other golden is captured with M3TE_FPS unset and is unaffected.

Move-timeline frame goldens (P6.1 / P6.2)

The board-motion timeline (board_anim.sx: swap slide → matched-gem clear → collapse/refill fall) and the match-FX layer (board_fx.sx) were first locked by a set of frame goldens captured off ONE committed move. They use the same M3TE_FX hook as the FX captures above — M3TE_FX=3 is the seed-1337 vertical red 3-match (a single round) — each pinned with M3TE_ANIM_TIME to a phase of the swap→clear→fall→ settled timeline. Re-captured in P19.2 so each now shows the organic motion merged in P16–P18 (swap overshoot, anticipation-pop clear ripple, gravity-accel fall); the canonical per-feature organic goldens live in the P16/P17/P18 sections above, and these are the generic timeline frames at their segment midpoints.

# Swap segment midpoint — the swapped gems caught PAST target (ease_out_back
# overshoot): goldens/p6_anim_swap.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.08 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Clear segment midpoint — matched gems mid pop-ripple, composed with the burst and
# "+30" popup. The SAME committed-move frame backs all three of:
#   goldens/p6_anim_clear.png == goldens/p6_fx.png == goldens/p6_inputlock_board.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.23 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Fall segment midpoint — the refilled column caught bunched high under gravity
# accel: goldens/p6_anim_fall.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=0.41 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
# Settled board past the timeline — FX fully pruned, the move's final board. The
# SAME settled frame backs all three of:
#   goldens/p6_anim_after.png == goldens/p5_swap_after.png == goldens/p6_fx_after.png
env SIMCTL_CHILD_M3TE_FX=3 SIMCTL_CHILD_M3TE_ANIM_TIME=2.0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

p6_anim_clear / p6_fx / p6_inputlock_board are one and the same frame — the timeline's clear segment, the burst/popup FX, and the input-locked in-flight board are all the same committed-move moment — as are the three settled *_after goldens.

The resting-board goldens — goldens/p4_board.png, goldens/p4_hud.png, goldens/p9_polish.png, and goldens/p5_swap_before.png (the swap's start pose) — are the seed-1337 board at rest, captured with no move committed:

# Resting candy board / HUD (no move): p4_board.png, p4_hud.png, p9_polish.png,
# p5_swap_before.png
SIMCTL_CHILD_M3TE_ANIM_TIME=0 \
    xcrun simctl launch --terminate-running-process booted co.swipelab.m3te

They match goldens/p6_idle_t0.png over the board+HUD region (the t==0 rest invariant, tests/gem_pose.sx); only the status-bar clock and the bottom home-indicator chrome vary per grab, never the board or HUD.

Audio bank (P10) — final model

The SFX bank (audio.sx) is a purely additive layer over iOS System Sound Services (AudioToolbox, reached by #foreign FFI exactly as the platform reaches UIKit/Metal). Each cue is loaded once at startup into its own SystemSoundID; playback is a single C call. The bank only plays when every cue loaded (loaded gate), so a partial/failed bank mutes rather than playing a stale id. It never reads or mutates score / board / move state — board_view and the frame loop just tell it an event happened.

Provenance — the user-provided "Triple Treat SFX" pack

The nine shipped cues are best-fit selections from the user-supplied Triple Treat SFX pack (Triple_Treat_SFX.zip, ~30 MB, 280 Unity-style files). The pack itself is not committed — only the selected, converted cues live in assets/audio/; the source archive is kept outside the repo (in ~/Downloads). Full per-cue notes are in assets/audio/LICENSE.txt. The shipped game never re-synthesizes anything; it only loads the finished WAVs.

cue	game event	pack source (under Triple Treat SFX/)
swap.wav	every committed swipe (subtle)	Transition SFX/Swipe FX 1-RCM.wav
match.wav	first clear of a legal move (pop)	Pop:Bubble SFX/Pop FX 5-RCM.wav
combo1.wav	cascade round 1 (dullest)	Match SFX/Match FX 2-RCM.wav (~1.7 kHz)
combo2.wav	cascade round 2	Match SFX/Match FX 4-RCM.wav (~2.1 kHz)
combo3.wav	cascade round 3	Match SFX/Match FX 6-RCM.wav (~3.2 kHz)
combo4.wav	cascade round 4	Match SFX/Match FX 7-RCM.wav (~4.7 kHz)
combo5.wav	cascade round ≥5 (brightest)	Match SFX/Match FX 3-RCM.wav (~6.8 kHz)
win.wav	level won (stinger)	Success:Power-Up SFX/Power Up FX 1-RCM.wav
lose.wav	level lost (stinger)	Fail SFX/Fail FX 2-RCM.wav

The Match-FX set does not cleanly pitch-ascend, so combo1..5 are ordered by ascending spectral brightness (centroid 1.68 < 2.09 < 3.18 < 4.70 < 6.77 kHz) so a deeper cascade reads as more exciting.

Per-round ascending cascade

The cascade plays one ascending cue per cascade round — round 1 → combo1, round 2 → combo2, … clamped at combo5 — not a single end-of-move sound. Each cue fires on the move's animation timeline, edge-triggered as that round's clear begins: the frame loop (main.sx) diffs cascade_rounds_started(elapsed, rounds) against BoardAnim.cascade_fired and plays the next combo cue per newly-cleared round (sfx_cascade). The depth→index clamp (cascade_cue_index: depth ≤ 1 → 0, depth ≥ 5 → 4) is pure + headless, snapshot-tested by tests/cascade_cue.sx and tests/cascade_rounds.sx. A single match (one round) plays only the match pop — no combo cue. The swap cue plays for any committed gesture (legal or the reverted ping-back); a legal move adds the match pop on its first clearing round; the win/lose stinger fires once, edge-triggered, as the banner comes up.

Format / level spec

Every cue is delivered in exactly the form System Sound Services loads directly: WAVE / mono / 44100 Hz / signed-16-bit PCM. The pack sources are 24-bit / 48 kHz / stereo; each was down-mixed to mono, trimmed to its punchy window, eased in with a short fade, rounded out with a cosine fade-out tail, and peak-normalized to a gentle −15 dBFS (the user rejected aggressive SFX twice). The candy character of the pack is preserved — the cues are not re-synthesized.

Capturing the cue ordering

Every play is NSLog'd, so a playthrough's cue order is readable from the device log. The deep cascade (M3TE_FX=11, depth-5 on seed 1337) must be launched live (no M3TE_ANIM_TIME pin) so the timeline advances and the per-round cues fire in sequence:

# Deep cascade, live — fires combo1..combo5 one per round on the timeline:
SIMCTL_CHILD_M3TE_FX=11 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te
xcrun simctl spawn booted log show --last 20s \
    --predicate 'eventMessage CONTAINS "[sx] audio"' --style compact
# Win / lose stingers (also live so the banner edge-triggers the cue). Each pinned
# launch passes --terminate-running-process: the M3TE_* pins are read only at
# startup, so relaunching a still-running copy reuses its PID and the new pin is
# ignored — without it the lose launch reuses the win process and only `cue win`
# ever prints. A changed PID between the two launches confirms each pin took:
SIMCTL_CHILD_M3TE_TARGET=0     xcrun simctl launch --terminate-running-process booted co.swipelab.m3te   # cue win
SIMCTL_CHILD_M3TE_MOVE_LIMIT=0 xcrun simctl launch --terminate-running-process booted co.swipelab.m3te   # cue lose

Asset regeneration

The shipped game only loads finished assets; the steps below rebuild them and are never run at play time. Refresh any affected goldens/ after an art change.

Audio (the SFX bank)

The shipped cues are not synthesized — each is a real Triple Treat SFX pack clip selected per game event (per-cue source in assets/audio/LICENSE.txt). To re-derive a cue from the pack, take its source file and apply the same DSP the shipped bank used: down-mix to mono, trim to the punchy onset window (≤ ~600 ms), ease in with a short fade, round out with a cosine fade-out tail, peak-normalize to a gentle −15 dBFS, then re-wrap to the canonical container with afconvert (afconvert -f WAVE -d LEI16@44100 -c 1 in.wav out.wav → WAVE / LEI16 / 44100 / mono). The combo ladder is five real Match FX cues ordered by ascending spectral brightness (P10.9, combo1→combo5); the cascade plays one cue per round on the animation timeline (P10.10). Verify the result read-only with tools/measure_pitch.py (it never writes a WAV) — it prints each clip's dominant frequency, and clear.wav's ~784 Hz CC0 reference is the documented baseline. The 30 MB pack and its .meta / __MACOSX cruft are not committed.

There is intentionally no procedural-synthesis regeneration script: the cues are the curated pack clips, so the original P10.1 note-frequency synthesizer (tools/synth_audio.py) was removed — running it would have clobbered the curated WAVs with synthetic audio.

Image art

Real art is produced with codex's built-in imagegen tool through codex exec, then sips-normalized to each asset's exact dimensions and source format:

asset	dims (px)	format	role
assets/board/background.png	863×1822	PNG	full-view candy gradient backdrop
assets/board/cell.png	128×128	PNG	one grid cell tile
assets/gems/gems.png	768×128	PNG	6 gem columns (a gem's UV column = its index)
assets/fx/particle.png	256×256	PNG	soft match-burst sprite (tinted per gem)

# 1. Generate (codex's imagegen tool, driven non-interactively):
codex exec "use the imagegen tool to render <prompt for the asset>"
# 2. Normalize to the exact per-asset dims + format, e.g. the gem sheet:
sips -z 128 768 --setProperty format png <generated>.png --out assets/gems/gems.png

After any art change, re-capture the affected goldens with the deterministic hooks above (M3TE_ANIM_TIME / M3TE_SELECT / M3TE_FX / M3TE_BADSWAP / M3TE_TARGET / M3TE_MOVE_LIMIT / M3TE_RESTART / M3TE_FPS) and state per golden whether it was refreshed, left unchanged, or removed.