Skip to content

fix(engine): Keep a Character's own half-width clear of a display edge - #328

Closed
omesser wants to merge 2 commits into
mainfrom
fix/327-sprite-width-edge-clearance
Closed

omesser wants to merge 2 commits into
mainfrom
fix/327-sprite-width-edge-clearance

Conversation

@omesser

@omesser omesser commented Sep 4, 2026 •

Copy link
Copy Markdown
Owner

Why

EDGE_CLEARANCE promises that "the full sprite is on-screen when standing" and
guesses at how wide a sprite is — 64 points, "enough for a character of typical
width". Two shipped Characters are wider than the guess. Timber Wolf's frames
are 176 points across, so its feet stop 64 from the edge and 24 points of art
hang past it; Jotaro clips by 22.

At a seam that would be harmless, because the neighbouring display's overlay
draws the other half. At the outermost edge there is no neighbour, so the
clipped part is drawn by nobody. #55 accepted seam clipping as "a brief pop
during a crossing, not a resting state" — this is the resting state.

The guess was made for Nim, which is why it fits Nim exactly: 32 points of art
at the default scale = 4 is 128 wide, and half of that is the 64 in the
constant. Every Character drawn at a different scale is one the guess was never
made for.

What changed

The Engine is told how wide its Character is. EDGE_CLEARANCE stays as the
fallback for an Engine nobody told, so existing callers keep today's behaviour.

Every edge the Engine keeps the sprite clear of — the display's and the Dock's —
is a distance from the feet, and how far that has to be is half a sprite, so
at_horizontal_edge, dock_side_reached and dock_top_at now take the
clearance as a parameter rather than reading the constant.

Character::sprite_width is the widest declared frame times the Character's
scale, and Roster::spawn hands it over. The widest rather than the one
currently drawing: the Engine holds this for the Instance's life, so it has to
cover whichever Animation is playing when the sprite reaches an edge. The whole
frame rather than the opaque pixels in it — measuring the ink would mean
remeasuring every frame, and the mask is the renderer's business; the cost is a
Character resting with its transparent padding off screen, which is invisible.

What this does to the shipped Characters:

Character width clearance was
timber-wolf 176 88 64
jotaro-kujo 172 86 64
bmo 126 63 64
cat 113 56 64
black-mage 111 55 64
trump 108 54 64
buddy-bot 90 45 64
nim 128 64 64

Deliberately not fixed here: the climb. wall_reached pins the feet exactly
on the outermost edge and the climb frames assume the wall runs down the middle
of the frame, so a climb there is still half off screen — several seconds of it,
in the trace below. That is correct at a seam and wrong only at the outer edge,
and telling the two apart is its own change.

How to verify

cargo test --workspace — 637 pass. cargo clippy --workspace --all-targets -D warnings
and cargo fmt --check are clean.

Three tests, each confirmed to fail without the fix:

  • a_sprite_wider_than_the_default_clearance_rests_fully_on_screen — the Engine
    invariant, asserted on the art's extent rather than on the constant so it
    cannot quietly drift back.
  • a_spawned_instance_keeps_its_own_width_clear_of_the_display_edge — the
    wiring through Roster::spawn. With the with_sprite_width call removed it
    reports the art's right edge is off screen: feet at 1856 put it at 2056.
  • a_sprite_is_as_wide_as_its_widest_frame_blown_up_by_its_own_scale — pins the
    scale multiplication, the easiest part of this to get wrong.

The original reproduction, run through the Engine with the reporter's real
desktop (two displays, the right-hand one ending at x=3648). drawn is how much
of the 176-point art falls inside any overlay:

485 Grounded pos(3647,1117) drawn=176px walk
486 Falling  pos(3648, 161) drawn=88px  climb   <- caught by the wall, climbs
    ... ~5 seconds of climbing ...
525 Falling  pos(3648,1114) drawn=88px  fall
526 Grounded pos(3584,1117) drawn=152px land    <- settles, still 24px clipped

The last line is what this fixes: it now rests at 3560, art flush with the edge.
Line 486's drawn=88px is the climb, left for another change.

Notes

Diagnosing this turned up a second failure mode I did not touch: "over no
display" is the union of the display frames, not their bounding box, so a
desktop whose screens do not touch has a band between them where the feet have
no floor and no overlay. The reporter's arrangement had a 25-point gap at the
time. Worth its own issue if it bites.

Closes #327

— Cursor agent, on @omesser's behalf.

Made with Cursor

@omesser

omesser commented Sep 4, 2026

Copy link
Copy Markdown
Owner Author

Raised in review: does widening the resting inset fight the climb? Characters
are let to the edge deliberately so the climb makes sense, and climb art like
BMO's is drawn with the wall down the middle of the frame, not at its side.

They don't fight, and the reason is that the climb never goes through anything
this changes.

wall_reached takes no clearance — it returns the outermost edge itself, and
it is what catches a sprite and starts a climb. at_horizontal_edge is the one
that got the clearance, and it only runs in the stationary branch. So the
clearance is the resting inset and the wall is still the wall: the sprite
walks all the way to the edge, grabs it, and climbs centred on it exactly as
before. climbing_preserves_wall_centered_frames_and_may_clip already pinned
that for a default Engine and still passes untouched.

Pushed cd8e8fb to pin it for a wide one too, since that is the case the
question is about: a_wide_sprite_climbs_the_wall_it_rests_clear_of throws a
176-point sprite at the edge and asserts it climbs at the edge, then rests a
half-width in. The two numbers are meant to differ, and now something says so.

On BMO specifically: its widest frame is 126, so its clearance moves 64 → 63.
A one-point change, and its climb frames are the same 126 wide, so the
wall-centred art lands where it always did.

— Cursor agent, on @omesser's behalf.

omesser and others added 2 commits September 5, 2026 19:51
EDGE_CLEARANCE guessed at 64; Timber Wolf's half-width is 88, so it rested
24 points over the outermost edge, where no overlay draws it.

Co-authored-by: Cursor <cursoragent@cursor.com>
…lear of

Co-authored-by: Cursor <cursoragent@cursor.com>
@omesser
omesser force-pushed the fix/327-sprite-width-edge-clearance branch from 438af99 to b8305cd Compare September 5, 2026 16:52
@omesser

omesser commented Sep 5, 2026

Copy link
Copy Markdown
Owner Author

Closing. The premise is wrong, and measuring the art rather than the frame
shows it.

The clearance here comes from the frame canvas width. These canvases are
padded — every Timber Wolf pose is matted onto a shared 176x160 canvas — so the
canvas is not the art. Measuring the opaque pixels in every declared frame of
every shipped Character:

Character canvas -> clearance this PR sets widest real ink reach from centre clipped at the old 64?
timber-wolf 176 -> 88 57 for every pose but scan no
jotaro-kujo 172 -> 86 60 no
bmo 126 -> 63 63 no
buddy-bot 90 -> 45 40 no

This PR claimed "Timber Wolf's feet stop 64 from the edge and 24 points of art
hang past it; Jotaro clips by 22". Those points are transparent padding. No
shipped Character's body was ever clipped, because EDGE_CLEARANCE's 64
already exceeds every pose's reach.

The one thing that does reach 88 is scan, and it is the laser sweep, not the
mech. So the whole effect of this change is to keep the tip of an idle laser on
screen, while making Timber Wolf stand 31 points further from the edge than its
body needs and Jotaro 26 — a permanent gap traded for a transient one.

The PR argued past this in its own text: "the cost is a Character resting with
its transparent padding off screen, which is invisible."
Padding is exactly
what sets the number, so that sentence dismissed the load-bearing fact. The
change swaps one wrong constant for a differently wrong measurement.

It also never addressed the report that started it (#55-style disappearance):
24 points of clipping is not a Character vanishing. The real candidates are the
climb at the outermost edge, which sits half off screen for several seconds,
and the band between two non-touching displays. Going after the second.

Kept for the record rather than deleted, in case a third-party Character
package ever ships art genuinely wider than 128 points — at which point the
mechanism here is right and the measurement should be the ink, not the canvas.

— Cursor agent, on @omesser's behalf.

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.

A Character wider than the edge clearance rests half off the outermost display edge

1 participant