Proposed core schema draft for discussion

Three things broke at once when we dug into Step 2:

1. The data model is a fantasy combat deck-builder. Types like Unit / Structure / Event, behaviours like Permanent / Strike / Targetable, zones like Battlefield. A user who picked Trick-Taking at Step 1 lands on a page asking them to tick Units and Structures. Wrong vocabulary.
2. Nothing describes how the game is played. The schema covers pieces (what's on a card, where cards live, what they cost) but not flow (turns, phases, win conditions as structured data). The engine couldn't simulate a game even if it wanted to.
3. Terminology is overloaded. “Mechanic” means two unrelated things. “Archetype” means three. The code calls the same concept card-type, subtype, and archetype in different places.

All three are schema problems. Patching Step 2's UI without fixing the underlying model just pushes the mess around.

A game is modelled as six nested layers, each answering a different question:

Layers 1, 2, 3a, 3b, and 5 map to things the wizard already asks about. Layer 4 is new. Layer 6 is deferred.

The four concepts that are tangled in today's code, split into their proper roles:

The mental model

(type) + (some subset of type's allowed behaviours) is the engine-level identity of a card. Two different subtypes with the same type and behaviours are indistinguishable to the engine.

That means subtypes are a soft layer. They exist to help the AI generate thematically consistent cards ("generate a Guardian Unit: a Permanent+Outpost Unit that forces opponents to target it first") and to give the UI preset shortcuts. Nothing breaks if you never use a subtype.

This is why the current "subtype table" on Step 2 is wrong as the primary selection surface: it makes users commit to a soft label as if it were a hard decision.

Today the only part of flow that's captured is the Rules panel on Step 2, which generates free-text setup actions. Everything else about playing the game lives in the user's head.

The proposed Flow layer covers:

• Turn order — clockwise / counter-clockwise / simultaneous.
• Phases — named stages of a turn. Each phase declares allowed_actions (player-chosen) and/or mandatory_actions (automatic). Phases can repeat ("until_ended_by_player", "once_per_player", "until_hands_empty") or be one-shot ("one_time_per_round": true).
• Win conditions — structured triggers. Metric (tracker:authority, tracker:score), comparator, threshold, target (self / opponent / any_team). Multiple conditions can coexist.
• Loss conditions — same shape as win, reversed target.
• Interrupt rules — whether non-active players can act during someone else's turn.
• Game length cap — optional turn / round limit to prevent stalemates.

assets/data/zones-default.json ships 7 zones: deck, hand, in_play, discard, trash, market, market_deck. Each is a JSON object with some subset of:

• Zones correctly live at the game level, not on cards. Same shape we committed to for Flow.
• Data is id-referenceable — flow actions like { "do": "move", "from": "deck", "to": "hand" } compose naturally.
• Shared vs per-player ownership is already modelled (market uses "owner": "shared").
• accepts on in_play is a smart constraint — it encodes which types can persist there. Under-used but the idea is right.
• rules.refill on market proves the model can capture automatic zone behaviour.

1. Inconsistent field presence. Some zones have initial, only market has rules, only in_play has accepts, only market_deck uses visibility: ["none"]. Readers have to handle "key may or may not exist" for almost every field.
2. initial: [] is runtime state, not config. Same smell as objective.progress.current. The zone definition says what the zone IS; starting contents belong to setup / Flow.
3. visibility / access as arrays of one-element enums. Every zone uses one of ["owner"], ["all"], ["none"], or []. They look like multi-value arrays but are effectively single enums. Either formalise them as enums, or document which combinations mean something.
4. type is an undocumented enum. Values actually used: deck, hand, area. The (now-dead) zone-suggestion AI prompt mentions deck | pile | battlefield | market | discard | custom — a different set. No single source of truth. Semantics overlap with other fields (ordering + owner already communicate most of what type does).
5. ordering has undocumented values. stack and none are used. queue (FIFO), sorted, random might be needed for other games. No doc lists the valid set.
6. No link to the economy layer. If a zone holds resource_cards, nothing in the zone def tells the engine "when a card lands here, increment tracker X". Will matter once Flow is real.
7. No lifecycle scope. Some zones exist all game (hand, deck). Some only during certain phases (current_trick in a trick-taker). No phase_scope or always flag. Flow will need this.
8. No max_cards for player hand. Present on market-like rules, absent where it's most commonly needed. Hand-size limits are a first-class design knob.
9. Zones are not mechanic-scoped. Parallel problem to what we just fixed for types. A trick-taking game doesn't have in_play or market — it has current_trick and won_tricks. Today's single-file default is deck-builder-centric.
10. No way to customise a zone per game. User can tick/untick defaults. No rename, no max_cards override, no "add a custom zone". Every game gets the same topology.

• Revealed / preview zone — face-up peek at the next card (Dominion-like).
• Score pile — won tricks, completed sets, victory cards. Owned per-player or per-team.
• Staging zone — drafting, trade offer, pending-bid.
• Persistent setup zone — role cards, quest tokens, identity cards that aren't in the deck cycle.
• Supply pile (per-stack) — Dominion's supply is several decks keyed by card, not a single pool. The market concept is close but not quite it.

Fix now, mechanical:

• Fix stale in_play.accepts reference

  Change ["unit", "location", "trap"] to ["unit", "structure"] or drop the constraint.
• Decide visibility / access shape

  Enum vs array. Normalise existing entries either way.
• Remove initial from zone definitions

  Setup state, not config. Will live in Flow's setup phase.

Fix soon, schema shape:

• Document the enums (type, owner, visibility, access, ordering)

  Add a Zone Schema section to this doc or JSON Schema alongside the data file.
• Add max_cards as first-class optional field

  Hand limits, deck limits, zone caps.
• Promote rules.refill to a named field

  auto_refill_from + auto_refill_to. Common pattern; shouldn't hide in a generic rules bag.

Fix when convenient (parallel to mechanic-aware Step 2):

• Split zones into assets/data/zones/{mechanic}.json

  Parallel to the types split. Keep a small universal set only if the zones really are universal.
• Add auto_tracker_effect hook

  Link zones to the economy: "when a card lands here, +N to tracker X".
• Introduce phase_scope on zones

  Requires Flow to exist. Distinguishes persistent zones from per-phase zones.

Fix when rewriting Step 2 UI:

• Allow per-game zone customisation

  Rename, edit max_cards, add/remove custom zones. Not just tick/untick.
• Replace the raw JSON <pre> display

  Already captured in the Step 2 analysis as "visual zone layout instead of JSON". Linked here for completeness.

A Star-Realms-inspired 2-player game fits naturally into the schema. Excerpt (full version in proposed-schema.json, key EXAMPLE_1_DECK_BUILDER):

{
  "briefing": {
    "game_name": "StarForge",
    "mechanic": "deckbuild",
    "subgenre": "combat",
    "player_mode": "competitive",
    "player_count_min": 2, "player_count_max": 2,
    "age_rating": "12+", "play_time": "30_60", "complexity": 3,
    "game_goal": "Reduce opponent's Authority to zero."
  },
  "schema": {
    "types_enabled":      [{ "id": "unit" }, { "id": "structure" }, { "id": "event" }],
    "behaviours_enabled": ["Permanent", "Strike", "Instant", "Outpost"],
    "effects_enabled":    ["deal_damage", "heal", "draw", "gain_resource", "destroy"]
  },
  "economy": {
    "trackers": [
      { "id": "authority", "role": "life",     "starts_at": 50, "per_player": true },
      { "id": "trade",     "role": "resource", "starts_at": 0,  "regenerates": "per_turn_reset_to_zero" },
      { "id": "combat",    "role": "resource", "starts_at": 0,  "regenerates": "per_turn_reset_to_zero" }
    ]
  },
  "flow": {
    "phases": [
      { "id": "main", "repeat": "until_ended_by_player",
        "allowed_actions": [
          { "id": "play_card",       "from": "hand",      "to": "in_play",  "any_number": true },
          { "id": "buy_from_row",    "from": "trade_row", "to": "discard",  "cost_in": "trade" },
          { "id": "attack_opponent", "cost_in": "combat", "effect": "reduce_tracker", "tracker": "authority" }
        ]},
      { "id": "cleanup", "automatic": true,
        "mandatory_actions": [
          { "id": "move_all", "from": "in_play", "to": "discard" },
          { "id": "draw",     "from": "draw_pile", "to": "hand", "count": 5 }
        ],
        "tracker_resets": ["trade", "combat"] }
    ],
    "win_conditions": [
      { "id": "authority_zero", "target": "opponent", "metric": "tracker:authority", "comparator": "<=", "threshold": 0 }
    ]
  }
}

A 4-player partnership trick-taking game fits the same schema with completely different content — no Units, no attack/defense behaviours, no Battlefield. Instead: one new type (ranked_card) with rank + suit fields, no behaviours, team-scoped score trackers.

This is the acid test for whether the schema is really mechanic-agnostic. It is:

{
  "briefing": {
    "game_name": "SkyBid",
    "mechanic": "tricktake",
    "player_mode": "team", "is_team_game": true,
    "player_count_min": 4, "player_count_max": 4,
    "game_goal": "First team to reach 500 points wins."
  },
  "schema": {
    "types_enabled":      [{ "id": "ranked_card" }],
    "behaviours_enabled": [],
    "effects_enabled":    []
  },
  "economy": {
    "trackers": [
      { "id": "team_score", "role": "score",      "per_team": true, "starts_at": 0 },
      { "id": "bid",        "role": "commitment", "per_team": true, "starts_at": 0 }
    ]
  },
  "topology": {
    "zones": [
      { "id": "deck",          "owner": "shared" },
      { "id": "hand",          "owner": "per_player", "visibility": "owner" },
      { "id": "current_trick", "owner": "shared",     "visibility": "public" },
      { "id": "won_tricks",    "owner": "per_team" }
    ]
  },
  "flow": {
    "phases": [
      { "id": "deal",  "one_time_per_round": true, "automatic": true,
        "mandatory_actions": [
          { "id": "shuffle", "target": "deck" },
          { "id": "deal",    "from": "deck", "to": "hand", "count": 13, "to_each_player": true }
        ]},
      { "id": "bid",   "repeat": "once_per_player",
        "allowed_actions": [{ "id": "place_bid", "min": 0, "max": 500 }, { "id": "pass" }] },
      { "id": "play",  "repeat": "until_hands_empty",
        "allowed_actions": [{ "id": "play_card", "from": "hand", "to": "current_trick", "follow_suit_if_possible": true }] },
      { "id": "resolve_trick", "trigger": "current_trick_has_N_cards", "N": 4,
        "mandatory_actions": [
          { "id": "determine_winner", "by": "highest_rank_in_lead_suit_or_trump" },
          { "id": "move_all", "from": "current_trick", "to": "won_tricks.of_winner" },
          { "id": "increment_tracker", "who": "winner_team", "tracker": "team_score", "by": "sum_of_point_values_in_trick" }
        ]}
    ],
    "win_conditions": [
      { "id": "reach_target", "target": "any_team", "metric": "tracker:team_score", "comparator": ">=", "threshold": 500 }
    ]
  }
}

The new type ranked_card with rank / suit / point_value fields would be added to the default type catalog to make trick-taking / rummy / bridge-like games first-class.

Big-bang rewrites on a WIP project are risky. A realistic migration in three tracks:

1. Track A — rename & split (low risk). cardtypes-default.json splits into types + subtypes. mechanics-effect.json renames to effects-default.json. No schema changes yet — just file housekeeping + inc-game-defaults.php updated to load the new locations.
2. Track B — terminology alignment (medium risk). Rename "enabled_mechanics" meta key → "effects_enabled". Rename archetype usages in UI and code. Unify resources and life-points as trackers. Add back-compat readers on the meta layer so existing games keep working.
3. Track C — Flow layer (bigger work). Introduce the flow structure as a new meta key. Start with a minimum viable spec: phases + win_conditions. First AI integration: have provideContextToIA generate a proposed Flow for the briefing and persist it. Iterate from there.

Tracks A and B are maybe a day each. Track C is a week+ of design and AI-prompt iteration.

What changed

Replaced the monolithic cardtypes-default.json with mechanic-scoped types/ and subtypes/ catalogs, dropped three root types that didn't belong (location, role, rulemod), promoted trap to an Event subtype, renamed resource to resource_card, and widened two allowed_behaviours lists so subtypes no longer leak behaviours outside the parent's allow-list.

File layout

assets/data/
  cardtypes-default.json
  # single flat array, 27 entries,
  # roots and subtypes mixed,
  # distinguished only by a `parent` field

assets/data/
  types/
    deckbuild.json          6 roots
  subtypes/
    deckbuild.json         18 subtypes
  # per-mechanic catalogs;
  # when tcg/tricktake/etc. arrive
  # they get their own files here

Catalog contents

Field names & terminology

allowed_behaviours widening

PHP access patterns

// inc-game-defaults.php
$_game_defaults['card-types'];
// flat array, roots + subtypes,
// roots identified by parent===null

// loadCardTypeSchema() read the file
// directly on every call

// inc-game-defaults.php
$_game_defaults['types'];      // roots only
$_game_defaults['subtypes'];   // subtypes only
$_game_defaults['card-types']; // legacy flat
                               // (auto-rebuilt for
                               // back-compat)

// loadCardTypeSchema() uses the global
// (no file reads)

Side-effect: behaviour-driven inheritance now works

loadCardTypeSchema() was previously reading a non-existent behaviours.json (typo; real file is card-behaviours.json), so the behaviour metadata came back empty and the subtype-inheritance pass silently did nothing. Fixed in the same migration. Observable effect:

• Strike subtypes (e.g. unit__striker) now have attributes.health stripped from their rendered schema (Strike declares removes_field: ["attributes.health"]).
• Permanent subtypes (e.g. unit__frontliner) now have attributes.health inherited from the parent (Permanent declares requires_field: ["attributes.health"]).

This is the intended behaviour per the original schema design docstrings — it just wasn't firing before. Downstream AI prompts that go through loadCardTypeSchema() will see slightly different (more accurate) card shapes. Smoke-test before assuming parity.

Follow-ups

• Delete assets/data/cardtypes-default.json — no live reader references it; kept temporarily for safety.
• Migrate index-step2.php + partial-form-cardtypes.php to use $_game_defaults['types'] / ['subtypes'] directly instead of the back-compat flat array.
• Add types/{mechanic}.json for additional mechanics when those genres enter scope.

• Unify trackers? Is it right to fold resources and life under one trackers concept with a role field? Simpler schema, but the user thinks about Mana differently from HP.
• Subtypes: global or per-game? Today, defaults are global and custom subtypes live in game_meta. Proposal keeps that split. OK?
• Flow scope for v1? Minimum would be phases + win_conditions, everything else optional. Even that is non-trivial.
• Effect params — how structured? "deal_damage amount: 3, target: opponent_authority" is clean. But composite effects ("draw a card, then if it's a Unit gain 1 Combat") get messy. Recommend: one effect entry per action; composites are arrays of effects. No DSL.
• Composite win conditions? Score >= 500 AND hand empty. Model as AND/OR tree, or as flat list of independent conditions? Recommend flat list (any one fires) — simpler.
• Localised card text? content.cards[].rules_text_localised[lang]. Small tax now, huge cost to retrofit. Recommend designing in now, even if only en ships.
• Where does game-length cap live? Currently proposed as flow.game_length_cap, separate from loss conditions. It's game-ending but not player-attributable. Keep separate?
• Does the schema version itself? Add a top-level schema_version so we can migrate persisted games forward when the schema changes. Recommend yes, string like "0.1".

Read the schema file, push back on anything that feels wrong or over-engineered, then we can scope Track A / B / C concretely and pick a starting point. Nothing in the wizard or the engine needs to change until we agree on the shape.