Skip to content

adr: engine-content-seam

Status: accepted · Context: we expect to churn through many prototypes; some will pivot ("maybe another mechanic would've worked better").

Decision

Keep a hard seam between the reusable engine and swappable per-game content.

  • _engine/ (reusable, never touched per-game): LLM call wrapper, world- state store, the propose-deltas contract + validation/roll loop, the Director/ adjudicator turn loop, the tile renderer, and the shared web launcher.
  • <tag>/ (swappable content): map, entities, meters, actions/stations, the Director + adjudicator system prompts, win condition, renderer hints.

The engine talks to a game through a small content manifest — { map, meters, actions, director_prompt, adjudicator_prompt, win_condition, renderer_hints } — and the launcher discovers games by that manifest.

Why

  • The force multiplier for churning out prototypes is clone-and-swap, not a saved process. A new game = copy <tag>/, swap the content files, register in the launcher; the engine is untouched.
  • A pivot becomes cheap: clone hunker/, rip the survival content, drop a different mechanic's content into the same manifest — same harness, new soul.

Consequences

  • Slice 1 of the first tracer (hunker) must draw this seam even though there's only one game — a little extra discipline now, paid back on game #2.
  • The manifest is the stable interface; adding engine features must not require games to change their manifest shape without a deliberate version bump.
  • Keep the engine thin (gear, not a framework) — resist absorbing game- specific logic into _engine/.

Note

The process itself (fun-test → LLM-load-bearing check → honest split → minimal environment → slice-1 cut) will be captured as a skill after hunker proves out, so we encode a proven process rather than a guessed one.