Skip to content

Engine core: a snapshot in, a frame out - #22

Merged
omesser merged 2 commits into
mainfrom
feat/3-engine-core
Aug 28, 2026
Merged

omesser merged 2 commits into
mainfrom
feat/3-engine-core

Conversation

@omesser

@omesser omesser commented Aug 27, 2026

Copy link
Copy Markdown
Owner

Closes #3.

What changed

The Engine: one synchronous tick(&WorldSnapshot) -> Frame, in
src-tauri/src/engine.rs, plus the line in lib.rs that exposes it.

  • WorldSnapshot — display frames, visible window rectangles in descending
    z-order, cursor, pending interaction verbs, elapsed milliseconds, and an
    optional Behavior proposal from the Director.
  • Frame — the sprite's contact point, velocity, State, Animation name and
    frame index, and dialogue for that frame only.
  • The State machine over grounded, falling, dragged, perched,
    climbing, asleep.

Time reaches the Engine only as elapsed_ms. The module imports nothing outside
its own test module: no clock, no window handle, no model.

14 engine tests. a_day_in_the_life scripts one sequence of snapshots — falls
onto a window, the window closes, lands, dozes off, is Poked awake, is Grabbed
and carried, is dropped, is Grabbed again and thrown at the screen edge, which
it climbs — and two tests read that one script: every State is entered and left
again, and playing it twice yields identical frames.

Why it looks like this

A review found the one-way Perch rule had no test at all. The filter in
support_below is window.y >= position.y: a window counts as a surface only
when the sprite is above its top edge, which is what stops the sprite being
yanked up onto a window it is standing underneath and trapped there. Inverting
that operator to <= left the whole suite of 17 tests passing. It is now covered by
a_window_is_passed_through_from_below_and_landed_on_from_above, which flings a
sprite up through a window's top edge from inside it and then catches it on the
same edge coming down. I re-ran the mutation in the worktree before writing
this: with <= in place, exactly that one test fails and the other 19 pass.

A sprite over no display used to fall for ever. floor_under finds nothing
out there, so there was nothing to land on, and the screen-edge catch only fired
on non-zero horizontal velocity — a straight vertical drop outside every display
just counted y upwards. wall_reached now fires on position alone as well as on
velocity, so being outside is itself reason enough to grab the nearest edge. The
recovery from there was already in the code: it climbs, reaches the top, lets
go, and falls back onto the display.

Throw follows the glossary, not the doc comment. The Engine honoured a
Verb::Throw from any State, so a stray verb could fling a sleeping or perched
sprite, while the variant's own doc comment said "A Grab released while moving".
CONTEXT.md defines Throw as releasing a Grab with velocity, so the code was
changed to match the glossary rather than the comment being loosened to match
the code. Letting go with and without velocity is now the same branch off
State::Dragged. Two existing tests threw without holding first; they Grab
first now, which is what the Shell emits.

How to verify

git worktree add /tmp/pr-3 origin/feat/3-engine-core
cargo test --manifest-path src-tauri/Cargo.toml
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings

Observed on this branch:

test result: ok. 20 passed; 0 failed        (14 engine, 6 overlay)
clippy: Finished `dev` profile              no warnings

And the mutation check, run by hand in that worktree — swap >= for <= in
support_below:

test engine::tests::a_window_is_passed_through_from_below_and_landed_on_from_above ... FAILED
test result: FAILED. 19 passed; 1 failed

Known and deferred

This branch contains more than #3 asked for. Gravity and the integrator,
ballistic Throw, clamping to the display edges, landing on a Perch and falling
when a Perch disappears are acceptance criteria of #4 (Physics) and #5 (Perch
collision), not of #3. They are here because the State machine could not be
shown to be free of dead ends without something that actually moves the sprite.
The maintainer has decided to keep them rather than delete them and rewrite them
under those issues, and will retitle #4 and #5 around what is genuinely left.

Verb has three variants; CONTEXT.md defines five. Menu and Summon belong to
#6.

The Engine is pure in its source, but it lives in the crate with Tauri, so
cargo test still builds and links the platform stack. #3 asks that the Engine
test without a platform dependency; it does not import one, but the test binary
does. Splitting the pure core into its own workspace crate is an open question,
not settled here.

A sprite dropped into a gap between two non-aligned displays is still not
recovered. wall_reached clamps to the outermost left and right edges of all
displays, not to the true union of their frames, so an x inside the bounding box
but over no actual display finds no wall and no floor. There is a ponytail:
comment on the function saying so; #4 owns the true union.

FRAME_MS gives every Animation one cadence of roughly 8fps. Per-Animation
frame rate and loop mode arrive on the Character manifest with #7. Marked with a
ponytail: comment.

A Behavior proposal's dialogue is spoken; the named behavior is ignored,
because playing it needs the Primitives and the Character's declarations from
#8.

🤖 Generated with Claude Code

omesser and others added 2 commits August 28, 2026 05:27
Everything in the Spatial Layer is either physics, Perch collision, verbs or
Behavior playback, and every one of those is untestable if it can only be
observed by looking at a real screen. Putting the whole lot behind one
synchronous function — WorldSnapshot in, Frame out, time arriving as elapsed
milliseconds — is what lets the rest of the layer be written against
constructed worlds instead of against a windowing system, a model and a
stopwatch.

Without this seam each later issue would have to invent its own way in, and
the first one to reach for a clock or a window handle would make every test
after it slow, flaky and macOS-only. The State machine is here for the same
reason: grounded, falling, dragged, perched, climbing and asleep are the six
places a sprite can be, and a test that walks a scripted day proves each is
reachable and none is a trap.

Physics beyond a plain integrator, the true display union, Perch walk-off,
the remaining verbs and Behavior playback are deliberately left to the issues
that own them. What lands here is the contract they all plug into.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The one-way platform filter was the load-bearing line nothing tested: swap
its `>=` for `<=` and all 17 tests still passed, while a sprite underneath a
window would be yanked up onto its top edge and trapped there. A window is
now exercised from both sides in one test — flung up through the top edge
from below, then caught by the same edge coming down.

A sprite outside every display had no floor and no way back: floor_under
finds nothing out there and the edge catch only fired when it was moving
sideways, so a straight vertical drop counted y upwards for ever. Being
outside is now reason enough to grab the nearest edge, which is the recovery
already in the code — it climbs and drops back onto a display.

Throw said "a Grab released while moving" and meant it for the Shell, but the
Engine honoured one from any State, so a sleeping or perched sprite could be
flung by a stray verb. CONTEXT.md defines a Throw as the release of a Grab,
so the code follows the glossary rather than the other way round, and letting
go with and without velocity is now one branch. Two existing tests threw
without holding first; they Grab first now, which is what the Shell emits.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser
omesser force-pushed the feat/3-engine-core branch from 9ea2dfa to cc80bb2 Compare August 28, 2026 02:28
@omesser
omesser merged commit 3810b12 into main Aug 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Engine core: snapshot, frame, State machine

1 participant