Repository navigation
Engine core: a snapshot in, a frame out - #22
Merged
Merged
Conversation
This was referenced Aug 27, 2026
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
force-pushed
the
feat/3-engine-core
branch
from
August 28, 2026 02:28
9ea2dfa to
cc80bb2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3.
What changed
The Engine: one synchronous
tick(&WorldSnapshot) -> Frame, insrc-tauri/src/engine.rs, plus the line inlib.rsthat exposes it.WorldSnapshot— display frames, visible window rectangles in descendingz-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 andframe index, and dialogue for that frame only.
grounded,falling,dragged,perched,climbing,asleep.Time reaches the Engine only as
elapsed_ms. The module imports nothing outsideits own test module: no clock, no window handle, no model.
14 engine tests.
a_day_in_the_lifescripts one sequence of snapshots — fallsonto 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_belowiswindow.y >= position.y: a window counts as a surface onlywhen 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 bya_window_is_passed_through_from_below_and_landed_on_from_above, which flings asprite 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_underfinds nothingout 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_reachednow fires on position alone as well as onvelocity, 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::Throwfrom any State, so a stray verb could fling a sleeping or perchedsprite, 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 Grabfirst 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 warningsObserved on this branch:
And the mutation check, run by hand in that worktree — swap
>=for<=insupport_below: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.
Verbhas 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 teststill builds and links the platform stack. #3 asks that the Enginetest 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_reachedclamps to the outermost left and right edges of alldisplays, 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_MSgives every Animation one cadence of roughly 8fps. Per-Animationframe rate and loop mode arrive on the Character manifest with #7. Marked with a
ponytail:comment.A Behavior proposal's
dialogueis spoken; the namedbehavioris ignored,because playing it needs the Primitives and the Character's declarations from
#8.
🤖 Generated with Claude Code