From 044424b6302425421b4ff408705d496e614746b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 23:14:54 -0500 Subject: [PATCH] =?UTF-8?q?game:=20=C2=A72.1=20starter=20decks=20(pinned?= =?UTF-8?q?=20loaners),=20trendDown=20-200,=20derive=20pinned=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- shared/game/derive.ts | 14 +++++--- shared/game/index.ts | 2 +- shared/game/starter.ts | 68 ++++++++++++++++++++++++++++++++++++++ tests/game-derive.test.ts | 16 ++++++++- tests/game-starter.test.ts | 52 +++++++++++++++++++++++++++++ 5 files changed, 145 insertions(+), 7 deletions(-) create mode 100644 tests/game-starter.test.ts diff --git a/shared/game/derive.ts b/shared/game/derive.ts index ed60366..58e61a2 100644 --- a/shared/game/derive.ts +++ b/shared/game/derive.ts @@ -21,6 +21,8 @@ export interface CardInput { live: { trendPercent: number | null; dailyAverage: number | null }; /** §1.10, set by the host. Only 'unchecked' changes derivation (cost cap). */ check: 'verified' | 'unverified' | 'unchecked' | 'loaner'; + /** Loaners only (§2.1): replaces §1.1–1.5. Ignored unless check === 'loaner'. */ + pinned?: { cost: number; home: Stat; faction: Faction }; } /** 99 ascending cut points per stat (§1.1). */ @@ -45,7 +47,7 @@ export const DEFAULT_DERIVATION: DerivationRules = { vanillaBonus: 1, keywordsEnabled: V1_KEYWORDS, keywordParams: {}, - trendUp: 25, trendDown: -25, trendMinDaily: 20, + trendUp: 25, trendDown: -200, trendMinDaily: 20, // −200: no down arrow in v1 (§1.6) uncheckedCostCap: 4, }; @@ -113,17 +115,19 @@ export function keywordFor(faction: Faction, cost: number, hasCopyInDeck: boolea export function deriveCard(input: CardInput, table: PercentileTable, rules: DerivationRules = DEFAULT_DERIVATION, hasCopyInDeck = false): GameCard { + const pinned = input.check === 'loaner' ? input.pinned : undefined; const pct = percentiles(input.snapshot.stats, table); - let cost = costFor(fame(pct), rules.costThresholds); + let cost = pinned ? pinned.cost : costFor(fame(pct), rules.costThresholds); if (input.check === 'unchecked') cost = Math.min(cost, rules.uncheckedCostCap); + const faction = pinned ? pinned.faction : input.category; const base = rules.powerByCost[cost]; if (base === undefined) throw new RangeError(`powerByCost has no entry for cost ${cost}`); - const { keyword, vanilla } = keywordFor(input.category, cost, hasCopyInDeck, rules); + const { keyword, vanilla } = keywordFor(faction, cost, hasCopyInDeck, rules); const delta = keyword ? Math.max(-3, Math.min(0, rules.keywordParams[keyword]?.powerDelta ?? 0)) : 0; return { - cardId: input.cardId, pageId: input.pageId, title: input.title, faction: input.category, rarity: input.rarity, + cardId: input.cardId, pageId: input.pageId, title: input.title, faction, rarity: pinned ? 'Common' : input.rarity, cost, power: Math.max(0, base + (vanilla ? rules.vanillaBonus : 0) + delta), - home: homeStat(pct), trend: trendFor(input.live, rules), keyword, + home: pinned ? pinned.home : homeStat(pct), trend: pinned ? 0 : trendFor(input.live, rules), keyword, source: input.check === 'loaner' ? 'loaner' : 'owned', }; } diff --git a/shared/game/index.ts b/shared/game/index.ts index 9819929..e1c4328 100644 --- a/shared/game/index.ts +++ b/shared/game/index.ts @@ -14,4 +14,4 @@ export { DEFAULT_DERIVATION, HOME_TIE_ORDER, percentile, percentiles, fame, costFor, homeStat, trendFor, keywordFor, deriveCard, deriveDeck, type CardInput, type PercentileTable, type DerivationRules, } from './derive.ts'; -export { STARTER_POOL, loanerCard, previewPool, starterDeck } from './starter.ts'; +export { STARTER_POOL, STARTER_DECKS, loanerCard, loanerInput, loanerPageId, previewPool, starterDeck, starterDeckById, type StarterDeckDef } from './starter.ts'; diff --git a/shared/game/starter.ts b/shared/game/starter.ts index 189460d..7fb6d76 100644 --- a/shared/game/starter.ts +++ b/shared/game/starter.ts @@ -5,6 +5,7 @@ * engine-b / council-data replace STARTER_POOL with derived cards (cards.ts). */ import { Rng } from './rng.ts'; +import { DEFAULT_DERIVATION, deriveCard, type CardInput, type DerivationRules } from './derive.ts'; import { FACTION_KEYWORD } from './keywords.ts'; import type { Faction, GameCard, Stat } from './types.ts'; @@ -59,3 +60,70 @@ export function starterDeck(seed: number | string): GameCard[] { } return deck; } + +// ---------- DESIGN §2.1 starter decks v1 (PR #18) ---------- + +type Pin = [cost: number, title: string, faction: Faction, home: Stat]; + +/** Real pageIds for the shared/catalog.ts cards; the others have none yet (§2.1), see loanerPageId. */ +const CATALOG_PAGE_IDS: Record = { Moon: 19331, 'Periodic table': 23053, Octopus: 22780, 'Albert Einstein': 736 }; + +export interface StarterDeckDef { id: string; name: string; cards: readonly Pin[] } + +/** Four 12-card loaner decks, each with the curve 1,1,2,2,3,3,3,4,4,5,5,6, 6+6 factions and 4 cards per home stat. */ +export const STARTER_DECKS: readonly StarterDeckDef[] = [ + { id: 'stargazers', name: 'Stargazers', cards: [ + [1, 'Moon', 'Space', 'reach'], [1, 'Electron', 'Science', 'depth'], [2, 'Mars', 'Space', 'attention'], + [2, 'Periodic table', 'Science', 'depth'], [3, 'Saturn', 'Space', 'reach'], [3, 'Photosynthesis', 'Science', 'attention'], + [3, 'Black hole', 'Space', 'depth'], [4, 'Quantum mechanics', 'Science', 'reach'], [4, 'Milky Way', 'Space', 'attention'], + [5, 'DNA', 'Science', 'attention'], [5, 'Sun', 'Space', 'reach'], [6, 'Theory of relativity', 'Science', 'depth'], + ] }, + { id: 'field-guide', name: 'Field Guide', cards: [ + [1, 'Octopus', 'Nature', 'depth'], [1, 'Stonehenge', 'History', 'attention'], [2, 'Axolotl', 'Nature', 'attention'], + [2, 'Rosetta Stone', 'History', 'reach'], [3, 'Coral reef', 'Nature', 'depth'], [3, 'Roman Empire', 'History', 'reach'], + [3, 'Honey bee', 'Nature', 'attention'], [4, 'Ancient Egypt', 'History', 'depth'], [4, 'Amazon rainforest', 'Nature', 'reach'], + [5, 'Blue whale', 'Nature', 'attention'], [5, 'Great Wall of China', 'History', 'reach'], [6, 'World War II', 'History', 'depth'], + ] }, + { id: 'headliners', name: 'Headliners', cards: [ + [1, 'Haiku', 'Culture', 'attention'], [1, 'Ada Lovelace', 'People', 'depth'], [2, 'Jazz', 'Culture', 'attention'], + [2, 'Marie Curie', 'People', 'reach'], [3, 'Mona Lisa', 'Culture', 'reach'], [3, 'Frida Kahlo', 'People', 'attention'], + [3, 'Chess', 'Culture', 'depth'], [4, 'Leonardo da Vinci', 'People', 'reach'], [4, 'The Beatles', 'Culture', 'attention'], + [5, 'William Shakespeare', 'People', 'depth'], [5, 'Olympic Games', 'Culture', 'reach'], [6, 'Wolfgang Amadeus Mozart', 'People', 'depth'], + ] }, + { id: 'pioneers', name: 'Pioneers', cards: [ + [1, 'Sputnik 1', 'Space', 'reach'], [1, 'Nikola Tesla', 'People', 'attention'], [2, 'Hubble Space Telescope', 'Space', 'depth'], + [2, 'Isaac Newton', 'People', 'reach'], [3, 'Neil Armstrong', 'People', 'attention'], [3, 'Jupiter', 'Space', 'reach'], + [3, 'Galileo Galilei', 'People', 'depth'], [4, 'Albert Einstein', 'People', 'attention'], [4, 'International Space Station', 'Space', 'depth'], + [5, 'Apollo 11', 'Space', 'attention'], [5, 'Charles Darwin', 'People', 'reach'], [6, 'Solar System', 'Space', 'depth'], + ] }, +]; + +const kebab = (title: string) => title.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''); + +/** + * §2.1 wants pageId null for loaners without a known article id, but GameCard.pageId is a number. + * Until the type allows null, such loaners get a stable negative id (never a real Wikipedia pageId), + * so copy counting stays per card (§2.1: "copies are counted per cardId"). + */ +export function loanerPageId(title: string): number { + if (Object.hasOwn(CATALOG_PAGE_IDS, title)) return CATALOG_PAGE_IDS[title]; + let h = 2166136261; + for (let i = 0; i < title.length; i++) h = Math.imul(h ^ title.charCodeAt(i), 16777619); + return -1 - ((h >>> 0) % 1_000_000_000); +} + +/** The §1 CardInput for a pinned loaner. Snapshot stats are unused (pinned replaces §1.1–1.5). */ +export function loanerInput([cost, title, faction, home]: Pin): CardInput { + return { cardId: `loaner:${kebab(title)}`, pageId: loanerPageId(title), title, category: faction, rarity: 'Common', + snapshot: { stats: { attention: null, depth: 0, reach: 0 } }, live: { trendPercent: null, dailyAverage: null }, + check: 'loaner', pinned: { cost, home, faction } }; +} + +const NO_TABLE = { attention: [], depth: [], reach: [] }; + +/** A §2.1 starter deck by id, derived with the given rules (modes that change the curve change loaners too). */ +export function starterDeckById(id: string, rules: DerivationRules = DEFAULT_DERIVATION): GameCard[] { + const def = STARTER_DECKS.find(deck => deck.id === id); + if (!def) throw new RangeError(`Unknown starter deck: ${id}`); + return def.cards.map(pin => deriveCard(loanerInput(pin), NO_TABLE, rules)); +} diff --git a/tests/game-derive.test.ts b/tests/game-derive.test.ts index 13adf63..f56d0db 100644 --- a/tests/game-derive.test.ts +++ b/tests/game-derive.test.ts @@ -52,8 +52,10 @@ test('home stat: highest percentile, ties depth > reach > attention, never null }); test('trend: ±1 at inclusive thresholds, 0 for null, 0 under trendMinDaily (§1.6)', () => { - const t = (trendPercent: number | null, dailyAverage: number | null = 100) => trendFor({ trendPercent, dailyAverage }, RULES); + const modeRules = { ...RULES, trendDown: -25 }; // a mode that turns the down arrow back on + const t = (trendPercent: number | null, dailyAverage: number | null = 100) => trendFor({ trendPercent, dailyAverage }, modeRules); assert.deepEqual([t(25), t(24.9), t(-25), t(-24.9), t(null), t(Number.NaN), t(1e9)], [1, 0, -1, 0, 0, 0, 1]); + assert.equal(trendFor({ trendPercent: -99, dailyAverage: 1000 }, RULES), 0, 'v1 default: no down arrow'); assert.equal(t(80, 19.9), 0); assert.equal(t(80, 20), 1); assert.equal(t(80, null), 0); @@ -130,3 +132,15 @@ test('power depends only on cost: forged stats only move a card up the curve (§ test('deriveCard rejects a rules config with no power for the derived cost', () => { assert.throws(() => deriveCard(input({ attention: 100, depth: 100, reach: 100 }), TABLE, { ...RULES, powerByCost: [0, 1, 2] }), RangeError); }); + +test('pinned values replace §1.1–1.5 for loaners only (§2.1)', () => { + const pinned = { cost: 5, home: 'reach' as const, faction: 'History' as const }; + const stats = { attention: 5, depth: 5, reach: 5 }; + const loaner = deriveCard(input(stats, { check: 'loaner', pinned, rarity: 'Epic', live: { trendPercent: 99, dailyAverage: 999 } }), TABLE); + assert.deepEqual([loaner.cost, loaner.power, loaner.home, loaner.faction, loaner.keyword, loaner.rarity, loaner.trend, loaner.source], + [5, 8, 'reach', 'History', 'nostalgic', 'Common', 0, 'loaner']); + const owned = deriveCard(input(stats, { pinned }), TABLE); + assert.deepEqual([owned.cost, owned.faction], [1, 'Science'], 'pinned is ignored when check !== loaner'); + const cheap = deriveCard(input(stats, { check: 'loaner', pinned: { ...pinned, cost: 1 } }), TABLE); + assert.deepEqual([cheap.power, cheap.keyword], [2, null], 'vanillaBonus still applies to pinned cost-1'); +}); diff --git a/tests/game-starter.test.ts b/tests/game-starter.test.ts new file mode 100644 index 0000000..6cf3b2a --- /dev/null +++ b/tests/game-starter.test.ts @@ -0,0 +1,52 @@ +// DESIGN §2.1 starter decks (PR #18). Owner: engine-b. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + DEFAULT_DERIVATION, DEFAULT_RULESET, FACTION_KEYWORD, STARTER_DECKS, createMatch, starterDeckById, validateDeck, +} from '../shared/game/index.ts'; + +const countBy = (keys: string[]) => keys.reduce>((m, k) => ({ ...m, [k]: (m[k] ?? 0) + 1 }), {}); + +test('four starter decks, each with the frozen curve, 6+6 factions and 4 cards per home stat', () => { + assert.deepEqual(STARTER_DECKS.map(d => d.id), ['stargazers', 'field-guide', 'headliners', 'pioneers']); + for (const def of STARTER_DECKS) { + const deck = starterDeckById(def.id); + assert.deepEqual(deck.map(c => c.cost), [1, 1, 2, 2, 3, 3, 3, 4, 4, 5, 5, 6], def.id); + const factions = Object.values(countBy(deck.map(c => c.faction))); + assert.deepEqual(factions, [6, 6], `${def.id} factions`); + const homes = Object.values(countBy(deck.map(c => c.home))); + assert.deepEqual(homes, [4, 4, 4], `${def.id} homes`); + } +}); + +test('starter cards follow §10.1 and the power curve like owned cards', () => { + for (const def of STARTER_DECKS) for (const card of starterDeckById(def.id)) { + assert.equal(card.source, 'loaner'); + assert.equal(card.rarity, 'Common'); + assert.equal(card.trend, 0); + assert.match(card.cardId, /^loaner:[a-z0-9-]+$/); + if (card.cost === 1) assert.deepEqual([card.keyword, card.power], [null, 2]); + else assert.deepEqual([card.keyword, card.power], [FACTION_KEYWORD[card.faction], DEFAULT_DERIVATION.powerByCost[card.cost]]); + } +}); + +test('all 6 factions and all 4 shared/catalog.ts cards (with real pageIds) are covered', () => { + const all = STARTER_DECKS.flatMap(d => starterDeckById(d.id)); + assert.equal(new Set(all.map(c => c.faction)).size, 6); + const ids = Object.fromEntries(all.map(c => [c.title, c.pageId])); + assert.deepEqual([ids.Moon, ids['Periodic table'], ids.Octopus, ids['Albert Einstein']], [19331, 23053, 22780, 736]); + for (const c of all) if (!['Moon', 'Periodic table', 'Octopus', 'Albert Einstein'].includes(c.title)) assert.ok(c.pageId < 0, c.title); +}); + +test('every starter deck passes engine deck validation and starts a match against every other', () => { + for (const a of STARTER_DECKS) { + assert.deepEqual(validateDeck(DEFAULT_RULESET, starterDeckById(a.id)), [], a.id); + for (const b of STARTER_DECKS) assert.doesNotThrow(() => createMatch(DEFAULT_RULESET, [starterDeckById(a.id), starterDeckById(b.id)], 1)); + } +}); + +test('modes changing the curve change loaners too; unknown ids are rejected', () => { + const flat = starterDeckById('pioneers', { ...DEFAULT_DERIVATION, powerByCost: [0, 3, 3, 3, 3, 3, 3], vanillaBonus: 0 }); + assert.ok(flat.every(c => c.power === 3)); + assert.throws(() => starterDeckById('nope'), RangeError); +});