gamekit777 0.1.0

package/studio/src/game-vite.ts

@@ -0,0 +1,91 @@
+/* 对游戏目录起真 vite dev server。
+ *
+ * 游戏的 vite.config.ts 原样吃进来，一个字节不改；studio 的东西全部走 inline 合并。
+ * 这样预览走的就是 `bun run dev` 那条路——同一份 defineGameConfig、同一套 HMR，
+ * 不存在「studio 里演得好好的，真 build 出来不一样」的分叉空间。 */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createLogger, createServer, searchForWorkspaceRoot, type Logger, type ViteDevServer } from 'vite';
+import type { Engine } from './engine.ts';
+import { studioPlugin } from './studio-plugin.ts';
+
+export interface GameServerOptions {
+  gameDir: string;
+  studioRoot: string;
+  port: number;
+  /** 平台后端，/v1 反代到它。页面同源登录之后，发布用的就是浏览器里的这份身份 */
+  backendUrl: string;
+  engine: Engine;
+  /** stdio 模式下 stdout 是 MCP 协议，vite 的一切输出都得走 stderr */
+  quiet?: boolean;
+}
+
+/** 游戏入口。从 package.json 的 exports['.'] 读，没有就按脚手架的约定 */
+export function resolveGameEntry(gameDir: string): string {
+  const pkgPath = join(gameDir, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { exports?: Record<string, string> | string };
+  const entry = typeof pkg.exports === 'string' ? pkg.exports : pkg.exports?.['.'] ?? './src/index.ts';
+  const abs = resolve(gameDir, entry);
+  if (!existsSync(abs)) throw new Error(`游戏入口 ${abs} 不存在`);
+  return abs;
+}
+
+/**
+ * vite 的 fs.allow 检查的是 **realpath**，而且一旦显式给了这个字段，
+ * 默认的 workspace 根探测就整个失效——只放行 gameDir 和 studioRoot 是不够的：
+ * 预览壳 import 的 `gamekit777/dev-host` 在仓库内是符号链接，realpath 落在
+ * packages/dev-host，不在这两个目录下，直接 403。第一次跑就是这么白屏的。
+ *
+ * 所以两侧的 workspace 根都要进名单：仓库内它们是同一个（仓库根），
+ * 创作者机器上 gameDir 找不到 workspace 就返回自己，studio 那边返回 gamekit777 的包根。
+ */
+function allowList(o: GameServerOptions): string[] {
+  const list = new Set([
+    o.gameDir, searchForWorkspaceRoot(o.gameDir),
+    o.studioRoot, searchForWorkspaceRoot(o.studioRoot),
+  ]);
+  try { list.add(realpathSync(join(o.studioRoot, 'node_modules', 'gamekit777'))); } catch { /* 没装就算了 */ }
+  return [...list];
+}
+
+function stderrLogger(): Logger {
+  const base = createLogger('info', { allowClearScreen: false });
+  const w = (m: string): void => { process.stderr.write(`${m}\n`); };
+  return { ...base, info: w, warn: w, warnOnce: w, error: w, clearScreen: () => {} };
+}
+
+export async function startGameServer(o: GameServerOptions): Promise<ViteDevServer> {
+  const server = await createServer({
+    root: o.gameDir,
+    configFile: join(o.gameDir, 'vite.config.ts'),
+    customLogger: o.quiet ? stderrLogger() : undefined,
+    clearScreen: false,
+    plugins: [studioPlugin({
+      engine: o.engine,
+      gameEntry: resolveGameEntry(o.gameDir),
+      studioRoot: o.studioRoot,
+    })],
+    server: {
+      port: o.port,
+      strictPort: false,
+      host: '127.0.0.1',
+      /* 预览页嵌在 studio 页面的 iframe 里；同源，但照抄 apps/web 的做法放开——
+         sandbox 属性一加 Origin 就是 null，默认的 cors 会挡 */
+      cors: { origin: '*' },
+      fs: { allow: allowList(o) },
+      /* 同源代理到平台后端：cookie 才带得上。发布时用的就是这份身份 */
+      proxy: {
+        '/v1': { target: o.backendUrl, changeOrigin: false },
+        '/api': { target: o.backendUrl, changeOrigin: false },
+      },
+    },
+    /* 预览壳和游戏各自 import svelte，物理上可能是两份（studio 的和游戏的 node_modules）。
+       runes 跨实例静默失灵，没有任何报错——必须收敛成一份 */
+    resolve: { dedupe: ['svelte'] },
+    /* defineGameConfig 里也有这条；这里再写一遍是防创作者的 vite.config.ts 没用预设。
+       gamekit777 在 node_modules 里是真目录时会被 esbuild 预构建，*.svelte.ts 过不了 */
+    optimizeDeps: { exclude: ['gamekit777'] },
+  });
+  await server.listen();
+  return server;
+}

package/studio/src/game.ts

@@ -0,0 +1,173 @@
+/* 一个游戏目录在 studio 里的句柄。
+ *
+ * 持有的全是纯数据（快照、指纹）和一池 worker。想调游戏代码就发任务给池。
+ * 指纹变了池就重建——调用方不用关心缓存，每次 `pool()` 拿到的一定是当前代码。
+ *
+ * 游戏只有一份清单：<gameDir>/game.ts 默认导出 defineGame({...})。逻辑与发布信息都在里面。 */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { ConfigSchema, Paytable, RngSeed, RoundResult } from 'gamekit777/sdk';
+import { fingerprintOf, type Fingerprint } from './fingerprint.ts';
+import { WorkerPool } from './worker/pool.ts';
+
+export type Config = Record<string, unknown>;
+
+/** 清单里过得了 structured clone 的那部分。主进程只认识这个，不认识清单本身 */
+export interface SpecSnapshot {
+  slug: string; title: string; description?: string;
+  autoplay: boolean; rtp: number; sims: number; seedPrefix: string;
+  book: 'none' | 'seed' | 'custom';
+  modes: { name: string; config: Config }[];
+  /** 出现在 mode.config 里的键，即影响分布的字段。单表游戏为空 */
+  modeKeys: string[];
+}
+
+export interface Snapshot {
+  schema: ConfigSchema<Config>;
+  spec: SpecSnapshot;
+}
+
+export interface Normalized {
+  config: Config;
+  issues: { field: string; code: string }[];
+  /** null = 没有 mode 匹配这份配置——modes 声明不完整 */
+  mode: string | null;
+}
+
+function resolveSpecPath(gameDir: string): string {
+  const spec = join(gameDir, 'game.ts');
+  if (existsSync(spec)) return spec;
+  if (existsSync(join(gameDir, 'publish.ts')) || existsSync(join(gameDir, 'src', 'rules', 'index.ts'))) {
+    throw new Error(`${gameDir} 还是旧结构：publish.ts / src/rules/index.ts 已并入 game.ts。把 defineGame({...}) 放到 game.ts 并默认导出（参考 games/coin-flip/game.ts）`);
+  }
+  throw new Error(`${gameDir} 下找不到 game.ts（游戏清单：默认导出 defineGame({...})）`);
+}
+
+export class Game {
+  readonly dir: string;
+  readonly specPath: string;
+  #fp: Fingerprint;
+  #pool: WorkerPool | null = null;
+  #snapshot: Snapshot | null = null;
+
+  constructor(dir: string) {
+    this.dir = resolve(dir);
+    this.specPath = resolveSpecPath(this.dir);
+    this.#fp = fingerprintOf(this.dir);
+  }
+
+  get fingerprint(): string { return this.#fp.hash; }
+
+  get packageName(): string {
+    try { return (JSON.parse(readFileSync(join(this.dir, 'package.json'), 'utf8')) as { name?: string }).name ?? ''; }
+    catch { return ''; }
+  }
+
+  /** 重算指纹；变了就把池和快照都作废。每次外部调用前都该过一遍 */
+  refresh(): boolean {
+    const fp = fingerprintOf(this.dir);
+    if (fp.hash === this.#fp.hash) return false;
+    this.#fp = fp;
+    this.#snapshot = null;
+    const old = this.#pool;
+    this.#pool = null;
+    void old?.dispose();
+    return true;
+  }
+
+  async pool(): Promise<WorkerPool> {
+    this.refresh();
+    if (!this.#pool) {
+      this.#pool = new WorkerPool({ specPath: this.specPath });
+      await this.#pool.ready();
+    }
+    return this.#pool;
+  }
+
+  async snapshot(): Promise<Snapshot> {
+    this.refresh();
+    if (!this.#snapshot) this.#snapshot = await (await this.pool()).call<Snapshot>('snapshot', {});
+    return this.#snapshot;
+  }
+
+  async normalize(config: Partial<Config>, prev?: Config): Promise<Normalized> {
+    return (await this.pool()).call('normalize', { config, prev });
+  }
+
+  async paytable(config: Config): Promise<Paytable> {
+    return (await this.pool()).call('paytable', { config });
+  }
+
+  /** 每份配置该抽哪张表；null = 没有匹配的 mode */
+  async modeOf(configs: Config[]): Promise<(string | null)[]> {
+    return (await this.pool()).call('modeOf', { configs });
+  }
+
+  async round(config: Config, bet: number, seed: RngSeed, purity = false): Promise<RoundResult<unknown>> {
+    return (await this.pool()).call('round', { config, bet, seed, purity });
+  }
+
+  /** 表模型往返：重建第 simId 局 → book → restore。不需要先建表 */
+  async tableRoundtrip(modeIndex: number, simId: number, config: Config, bet: number): Promise<{
+    payoutCenti: number; frames: Uint8Array | null; seed: RngSeed; restored: RoundResult<unknown>;
+  }> {
+    return (await this.pool()).call('tableRoundtrip', { modeIndex, simId, config, bet });
+  }
+
+  /** 用现成的采样结果建表（在一个 worker 里跑 buildTable） */
+  async buildFromBatch(modeIndex: number, batch: { payoutCenti: Int32Array; books: Uint8Array[]; draws: number },
+    o: { declaredRtpPpm?: number; segments?: import('gamekit777/weights').Segment[] } = {}): Promise<import('gamekit777/publish').BuiltTable> {
+    let total = 0;
+    for (const b of batch.books) total += b.length;
+    const data = new Uint8Array(total);
+    const offsets = new Int32Array(batch.books.length + 1);
+    let at = 0;
+    for (let i = 0; i < batch.books.length; i++) { data.set(batch.books[i]!, at); at += batch.books[i]!.length; offsets[i + 1] = at; }
+    return (await this.pool()).call('buildFromBatch', {
+      modeIndex, payoutCenti: batch.payoutCenti, data, offsets, draws: batch.draws, ...o,
+    });
+  }
+
+  async restore(input: { config: Config; bet: number; payoutCenti: number; frames: Uint8Array | null; mode: string; seed: RngSeed }): Promise<RoundResult<unknown>> {
+    return (await this.pool()).call('restore', input);
+  }
+
+  /** 对任意配置多核采样，按序拼回。probe 用——不要求这份配置对应某个 mode */
+  async sample(config: Config, name: string, seedPrefix: string, sims: number): Promise<{ payoutCenti: Int32Array; draws: number }> {
+    const pool = await this.pool();
+    const parts = await pool.spread(sims, (w, from, to) =>
+      pool.call<{ payoutCenti: Int32Array; draws: number }>('sample', { config, name, seedPrefix, from, to }, w));
+    const out = new Int32Array(sims);
+    let at = 0, draws = 0;
+    for (const p of parts) { out.set(p.payoutCenti, at); at += p.payoutCenti.length; draws += p.draws; }
+    return { payoutCenti: out, draws };
+  }
+
+  /** 按清单里的 mode 采样，含 book 字节 */
+  async sampleSpec(modeIndex: number, sims: number): Promise<{ payoutCenti: Int32Array; books: Uint8Array[]; draws: number }> {
+    const pool = await this.pool();
+    type Part = { payoutCenti: Int32Array; data: Uint8Array; offsets: Int32Array; draws: number };
+    const parts = await pool.spread(sims, (w, from, to) => pool.call<Part>('sampleSpec', { modeIndex, from, to }, w));
+    const payoutCenti = new Int32Array(sims);
+    const books: Uint8Array[] = [];
+    let at = 0, draws = 0;
+    for (const p of parts) {
+      payoutCenti.set(p.payoutCenti, at); at += p.payoutCenti.length; draws += p.draws;
+      for (let i = 0; i + 1 < p.offsets.length; i++) books.push(p.data.subarray(p.offsets[i]!, p.offsets[i + 1]!));
+    }
+    return { payoutCenti, books, draws };
+  }
+
+  async pairedDiff(configA: Config, configB: Config, seedPrefix: string, count: number): Promise<{ changed: number; count: number }> {
+    return (await this.pool()).call('pairedDiff', { configA, configB, seedPrefix, count });
+  }
+
+  async betLinearity(config: Config, seedPrefix: string, indices: number[]): Promise<void> {
+    await (await this.pool()).call('betLinearity', { config, seedPrefix, indices });
+  }
+
+  async dispose(): Promise<void> {
+    await this.#pool?.dispose();
+    this.#pool = null;
+  }
+}

package/studio/src/jobs.ts

@@ -0,0 +1,59 @@
+/* 长任务：采样几十秒、建表几十秒、上传几分钟。
+ *
+ * MCP 的一次工具调用不该卡这么久，所以 >10s 的工具统一返回 jobId，
+ * 由 job_status 轮询。进度消息同时推给 SSE 总线，页面和 AI 看到的是同一份。 */
+
+export type JobStatus = 'running' | 'done' | 'failed' | 'cancelled';
+
+export interface Job<T = unknown> {
+  id: string;
+  kind: string;
+  status: JobStatus;
+  startedAt: number;
+  endedAt: number | null;
+  progress: string[];
+  result: T | null;
+  error: string | null;
+}
+
+export class Jobs {
+  #jobs = new Map<string, Job>();
+  #onProgress: (job: Job, msg: string) => void;
+
+  constructor(onProgress: (job: Job, msg: string) => void = () => {}) {
+    this.#onProgress = onProgress;
+  }
+
+  start<T>(kind: string, run: (say: (msg: string) => void) => Promise<T>): Job<T> {
+    const id = `${kind}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const job: Job<T> = { id, kind, status: 'running', startedAt: Date.now(), endedAt: null, progress: [], result: null, error: null };
+    this.#jobs.set(id, job as Job);
+
+    const say = (msg: string): void => {
+      job.progress.push(msg);
+      if (job.progress.length > 200) job.progress.shift();
+      this.#onProgress(job as Job, msg);
+    };
+    void run(say).then(
+      (r) => { job.status = 'done'; job.result = r; job.endedAt = Date.now(); this.#onProgress(job as Job, '完成'); },
+      (e: unknown) => { job.status = 'failed'; job.error = e instanceof Error ? e.message : String(e); job.endedAt = Date.now(); this.#onProgress(job as Job, `失败：${job.error}`); },
+    );
+    return job;
+  }
+
+  get(id: string): Job | undefined { return this.#jobs.get(id); }
+
+  list(): Job[] { return [...this.#jobs.values()].sort((a, b) => b.startedAt - a.startedAt); }
+
+  /** 等一个 job 结束。工具想同步拿结果时用 */
+  async wait<T>(id: string, timeoutMs = 600_000): Promise<Job<T>> {
+    const t0 = Date.now();
+    for (;;) {
+      const j = this.#jobs.get(id) as Job<T> | undefined;
+      if (!j) throw new Error(`没有 job ${id}`);
+      if (j.status !== 'running') return j;
+      if (Date.now() - t0 > timeoutMs) throw new Error(`job ${id} 超时`);
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+}