gamekit777 0.1.10 → 0.1.14

package/README.md

@@ -37,7 +37,7 @@ studio 同时是 MCP server、创作页面（预览 / 调参 / 建表 / Case /
 | import | 内容 |
 |---|---|
 | `gamekit777/sdk` | `defineGame`、契约类型、可证明公平的 RNG、SHA-256 / HMAC、加权抽样原语 |
-| `gamekit777/runtime` | 资源注册表（目录即清单）、平台侧预加载器、字体注入 |
+| `gamekit777/runtime` | 资源注册表（目录即清单）、平台侧预加载器、字体注入。游戏不直接 import，从 `gamekit777/svelte` 拿 |
 | `gamekit777/vite-config` | `defineGameConfig`：一个游戏的 `vite.config.ts` 只要三行 |
 | `gamekit777/dev-host` | 参考平台与本地表模型服务端；`createRemotePlatform` 接真平台 |
 | `gamekit777/protocol` · `client` | 平台 REST 契约（zod）与类型化客户端 |

package/client/index.ts

@@ -26,6 +26,9 @@ import {
   type RotateResult as TRotateResult, RotateResult,
   type RoundDetail as TRoundDetail, RoundDetail,
   type RoundPage as TRoundPage, RoundPage,
+  type RuntimeIndex as TRuntimeIndex, RuntimeIndex,
+  type RuntimeListing as TRuntimeListing, RuntimeListing,
+  type RuntimePackage, RUNTIME_INDEX_PATH, runtimeListPath,
   type SeedState as TSeedState, SeedState,
   type SessionView as TSessionView, SessionView,
   type UpdateGame,
@@ -182,6 +185,14 @@ export function createClient(opts: ClientOptions) {
       },
     },
 
+    /** 平台注入的运行时库（svelte、gamekit777/sdk）。只读：写入是平台方的 `bun run rt:push`，创作者只能查有没有 */
+    rt: {
+      index: (): Promise<TRuntimeIndex> =>
+        http.request({ method: 'GET', path: RUNTIME_INDEX_PATH, schema: RuntimeIndex }),
+      list: (pkg: RuntimePackage, version: string): Promise<TRuntimeListing> =>
+        http.request({ method: 'GET', path: runtimeListPath(pkg, version), schema: RuntimeListing }),
+    },
+
     /** studio 配对：站点签 code，studio 拿 code 换一个同一用户的会话（cookie 落在 studio 的 origin） */
     pair: {
       start: (): Promise<TPairStartResult> =>
@@ -197,6 +208,9 @@ export function createClient(opts: ClientOptions) {
         http.request({ method: 'PATCH', path: `/v1/games/${id}`, json: body, schema: Game }),
       publish: (id: string, body: PublishGame): Promise<TGame> =>
         http.request({ method: 'POST', path: `/v1/games/${id}/publish`, json: body, schema: Game }),
+      /** 试玩游戏只传包不传表，有包就能发（docs/demo.md） */
+      publishDemo: (id: string): Promise<TGame> =>
+        http.request({ method: 'POST', path: `/v1/games/${id}/publish-demo`, json: {}, schema: Game }),
       list: (query: Partial<ListGamesQuery> = {}): Promise<TGamePage> =>
         http.request({ method: 'GET', path: '/v1/games', query, schema: GamePage }),
       /** 详情比列表多一份已生效的 mode 清单——对局页要靠它知道有哪几张表可选 */

package/create-game/scaffold.ts

@@ -75,7 +75,7 @@ const STANDALONE_TSCONFIG = {
     target: 'ES2022', lib: ['ES2022', 'DOM', 'DOM.Iterable'], module: 'ESNext', moduleResolution: 'bundler',
     strict: true, noUnusedLocals: true, noUnusedParameters: true, noImplicitOverride: true, noFallthroughCasesInSwitch: true,
     noEmit: true, isolatedModules: true, verbatimModuleSyntax: true, skipLibCheck: true, forceConsistentCasingInFileNames: true,
-    allowImportingTsExtensions: true, types: [],
+    allowImportingTsExtensions: true, types: ['vite/client'],
   },
   include: ['game.ts', 'src', 'scripts', 'test'],
 };
@@ -127,9 +127,8 @@ export function scaffoldGame(o: ScaffoldOptions): ScaffoldResult {
       out = `${JSON.stringify(STANDALONE_TSCONFIG, null, 2)}\n`;
     }
     writeFileSync(file, out);
-    // overlay 里带 .tmpl 后缀，免得脚手架自己的 lint / 构建去处理它们；
     // .gitignore 叫 _gitignore，因为 npm 打包会把包里的 .gitignore 改名或丢掉
-    let final = file.endsWith('.tmpl') ? file.slice(0, -5) : file;
+    let final = file;
     if (final.endsWith('/_gitignore')) final = `${final.slice(0, -'_gitignore'.length)}.gitignore`;
     if (final !== file) renameSync(file, final);
     files.push(final);

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

@@ -1,9 +1,9 @@
 {
   "id": "coin-flip",
   "title": "抛硬币",
-  "gameId": "95d28dcf-fe8f-45f0-a03b-f68523efd865",
   "version": "1.0.0",
   "aspect": "16:9",
   "orientation": "any",
-  "fonts": []
+  "fonts": [],
+  "gameId": "80c89eb8-d5ad-45b9-be5d-f2696fcf6edb"
 }

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

@@ -1,63 +1,52 @@
-/* 抛硬币的清单。只依赖 gamekit777/sdk 和自己的 rules/，Node 和浏览器都能 import：
-   打包流水线用它采样、studio 用它探测和建表、浏览器入口把它和 mount 拼在一起。
+/* 抛硬币的清单。纯清单对象，只有类型导入，Node 和浏览器都能 import：
+   打包流水线用它采样、studio 用它探测和建表、构建预设把它和 view 拼成浏览器入口。
 
    这个游戏同时是脚手架的底：`gamekit777 new` 把整个目录复制出去再换名字。
    改成你自己的游戏时，先用 studio 的 probe_table 看看：
      哪些字段改变赔付分布 → 写进 modes（一张表 = 一种分布），只写那几个字段
      哪些字段只改变这一局 → 保持自由，用 book 编码演出（参考 coco 的 book.ts）
-     赔付必须是 centi 精度、必须是注额的线性函数——这两条 probe 会替你查
    逻辑侧三个必填：schema 说有哪些参数，round 说结果怎么算，paytable 说赔多少。
-   normalize / validate / modeOf 不用写——它们由 schema 和 modes 推导。
+   演出侧两个：settings 是只影响演出的设置（平台渲染、游戏只读），view 惰性指向演出模块——
+   惰性是为了让 Node 侧 import 这份清单时永远不碰 Svelte 与 DOM。
+   normalize / validate / modeOf / 钱 都不用写：加载方 defineGame 时由 schema 和 modes 推导；
+   round 收到的 config 已填满、rng 已播好，只回 { outcome, mult }，payout = bet/100 × round(mult×100) 由框架算。
 
    两面对称，只有一种赔付分布，所以一张表就够。`side` 不改变分布，只改变某一局落在哪面——
-   服务端不需要知道它，玩家运行时自由选。book 因此可以完全不传：payout > 0 就说明
+   服务端不需要知道它，玩家运行时自由选。book 因此可以完全不传：赔了钱就说明
    硬币落在你押的那面（见 rules/restore.ts）。
 
    纯度由 scripts/verify.ts 的运行时桩保证：把 Math.random 和 crypto 换成会抛的假实现
    再调 round()，查的是实际执行路径含全部传递依赖。 */
-import { createRng, defineGame, normalizeBySchema, type RoundInput, type RoundResult } from 'gamekit777/sdk';
+import type { GameManifest, RoundInput, RoundReturn } from 'gamekit777/svelte';
 import meta from './game.meta.json' with { type: 'json' };
 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 { CoinFlipConfig, CoinFlipOutcome } from './src/rules/types.ts';
-
-export { schema, simulate, restore };
-export * from './src/rules/types.ts';
+import { settings } from './src/rules/settings.ts';
+import type { CoinFlip } from './src/rules/types.ts';
 
 /**
- * 一局的结果。同步纯函数：同样的 (config, bet, seed) 恒得同样的 payout。
- *
+ * 一局的判定。同步纯函数：同样的 (config, seed) 恒得同样的结果。
  * 随机数的抽取顺序是契约的一部分：flip 子流 below(2) 一次。
  * 已发布 mode 的这段逻辑不能改——历史局的 book 要靠它解；要改就换 slug。
  */
-export function round(input: RoundInput<CoinFlipConfig>): RoundResult<CoinFlipOutcome> {
-  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 },
-  };
+function round({ config, rng }: RoundInput<CoinFlip>): RoundReturn<CoinFlip> {
+  const landed = rng.fork('flip').below(2) === 0 ? 'heads' : 'tails';
+  const win = landed === config.side;
+  return { outcome: { side: config.side, landed, win }, mult: win ? MULT : 0 };
 }
 
-export default defineGame<CoinFlipConfig, CoinFlipOutcome>({
-  // 名字只在 game.meta.json 里改：slug 同时是大厅里的 id、产物目录名和 CSS 命名空间
-  slug: meta.id,
-  title: meta.title,
+export default {
+  // 名字只在 game.meta.json 里改：id 同时是大厅里的 slug、产物目录名和 CSS 命名空间
+  meta,
   description: '押正面还是反面。猜中赔 1.96 倍，RTP 98%。',
   rtp: HOUSE_EDGE,
   sims: 100_000,
   schema,
+  settings,
   round,
-  paytable: [{ label: { 'zh-CN': '猜中' }, mult: MULT }],
+  paytable: [{ label: { 'zh-CN': '猜中', en: 'Hit' }, mult: MULT }],
   book: 'none',
   restore,
-});
+  view: () => import('./src/index.ts'),
+} satisfies GameManifest<CoinFlip>;

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

@@ -3,9 +3,6 @@
   "private": true,
   "version": "1.0.0",
   "type": "module",
-  "exports": {
-    ".": "./src/index.ts"
-  },
   "scripts": {
     "dev": "GAMEKIT_BASE_URL=http://127.0.0.1:8787 GAMEKIT_SITE_URL=http://localhost:5180 gamekit777 studio --no-mcp",
     "build": "svelte-check --tsconfig ./tsconfig.json && vite build",
@@ -21,7 +18,7 @@
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
     "@tsconfig/svelte": "^5.0.5",
     "happy-dom": "^20.14.5",
-    "svelte": "^5.42.2",
+    "svelte": "5.57.1",
     "svelte-check": "^4.3.3",
     "typescript": "^5.9.3",
     "vite": "^7.1.5",

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

@@ -6,7 +6,13 @@
      RTP    实际期望要对得上清单的 rtp
      分布   随机源本身是否无偏 */
 import { MULT, WIN_CHANCE } from '../src/rules/const.ts';
-import game, { round } from '../game.ts';
+import manifest from '../game.ts';
+import { defineGame } from 'gamekit777/sdk';
+/* scripts/ 在 Node 里跑，是唯一直接用 gamekit777/sdk 的地方：清单要经 defineGame 才有包好 rng 与 normalize 的 round */
+const game = defineGame(manifest);
+
+/* round 从 definition 上取：包过一层，config 填满、rng 播好、结果带 seed */
+const { round } = game;
 
 const ROUNDS = Number(process.argv[2] ?? 200_000);
 let fails = 0;

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

@@ -1,51 +1,35 @@
 <script lang="ts">
   /* 游戏的根组件。平台化之后它只有画面——
      注额、押哪一面、音效、极速都是平台该渲染的 UI。
+     抛出中硬币一鼓一缩是循环表的 spin（src/effects.ts），挂在 .coin 上、在演时播；不写 CSS animation，减弱动效时框架自己停。
 
-     实例经 context 往下传，子组件一律 getInstance()，不 import 任何状态对象，
-     这样同页挂两个实例才不会互相污染。 */
-  import { setInstance, type Instance } from '../context.svelte.ts';
+     实例经 context 往下传（gamekit777/svelte 的 composeGame 设好），子组件一律 useGame()，
+     不 import 任何状态对象，这样同页挂两个实例才不会互相污染。
+     赢面牌子这类内置效果画在框架的覆盖层上（容器末尾，盖在画面之上），这里不用放任何东西。 */
+  import { useGame } from '../use-game.ts';
   import { MULT } from '../rules/const.ts';
 
-  let { instance }: { instance: Instance } = $props();
+  const { game, t } = useGame();
 
-  /* 只取初始值是故意的：一个组件树对应一个实例，换实例应当整个重挂 */
-  // svelte-ignore state_referenced_locally
-  const inst = instance;
-  setInstance(inst);
-  const { game } = inst;
-
-  const label = (s: 'heads' | 'tails') => (s === 'heads' ? '正' : '反');
-  const money = (minor: number) => (minor / 100).toFixed(2);
+  const label = (s: 'heads' | 'tails') => t(`side.${s}`);
 </script>
 
 <div class="game">
-  <p class="head">押 <b>{label(game.side)}</b> · 猜中赔 {MULT.toFixed(2)}×</p>
+  <p class="head">{@html t('head', { side: `<b>${label(game.config.side)}</b>`, mult: MULT.toFixed(2) })}</p>
 
-  <div class="coin" class:spin={game.live} aria-live="polite">
-    <span>{label(game.face)}</span>
+  <div class="coin" {@attach game.loops.spin.when(game.rounds.live)} aria-live="polite">
+    <span>{label(game.state.face)}</span>
   </div>
 
-  <p class="foot" class:win={game.last?.win} class:lose={game.last && !game.last.win}>
-    {#if game.phase === 'over' && game.last}
-      {game.last.win ? '猜中了' : '没猜中'}
-    {:else if game.live}
-      抛出中…
-    {:else if game.layout === 'mobile'}
-      在参数里选一面，下注开始
+  <p class="foot" class:win={game.state.last?.win} class:lose={game.state.last && !game.state.last.win}>
+    {#if game.rounds.phase === 'settled' && game.state.last}
+      {game.state.last.win ? t('hit') : t('miss')}
+    {:else if game.rounds.live}
+      {t('flipping')}
     {:else}
-      在左边选一面，下注开始
+      {t(game.stage.layout === 'mobile' ? 'hint.mobile' : 'hint.desktop')}
     {/if}
   </p>
-
-  <!-- 赢了弹一下就走：不遮画面、不用点。key 到局号，连赢两局是两次弹出而不是一次拉长 -->
-  {#if game.toast}
-    {#key game.toast.id}
-      <div class="toast" style:animation-duration="{game.toast.ms}ms" aria-hidden="true">
-        <b>{game.toast.mult.toFixed(2)}×</b><span>+{money(game.toast.payout)}</span>
-      </div>
-    {/key}
-  {/if}
 </div>
 
 <style>
@@ -57,21 +41,11 @@
     padding:calc(28px + var(--gk-safe-top,0px)) calc(28px + var(--gk-safe-right,0px)) calc(28px + var(--gk-safe-bottom,0px)) calc(28px + var(--gk-safe-left,0px));
     background:var(--bg);color:var(--ink);font-family:var(--txt)}
   .head{margin:0;font-size:13px;color:var(--dim)}
-  .head b{color:var(--ink);font-size:16px}
+  .head :global(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}
   .foot.lose{color:var(--lose)}
-
-  .toast{position:absolute;left:50%;top:calc(var(--gk-safe-top,0px) + 22%);transform:translate(-50%,0);pointer-events:none;
-    display:flex;align-items:baseline;gap:10px;padding:10px 22px 12px;border-radius:18px;
-    background:var(--panel);color:var(--ink);box-shadow:0 0 0 3px var(--win),0 10px 30px rgba(0,0,0,.45);
-    animation:toast 1400ms ease-out forwards}
-  .toast b{font-family:var(--num);font-size:34px;line-height:1;color:var(--win)}
-  .toast span{font-family:var(--num);font-size:16px;color:var(--ink)}
-
-  @media (prefers-reduced-motion:reduce){.coin.spin{animation:none}.toast{animation-name:toastStill}}
 </style>

package/create-game/template/base/src/effects.ts

@@ -0,0 +1,21 @@
+/* 效果表与循环表。翻动音是过程效果；输赢音与赢面牌子标 always，快进后也要听到、看到。
+   动画不要用 JS 逐帧驱动（跨源 iframe 里 iOS 会把 rAF 限到 30fps），都交给 WAAPI：
+     发生一次的（弹一下、翻开、飞过去）→ 效果表里的 effect.keyframes，位置演出时才知道就把 frames 写成 payload 的函数；
+     处在某个状态期间一直循环的（呼吸、旋转、闪烁）→ 循环表 defineLoops，模板里 {@attach game.loops.x.when(条件)}；
+     只有数字读数、必须进 state 的量才用 ctx.tween。
+   改成你自己的游戏时：哪些东西该进哪张表、always 怎么定，见 node_modules/gamekit777/docs/view.md「先分清三类东西」。 */
+import { sound, effect, defineEffects, defineLoops } from 'gamekit777/svelte';
+import { T } from './tempo.ts';
+
+export const effects = defineEffects({
+  flip: effect.sound(sound.tone({ f: 880, dur: 0.05, type: 'triangle', gain: 0.08 })),
+  win: effect.sound(sound.chord({ notes: [659, 784, 988], step: 0.08, dur: 0.28, gain: 0.12 }), { always: true }),
+  lose: effect.sound(sound.tone({ f: 220, dur: 0.18, type: 'sine', gain: 0.1, slide: 140 }), { always: true }),
+  /** 赢了弹一下就走。tier 0 只有牌子，不遮画面、不用点；自动模式连赢也只是连弹两次 */
+  plate: effect.builtin('big-win', { always: true, ms: T.linger }),
+});
+
+export const loops = defineLoops({
+  /** 抛出中：硬币一鼓一缩（App 里 {@attach game.loops.spin.when(game.rounds.live)}） */
+  spin: { ms: 420, easing: 'ease-in-out', frames: [{ transform: 'scale(1)' }, { transform: 'scale(1.1)', offset: 0.5 }, { transform: 'scale(1)' }] },
+});

package/create-game/template/base/src/game.svelte.ts

@@ -0,0 +1,24 @@
+/* 游戏类。平台的投影（config / settings / run / stage）、phase / rid / skip、status 派生、作废，全在基类里；
+   画面上是什么在 game.state（形状在 rules/types.ts，初值是这里的 initial，编排写、模板直接读）。这里只剩静态声明。
+   改成你自己的游戏时，类上只放三样：声明（静态字段、锚点把手）；编排和组件都要用的派生与改 state 的方法；玩家在画布上的选择与交互。
+   state / config / settings 的字段不要在这里再包一层 getter（模板直接写 game.state.face、game.config.side）；只有组件用的尺寸、颜色、格式化写在组件里。
+   做成可实例化的类而不是模块级单例：同页挂两个实例时各自一套状态。 */
+import { RoundGame } from 'gamekit777/svelte';
+import type { CoinFlip, CoinFlipState } from './rules/types.ts';
+import { effects, loops } from './effects.ts';
+import App from './components/App.svelte';
+import { presenter } from './present.ts';
+
+export class Game extends RoundGame<CoinFlip, typeof effects, typeof loops> {
+  /* 效果表与循环表交给基类：写成静态字段，不用写构造函数（框架每次 mount new 一个） */
+  static override App = App;
+  static override presenter = presenter;
+  static override effects = effects;
+  static override loops = loops;
+
+  /** 挂载时的画面：正面朝上、没有上一局 */
+  static override initial(): CoinFlipState { return { face: 'heads', last: null }; }
+
+  /* 收掉上一局（换了押的面、作废）：结果不作数了，硬币停在哪面还是哪面 */
+  protected override onReset(): void { this.state.last = null; }
+}

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

@@ -1,19 +1,5 @@
-/* 游戏包的浏览器入口 = 清单 + view。平台加载这个文件：
-
-     import game from '/g/<gameId>/<bundleHash>/index.js'   // 平台从 R2 流出的包
-     const inst = await game.mount(host, el)
-     await inst.present(result)
-
-   清单在根目录的 game.ts，Node 侧（采样、studio）import 的是它；这里只是把 mount 拼上去。
-   assets 是 src/assets/ 目录的清单（runtime 按目录生成），平台在 mount 之前按它预加载、画进度条——游戏自己不加载。 */
+/* 演出模块：game.ts 的 view 惰性指向这里，浏览器入口由构建预设生成、经 gamekit777/svelte 的 composeGame 挂起来。
+   一个游戏在演出侧只声明一个类（game.svelte.ts）：App、演出把手、效果表、循环表都是它的静态字段。
+   这个文件 import 了样式、间接 import 了 Svelte 组件，Node 侧永远不会执行它。 */
 import './styles/global.css';
-import './styles/animations.css';
-
-import { assets } from 'gamekit777/runtime';
-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, assets: assets.bundle() };
+export { Game as default } from './game.svelte.ts';

package/create-game/template/base/src/locales/en.json

@@ -0,0 +1,10 @@
+{
+  "side.heads": "Heads",
+  "side.tails": "Tails",
+  "head": "Bet {side} · pays {mult}×",
+  "hit": "You called it",
+  "miss": "Missed",
+  "flipping": "Flipping…",
+  "hint.mobile": "Pick a side in settings, then bet",
+  "hint.desktop": "Pick a side on the left, then bet"
+}

package/create-game/template/base/src/locales/zh-CN.json

@@ -0,0 +1,10 @@
+{
+  "side.heads": "正",
+  "side.tails": "反",
+  "head": "押 {side} · 猜中赔 {mult}×",
+  "hit": "猜中了",
+  "miss": "没猜中",
+  "flipping": "抛出中…",
+  "hint.mobile": "在参数里选一面，下注开始",
+  "hint.desktop": "在左边选一面，下注开始"
+}

package/create-game/template/base/src/present.ts

@@ -0,0 +1,37 @@
+/* 演出：把已经算好的结果播出来。
+
+   判定一行都不在这里——outcome 是传进来的；极速、减弱动效由框架施加在演出上，改不了结果，
+   因为它们根本不在 round() 的入参里。
+   run 是生成器：yield 出去的是「要等什么」，什么时候接着跑由框架定——快进、直接看结果、减弱动效时不等，局被作废时不再往下跑。
+   只写 g.state 和发效果。翻动中途的那一面也写在 state 里，演完一定落在开出的那面：正常演、快进、直接看结果，最后的 state 一样（一致性套件验）。
+   节拍是 tempo.ts 里的常数，这里不看 turbo / reducedMotion。
+   装饰性随机只能来自 ctx.rand（按这一局的种子播种，回放一模一样）；这个游戏暂时没用到。 */
+import { definePresent } from 'gamekit777/svelte';
+import type { CoinFlip } from './rules/types.ts';
+import { T } from './tempo.ts';
+
+const money = (minor: number): string => (minor / 100).toFixed(2);
+
+/* 翻动几下再定格。次数只是节奏（总时长 / 翻一下多久），不占用可复现的随机数 */
+const STEPS = Math.max(2, Math.round(T.total / T.flip));
+
+export const presenter = definePresent<CoinFlip>({
+  *run(ctx, g, r) {
+    const o = r.outcome;
+    /* 翻面是离散的几下（每 90ms 换一次字），不是逐帧驱动的动画；硬币一鼓一缩是循环表的 spin（WAAPI） */
+    for (let i = 0; i < STEPS; i++) {
+      g.state.face = i % 2 === 0 ? 'tails' : 'heads';
+      ctx.fx.flip();
+      yield ctx.delay(T.total / STEPS);
+    }
+    g.state.face = o.landed;
+    g.state.last = o;
+  },
+  settle(ctx, g, r) {
+    const o = r.outcome;
+    (o.win ? ctx.fx.win : ctx.fx.lose)();
+    /* 牌子是余韵，present 不等它——弹窗不该拖慢下一注（自动模式尤其）；停多久写在效果表里，下一局开始时框架会清掉 */
+    /* 游戏自己声明的设置在 g.settings 里（和平台内置的 sound / locale 合在一起） */
+    if (o.win && g.settings.toast) ctx.fx.plate({ tier: 0, mult: `${r.multiplier.toFixed(2)}×`, amount: `+${money(r.payout)}` });
+  },
+});

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

@@ -1,41 +1,25 @@
-/* 表模型下的还原：把平台抽中的那一行变回一局可演出的结果。
+/* 表模型下的还原：把平台抽中的那一行变回一局的结果快照。
  *
  * coin-flip 是最省的那一档——**不需要任何演出数据**。
- * 猜中了硬币就落在你押的那面，猜错了就落在另一面，payout 已经把这件事说完了。
+ * 猜中了硬币就落在你押的那面，猜错了就落在另一面，赔付已经把这件事说完了。
  * 所以这张表只有两行，book 一个字节都不传。
  *
  * 押哪一面（side）因此可以保持玩家自由选：它不改变赔付分布，服务端也不需要知道。
  *
  * 改成你自己的游戏时：
  *   所有影响结果的字段都在 modes 里 → 删掉这个文件，game.ts 里不写 book 和 restore，
- *     defineGame 会给你 restoreFromSeed（存种子重跑 round()，渲染代码一行不用改）
+ *     框架会给你 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 { CoinFlipConfig, CoinFlipOutcome } from './types.ts';
+ * 只返回 { outcome, mult }：钱由框架按 payoutCenti 算，还原出的 mult 和表里那一行对不上框架会抛错不演。 */
+import type { Restore } from 'gamekit777/svelte';
+import { MULT } from './const.ts';
+import type { CoinFlip } from './types.ts';
 
-export const restore: Restore<CoinFlipConfig, CoinFlipOutcome> = (input) => {
-  const { side } = normalizeBySchema(schema, input.config);
+export const restore: Restore<CoinFlip> = (input) => {
+  const { side } = input.config;
   const win = input.payoutCenti > 0;
-  const mult = input.payoutCenti / PAYOUT_SCALE;
-
-  const outcome: CoinFlipOutcome = {
-    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 },
+    outcome: { side, landed: win ? side : side === 'heads' ? 'tails' : 'heads', win },
+    mult: win ? MULT : 0,
   };
 };

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

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

package/create-game/template/base/src/rules/settings.ts

@@ -0,0 +1,6 @@
+import type { SettingsSchema } from 'gamekit777/svelte';
+
+/** 只影响演出的设置。平台渲染控件并存值，游戏从 host.settings 读；键不许撞平台内置的 sound / turbo 那些 */
+export const settings = {
+  toast: { kind: 'bool', default: true, label: { 'zh-CN': '赢面弹窗', en: 'Win toast' }, control: 'switch', order: 1 },
+} as const satisfies SettingsSchema;

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

@@ -1,13 +1,27 @@
-/** 影响结果的参数。平台在下注这一刻冻结一份传进 round() */
-export interface CoinFlipConfig {
-  /** 押正面还是反面 */
-  side: 'heads' | 'tails';
-}
+/* 一个接口描述整个游戏。config 与 settings 从 schema 声明反推，outcome 是 round 算出来的东西、只能声明，
+   state 是画面上是什么（game.state：编排写、模板读），game 是演出侧的游戏类（只是类型引用，Node 里不会加载它）。清单、round、游戏类、视图、实例都只写 CoinFlip 这一个名字。 */
+import type { InferConfig, InferSettings } from 'gamekit777/svelte';
+import type { schema } from './schema.ts';
+import type { settings } from './settings.ts';
+import type { Game } from '../game.svelte.ts';
 
 /** 一局的完整结果快照。演出层只读它，不做任何判定 */
 export interface CoinFlipOutcome {
   side: 'heads' | 'tails';
   landed: 'heads' | 'tails';
   win: boolean;
-  mult: number;
+}
+
+/** 画面上是什么（game.state）：硬币朝上的那一面（翻动中也在变）、最近一局的结果 */
+export interface CoinFlipState {
+  face: 'heads' | 'tails';
+  last: CoinFlipOutcome | null;
+}
+
+export interface CoinFlip {
+  config: InferConfig<typeof schema>;
+  outcome: CoinFlipOutcome;
+  settings: InferSettings<typeof settings>;
+  state: CoinFlipState;
+  game: Game;
 }

package/create-game/template/base/src/styles/global.css

@@ -1,14 +1,16 @@
 /* 游戏自己的设计变量和 reset。
 
    构建时 @gamekit/vite-config 的 namespace-css 插件会把这里的 :root / html / body
-   收敛到游戏根元素 .gk-<id>，@keyframes 也会改名。原因是同页可能挂着两个游戏，
-   而 @keyframes 是全局命名空间、后定义覆盖先定义——撞名不报错，只是动画播成别人的。
+   收敛到游戏根元素 .gk-<id>：同页可能挂着两个游戏，变量不能互相覆盖。
+   这里不写 @keyframes（构建直接报错）：一次性的动画进效果表 effect.keyframes，循环的进 defineLoops。
 
    页面外框（body 的底色、外边距）不放这里：那是平台的地盘。 */
 :root{
   --bg:#0E1116; --panel:#161B23; --line:#232B36;
   --ink:#E8EDF4; --dim:#8A97A8;
   --win:#31D07A; --lose:#F0554A; --mark:#FFC93C;
+  /* 内置的大奖牌读这几个：覆盖层在 .game 之外，所以写在这里 */
+  --gold:var(--win); --gold-d:#1a6b40; --cream:var(--ink);
   --num:ui-monospace,SFMono-Regular,Menlo,monospace;
   --txt:system-ui,-apple-system,"Noto Sans SC",sans-serif;
 }

package/create-game/template/base/src/tempo.ts

@@ -0,0 +1,4 @@
+/* 节拍（毫秒）：效果表的时长和演出的时间线都读这一份，两边的数字对得上。
+   只写一套：极速、减弱动效由框架统一处理（极速时这一局的等待与效果按平台给的倍率加速，减弱动效时每一段直接落到终态），游戏不读 turbo、不判 reducedMotion。
+   flip：翻一下多久；total：翻动多久再定格；linger：赢面牌子停多久 */
+export const T = { flip: 90, total: 800, linger: 1600 } as const;

package/create-game/template/base/src/use-game.ts

@@ -0,0 +1,5 @@
+import { useGame as useGameOf, type Instance } from 'gamekit777/svelte';
+import type { CoinFlip } from './rules/types.ts';
+
+/** 组件里一律用它取实例，不 import 任何状态对象：同页两个实例才不会互相污染。框架的 useGame 是泛型的，这里钉上类型 */
+export const useGame: () => Instance<CoinFlip> = useGameOf;

package/create-game/template/base/test/conformance.test.ts

@@ -0,0 +1,11 @@
+/* 演出层的一致性：终态、快进、作废、可复现、无残留、双实例、不碰钱。脚手架必带，bun run test 强制跑 */
+import { test } from 'vitest';
+import { composeGame } from 'gamekit777/svelte';
+import { conformanceCases } from 'gamekit777/svelte/test';
+import { EMPTY_ASSETS } from 'gamekit777/svelte/test';
+import def from '../game.ts';
+import zhCN from '../src/locales/zh-CN.json' with { type: 'json' };
+import en from '../src/locales/en.json' with { type: 'json' };
+
+const game = composeGame(def, { assets: EMPTY_ASSETS.bundle(), locales: { 'zh-CN': zhCN, en } });
+for (const c of conformanceCases(game)) test(c.name, c.run);