forked from WikiDeck/wikideck
ENGINE_API.md: starter decks, previewPool, derivation; CardInput trust boundary; obscure not masked yet
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -47,8 +47,10 @@ const r = result(state); // { winner: 0 | 1 | null, reason, topicsLed, lanePow
|
||||
| `scoringPower(state, lane)` | Lane power plus revealed "at scoring" Portals (§7). `result().lanePower` uses this. |
|
||||
| `laneCapacity(state, lane)` | Per-seat capacity of a lane. A Portal such as Stub may override it. |
|
||||
| `isOnTopic(state, cardInPlay)` | §1.4/§6 on-topic test, including Disambiguation. |
|
||||
| `starterDeck(seed): GameCard[]` | A 12-card loaner deck (DESIGN §2). **Placeholder** cards until starter-cards.json lands. |
|
||||
| `previewPool(): GameCard[]` | Every loaner card once. For draft modes. |
|
||||
| `starterDeck(seed): GameCard[]` | A random 12-card **placeholder** loaner deck (2 per cost from `STARTER_POOL`). Kept for tests and tools; it is not a §2.1 starter deck. |
|
||||
| `STARTER_DECKS`, `starterDeckById(id, rules?): GameCard[]` | The 4 DESIGN §2.1 starter decks (`stargazers`, `field-guide`, `headliners`, `pioneers`): pinned loaners derived through `deriveCard`. |
|
||||
| `previewPool(rules?): GameCard[]` | The 19 frozen `docs/game/starter-cards.json` loaners, derived via §1 against the card-sample percentile table. For loaner slots and draft modes. |
|
||||
| `deriveCard(input, table, rules?)`, `deriveDeck(inputs, table, rules?)` | DESIGN §1 + §10.1 derivation (`shared/game/derive.ts`). |
|
||||
| `placeCard(state, seat, lane, card)`, `revealPortal(state, lane)` | Test helpers for building boards by hand. |
|
||||
|
||||
## 2. Actions
|
||||
@@ -106,6 +108,11 @@ interface GameCard {
|
||||
- **The engine takes already-derived cards and never reads raw stats.** The council asked for this, because snapshot stats are self-reported (#1, critic brief A.1).
|
||||
- Derivation (DESIGN §1 and §10.1: percentile → fame → cost → power, home, trend, keyword and vanillaBonus) lives in `shared/game/derive.ts`, which engine-b owns. Hosts run it on host-frozen, plausibility-checked inputs before calling `createMatch`.
|
||||
- Modes may adjust `GameCard` fields such as `power` before `createMatch`. The engine does not re-derive them.
|
||||
- **Trust boundary for `CardInput`.** `check` and `pinned` are host decisions, not player input. `deriveCard` trusts them:
|
||||
`check: 'loaner'` with `pinned` replaces §1.1–1.5, and `check: 'unchecked'` only caps cost. A host must build loaner inputs
|
||||
**only** from shipped data (`STARTER_DECKS`, `previewPool()`, `LOANER_SNAPSHOTS`), never from client JSON, and must set
|
||||
`check` for owned cards from its own §1.10 plausibility check. Otherwise a client could send `check: 'loaner', pinned: {cost: 1, …}` for any card.
|
||||
- **`obscure` leaks in v1.** `viewFor` does not mask Obscure cards yet. Modes must not put `obscure` in `keywordsEnabled` until it does.
|
||||
- A keyword that isn't in `ruleset.keywordsEnabled` never runs. Derivation is responsible for not giving that card `vanillaBonus`.
|
||||
- Lane power = `power` + `bonus` + `trend` + `onTopicBonus[cost]` if on-topic + ongoing keyword and Portal effects, floored at 0.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user