← All decisions

#0058 · 2026-08-09 · accepted · architecture

Promote circle-vs-Rect detection and the x-fraction/rect-to-CSS helpers from games/breakout into Core, at RM-034's second real caller

architecturecore-apithird-gameplatformerrect

Context

Phase 0 of RM-034 (glemy's third reference game, a platformer, chosen specifically to produce a real second data point on two Core generalizations decision 0052 explicitly deferred: whether physics.update's restitution composition generalizes, and whether rectangle collision deserves promotion into glemy/physics). Before writing any platformer-specific code, direct comparison against what a platformer's player-vs-platform collision needs confirmed games/breakout/rect.gleam's Rect/nearest_point/overlaps/penetration_axis are already game-agnostic circle-vs-AABB math with nothing Breakout-specific in them -- the only thing that differs between Breakout (reflect off a brick) and a platformer (stop dead on a platform) is what happens after detection, exactly the same detection-vs-resolution split physics/collision.gleam already draws against collision_sweep's caller-supplied interact. Critically, a platformer cannot import games/breakout/rect.gleam directly -- one game reaching into another game's own games/<name>/ tree would violate the exact boundary decision 0052 established -- so the only honest choices were duplicate the identical ~90 lines a second time, or promote them. Same reasoning applied to game_breakout.gleam's x_fraction/rect_to_css, both already documented as 'kept local, exactly one real caller.'

Options considered

Duplicate games/breakout/rect.gleam's detection math into games/platformer's own local copy — rejected
The math is already provably identical (verified by direct comparison, not discovered mid-implementation) -- duplicating a second, byte-for-byte-identical ~90-line file specifically to avoid touching Core would be process over substance. This project's own precedent (clamp_x/cooldown/stopwatch/random promoted out of games/tiers, decisions 0049/0050) already established that a real second need is exactly the trigger to promote, not a reason to keep duplicating.
Have games/platformer import glemy/games/breakout/rect directly, since the functions are already game-agnostic in practice — rejected
Would violate the games/<name>/ boundary decision 0052 established: each game's own tree is that game's local concern, never imported by a sibling game. This constraint is what actually forced the promote-or-duplicate choice above -- there was no third option that kept both games decoupled from each other without touching Core.
Promote Rect itself as an alias/reuse of physics/bounds.Bounds, since they're structurally identical (min/max Vector2 corners) — rejected
Bounds is specifically the physics world's own containing box (what entities bounce inside of); Rect is an inert obstacle a circle collides against -- different roles that happen to share a shape, not the same concept, the exact distinction the original games/breakout/rect.gleam's own doc comment already drew and this promotion had no reason to reopen.

Decision

Moved games/breakout/rect.gleam to physics/rect.gleam verbatim (Rect, nearest_point, overlaps, Axis/penetration_axis), doc comments updated to describe it as Core rather than game-specific, and its own test file relocated to test/glemy/physics/rect_test.gleam. games/breakout/brick.gleam, paddle.gleam, and breakout.gleam updated to import glemy/physics/rect instead. Added bounds.x_fraction(world_x, bounds) -> Float to physics/bounds.gleam (moved verbatim from game_breakout.gleam, now documented as y_fraction_from_top's x-axis sibling) and rect.to_css(rect, bounds) -> #(Float, Float, Float, Float) to physics/rect.gleam (moved verbatim from game_breakout.gleam's rect_to_css, renamed to fit its new home). game_breakout.gleam deleted both local functions and calls the promoted Core versions instead; its own x_fraction/rect_to_css tests relocated into test/glemy/physics/bounds_test.gleam and rect_test.gleam respectively. No public API changed shape anywhere in Breakout -- Brick.rect, paddle_rect, etc. keep their existing field types, now typed against physics/rect.Rect instead of games/breakout/rect.Rect.

Verification

gleam test and gleam test --target javascript both pass with identical counts to before this phase (263 Erlang / 288 JavaScript) -- a pure relocation with tests moved, not added or removed, is exactly the expected regression proof. deno task check-warnings passes after updating the baseline (76 warnings, every new/changed entry confirmed as the already-documented @target(javascript) target-gating artifact under new file paths, plus one genuine improvement -- an unused type import this refactor incidentally fixed). deno task browser-check-breakout passes for real (57 real requestAnimationFrame frames, a real held ArrowLeft pinned the paddle at the left wall, a real ball-brick collision hid a brick div and updated the score, 1 sound played, zero page errors) -- confirms Breakout's actual runtime behavior is byte-for-byte unchanged after the refactor, not just that it type-checks. deno task browser-check (Tiers) also re-run since physics/bounds.gleam was touched -- still passes for real (185 frames, a real click-and-hold grew the entity count, zero page errors).

Consequences

physics/rect.gleam is now Core, alongside physics/bounds.gleam/collision.gleam/collision_sweep.gleam/entity.gleam -- the first Core module added since the original Tiers-to-Breakout generalization round (decisions 0047-0050), and the first one promoted with a second caller's real evidence in hand from the start rather than discovered after the fact. games/platformer (Phase 1, next) builds its own player-vs-platform collision directly on physics/rect's detection functions, writing only its own resolution logic (stop, not reflect) -- the actual point of this promotion. A fourth game needing the same detection math has zero further Core work to do; a fourth game needing genuinely different detection math (rect-vs-rect, say) is real new evidence to design from, not a guess.

References