gamekit777 0.1.0

package/create-game/template/CLAUDE.md.tmpl

@@ -0,0 +1,167 @@
+# __TITLE__（`__ID__`）— 写给 AI 的游戏开发指南
+
+这是一个 GameKit 游戏目录。平台**不执行游戏代码**：打包时用你的 `round()` 采样出一张权重表，
+运行时平台按权重抽一行、查表赔付，浏览器用你的 `restore()` 把那一行还原成演出。
+所以你写的每一行逻辑都要满足「三处逐位一致」：作者机器采样、玩家浏览器还原、审计脚本复算。
+
+先读这份文件，再读 `game.ts`。模板是一个**能跑的抛硬币**——从能跑的东西开始改，不要从零写。
+
+## 目录
+
+```
+game.ts              清单：defineGame({...})。Node 与浏览器都 import 它，不能碰 DOM / Svelte
+src/rules/           纯逻辑：schema、simulate、restore、常量、类型。零 DOM、零自取随机
+src/index.ts         浏览器入口 = { ...game, mount }。平台加载的是它
+src/state/           单局状态（Svelte runes 类），只放「演到哪一步了」
+src/view/            mount（接平台）与 present（把结果播出来）
+src/components/      画面。子组件一律 getInstance()，不 import 状态对象
+src/assets/          资源清单与注册表；critical/ 首屏必需，lazy/ 后台预取
+scripts/verify.ts    数学回归：纯度、确定性、RTP、分布
+test/e2e.test.ts     happy-dom 里跑完整一局
+studio/cases.jsonl   case 库（进版本控制），studio 维护
+.studio/             采样缓存与建好的表，按规则指纹分目录，可随手删
+```
+
+**没有** `publish.ts`、`src/rules/index.ts`、`meta`、版本号。看到教程里有这些就是旧结构，忽略。
+
+## 清单：`game.ts`
+
+```ts
+export default defineGame<Config, Outcome>({
+  slug: '__ID__', title: '__TITLE__', description?: string,
+  rtp: 0.98,          // 目标 RTP，小数。所有 mode 都由求解器钉到这一个数
+  sims: 100_000,      // 每张表采样多少局。行数为的是「牌局不重复」，不是「结果种类多」
+  autoplay?: true,    // 平台要不要显示自动按钮
+
+  schema,             // 有哪些参数（见下）
+  round,              // 一局怎么算（见下）
+  paytable,           // 赔率表：PaytableRow[] 或 (config) => PaytableRow[]。给大厅展示，不参与计算
+
+  modes?,             // 要几张表。不写 = 单表 'base'
+  book?,              // 演出怎么编进表里：'none' | 'seed' | { encode(sample): Uint8Array }。不写 = 'seed'
+  restore?,           // 怎么把一行还原成演出。book 为 'seed' 时不写，SDK 给 restoreFromSeed
+});
+```
+
+`normalize` / `validate` / `modeOf` / `configOf` **不要写**，`defineGame` 按 schema 和 modes 推导后挂在返回值上。
+清单里也**没有注额区间**——那是平台的事。
+
+### `round(input)`
+
+```ts
+function round(input: RoundInput<Config>): RoundResult<Outcome>
+// RoundInput  = { config, bet, seed: { server, client, nonce } }
+// RoundResult = { bet, payout, multiplier, outcome, pacing: { durationMs, postDelayMs } }
+```
+
+硬约束，每一条违反都会让表里的 payout 和客户端演出来的对不上，而且是概率性的：
+
+1. **同步纯函数**。不碰 DOM、时间、全局状态；随机只来自 `createRng(input.seed)`。`Math.random` / `crypto` 一次都不能碰——`scripts/verify.ts` 会把它们换成会抛的桩。
+2. **随机数抽取顺序是契约**。用 `rng.fork('tag')` 把子系统分开（发牌一条、金牌一条），将来改一处不会让另一处跟着漂。`below(n)` 是无偏整数，不要自己写 `% n`。
+3. **金额是最小货币单位的整数**。`payout` 是整数分；`multiplier` 最多两位小数（平台按 centi = ×100 存）；`payout` 必须是 `bet` 的精确线性函数（bet 恒为 100 的倍数，`payout = bet * mult` 或 `(bet / 100) * payoutCenti` 都行，取整方式不能随 bet 变）。
+4. 先 `normalizeBySchema(schema, input.config)` 再用 config——调用方给的可能是部分或越界的值。
+5. 平台有最大倍数上限，超过就进不了表。
+
+装饰性随机（粒子角度、台词抽签）用 `Math.random()`，**放在 `src/view` / 组件里**，绝不进 `round()`：它们不该占用可复现的随机数，否则加一句台词就会改变牌序。
+
+### `schema`
+
+`ConfigSchema<Config>`，每个字段 = 一种 kind + 元数据 + `default`：
+
+| kind | 形状 | 例子 |
+|---|---|---|
+| `int` / `number` | `{ min, max, step? }` | 翻几张牌 |
+| `bool` | — | 金牌开关 |
+| `enum` | `{ options: [{ value, label }] }` | 押哪一面 |
+| `pick` | `{ of: Option[], count, exact?, ordered? }` | 13 选 4 个点数 |
+
+元数据：`label`（`{'zh-CN': …}` 这种 I18n 记录）、`hint?`、`affectsOutcome`（影响结果的字段才进 schema；不影响的放 `ViewSettings`，别写进来）、
+`lock`（`'never' | 'inRound' | 'inRoundOrAuto'`）、`ui`（`'host'` 平台的设置面板渲染 / `'stage'` 你在画布里渲染，但值仍归平台）、
+`devOnly?`（只在开发环境允许，生产被服务端拒绝）、`control?` / `group?` / `order?`（渲染建议）。
+
+平台不认识你的游戏，它只认识 kind——设置 UI 是按 schema 自动渲染的。
+
+## 能不能打表：`modes` 与 `book`
+
+先问 studio：**`probe_table`**。它逐字段采样，告诉你两件不同的事：
+
+- **影响分布**的字段（换值后赔付的概率分布变了）→ 必须写进 `modes`。一张表 = 一种分布。
+- **只影响这一局**的字段（同一个种子下结果变了，但分布没变；抛硬币的 `side`、coco 的 `ranks`）→ 不进 modes，玩家运行时自由选。
+
+```ts
+modes: [{ name: 'n16g0', config: { N: 16, goldOn: false } }, ...]   // 只写影响分布的字段，每个 mode 写同一组键
+```
+
+出现在 `mode.config` 里的键就是 `modeKeys`；`modeOf(config)` 按它匹配，匹配不到就抛——那是你的 modes 声明不完整。
+表数 = modes 数，超过几十张就该把连续参数冻结成几档，或改成从有限档位里选。
+
+`book` 按 probe 的建议选：
+
+| 情形 | `book` | `restore` |
+|---|---|---|
+| 演出能从 payout 推导（≤3 种赔付，赢了就是你押的那面） | `'none'` | 自己写：从 `payoutCenti` 反推 outcome |
+| 所有影响结果的字段都在 modes 里 | `'seed'`（默认） | 不写。SDK 存采样种子、还原时重跑 `round()` |
+| 有字段只影响这一局（`side`、`ranks` 这类） | `{ encode(s) => Uint8Array }` | 自己写：解码时用玩家**当下**的自由字段。参考 coco 的 `rules/book.ts`：把 ranks 当重标记，存「命中第 k 格」而不是牌 id |
+
+`'seed'` 用错的后果：表里写 0x，客户端按玩家当下选的值算出 4.64x。`restoreFromSeed` 会在还原时抛出来，但那已经是运行时了——先跑 probe。
+
+### `restore(input)` 的硬契约
+
+```ts
+// RestoreInput = { config, bet, payoutCenti, frames: Uint8Array | null, mode, seed }
+```
+
+**返回的 `payout` 必须恰好等于 `(input.bet / 100) * input.payoutCenti`**，对不上就 `throw`、不演出。
+「玩家看到连成三条线，余额却没动」这类 bug 完全静默，最伤信任。能多验一道就多验：解码出的局面算出的倍数应当等于 `payoutCenti`。
+`input.config` 是玩家当下的配置（回放时是下注那一刻存下的），先 `normalizeBySchema` 再用。
+
+## 演出侧：`src/index.ts` 与 `mount`
+
+```ts
+export default { ...game, mount: mountGame, skins?: Skin[] };
+mount(host: Host<Config>, el: HTMLElement): Promise<GameInstance<Outcome>>
+```
+
+`Host` 是平台给你的，**全是只读**：`config` / `view` / `wallet` / `jackpot` 四个 `Readable`（`get()` + `subscribe()`），
+`audio.context()`（不要自己 new AudioContext）、`locale`、`emit(event)`、`log()`。
+想改参数只能 `host.requestConfig(patch)` 申请——平台校验、可能否决（局中、自动中）、批了才会从 `host.config` 推回来。
+画布内的控件因此也是受控组件：渲染平台的值，改动走申请。`ViewSettings.autoActive` 为真时禁用画布内的设置控件。
+
+`GameInstance`：`status`（`Readable<GameStatus>`，平台据 `busy` / `canBet` / `canSkip` / `canEditConfig` 控制自己的按钮）、
+`present(result, { rate? })`（演一局，resolve 于演完；`rate: Infinity` 直接看结果）、`preview()`（只演不结账，回放用）、`skip()` / `reset()` / `resize()` / `destroy()`。
+演出开始/结束发 `host.emit({ type: 'present:start' })` / `{ type: 'present:end', payout }`。
+
+约定：
+- **模块级不留可变状态**。`createInstance(host)` 造一棵状态树经 Svelte context 下传，组件 `getInstance()`。同页两个实例互不干扰，`test/e2e.test.ts` 会验。
+- `turbo` / `reducedMotion` 只改演出时长，改不了结果——它们根本不在 `round()` 的入参里。
+- CSS 命名空间挂在容器 `el` 上（`gk-__ID__`），不写 `document.documentElement`。
+- 画布是固定 900×771 的逻辑画面，平台整体缩放；按这个尺寸排版。
+- 资源放 `src/assets/critical|lazy`，走 `registry.ts` 注册；`game.meta.json` 的 `fonts` 声明字体。
+
+## 工作流（studio 的 MCP 工具）
+
+```
+改 src/rules/ 或 game.ts
+  → run_task check / verify / test         类型、数学回归、端到端
+  → probe_table                            能不能打表、modes 该写哪些键、book 怎么选
+  → preview_play { rounds, seed?, simId? } 在预览里演几局（本地表模型：就地建表 → 抽行 → restore）
+  → case_add                               把值得盯的局面存进 studio/cases.jsonl
+  → build_table                            采样 → 求解 → 编码 → 本地终验 → .studio/build/<指纹>/
+  → publish_dry_run → publish              发布要作者在页面上点确认，不可逆
+```
+
+- `game_info` 是第一跳：清单、schema、指纹、已建的表、预览连没连。
+- 长任务返回 `jobId` 就用 `job_status` 轮询。
+- `case_run` 任何结果变化都是 `fail`。是有意改的规则且这个 mode 没发布过，`case_bless` 接受；已发布过的 mode 解码逻辑**不能改**，要改就换 slug。
+- `preview_set` 被否决会在 `rejected` 里说明——那是平台的否决权在起作用，不是 bug。
+- 手动：`bun run dev`（参考平台，5173）、`bun run verify`、`bun run test`、`bun run build`。
+
+## 不要做的事
+
+- 不写 `normalize` / `validate` / `modeOf`；不加 `meta`、版本号；不在清单里写注额区间。
+- 不在 `round()` 或 `rules/` 里 import Svelte、DOM、`gamekit777/runtime`。
+- 不用 `Math.random` 决定任何影响赔付的事；不用 `% n` 取整数随机。
+- 不让 `payout` 出现小数或随 bet 变化的取整；`multiplier` 不超过两位小数。
+- 不在 `restore` 里「修正」对不上的 payout——对不上就抛。
+- 不把 `'seed'` 用在有自由字段的游戏上。
+- 不改已发布 mode 的发牌逻辑 / book 编解码 / 取整方式。

package/create-game/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+# studio 的采样缓存与建表产物，按规则指纹分目录，随手就能重建
+.studio/

package/create-game/template/game.meta.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "id": "__ID__",
+  "title": "__TITLE__",
+  "version": "1.0.0",
+  "aspect": "16:9",
+  "orientation": "any",
+  "fonts": []
+}

package/create-game/template/game.ts.tmpl

@@ -0,0 +1,57 @@
+/* __TITLE__ 的清单。只依赖 gamekit777/sdk 和自己的 rules/，Node 和浏览器都能 import：
+   studio 用它探测和建表、打包流水线用它采样、浏览器入口把它和 mount 拼在一起。
+
+   模板是抛硬币：两面对称，**只有一种赔付分布**，所以一张表就够。
+   `side` 不改变分布，只改变某一局落在哪面——服务端不需要知道它，玩家运行时自由选。
+   book 因此可以完全不传：payout > 0 就说明硬币落在你押的那面（见 rules/restore.ts）。
+
+   改成你自己的游戏时，先用 studio 的 probe_table 看看：
+     哪些字段改变赔付分布 → 写进 modes（一张表 = 一种分布），只写那几个字段
+     哪些字段只改变这一局 → 保持自由，用 book 编码演出（参考 coco 的 book.ts）
+     赔付必须是 centi 精度、必须是注额的线性函数——这两条 probe 会替你查
+   逻辑侧三个必填：schema 说有哪些参数，round 说结果怎么算，paytable 说赔多少。
+   normalize / validate / modeOf 不用写——它们由 schema 和 modes 推导。 */
+import { createRng, defineGame, normalizeBySchema, type RoundInput, type RoundResult } from 'gamekit777/sdk';
+import { HOUSE_EDGE, MULT } from './src/rules/const.ts';
+import { restore } from './src/rules/restore.ts';
+import { schema } from './src/rules/schema.ts';
+import { simulate } from './src/rules/simulate.ts';
+import type { __PASCAL__Config, __PASCAL__Outcome } from './src/rules/types.ts';
+
+export { schema, simulate, restore };
+export * from './src/rules/types.ts';
+
+/**
+ * 一局的结果。同步纯函数：同样的 (config, bet, seed) 恒得同样的 payout。
+ *
+ * 随机数的抽取顺序是契约的一部分：flip 子流 below(2) 一次。
+ * 已发布 mode 的这段逻辑不能改——历史局的 book 要靠它解；要改就换 slug。
+ */
+export function round(input: RoundInput<__PASCAL__Config>): RoundResult<__PASCAL__Outcome> {
+  const cfg = normalizeBySchema(schema, input.config);
+  const flip = createRng(input.seed).fork('flip').below(2);
+  const outcome = simulate(flip, cfg);
+  /* 金额一律是最小货币单位的整数。取整规则是契约的一部分——
+     服务端按 bet/100 × payoutCenti 赔付，这里必须得出同一个整数 */
+  const payout = outcome.win ? Math.floor(input.bet * outcome.mult) : 0;
+  return {
+    bet: input.bet,
+    payout,
+    multiplier: outcome.mult,
+    outcome,
+    pacing: { durationMs: 900, postDelayMs: outcome.win ? 400 : 250 },
+  };
+}
+
+export default defineGame<__PASCAL__Config, __PASCAL__Outcome>({
+  slug: '__ID__',
+  title: '__TITLE__',
+  description: '押正面还是反面。',
+  rtp: HOUSE_EDGE,
+  sims: 100_000,
+  schema,
+  round,
+  paytable: [{ label: { 'zh-CN': '猜中' }, mult: MULT }],
+  book: 'none',
+  restore,
+});

package/create-game/template/index.html.tmpl

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>__TITLE__</title>
+<script type="module" src="/src/dev.ts"></script>
+</head>
+<body>
+</body>
+</html>

package/create-game/template/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "@game/__ID__",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "svelte-check --tsconfig ./tsconfig.json && vite build",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run",
+    "verify": "bun scripts/verify.ts"
+  },
+  "dependencies": {
+    "gamekit777": "workspace:*"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@tsconfig/svelte": "^5.0.5",
+    "happy-dom": "^20.14.5",
+    "svelte": "^5.42.2",
+    "svelte-check": "^4.3.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.5",
+    "vitest": "^3.2.7"
+  }
+}

package/create-game/template/scripts/verify.ts.tmpl

@@ -0,0 +1,79 @@
+/* 逻辑回归。跑法：bun scripts/verify.ts [局数]
+
+   这四项是每个游戏都该有的：
+     纯度   round() 不碰全局随机源，否则端服算出的 payout 会不一致
+     确定性 同种子必然同结果，这是对账的前提
+     RTP    实际期望要对得上清单的 rtp
+     分布   随机源本身是否无偏 */
+import { MULT, WIN_CHANCE } from '../src/rules/const.ts';
+import game, { round } from '../game.ts';
+
+const ROUNDS = Number(process.argv[2] ?? 200_000);
+let fails = 0;
+
+console.log(`${game.title}（${game.slug}），目标 RTP=${game.rtp}`);
+
+console.log('\n[1/4] round() 的纯度：把全局随机源换成会抛的桩');
+{
+  const realRandom = Math.random, realCrypto = globalThis.crypto;
+  const boom = (who: string) => () => { throw new Error(`round() 调用了 ${who}`); };
+  Math.random = boom('Math.random') as typeof Math.random;
+  Object.defineProperty(globalThis, 'crypto', { configurable: true, get: boom('crypto') as () => Crypto });
+  let err: unknown = null;
+  try {
+    for (const side of ['heads', 'tails'] as const) {
+      round({ config: { side }, bet: 500, seed: { server: 'p', client: 'c', nonce: 1 } });
+    }
+  } catch (e) { err = e; } finally {
+    Math.random = realRandom;
+    Object.defineProperty(globalThis, 'crypto', { configurable: true, value: realCrypto, writable: true });
+  }
+  if (err) { console.error('  ✗', (err as Error).message); fails++; }
+  else console.log('  ✓ 没碰全局随机源');
+}
+
+console.log('\n[2/4] 确定性：同种子必然同结果');
+{
+  const seed = { server: 'det', client: 'c', nonce: 7 };
+  const a = round({ config: { side: 'heads' }, bet: 1000, seed });
+  const b = round({ config: { side: 'heads' }, bet: 1000, seed });
+  const ok = a.payout === b.payout && a.outcome.landed === b.outcome.landed;
+  console.log(ok ? '  ✓ 一致' : '  ✗ 同种子产出不同结果');
+  if (!ok) fails++;
+}
+
+console.log(`\n[3/4] RTP 蒙特卡洛 · ${ROUNDS.toLocaleString()} 局`);
+{
+  const BET = 100;
+  let staked = 0, returned = 0;
+  for (let i = 0; i < ROUNDS; i++) {
+    const r = round({ config: { side: 'heads' }, bet: BET, seed: { server: 'rtp', client: 'c', nonce: i } });
+    staked += BET; returned += r.payout;
+  }
+  const rtp = returned / staked;
+  /* 赔付是二值的（0 或 MULT），方差小，标准误可以直接算 */
+  const sd = MULT * Math.sqrt(WIN_CHANCE * (1 - WIN_CHANCE));
+  const se = sd / Math.sqrt(ROUNDS);
+  const z = Math.abs(rtp - game.rtp) / se;
+  const ok = z < 4;
+  if (!ok) { console.error(`  ✗ RTP=${rtp.toFixed(4)} 偏离期望 ${z.toFixed(1)}σ`); fails++; }
+  else console.log(`  ✓ RTP=${rtp.toFixed(4)}（期望 ${game.rtp}，偏离 ${z.toFixed(1)}σ）`);
+}
+
+console.log('\n[4/4] 正反面分布：卡方检验');
+{
+  let heads = 0;
+  for (let i = 0; i < ROUNDS; i++) {
+    const r = round({ config: { side: 'heads' }, bet: 100, seed: { server: 'dist', client: 'c', nonce: i } });
+    if (r.outcome.landed === 'heads') heads++;
+  }
+  const exp = ROUNDS / 2;
+  const chi2 = (heads - exp) ** 2 / exp + ((ROUNDS - heads) - exp) ** 2 / exp;
+  const bound = 1 + 6 * Math.sqrt(2);         // df=1，6 sigma 上界
+  const ok = chi2 < bound;
+  if (!ok) { console.error(`  ✗ chi2=${chi2.toFixed(1)} 超过 ${bound.toFixed(1)}`); fails++; }
+  else console.log(`  ✓ chi2=${chi2.toFixed(2)}（正面 ${(heads / ROUNDS * 100).toFixed(2)}%）`);
+}
+
+console.log(fails === 0 ? '\n✅ 通过' : `\n❌ ${fails} 处问题`);
+process.exit(fails === 0 ? 0 : 1);

package/create-game/template/src/assets/manifest.ts

@@ -0,0 +1,30 @@
+/* 取资源清单。
+
+   生产环境下 manifest.json 是构建产物，和 index.js 同目录，用 import.meta.url 定位——
+   这样游戏文件夹放到 CDN 任意子目录都找得到。
+   开发和测试环境没有这个文件，从注册表现造一份。 */
+import type { GameManifest } from 'gamekit777/runtime';
+import { assets } from './registry.ts';
+import buildMeta from '../../game.meta.json' with { type: 'json' };
+
+const fallback = (): GameManifest => ({
+  id: buildMeta.id, version: buildMeta.version,
+  generatedAt: new Date().toISOString(),
+  entry: 'index.js', css: null, totalBytes: 0, criticalBytes: 0,
+  assets: assets.keys.map(key => ({
+    key, path: assets.url(key),
+    type: /\.(jpe?g|png|webp|avif|gif|svg)$/i.test(key) ? 'image' as const
+        : /\.(mp3|ogg|wav|m4a)$/i.test(key) ? 'audio' as const : 'binary' as const,
+    bytes: 1,
+    priority: key.startsWith('lazy/') ? 'lazy' as const : 'critical' as const
+  }))
+});
+
+export async function loadManifest(signal?: AbortSignal): Promise<GameManifest> {
+  if (!import.meta.url.includes('/dist/')) return fallback();
+  try {
+    const r = await fetch(new URL(/* @vite-ignore */ 'manifest.json', import.meta.url), { signal });
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    return await r.json() as GameManifest;
+  } catch { return fallback(); }
+}

package/create-game/template/src/assets/registry.ts

@@ -0,0 +1,23 @@
+/* 资源注册表。目录即优先级。?no-inline 是必须的——
+   lib 模式会无条件把资源 base64 内联进 JS，这个 query 是唯一逃生口。
+   这个游戏暂时没有资源文件，表是空的，但结构保持一致。 */
+const critical = import.meta.glob('./critical/**/*', {
+  eager: true, query: '?no-inline', import: 'default'
+}) as Record<string, string>;
+
+const lazy = import.meta.glob('./lazy/**/*', {
+  eager: true, query: '?no-inline', import: 'default'
+}) as Record<string, string>;
+
+const table: Record<string, string> = {};
+for (const [k, v] of Object.entries({ ...critical, ...lazy })) table[k.replace(/^\.\//, '')] = v;
+
+export const assets = {
+  url(key: string): string {
+    const u = table[key];
+    if (!u) throw new Error(`[assets] 未知资源: ${key}`);
+    return u;
+  },
+  keys: Object.keys(table),
+  all: table
+};

package/create-game/template/src/components/App.svelte.tmpl

@@ -0,0 +1,54 @@
+<script lang="ts">
+  /* 游戏的根组件。平台化之后它只有画面——
+     注额、押哪一面、音效、极速都是平台该渲染的 UI。
+
+     实例经 context 往下传，子组件一律 getInstance()，不 import 任何状态对象，
+     这样同页挂两个实例才不会互相污染。 */
+  import { setInstance, type Instance } from '../context.svelte.ts';
+  import { MULT } from '../rules/const.ts';
+
+  let { instance }: { instance: Instance } = $props();
+
+  /* 只取初始值是故意的：一个组件树对应一个实例，换实例应当整个重挂 */
+  // svelte-ignore state_referenced_locally
+  const inst = instance;
+  setInstance(inst);
+  const { game } = inst;
+
+  const label = (s: 'heads' | 'tails') => (s === 'heads' ? '正' : '反');
+</script>
+
+<div class="game" class:flash={game.phase === 'over' && game.last?.win}>
+  <p class="head">押 <b>{label(game.side)}</b> · 猜中赔 {MULT.toFixed(2)}×</p>
+
+  <div class="coin" class:spin={game.live} aria-live="polite">
+    <span>{label(game.face)}</span>
+  </div>
+
+  <p class="foot" class:win={game.last?.win}>
+    {#if game.phase === 'over' && game.last}
+      {game.last.win ? `猜中了，${MULT.toFixed(2)}× 到手` : '没猜中'}
+    {:else if game.live}
+      抛出中…
+    {:else}
+      在左边选一面，下注开始
+    {/if}
+  </p>
+</div>
+
+<style>
+  .game{position:relative;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:16px;
+    height:100%;min-height:240px;padding:28px;border-radius:16px;
+    background:var(--bg);color:var(--ink);font-family:var(--txt)}
+  .game.flash::after{content:"";position:absolute;inset:0;pointer-events:none;border-radius:16px;
+    background:var(--win);animation:flash var(--d-flash,500ms) ease-out forwards}
+  .head{margin:0;font-size:13px;color:var(--dim)}
+  .head b{color:var(--ink);font-size:16px}
+  .coin{display:grid;place-items:center;width:104px;height:104px;border-radius:50%;
+    background:var(--mark);color:#241A00;font-family:var(--num);font-size:38px;font-weight:700;
+    box-shadow:inset 0 -6px 0 rgba(0,0,0,.18)}
+  .coin.spin{animation:pulse 420ms ease-in-out infinite}
+  .foot{margin:0;min-height:1.5em;font-size:13px;color:var(--dim)}
+  .foot.win{color:var(--win);font-weight:700}
+  @media (prefers-reduced-motion:reduce){.coin.spin{animation:none}.game.flash::after{animation:none}}
+</style>

package/create-game/template/src/context.svelte.ts.tmpl

@@ -0,0 +1,22 @@
+import { getContext, setContext } from 'svelte';
+import type { Host } from 'gamekit777/sdk';
+import type { __PASCAL__Config } from './rules/types.ts';
+import { Game } from './state/game.svelte';
+
+const KEY = Symbol('__ID__');
+
+/** 一个游戏实例的全部状态。模块级不留任何可变状态，同页挂两个实例是安全的 */
+export interface Instance {
+  game: Game;
+  host: Host<__PASCAL__Config>;
+}
+
+export const createInstance = (host: Host<__PASCAL__Config>): Instance => ({ game: new Game(), host });
+
+/* 用 context 而不是模块级单例：组件一律 getInstance()，不 import 任何状态对象 */
+export const setInstance = (i: Instance): void => { setContext(KEY, i); };
+export const getInstance = (): Instance => {
+  const i = getContext<Instance>(KEY);
+  if (!i) throw new Error('[__ID__] 组件不在 <App> 之下，拿不到游戏实例');
+  return i;
+};

package/create-game/template/src/dev.ts

@@ -0,0 +1,8 @@
+/* 本地开发的宿主。index.html 指向它。
+
+   外壳来自 gamekit777/dev-host——一个**泛型**参考平台，驱动任何符合契约的游戏。
+   它不认识这个游戏：设置控件按 schema 渲染，赔率表来自清单的 paytable。 */
+import { runDevShell } from 'gamekit777/dev-host';
+import game from './index.ts';
+
+runDevShell(game);

package/create-game/template/src/index.ts.tmpl

@@ -0,0 +1,17 @@
+/* 游戏包的浏览器入口 = 清单 + view。平台加载这个文件：
+
+     import game from './dist/games/__ID__/index.js'
+     const inst = await game.mount(host, el)
+     await inst.present(result)
+
+   清单在根目录的 game.ts，Node 侧（采样、studio）import 的是它；这里只是把 mount 拼上去。 */
+import './styles/global.css';
+import './styles/animations.css';
+
+import game from '../game.ts';
+import { mountGame } from './view/mount.svelte.ts';
+
+export * from '../game.ts';
+export { mountGame as mount };
+
+export default { ...game, mount: mountGame };

package/create-game/template/src/rules/const.ts

@@ -0,0 +1,9 @@
+/* 规则常量。改动其中任何一个都会改变结果——已发布 mode 的结果不能改，要改就换 slug */
+
+/** 庄家优势。RTP = HOUSE_EDGE，赔率 = HOUSE_EDGE / 中奖概率 */
+export const HOUSE_EDGE = 0.98;
+/** 中奖概率：抛硬币就是一半 */
+export const WIN_CHANCE = 0.5;
+export const MULT = HOUSE_EDGE / WIN_CHANCE;
+/** 倍率 ×100 = payoutCenti。平台只存整数 payoutCenti，restore 按它反推 */
+export const PAYOUT_SCALE = 100;

package/create-game/template/src/rules/restore.ts.tmpl

@@ -0,0 +1,39 @@
+/* 表模型下的还原：把平台抽中的那一行变回一局可演出的结果。
+ *
+ * 抛硬币是最省的那一档——**不需要任何演出数据**。
+ * 猜中了硬币就落在你押的那面，猜错了就落在另一面，payout 已经把这件事说完了。
+ * 所以这张表只有两行，book 一个字节都不传（game.ts 里 book: 'none'）。
+ *
+ * 改成你自己的游戏时：
+ *   所有影响结果的字段都在 modes 里 → 删掉这个文件，game.ts 里不写 book 和 restore，
+ *     defineGame 会给你 restoreFromSeed（存种子重跑 round()，渲染代码一行不用改）
+ *   有字段改变这一局却不改变分布（像 coco 的 ranks）→ 自己写 book 编码和这里的解码
+ * 硬契约只有一条：返回的 payout 必须恰好等于 (bet / 100) × payoutCenti。对不上就抛错、不演出——
+ * 「玩家看到大奖动画，余额却没动」这类 bug 完全静默，最伤信任。studio 的表模型预览会替你验。 */
+import { normalizeBySchema, type Restore } from 'gamekit777/sdk';
+import { PAYOUT_SCALE } from './const.ts';
+import { schema } from './schema.ts';
+import type { __PASCAL__Config, __PASCAL__Outcome } from './types.ts';
+
+export const restore: Restore<__PASCAL__Config, __PASCAL__Outcome> = (input) => {
+  const { side } = normalizeBySchema(schema, input.config);
+  const win = input.payoutCenti > 0;
+  const mult = input.payoutCenti / PAYOUT_SCALE;
+
+  const outcome: __PASCAL__Outcome = {
+    side,
+    landed: win ? side : side === 'heads' ? 'tails' : 'heads',
+    win,
+    mult,
+  };
+
+  return {
+    bet: input.bet,
+    /* 必须和平台的 winCents 逐分相同。除法在前是故意的：
+       bet 保证能被 100 整除，先除再乘恒为精确整数 */
+    payout: (input.bet / PAYOUT_SCALE) * input.payoutCenti,
+    multiplier: mult,
+    outcome,
+    pacing: { durationMs: 900, postDelayMs: win ? 400 : 250 },
+  };
+};

package/create-game/template/src/rules/schema.ts.tmpl

@@ -0,0 +1,19 @@
+import type { ConfigSchema } from 'gamekit777/sdk';
+import type { __PASCAL__Config } from './types.ts';
+
+/* 平台按这份声明自动渲染设置控件，它不认识这个游戏。
+     affectsOutcome  影响结果 → 下注时冻结、随 RoundInput 上送、进 proof
+     lock            什么时候不许改
+     ui              谁渲染：'host' 平台的表单，'stage' 游戏画布内（仍然受控） */
+export const schema: ConfigSchema<__PASCAL__Config> = {
+  side: {
+    kind: 'enum',
+    options: [
+      {value: 'heads', label: {'zh-CN': '正面'}},
+      {value: 'tails', label: {'zh-CN': '反面'}}
+    ],
+    default: 'heads',
+    label: {'zh-CN': '押哪一面'},
+    affectsOutcome: true, lock: 'inRoundOrAuto', ui: 'host', control: 'select', order: 1
+  }
+};

package/create-game/template/src/rules/simulate.ts.tmpl

@@ -0,0 +1,9 @@
+/* 判定。纯函数：不碰 DOM、不碰时间、不碰全局状态、不自取随机数。 */
+import { MULT } from './const.ts';
+import type { __PASCAL__Config, __PASCAL__Outcome } from './types.ts';
+
+export function simulate(flip: number, c: __PASCAL__Config): __PASCAL__Outcome {
+  const landed = flip === 0 ? 'heads' : 'tails';
+  const win = landed === c.side;
+  return {side: c.side, landed, win, mult: win ? MULT : 0};
+}

package/create-game/template/src/rules/types.ts.tmpl

@@ -0,0 +1,13 @@
+/** 影响结果的参数。平台在下注这一刻冻结一份传进 round() */
+export interface __PASCAL__Config {
+  /** 押正面还是反面 */
+  side: 'heads' | 'tails';
+}
+
+/** 一局的完整结果快照。演出层只读它，不做任何判定 */
+export interface __PASCAL__Outcome {
+  side: 'heads' | 'tails';
+  landed: 'heads' | 'tails';
+  win: boolean;
+  mult: number;
+}