Educational Game Design

The shape

The mapping, made exact

The complexity ladder holds and gets steeper at each rung: manual groups by authored chapters with essentially flat entries; itinerary adds derived kind rosters, three classes, and cross-references; game adds a sub-group vocabulary that is invented per guide and that changes the entry's schema. Game is strictly the most complex of the three, which is the right expectation to carry in.

Where "how we adapted it" lives

Not in entries. In the game-type object, exactly the way a DayConfig carries label / title / date / headline and a ChapterConfig carries title / numeral:

"games": [
  { "id": "lineup",
    "label": "The Lineup",
    "order": 4,
    "mechanic": "judging-a-narrated-chain",     // → catalog entry id
    "subject": "Reading & Writing — con detection",
    "reskin": "A suspect narrates his reasoning; commit clean or con
               as early as you dare, then pick him from the mugshots.",
    "priorities": { "speed":"secondary", "accuracy":"primary", "stress":"secondary" },
    "divergence": "Adds the lineup after the call — naming the error,
                   not just flagging it. Feed this back to the catalog.",
    "bank_target": 40,
    "build_status": "built" }
]

divergence is the field that earns its place: it records how the built thing departed from the catalog entry and why, so discoveries flow back up instead of stranding in one game.

The real disanalogy with itinerary

There are two differences, and the bigger one is not the obvious one.

The one that's already solved

Game types are brainstormed rather than given, where eat / do / shop / photo are just… known. But the corpus already anticipated this: itinerary's kind_extensions lets a guide extend the kind vocabulary in guide.json, precisely because Asheville needed shelves NYC didn't. "The sub-group vocabulary varies by product" is a solved problem with shipped precedent.

The one that actually bites

So the C-row parallel is more true of games than the itinerary comparison suggests. There, parameters depend on class, not on section. Here they depend on the sub-group itself — and there are eleven of them in Peregrine, not four.

The schema language already handles it

Verified in source rather than assumed: a schema-extensions.json with extend omitted appends fields at the top level (SchemaModels.swift:129), and extension fields are ordinary FieldDefs, so they carry applies_when (SchemaModels.swift:57). That's the same mechanism Things With a Cost already uses to give only situation entries an incantation.

The category schema — what every item has

categories/game/schemas/entry.json

{"fields": [
  {"key":"title","required":true,"type":"string",
   "prompt":"How this reads in the navigator — not what the player sees."},

  {"key":"family","label":"Game Type","required":true,"type":"string",
   "prompt":"Which game type this feeds — an id from the games array in guide.json."},

  {"key":"class","label":"Item Class","type":"enum",
   "options":["item","flavor","asset"],
   "prompt":"item = the thing the player answers · flavor = in-fiction copy
     (transmissions, murmurs, taunts) · asset = the record about a picture or scene."},

  {"key":"number","type":"int"},

  {"key":"concept","type":"string",
   "prompt":"The skill this scores against. Miss logs and spaced repetition key on
     this, not on the id — three sign names share two pictograms apiece."},

  {"key":"difficulty","type":"enum","options":["intro","standard","hard","boss"]},

  {"key":"stem","label":"The Prompt","type":"prose",
   "prompt":"What the player is shown or asked. Empty for purely visual items."},

  {"key":"choices","type":"string_list"},
  {"key":"answer","type":"string"},

  {"key":"trap","label":"The Trap","type":"prose",
   "prompt":"The wrong answer a smart player reaches for, and why it's tempting."}
]}

A note on family. The key is named family and labelled "Game Type" on purpose: the app's generic template groups by family when the schema declares one (DocumentTemplates.swift:300), so the document chapters itself by game type with no Swift written. When you later add a real game template case, renaming to game_type is a mechanical sweep across entry files — or you leave it, since the label is what anyone actually sees.

The guide extensions — what this game type needs

guides/peregrine/schema-extensions.json

[
  {"fields":[
    {"applies_when":{"family":"lineup"},"key":"passage","type":"prose"},
    {"applies_when":{"family":"lineup"},"key":"reasoning","type":"object_list",
     "prompt":"The suspect's narration, one line per object.",
     "fields":[{"key":"t","label":"Line","type":"string"}]},
    {"applies_when":{"family":"lineup"},"key":"break_idx","label":"Break Index","type":"int",
     "prompt":"Index into reasoning where the con begins. Script-validated —
       the app cannot check a pointer into a sibling array."},
    {"applies_when":{"family":"lineup"},"key":"con_id","type":"string"}
  ]},
  {"fields":[
    {"applies_when":{"family":"target-practice"},"key":"claim","type":"prose"},
    {"applies_when":{"family":"target-practice"},"key":"verdict",
     "type":"enum","options":["clean","con"]}
  ]},
  {"fields":[
    {"applies_when":{"family":"recon-sweep"},"key":"image","type":"string",
     "prompt":"Path under assets/. The entry is the record about the picture,
       never the picture."},
    {"applies_when":{"family":"recon-sweep"},"key":"decoy_group","type":"string",
     "prompt":"Which near-twins this is confusable with. Drives the difficulty
       ramp — currently pure human judgment with no tooling anywhere."},
    {"applies_when":{"family":"recon-sweep"},"key":"shape","type":"enum",
     "options":["diamond","octagon","rectangle","pennant","circle","triangle"]}
  ]}
]

One block per game type, each self-contained. Adding a twelfth game type is appending a block — not touching the category, not touching the other eleven.

The mechanics catalog — and it may need no new category at all

Because root-level extensions work, the catalog can be a catalog-category guide with its beats added by extension. family, number, metadata, similar_to are already in that schema and already group correctly:

// guides/game-mechanics/schema-extensions.json  (no "extend" key = append at root)
{"fields":[
  {"key":"beats","type":"object","fields":[
    {"key":"player_verb","label":"The Verb",
     "prompt":"What the hands do. Tap, flick, strike, order, hold, draw.","type":"string"},
    {"key":"loop","label":"The Loop",
     "prompt":"One turn, from start to consequence.","type":"prose"},
    {"key":"knowledge_fit","label":"What It Teaches Well",
     "prompt":"The kind of knowing this exercises — visual recognition, name→image
       recall, free retrieval, discrimination between near-twins, procedure,
       judging someone else's reasoning. And what it teaches badly.","type":"prose"},
    {"key":"consequence","label":"The Consequence",
     "prompt":"How feedback lands inside the fiction. Never a red X.","type":"prose"},
    {"key":"repetition","label":"Why You Play Again",
     "prompt":"What makes the next round wanted, not assigned.","type":"prose"},
    {"key":"failure_mode","label":"When It Becomes a Worksheet",
     "prompt":"The specific way this mechanic collapses into drill.
       Name it so you can watch for it.","type":"prose"}
  ]},
  {"key":"priorities","type":"object","fields":[
    {"key":"speed","type":"enum","options":["primary","secondary","ignored","penalized"]},
    {"key":"accuracy","type":"enum","options":["primary","secondary","ignored","penalized"]},
    {"key":"stress","type":"enum","options":["primary","secondary","ignored","penalized"]}
  ]},
  {"key":"content_contract","type":"object","fields":[
    {"key":"unit","label":"One Unit Is","type":"string"},
    {"key":"requires","label":"Required Fields",
     "prompt":"One per line. This becomes a game's schema-extensions block.","type":"string_list"},
    {"key":"assets","label":"Asset Needs",
     "prompt":"Art, audio, scenes — state it now. Sniper Spot stalled here.","type":"prose"},
    {"key":"volume","label":"Viable Bank Size","type":"string"}
  ]},
  {"key":"mockup","label":"Behavioral Reference",
   "prompt":"Path to the HTML mockup that IS the spec. Prose cannot carry feel —
     link it, never claim to replace it.","type":"string"},
  {"key":"instances","label":"Built As",
   "prompt":"game:game-type — where this exists today.","type":"string_list"}
]}

The honest tradeoff: family in the catalog schema is a plain string, so the five motivators — Finding, Dodging, Optimizing, Building, Surviving — are free text rather than a picker, and a typo silently creates a phantom section. Extensions append, they don't override, so you can't tighten it to an enum without a new playbook category. Start with the string; promote to a category only if the typos actually bite.

content_contract is the load-bearing field either way. It's what makes the catalog generative rather than a documentation chore: a mechanic declares the fields a game must supply to feed it, which is precisely the schema-extensions block you write when you adapt it.

The join

One mechanic, three touchpoints, flowing one direction:

Nothing flows back automatically — divergence is a note to yourself, not a sync. That's deliberate; Press Raven exports one direction and shouldn't learn to do otherwise.

Why the catalog has to be separate

This is the part that isn't a matter of taste. Four things found in the repos:

Across both games there are roughly fifteen built game types and four specced-but-unbuilt. My guess is they collapse to eight or nine distinct mechanics. Finding that out is the catalog's first deliverable, and it's worth the exercise even if nothing else here gets built.

The philosophy belongs in the Brief

A category's brief.json can declare a slot with "writes": "editorial_notes", and editorial_notes is emitted into the CONTEXT half of every session packet. It's how Things With a Cost carries "the cost test" into every drafting session.

The game brief should also carry the game's forbidden vocabulary. Drive Corps bans quiz, test, practice, and study in UI copy; right now that rule lives in a handoff doc, which means it protects nothing at 2am. In the brief it rides along in every packet.

The dividing line

Press Raven owns authored content. The app owns runtime content. Draw it once and it stops being ambiguous later.

Assets follow the acrylics precedent: images live in guides/<game>/assets/ and the entry is the record about the asset — name, concept, decoy group, shape — never the asset itself. Drive Corps's signs.json is already exactly this shape, which is the cheapest possible proof that the model fits.

What it costs, stated plainly

1. The machine export target is declared, not built. framework.json lists it as "status": "declared"; ExportService emits paginated print HTML and MobileGuideExporter emits the mobile page — that is all that ships. Getting entries back into Data/signs.json is a script you write. Consistent with the README's own position that the press is already Claude Code pointed at the entries folder, but it is not a feature you have, and it remains the single largest gap in this proposal.
2. The games[] array won't be read yet — but it will survive. days and chapters are typed fields on GuideConfig with hardcoded template cases; a games array is not modelled. The good news, verified: updateGuideConfig round-trips guide.json through JSONValue specifically so keys the app doesn't model are preserved (CorpusStore.swift:591). You can author it today and the app won't eat it — it just won't render from it.
3. Making it first-class is a known, small piece of Swift: games: [GameTypeConfig]? on GuideConfig, plus a case "game" in DocumentTemplates mirroring what manual already does. Same shape of work, already precedented — not speculative. Until then the generic family grouping gives plain string headings and no per-type metadata on the page.
4. Volume is only proven to 144. The acrylics guide is the largest thing ever exercised. Drive Corps at ~154 items is a hair past it and a reasonable stress test. Peregrine — eleven game types, each wanting its own bank — is where the document metaphor stops meaning anything. Expect to split it, and treat the first migration as a measurement.
5. Some structure the schema language genuinely can't validate. A lineup round's break_idx points into its own reasoning array. object_list holds the shape, but nothing checks the pointer. That stays a script's job, and the field prompt should say so out loud.

Sequencing

Design systems, while you're here

The framework already has the vocabulary: noir (charcoal paper, warm white ink, brass) for Peregrine; fieldkit (utilitarian kit monochrome, heavy rules, oversized numerals) for Drive Corps. The catalog itself wants editorial or fieldnotes — it's a reference you read, not a mood piece.

Final review

Pros

• The structure is derived from three shipped categories rather than invented beside them, so nearly every piece has working precedent: authored sub-groups from chapters, extensible vocabulary from kind_extensions, conditional fields from incantation, root extensions from the schema resolver.
• Steps 1 and 2 are corpus files only. The Swift is Step 3 and it's optional for a long time.
• It solves two problems already named in the repos: a missing verb registry, and authored content stranded as static let arrays inside SwiftUI views.
• content_contract makes the catalog generative — it authors the schema-extensions block its adaptations need.

Cons

• The payoff for content still depends on an export target that doesn't exist. Until the script is written, a game guide is a nicer place to author content that must still be moved by hand.
• The generic template will feel thin for a game — plain string headings, no priorities on the page — and that gap arrives immediately, in Step 2, before the Swift that closes it.
• family as free text in the catalog means the five motivators aren't enforced, and motivator is the one axis you most want disciplined.

Edge cases where this is inadequate

• Behavioral specs. Peregrine treats ~40 HTML mockups as the real specification. Nothing in a schema captures how the hesitation drain feels. Hence the mockup field — link it, never claim to replace it.
• Index-pointer structure. break_idx and anything like it stays script-validated.
• Generated content. Runtime classification is out of scope by construction, and the §8 line has to hold or the corpus stops being the source of truth.
• Tuning constants. Fuel costs, timer ramps, crit multipliers belong in the game's code where they're iterated in a build-run loop. The guide records intent — "speed primary, stress rising" — not numbers. Two sources of truth for a tuning value will drift within a week.

Adjustments worth considering

• Skip the catalog at first and let it fall out of the second game, when you actually feel the reuse. Cheaper; risks writing it after the vocabulary has already forked.
• Promote the catalog to its own playbook category if free-text motivators bother you enough to want the picker. That's the only thing a new category buys.
• Decide you like the motivator names as printed chapter headings — Finding, Dodging, Optimizing, Building, Surviving become section titles the moment the guide renders. Worth liking them in that role before they're load-bearing.