@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/threejs/skills/playable-focus/scripts/generate-focus-reports.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Generate focus validate report stubs from sweep manifest + catalog.
+ * Usage: node scripts/generate-focus-reports.mjs <manifest.json>
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+function findComposite(catalog, specId) {
+  return catalog.composites.find((c) => c.primitives.includes(specId));
+}
+
+function reportBody(entry, catalog, manifest) {
+  const spec = catalog.specs.find((s) => s.id === entry.specId);
+  const typeMeta = spec ? catalog.renderTypes[spec.renderType] : null;
+  const composite = entry.specId ? findComposite(catalog, entry.specId) : null;
+  const dims = typeMeta?.validateDimensions || ['合成', '层叠', '时序'];
+
+  return `# Focus Validate — ${entry.id}
+
+| 字段 | 值 |
+|------|-----|
+| **Playground id** | \`${entry.id}\` |
+| **Sweep phase** | ${manifest.phase} |
+| **Render type** | ${entry.renderType} |
+| **Spec** | ${entry.specId || '—'} |
+| **Composite** | ${composite ? composite.id : '—'} |
+| **录屏** | \`${entry.mp4 || '(fail)'}\` |
+| **抽帧** | \`${entry.framesDir || '—'}\` |
+| **基线** | test11 |
+
+## Validate dimensions
+
+${dims.map((d) => `- [ ] ${d}`).join('\n')}
+
+## L exit
+
+| 级别 | 项 | 结论 |
+|------|-----|------|
+| P0 | | |
+| P1 | | |
+| P2 | | |
+
+**相对 test11**: 改善 / 仍存 / 回归 / N/A
+
+## 备注
+
+_(Agent 看视频后填写)_
+`;
+}
+
+async function sweepSummary(manifest, catalog) {
+  const lines = [
+    `# Sweep 汇总 — ${manifest.phase}`,
+    '',
+    `| 字段 | 值 |`,
+    `|------|-----|`,
+    `| **时间** | ${manifest.timestamp} |`,
+    `| **目录** | \`${manifest.sweepDir}\` |`,
+    `| **成功** | ${manifest.summary.ok}/${manifest.summary.total} |`,
+    '',
+    '## 矩阵',
+    '',
+    '| id | status | mp4 | P0 |',
+    '|----|--------|-----|-----|'
+  ];
+
+  for (const e of manifest.entries) {
+    lines.push(`| ${e.id} | ${e.status} | ${e.mp4 || '—'} | |`);
+  }
+
+  lines.push('', '## Composite 覆盖', '');
+  for (const c of catalog.composites) {
+    const covered = c.primitives.map((p) => {
+      const id = `clean:${catalog.specs.find((s) => s.id === p)?.renderType}:${p}`;
+      const ent = manifest.entries.find((e) => e.id === id);
+      return ent?.status === 'ok' ? p : `${p}(missing)`;
+    });
+    lines.push(`- **${c.id}**: ${covered.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+async function main() {
+  const manifestPath = process.argv[2];
+  if (!manifestPath) {
+    console.error('Usage: node scripts/generate-focus-reports.mjs <manifest.json>');
+    process.exit(1);
+  }
+
+  const absManifest = manifestPath.startsWith('/') ? manifestPath : join(ROOT, manifestPath);
+  const manifest = JSON.parse(await readFile(absManifest, 'utf8'));
+  const catalog = JSON.parse(await readFile(join(ROOT, 'playground', 'vfx-catalog.json'), 'utf8'));
+
+  for (const entry of manifest.entries) {
+    if (entry.kind !== 'clean' || !entry.specId) continue;
+    const type = entry.renderType;
+    const dir = join(ROOT, 'validate', 'focus', type);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, `${entry.specId}.md`);
+    await writeFile(path, reportBody(entry, catalog, manifest));
+    console.log(`[report] ${path.replace(ROOT + '/', '')}`);
+  }
+
+  const sweepDir = join(ROOT, 'validate', 'sweep');
+  await mkdir(sweepDir, { recursive: true });
+  const summaryPath = join(sweepDir, `${manifest.phase}-${manifest.timestamp}.md`);
+  await writeFile(summaryPath, await sweepSummary(manifest, catalog));
+  console.log(`[report] ${summaryPath.replace(ROOT + '/', '')}`);
+}
+
+main().catch((e) => {
+  console.error('[report]', e.message);
+  process.exit(1);
+});

package/project-templates/threejs/skills/playable-focus/scripts/playground.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * Playground CLI — catalog 穷举 clean specs + registry 里的 integration/flow
+ *
+ *   npm run playground -- list
+ *   npm run playground -- list --type=frame
+ *   npm run playground -- record clean:frame:match_burst_v2
+ *   npm run playground -- ladder clean:particle:shard_debris
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdir } from 'node:fs/promises';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = join(__dirname, '../..');
+const RECORD_SCRIPT = join(SKILLS_ROOT, 'playable-record/scripts/record-playable.mjs');
+
+function projectRootFromArgs(argv) {
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice(7);
+      return v.startsWith('/') ? v : join(process.cwd(), v);
+    }
+  }
+  return process.cwd();
+}
+
+const ROOT = projectRootFromArgs(process.argv.slice(2));
+const REGISTRY_PATH = join(ROOT, 'playground', 'registry.json');
+
+async function loadRegistry() {
+  const raw = await readFile(REGISTRY_PATH, 'utf8');
+  const registry = JSON.parse(raw);
+  const catalogPath = join(ROOT, 'playground', 'vfx-catalog.json');
+  const catalog = JSON.parse(await readFile(catalogPath, 'utf8'));
+  return { registry, catalog };
+}
+
+/** Expand vfx-catalog specs → clean playground entries */
+function expandCleanPlaygrounds(catalog) {
+  return catalog.specs.map((spec) => {
+    const typeMeta = catalog.renderTypes[spec.renderType];
+    return {
+      id: `clean:${spec.renderType}:${spec.id}`,
+      kind: 'clean',
+      scope: 'FX',
+      renderType: spec.renderType,
+      specId: spec.id,
+      label: `[${typeMeta.label}] ${spec.label}`,
+      problemTypes: typeMeta.validateDimensions,
+      entry: {
+        path: typeMeta.harness,
+        query: { spec: spec.id },
+        captureQuery: 'capture=1'
+      },
+      viewport: typeMeta.viewport,
+      record: {
+        durationMs: typeMeta.loopMs * 3,
+        warmupMs: 800,
+        outDir: 'clean',
+        filenamePrefix: `${spec.renderType}-${spec.id}`
+      },
+      ready: { sceneKey: typeMeta.sceneKey },
+      ladder: {
+        L: `clean:${spec.renderType}:${spec.id}`,
+        miniG: spec.usedIn?.includes('tile_shatter') ? 'integration:EVENT:match-once' : null,
+        G: 'flow:full'
+      },
+      usedIn: spec.usedIn || []
+    };
+  });
+}
+
+function allPlaygrounds(registry, catalog) {
+  return [...expandCleanPlaygrounds(catalog), ...registry.playgrounds];
+}
+
+function findPlayground(all, id) {
+  const pg = all.find((p) => p.id === id);
+  if (!pg) {
+    throw new Error(`Unknown id "${id}". Run: npm run playground -- list`);
+  }
+  return pg;
+}
+
+function buildUrl(pg, port = 8080) {
+  const base = `http://127.0.0.1:${port}${pg.entry.path}`;
+  const parts = [];
+  if (pg.entry.captureQuery) parts.push(pg.entry.captureQuery);
+  if (pg.entry.query) {
+    const q = new URLSearchParams(pg.entry.query);
+    parts.push(q.toString());
+  }
+  return parts.length ? `${base}?${parts.join('&')}` : base;
+}
+
+function timestamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/** L1 priority order from test12-plan */
+const L1_PRIORITY = [
+  'clean:frame:match_burst_v2',
+  'clean:particle:shard_debris',
+  'clean:particle:match_dust',
+  'clean:particle:gold_sparkles',
+  'clean:frame:victory_ray_v2',
+  'clean:frame:xianyun_swirl',
+  'clean:frame:combo_ring',
+  'clean:frame:firework_burst',
+  'clean:frame:golden_dragon',
+  'clean:frame:match_burst',
+  'clean:frame:victory_ray'
+];
+
+const G1_IDS = [
+  'integration:EVENT:match-once',
+  'integration:PHASE:endcard-win'
+];
+
+function printHelp() {
+  console.log(`playground.mjs — 按渲染类型穷举的局部 playground
+
+用法:
+  npm run playground -- list [--type=frame|particle|model]
+  npm run playground -- catalog [--type=frame]
+  npm run playground -- url <id>
+  npm run playground -- record <id> [--headed] [--duration=ms]
+  npm run playground -- ladder <id>
+  npm run playground -- sweep L1 [--type=frame] [--headed]
+  npm run playground -- sweep G1 [--headed]
+
+Sweep 产出: recordings/sweep/<phase>-<timestamp>/manifest.json
+
+Clean id 格式:  clean:<renderType>:<specId>
+  例: clean:frame:match_burst_v2
+      clean:particle:shard_debris
+
+Integration:
+  integration:EVENT:match-once
+  integration:PHASE:endcard-win
+  flow:full
+`);
+}
+
+function parseCliArgs(argv) {
+  const opts = { headed: false, duration: null, warmup: null, port: 8080, type: null, root: null };
+  const positional = [];
+  for (const arg of argv) {
+    if (arg === '--headed') opts.headed = true;
+    else if (arg.startsWith('--type=')) opts.type = arg.slice(7);
+    else if (arg.startsWith('--duration=')) opts.duration = Number(arg.slice(11));
+    else if (arg.startsWith('--warmup=')) opts.warmup = Number(arg.slice(9));
+    else if (arg.startsWith('--port=')) opts.port = Number(arg.slice(7));
+    else if (arg.startsWith('--root=')) opts.root = arg.slice(7);
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else positional.push(arg);
+  }
+  return { cmd: positional[0], id: positional[1], opts };
+}
+
+function recordArgsFromPlayground(pg, opts, sweepOutDir = null) {
+  const args = [RECORD_SCRIPT, `--root=${ROOT}`];
+
+  if (pg.kind === 'clean') {
+    args.push(`--harness=${pg.renderType}`);
+    args.push(`--spec=${pg.specId}`);
+  } else if (pg.kind === 'integration') {
+    args.push('--focus');
+    args.push(`--scope=${pg.scope}`);
+    if (pg.fixture) args.push(`--fixture=${pg.fixture}`);
+    else if (pg.entry.query?.fixture) args.push(`--fixture=${pg.entry.query.fixture}`);
+  }
+
+  if (sweepOutDir) {
+    args.push(`--out=${sweepOutDir}`);
+    args.push('--sweep');
+  }
+
+  const duration = opts.duration ?? pg.record?.durationMs;
+  const warmup = opts.warmup ?? pg.record?.warmupMs;
+  if (duration != null) args.push(`--duration=${duration}`);
+  if (warmup != null) args.push(`--warmup=${warmup}`);
+  if (opts.headed) args.push('--headed');
+  if (opts.port !== 8080) args.push(`--port=${opts.port}`);
+
+  return args;
+}
+
+async function findLatestMp4(dir, prefix) {
+  const files = await readdir(dir).catch(() => []);
+  const matches = files.filter((f) => f.endsWith('.mp4') && (!prefix || f.startsWith(prefix)));
+  matches.sort();
+  return matches.length ? join(dir, matches[matches.length - 1]) : null;
+}
+
+async function runRecordCapture(pg, opts, sweepOutDir) {
+  const args = recordArgsFromPlayground(pg, opts, sweepOutDir);
+  console.log(`[playground] record ${pg.id}`);
+  console.log(`[playground] node ${args.join(' ')}`);
+  try {
+    await runNode(args);
+    let prefix = null;
+    if (pg.kind === 'clean') prefix = `${pg.renderType}-${pg.specId}-`;
+    else if (pg.record?.filenamePrefix) prefix = `${pg.record.filenamePrefix}-`;
+    const searchDir = sweepOutDir || join(ROOT, 'recordings', pg.kind === 'clean' ? 'clean' : 'focus');
+    const mp4 = await findLatestMp4(searchDir, prefix);
+    return { status: 'ok', mp4 };
+  } catch (err) {
+    return { status: 'fail', error: err.message };
+  }
+}
+
+function runNode(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', args, { cwd: ROOT, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))));
+  });
+}
+
+async function cmdList(all, opts, catalog) {
+  const filtered = opts.type
+    ? all.filter((p) => p.renderType === opts.type || p.id.includes(`:${opts.type}:`))
+    : all;
+
+  console.log('ID\tKIND\tTYPE\tLABEL');
+  for (const pg of filtered) {
+    const type = pg.renderType || pg.scope || '-';
+    console.log(`${pg.id}\t${pg.kind}\t${type}\t${pg.label}`);
+  }
+
+  const frameCount = catalog.specs.filter((s) => s.renderType === 'frame').length;
+  const particleCount = catalog.specs.filter((s) => s.renderType === 'particle').length;
+  console.log(`\nCatalog: ${frameCount} frame + ${particleCount} particle specs (${catalog.specs.length} total)`);
+  console.log(`Harness: 3 types (frame / particle / model-reserved)`);
+}
+
+async function cmdCatalog(catalog, opts) {
+  const types = opts.type ? [opts.type] : Object.keys(catalog.renderTypes);
+  for (const t of types) {
+    const meta = catalog.renderTypes[t];
+    console.log(`\n## ${t} — ${meta.label} (${meta.harness})`);
+    if (meta.status === 'reserved') {
+      console.log('  (reserved)');
+      continue;
+    }
+    for (const spec of catalog.specs.filter((s) => s.renderType === t)) {
+      console.log(`  - ${spec.id}: ${spec.label}`);
+      console.log(`    record: npm run playground -- record clean:${t}:${spec.id}`);
+    }
+  }
+  console.log('\n## composites');
+  for (const c of catalog.composites) {
+    console.log(`  - ${c.id}: ${c.label} ← [${c.primitives.join(', ')}]`);
+  }
+}
+
+async function cmdUrl(all, id, opts) {
+  console.log(buildUrl(findPlayground(all, id), opts.port));
+}
+
+async function cmdLadder(all, id, catalog) {
+  const pg = findPlayground(all, id);
+  console.log(`Ladder: ${pg.label} (${pg.id})\n`);
+
+  const composite = catalog.composites.find((c) => c.primitives.includes(pg.specId));
+  if (composite) {
+    console.log(`  所属 composite: ${composite.id} (${composite.label})`);
+    console.log(`  同 composite 其它 primitive:`);
+    for (const pid of composite.primitives) {
+      if (pid === pg.specId) continue;
+      const s = catalog.specs.find((x) => x.id === pid);
+      if (s) console.log(`    - clean:${s.renderType}:${s.id}  (${s.label})`);
+    }
+    console.log('');
+  }
+
+  const ladder = pg.ladder || {};
+  for (const [step, targetId] of [['L', ladder.L], ['mini-G', ladder.miniG], ['G', ladder.G]]) {
+    if (!targetId) continue;
+    const target = findPlayground(all, targetId);
+    console.log(`  ${step}  ${targetId}`);
+    console.log(`       ${target.label}`);
+    console.log(`       npm run playground -- record ${targetId} --headed\n`);
+  }
+}
+
+async function cmdSweep(all, catalog, phase, opts) {
+  const ts = timestamp();
+  const sweepDir = join(ROOT, 'recordings', 'sweep', `${phase}-${ts}`);
+  await mkdir(sweepDir, { recursive: true });
+
+  let ids;
+  if (phase === 'L1') {
+    ids = L1_PRIORITY.filter((id) => {
+      if (!opts.type) return true;
+      return id.includes(`:${opts.type}:`);
+    });
+  } else if (phase === 'G1') {
+    ids = G1_IDS;
+  } else {
+    throw new Error('sweep phase must be L1 or G1');
+  }
+
+  const entries = [];
+  for (const id of ids) {
+    const pg = findPlayground(all, id);
+    const result = await runRecordCapture(pg, opts, sweepDir);
+    entries.push({
+      id: pg.id,
+      kind: pg.kind,
+      renderType: pg.renderType || pg.scope,
+      specId: pg.specId || null,
+      label: pg.label,
+      status: result.status,
+      mp4: result.mp4 ? result.mp4.replace(ROOT + '/', '') : null,
+      error: result.error || null,
+      viewport: pg.viewport
+    });
+  }
+
+  const manifest = {
+    phase,
+    timestamp: ts,
+    sweepDir: sweepDir.replace(ROOT + '/', ''),
+    entries,
+    summary: {
+      total: entries.length,
+      ok: entries.filter((e) => e.status === 'ok').length,
+      fail: entries.filter((e) => e.status === 'fail').length
+    }
+  };
+
+  const manifestPath = join(sweepDir, 'manifest.json');
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+  console.log(`\n[sweep] Done: ${manifestPath}`);
+  console.log(`[sweep] ${manifest.summary.ok}/${manifest.summary.total} ok`);
+  return manifest;
+}
+
+async function cmdRecord(all, id, opts) {
+  const pg = findPlayground(all, id);
+  await runRecordCapture(pg, opts, null);
+}
+
+async function main() {
+  const { cmd, id, opts } = parseCliArgs(process.argv.slice(2));
+  if (opts.help || !cmd) {
+    printHelp();
+    process.exit(cmd ? 0 : 1);
+  }
+
+  const { registry, catalog } = await loadRegistry();
+  const all = allPlaygrounds(registry, catalog);
+
+  switch (cmd) {
+    case 'list': await cmdList(all, opts, catalog); break;
+    case 'catalog': await cmdCatalog(catalog, opts); break;
+    case 'url':
+      if (!id) throw new Error('url requires <id>');
+      await cmdUrl(all, id, opts);
+      break;
+    case 'ladder':
+      if (!id) throw new Error('ladder requires <id>');
+      await cmdLadder(all, id, catalog);
+      break;
+    case 'record':
+      if (!id) throw new Error('record requires <id>');
+      await cmdRecord(all, id, opts);
+      break;
+    case 'sweep':
+      if (!id || !['L1', 'G1'].includes(id)) throw new Error('sweep requires L1 or G1');
+      await cmdSweep(all, catalog, id, opts);
+      break;
+    default:
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('[playground]', err.message);
+  process.exit(1);
+});

package/project-templates/threejs/skills/playable-focus/templates/focus-lab/frame.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+  <title>Frame Lab</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; overflow: hidden; background: #140808; }
+    canvas { display: block; margin: 0 auto; }
+  </style>
+</head>
+<body>
+  <script src="https://cdn.jsdelivr.net/npm/phaser@3.87.0/dist/phaser.min.js"></script>
+  <script src="../game/config/game-config.js"></script>
+  <script src="../game/config/anim-config.js"></script>
+  <script src="../game/config/asset-manifest.js"></script>
+  <script src="../game/gameplay/tween-utils.js"></script>
+  <script src="harness/clean-stage.js"></script>
+  <script src="../game/gameplay/frame-fx.js"></script>
+  <script src="harness/frame-lab-scene.js"></script>
+  <script>
+    (function () {
+      var capture = new URLSearchParams(window.location.search).get('capture') === '1';
+      var vp = CleanStage.viewport(capture);
+      window.__game = new Phaser.Game({
+        type: Phaser.AUTO,
+        width: vp.w,
+        height: vp.h,
+        parent: document.body,
+        backgroundColor: '#140808',
+        scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH, width: vp.w, height: vp.h },
+        scene: [FrameLabScene],
+        render: { pixelArt: false, antialias: true }
+      });
+    })();
+  </script>
+</body>
+</html>

package/project-templates/threejs/skills/playable-focus/templates/focus-lab/harness/clean-stage.js

@@ -0,0 +1,114 @@
+/**
+ * Shared clean-stage utilities for type-based focus labs.
+ */
+var CleanStage = {
+  parseParams() {
+    var params = new URLSearchParams(window.location.search);
+    return {
+      capture: params.get('capture') === '1',
+      spec: params.get('spec') || null
+    };
+  },
+
+  viewport(capture) {
+    return capture ? { w: 720, h: 800 } : { w: 1080, h: 960 };
+  },
+
+  preloadAssets(scene) {
+    ASSET_MANIFEST.standaloneImages.forEach(function (item) {
+      scene.load.image(item.key, ASSET_MANIFEST.getFullPath(item.path));
+    });
+    if (ASSET_MANIFEST.useAtlases) {
+      ASSET_MANIFEST.atlases.forEach(function (item) {
+        scene.load.atlas(item.key, ASSET_MANIFEST.getAtlasFullPath(item.png), ASSET_MANIFEST.getAtlasFullPath(item.json));
+      });
+    }
+  },
+
+  ensureProceduralTextures(scene) {
+    if (!scene.textures.exists('particle_gold')) {
+      var g = scene.make.graphics({ x: 0, y: 0, add: false });
+      for (var r = 16; r > 0; r -= 2) {
+        var t = r / 16;
+        g.fillStyle(0xFFD700, 0.15 * (1 - t) * (1 - t));
+        g.fillCircle(16, 16, r);
+      }
+      g.generateTexture('particle_gold', 32, 32);
+      g.destroy();
+    }
+    if (!scene.textures.exists('particle_spark')) {
+      var g2 = scene.make.graphics({ x: 0, y: 0, add: false });
+      g2.fillStyle(0xFFF5D0, 0.9);
+      g2.fillRoundedRect(3, 0, 4, 36, 2);
+      g2.generateTexture('particle_spark', 10, 36);
+      g2.destroy();
+    }
+  },
+
+  buildBackdrop(scene, capture, title, opts) {
+    opts = opts || {};
+    var cx = scene.scale.width / 2;
+    var cy = scene.scale.height / 2;
+    var g = scene.add.graphics();
+    if (opts.pureBlack || capture) {
+      g.fillStyle(0x000000, 1);
+      g.fillRect(0, 0, scene.scale.width, scene.scale.height);
+    } else {
+      g.fillStyle(0x140808, 1);
+      g.fillRect(0, 0, scene.scale.width, scene.scale.height);
+      g.fillStyle(0x2A1208, 0.85);
+      g.fillRoundedRect(cx - 320, cy - 280, 640, 560, 24);
+      g.lineStyle(2, 0x4A3020, 0.6);
+      g.strokeRoundedRect(cx - 320, cy - 280, 640, 560, 24);
+    }
+    g.setDepth(0);
+    if (!capture && title) {
+      scene.add.text(cx, 48, title, { fontSize: '28px', color: '#D4A838', fontStyle: 'bold' }).setOrigin(0.5).setDepth(10);
+    }
+    return { cx: cx, cy: cy };
+  },
+
+  blendMode(name) {
+    if (name === 'ADD') return Phaser.BlendModes.ADD;
+    if (name === 'MULTIPLY') return Phaser.BlendModes.MULTIPLY;
+    return Phaser.BlendModes.NORMAL;
+  },
+
+  scheduleLoop(scene, capture, loopMs, fn) {
+    if (capture) {
+      scene.time.delayedCall(400, fn);
+      scene.time.addEvent({ delay: loopMs, loop: true, callback: fn });
+    } else {
+      fn();
+      var btn = scene.add.text(scene.scale.width / 2, scene.scale.height - 60, '▶ Replay', {
+        fontSize: '24px', color: '#FFD700', backgroundColor: '#3A2000', padding: { x: 16, y: 8 }
+      }).setOrigin(0.5).setDepth(100).setInteractive({ useHandCursor: true });
+      btn.on('pointerdown', fn);
+    }
+  }
+};
+
+var VfxCatalog = {
+  _data: null,
+
+  load(url) {
+    var self = this;
+    return fetch(url)
+      .then(function (r) { return r.json(); })
+      .then(function (data) { self._data = data; return data; });
+  },
+
+  getSpec(specId) {
+    if (!this._data) return null;
+    return this._data.specs.find(function (s) { return s.id === specId; }) || null;
+  },
+
+  listByType(renderType) {
+    if (!this._data) return [];
+    return this._data.specs.filter(function (s) { return s.renderType === renderType; });
+  },
+
+  getTypeMeta(renderType) {
+    return this._data && this._data.renderTypes[renderType];
+  }
+};