@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -0,0 +1,123 @@
+// ============================================================
+// build-sprite-sheet.template.mjs — 精灵图合并 + 验证脚本模板
+// 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
+//
+// 使用方式：
+//   1. cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs ta-workspace/scripts/build-<name>-atlas.mjs
+//   2. 修改下方 CONFIG 区域
+//   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
+//   4. node ta-workspace/scripts/build-<name>-atlas.mjs
+// ============================================================
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'fs';
+import { join, extname } from 'path';
+
+// ============ CONFIG — 修改这里 ============
+const CONFIG = {
+  /** 处理好的图片目录（process-batch 的输出目录） */
+  processedDir: 'assets/images/processed',
+  /** 输出文件路径（不含扩展名，会生成 .png 和 .json 两个文件） */
+  outputBase: 'assets/bundles/atlas',
+  /** 每行帧数 */
+  columns: 8,
+  /** 帧间距（像素） */
+  padding: 2,
+  /**
+   * 精灵图背景色
+   * - 'transparent'（默认）：透明背景
+   * - 'white' / 'black' / '#RRGGBB'：固定背景色
+   *   某些引擎（如 PlayCanvas）处理透明精灵图时可能显示为黑色，此时用 'white' 更安全
+   */
+  background: 'transparent',
+  /** 文件名排序方式：'name'（字母序）或 'custom'（使用 ORDERED_NAMES） */
+  sort: 'name',
+};
+
+/**
+ * 自定义帧顺序（CONFIG.sort = 'custom' 时生效）
+ * 填写不含扩展名的文件名，按期望顺序排列
+ * 示例（扑克牌）：['spades_A', 'spades_2', 'spades_3', ...]
+ */
+const ORDERED_NAMES = [
+  // 填写文件名（不含扩展名）...
+];
+// ============ LOGIC — 通常不需要修改 ============
+
+const LOG_FILE = 'ta-workspace/logs/build-sprite-sheet.log';
+mkdirSync('ta-workspace/logs', { recursive: true });
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}`;
+  console.log(line);
+  appendFileSync(LOG_FILE, line + '\n');
+}
+
+// 收集输入文件
+let inputFiles;
+if (CONFIG.sort === 'custom' && ORDERED_NAMES.length > 0) {
+  // 自定义顺序：按 ORDERED_NAMES 排列，找不到的文件跳过并警告
+  inputFiles = [];
+  for (const name of ORDERED_NAMES) {
+    const candidates = ['.png', '.jpg', '.webp'].map(ext => join(CONFIG.processedDir, `${name}${ext}`));
+    const found = candidates.find(p => existsSync(p));
+    if (found) {
+      inputFiles.push(found);
+    } else {
+      log(`[WARN] Ordered file not found: ${name} (skipping)`);
+    }
+  }
+} else {
+  // 文件名排序
+  inputFiles = readdirSync(CONFIG.processedDir)
+    .filter(f => ['.png', '.jpg', '.webp'].includes(extname(f).toLowerCase()))
+    .sort()
+    .map(f => join(CONFIG.processedDir, f));
+}
+
+if (inputFiles.length === 0) {
+  log('ERROR: No input files found in ' + CONFIG.processedDir);
+  process.exit(1);
+}
+
+log(`=== Build Sprite Sheet Start ===`);
+log(`Frames: ${inputFiles.length} | Columns: ${CONFIG.columns} | Padding: ${CONFIG.padding} | BG: ${CONFIG.background}`);
+
+// 构建 --inputs 参数列表
+const inputsArg = inputFiles.map(p => `"${p}"`).join(' ');
+
+const cmd =
+  `playcraft image sprite-sheet` +
+  ` --inputs ${inputsArg}` +
+  ` --output "${CONFIG.outputBase}"` +
+  ` --columns ${CONFIG.columns}` +
+  ` --padding ${CONFIG.padding}` +
+  (CONFIG.background !== 'transparent' ? ` --background "${CONFIG.background}"` : '');
+
+log(`Running: playcraft image sprite-sheet ... --output ${CONFIG.outputBase}`);
+
+try {
+  execSync(cmd, { stdio: 'inherit' });
+} catch (e) {
+  log(`ERROR: sprite-sheet command failed: ${e.message}`);
+  process.exit(1);
+}
+
+// 验证输出
+const pngPath  = `${CONFIG.outputBase}.png`;
+const jsonPath = `${CONFIG.outputBase}.json`;
+
+if (!existsSync(pngPath) || !existsSync(jsonPath)) {
+  log('ERROR: Output files missing! Expected ' + pngPath + ' and ' + jsonPath);
+  process.exit(1);
+}
+
+const meta = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+const frameCount = Object.keys(meta.frames ?? {}).length;
+
+log(`\n=== Sprite Sheet Built ===`);
+log(`  Frames  : ${frameCount}`);
+log(`  PNG     : ${pngPath}`);
+log(`  JSON    : ${jsonPath}`);
+log(`  Columns : ${CONFIG.columns}`);
+log(`  Rows    : ${Math.ceil(frameCount / CONFIG.columns)}`);

package/project-templates/phaser/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs

@@ -0,0 +1,254 @@
+/**
+ * compare-style.template.mjs
+ *
+ * 色彩风格一致性定量检查脚本。
+ * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Artist 样本做客观色彩比较。
+ *
+ * 使用方法：
+ *   cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
+ *      ta-workspace/scripts/compare-style.mjs
+ *   # 修改下方 CONFIG 区域后运行：
+ *   node ta-workspace/scripts/compare-style.mjs
+ *
+ * 输出示例：
+ *   [COMPARE] tile_sample_1.png  vs  tile_comp_01.png
+ *     色相距离（加权）: 8.3°     → ✅ 优秀（< 15°）
+ *     明度差异:         0.06     → ✅ 优秀（< 0.10）
+ *     饱和度差异:       0.04     → ✅ 优秀（< 0.10）
+ *     综合一致性评分:   4.7 / 5  → ✅ 通过（≥ 3.0）
+ *
+ * 依赖：@gltf-transform/core（CLI 已内置）、sharp（CLI 已内置）
+ * 若 sharp 未全局可用，运行前：npm install sharp --no-save
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import path from 'path';
+
+// ─── CONFIG ───────────────────────────────────────────────────────────────────
+
+const CONFIG = {
+  /** Artist 样本图（风格基准） */
+  referenceImage: 'assets/images/tiles/tile_sample_1.png',
+
+  /** 要检查的 TA 补全素材目录或文件列表 */
+  targetDir: 'assets/images/tiles',
+
+  /** 只检查该目录下的哪些文件（glob 后缀匹配） */
+  targetGlob: '.png',
+
+  /** 排除文件名包含这些关键词的文件（Artist 样本自身） */
+  excludeKeywords: ['sample', 'concept', 'selected', 'storyboard'],
+
+  /** 日志输出路径 */
+  logFile: 'ta-workspace/logs/style-compare.log',
+
+  /** 评分阈值（低于此值输出警告） */
+  warnThreshold: 3.0,
+};
+
+// ─── HELPERS ──────────────────────────────────────────────────────────────────
+
+/**
+ * 用 playcraft image info 提取图片的 dominant colors（HSL 列表）
+ * 返回格式：[{ h, s, l, weight }]（weight 为面积占比估算）
+ */
+function extractDominantColors(imagePath) {
+  try {
+    const raw = execSync(
+      `playcraft image info --input "${imagePath}" --json`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const info = JSON.parse(raw);
+
+    // playcraft image info 返回 dominantColors 数组：[{ r, g, b, hex, percent }]
+    const colors = (info.dominantColors || []).slice(0, 5);
+    return colors.map(c => {
+      const hsl = rgbToHsl(c.r, c.g, c.b);
+      return { ...hsl, weight: (c.percent || 20) / 100 };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function rgbToHsl(r, g, b) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  switch (max) {
+    case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+    case g: h = ((b - r) / d + 2) / 6; break;
+    default: h = ((r - g) / d + 4) / 6;
+  }
+  return { h: h * 360, s, l };
+}
+
+/**
+ * 计算两组 dominant colors 之间的加权色相距离（°）
+ * 色相距离取最短弧（0–180°）
+ */
+function weightedHueDist(colorsA, colorsB) {
+  if (!colorsA.length || !colorsB.length) return 999;
+  let totalDist = 0, totalWeight = 0;
+  for (const a of colorsA) {
+    // 找 B 中色相最近的颜色
+    let minDist = Infinity;
+    for (const b of colorsB) {
+      const raw = Math.abs(a.h - b.h);
+      const dist = raw > 180 ? 360 - raw : raw;
+      if (dist < minDist) minDist = dist;
+    }
+    totalDist += minDist * a.weight;
+    totalWeight += a.weight;
+  }
+  return totalWeight > 0 ? totalDist / totalWeight : 999;
+}
+
+/**
+ * 计算明度 / 饱和度的加权平均差异（0–1）
+ */
+function weightedChannelDiff(colorsA, colorsB, channel) {
+  if (!colorsA.length || !colorsB.length) return 1;
+  const avgA = colorsA.reduce((s, c) => s + c[channel] * c.weight, 0) /
+               colorsA.reduce((s, c) => s + c.weight, 0);
+  const avgB = colorsB.reduce((s, c) => s + c[channel] * c.weight, 0) /
+               colorsB.reduce((s, c) => s + c.weight, 0);
+  return Math.abs(avgA - avgB);
+}
+
+/**
+ * 综合一致性评分 1–5
+ *
+ * 评分规则（与 playcraft-style-qa Micro-Batch 标准对齐）：
+ *   色相距离 < 15°  且 明度/饱和度差 < 0.10  → 5 分
+ *   色相距离 < 20°  且 明度/饱和度差 < 0.15  → 4 分
+ *   色相距离 < 30°  且 明度/饱和度差 < 0.20  → 3 分（勉强可接受）
+ *   色相距离 < 45°  且 明度/饱和度差 < 0.30  → 2 分（需调整）
+ *   其他                                       → 1 分（停止，提问 Artist）
+ */
+function calcScore(hueDist, lightDiff, satDiff) {
+  const channelOk = Math.max(lightDiff, satDiff);
+  if (hueDist < 15 && channelOk < 0.10) return 5;
+  if (hueDist < 20 && channelOk < 0.15) return 4;
+  if (hueDist < 30 && channelOk < 0.20) return 3;
+  if (hueDist < 45 && channelOk < 0.30) return 2;
+  return 1;
+}
+
+function scoreLabel(score) {
+  if (score >= 4) return '✅ 良好';
+  if (score >= 3) return '⚠️  可接受';
+  return '❌ 偏差过大，需停止';
+}
+
+function hueLabel(dist) {
+  if (dist < 15) return '✅ 优秀（< 15°）';
+  if (dist < 30) return '⚠️  偏差（< 30°）';
+  return '❌ 严重偏差（≥ 30°）';
+}
+
+function channelLabel(diff) {
+  if (diff < 0.10) return '✅ 优秀（< 0.10）';
+  if (diff < 0.20) return '⚠️  偏差（< 0.20）';
+  return '❌ 严重偏差（≥ 0.20）';
+}
+
+// ─── MAIN ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const logDir = path.dirname(CONFIG.logFile);
+  if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+
+  const refPath = CONFIG.referenceImage;
+  if (!existsSync(refPath)) {
+    console.error(`[ERROR] 参考图不存在: ${refPath}`);
+    process.exit(1);
+  }
+
+  console.log(`\n📊 色彩风格一致性检查`);
+  console.log(`   参考图: ${refPath}\n`);
+
+  const refColors = extractDominantColors(refPath);
+  if (!refColors.length) {
+    console.error('[ERROR] 无法从参考图提取颜色，请确认 playcraft image info 可用');
+    process.exit(1);
+  }
+
+  // 收集目标文件
+  let targets = [];
+  try {
+    const { readdirSync } = await import('fs');
+    targets = readdirSync(CONFIG.targetDir)
+      .filter(f => f.endsWith(CONFIG.targetGlob))
+      .filter(f => !CONFIG.excludeKeywords.some(kw => f.includes(kw)))
+      .map(f => path.join(CONFIG.targetDir, f));
+  } catch {
+    console.error(`[ERROR] 无法读取目录: ${CONFIG.targetDir}`);
+    process.exit(1);
+  }
+
+  if (!targets.length) {
+    console.log('  未找到需要检查的目标文件');
+    return;
+  }
+
+  const results = [];
+  let failCount = 0;
+
+  for (const target of targets) {
+    const targetColors = extractDominantColors(target);
+    if (!targetColors.length) {
+      console.log(`  [SKIP] ${path.basename(target)} — 无法提取颜色`);
+      continue;
+    }
+
+    const hueDist  = weightedHueDist(refColors, targetColors);
+    const lightDiff = weightedChannelDiff(refColors, targetColors, 'l');
+    const satDiff   = weightedChannelDiff(refColors, targetColors, 's');
+    const score     = calcScore(hueDist, lightDiff, satDiff);
+
+    if (score < CONFIG.warnThreshold) failCount++;
+
+    const line = [
+      `[COMPARE] ${path.basename(refPath)}  vs  ${path.basename(target)}`,
+      `  色相距离（加权）: ${hueDist.toFixed(1)}°     → ${hueLabel(hueDist)}`,
+      `  明度差异:         ${lightDiff.toFixed(2)}     → ${channelLabel(lightDiff)}`,
+      `  饱和度差异:       ${satDiff.toFixed(2)}     → ${channelLabel(satDiff)}`,
+      `  综合一致性评分:   ${score} / 5  → ${scoreLabel(score)}`,
+      '',
+    ].join('\n');
+
+    console.log(line);
+    results.push({ file: path.basename(target), score, hueDist, lightDiff, satDiff });
+  }
+
+  // 汇总
+  const avgScore = results.reduce((s, r) => s + r.score, 0) / (results.length || 1);
+  const summary = [
+    `=== 汇总 ===`,
+    `  检查文件数: ${results.length}`,
+    `  平均评分:   ${avgScore.toFixed(1)} / 5`,
+    `  低于阈值数: ${failCount}（阈值 ${CONFIG.warnThreshold}）`,
+    failCount > 0
+      ? `  ⚠️  建议：停止低分文件类型的批量生产，调整生成参数或向 Artist 提问 ICP`
+      : `  ✅  全部通过，可继续批量生产`,
+    '',
+  ].join('\n');
+
+  console.log(summary);
+
+  // 写日志
+  const timestamp = new Date().toISOString();
+  appendFileSync(CONFIG.logFile, `\n[${timestamp}]\n${results.map(r =>
+    `${r.file}: score=${r.score} hue=${r.hueDist.toFixed(1)}° L=${r.lightDiff.toFixed(2)} S=${r.satDiff.toFixed(2)}`
+  ).join('\n')}\n${summary}`);
+
+  if (failCount > 0) process.exit(1);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });