← All decisions

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

Formalize the Core API surface and introduce the glemy/games/<name>/ convention, moving all Suika-specific rule logic out of pe

architectureapi-designpegamesrefactor

Context

The user asked for stable, fundamental Core APIs to be defined deliberately -- the basic surface any game built on this engine would need -- rather than continuing straight into a second game. docs/technical-architecture.md §2.3 (decision 0042) already commits to a boundary requirement ("no genre-specific rule logic introduced into pe") but stops at physical package extraction, deferred until a second, genre-distinct game exists (RM-027). Auditing the actual code against that stated requirement found two real violations, not just theoretical risk: render.gleam directly imported glemy/pe/tier (a game-specific module) to compute colors -- a backwards Shell-importing-genre-logic dependency -- and pe.gleam's own Model/tick/Input/GameEvent carried Suika-specific fields (current_tier, next_tier, danger_timer, game_over, cooldown_remaining, score) and the hardcoded same-tier merge rule directly inside collision_sweep, despite pe being documented as the genre-agnostic layer.

Options considered

Physically extract pe/render/io into a separately versioned package now — rejected
docs/technical-architecture.md §2.3 already researched and committed to deferring this until a second, genre-distinct game begins active development (RM-027) -- extracting a package with only one real consumer would guess at packaging boundaries with no second consumer to validate them against, the same premature-structure failure mode already identified and reversed once in this project (the unused glemy/cs module). Nothing about this task changes that trigger; it only makes the in-repo boundary the extraction will eventually formalize actually honest today.
Add a generic type parameter to pe.Model itself (e.g. Model(state)) to hold a future game's own fields — rejected
This would be guessing at an unknowable future game-state shape with no second, genre-distinct game yet to validate the guess against -- the exact premature-genericity risk decision 0042/RM-027 already flags. Researched precedent (LOVE2D, raylib) confirms the better-supported design: a physics/rendering toolkit exposes no generic game-state type at all, and leaves every game to define and own its own state, wrapping the toolkit's own state as a field. Applied here: games/tiers.Model wraps pe.Model as a field alongside Tiers' own fields, and pe.Model stays exactly entities/bounds/gravity, no type parameter, no placeholder field.
Keep the same-tier merge rule as a hardcoded branch inside pe/collision_sweep.gleam's sweep, just move the tier data lookup elsewhere — rejected
The sweep's actual traversal/overlap-detection logic is genuinely generic and already fully specified; only the per-pair decision (bounce vs. produce a replacement entity) varies by game. Parametrizing the sweep over a caller-supplied interact(a, b) -> PairInteraction(event) function is dependency inversion applied to one already-stable algorithm, not a guess at a future data shape -- a materially safer and more precedented kind of genericity than the rejected Model(state) option above, and it fully removes collision_sweep's own hardcoded tier-equality/tier.next check.

Decision

Generalized glemy/pe/collision_sweep.gleam's merge logic into a caller-supplied `interact(a, b) -> PairInteraction(event)` callback (`Bounce` or `Consume(replacement, event)`), with `resolve_all_collisions(entities, interact) -> #(List(Entity), List(event))` replacing the old tier-aware sweep. Renamed Entity.tier to Entity.kind everywhere, redocumented as "a plain per-entity classification tag with no built-in meaning at this level" -- pe never inspects it itself. Fixed render.gleam's backwards dependency: render_entities_to_bytes/render_entities_to_canvas now take an explicit `colors: List(#(Float, Float, Float))` parameter, positionally paired with entities, with zero import of any genre-specific module. Reduced pe.gleam to Model(entities, bounds, gravity), update(model, dt, interact) -> #(Model, List(event)), spawn_entity, and max_dt -- removed Input, GameEvent, tick, preview_entity, danger_line_y, and every Suika-specific constant. Created glemy/games/tiers/rules.gleam (relocated from the deleted glemy/pe/tier.gleam: radius/color/score_for/next/merge/droppable-tier logic, unchanged) and glemy/games/tiers.gleam (the reference game's own Model wrapping pe.Model plus score/current_tier/next_tier/preview_x/cooldown_remaining/danger_timer/game_over, its own Input/GameEvent, and tick, which calls pe.update with a local interact function built from rules.gleam). Updated glemy/game.gleam to glue io/render to games/tiers instead of pe directly. This establishes glemy/games/<name>/ as the standing convention for where a game's own rules/state live, documented in docs/technical-architecture.md §2.4 alongside an explicit statement of what the Core API (pe.gleam, pe/*, collision_sweep, render, io) covers and doesn't, and Rust API Guidelines-informed design notes (naming, predictability, flexibility, documentation) applied to that surface.

Verification

gleam test and gleam test --target javascript both pass (164 Erlang / 187 JavaScript, all tests either migrated in place or rewritten for the new module layout -- collision_sweep_test.gleam rewritten against the new generic API with local test-only interact functions that don't depend on any game's rules module; pe_test.gleam slimmed to its now-generic-only surface; a new test/glemy/games/tiers_test.gleam holds every tick-specific test, migrated to the new Model/tick/Input/GameEvent shapes). deno task check-warnings passes after updating the baseline (52/52) -- every new/changed warning was confirmed as the already-documented @target(javascript)-only target-gating artifact (ARCHITECTURE.md's "Compiler warnings" section), not a real regression. deno task browser-check passes for real (181 real requestAnimationFrame frames, a real click-and-hold grew the entity count 4 -> 5, a real entity spawned near the expected world-x, zero page errors) -- confirming the actual running game still works end-to-end through the new games/tiers-mediated path, not just that it type-checks.

Consequences

pe is now honestly genre-agnostic in practice, not just by stated policy -- closing the concrete backwards-dependency bug this audit found in render.gleam, and giving the eventual RM-027 extraction a real, already-clean boundary to formalize rather than a redesign to do at that point. A second, genre-distinct game gets its own glemy/games/<name>/ tree beside games/tiers/, following the same wrap-pe.Model-as-a-field pattern, with no changes needed to pe itself unless that game's physics genuinely needs a new generic primitive. The Core API is still explicitly pre-1.0 and unversioned (docs/technical-architecture.md §2.4's stability posture) -- this decision establishes which surface is the right one to eventually freeze, not a stability guarantee made ahead of a real second consumer. Every current call site that previously reached into pe for Suika-specific state now goes through games/tiers instead, a one-time, already-completed migration cost across game.gleam and every affected test file.

References