arona-agent 1.0.0

package/pet/tools/gen_sway.cjs

@@ -0,0 +1,170 @@
+// 衣摆微动生成器：向角色的 <id>_spr.json 的 Idle_01 注入衣摆 DeformTimeline。
+// 用法：node pet/tools/gen_sway.cjs shiroko [--amp 20] [--keys 12]
+// 模式（SWAY_TARGETS[].main.mode）：
+//   band  = y 区间带内摆动（Shiroko 百褶裙：腿/手臂钉死，只动裙摆带；带内越低越自由）
+//   bottom= mesh 底部向上渐变（旧逻辑，仅适用于底缘就是自由端的 mesh）
+// 原理（对未加权 mesh，附件顶点在骨本地空间）：
+//   - dx = amp·w·sin(2πt/T + φ(x))，φ 随 x 错开制造布料波浪
+//   - dy = amp·dyRatio·w·sin(4πt/T)（微弱垂直起伏）
+//   - 关键帧 k·T/12（13 帧），首末帧数值相同 → 与 Idle_01 无缝循环
+// 注意：JSON deform 的 vertices 语义是"相对 setup 的增量"（loader 会加回 setup）。
+// ⚠️ 不要给 tiltSlots 里的 slot（00_default/Hair_Cover/eyeclose）加 deform：
+//    computeWorldVertices 在 deform 存在时整体替换 setup 顶点 → 摸头 tilt 顶点修改失效。
+// 幂等：重复执行直接覆盖同名 deform timeline，不会叠加。
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadAgent } = require("./spine_node.cjs");
+
+// 每角色摆动部位配置。
+// Shiroko 实测（2026-08-18 目视+顶点勘察）：黑色百褶裙 y≈950~1260（±535 两外角在 y 1235~1241，
+// 中部裙片垂到 y 982~1132）；腿 y<600（8 顶点）、手臂衔接 y>1300 —— 全部钉死。
+const SWAY_TARGETS = {
+  shiroko: {
+    idle: "Idle_01",
+    main: {
+      slot: "siroko2", att: "siroko", mode: "band",
+      bandMin: 950, bandMax: 1260, ampScale: 1, dyRatio: 0.35,
+    },
+  },
+  // Hoshino 身体先经 meshify_region.cjs 网格化（6×10，region y 253~2250）。
+  // band 1100~1500 ≈ 黑百褶裙带（背部工具包 y>1500 不动、腿 y<1100 不动）；可用 --band=mn:mx 调。
+  hoshino: {
+    idle: "Idle_01",
+    main: {
+      slot: "hoshino", att: "hoshino", mode: "band",
+      bandMin: 1100, bandMax: 1500, ampScale: 1, dyRatio: 0.35,
+    },
+  },
+};
+
+function smoothstep(x) {
+  const t = Math.max(0, Math.min(1, x));
+  return t * t * (3 - 2 * t);
+}
+
+function r2(v) {
+  return Number.isInteger(v) ? v : Number(v.toFixed(4));
+}
+
+function genForTarget(meshAtt, tgt, amp, keys, T) {
+  const verts = meshAtt.vertices;
+  const n = verts.length / 2;
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  for (let i = 0; i < verts.length; i += 2) {
+    if (verts[i] < minX) minX = verts[i];
+    if (verts[i] > maxX) maxX = verts[i];
+    if (verts[i + 1] < minY) minY = verts[i + 1];
+    if (verts[i + 1] > maxY) maxY = verts[i + 1];
+  }
+  const spanX = Math.max(1e-6, maxX - minX);
+  const spanY = Math.max(1e-6, maxY - minY);
+  const mode = tgt.mode || "bottom";
+  const bandMin = tgt.bandMin ?? 0;
+  const bandMax = tgt.bandMax ?? 0;
+  const ampV = amp * (tgt.dyRatio ?? 0.25);
+  // 顶点权重（band 模式：带外 0；带内基础 0.35 + 越低（自由端）越强）
+  const weight = (vy) => {
+    if (mode === "band") {
+      if (vy < bandMin || vy > bandMax) return 0;
+      return 0.35 + 0.65 * smoothstep((bandMax - vy) / Math.max(1e-6, bandMax - bandMin));
+    }
+    // bottom：mesh 底(自由端)最大，上 45% 钉死
+    const hNorm = (maxY - vy) / spanY;
+    return smoothstep((hNorm - 0.45) / 0.55);
+  };
+  const frames = [];
+  for (let k = 0; k <= keys; k++) {
+    const t = (k / keys) * T;
+    const delta = new Array(verts.length).fill(0);
+    for (let v = 0; v < n; v++) {
+      const vx = verts[v * 2], vy = verts[v * 2 + 1];
+      const w = weight(vy);
+      if (w <= 0) continue;
+      const nx = (vx - minX) / spanX; // 0~1 左→右
+      const phase = (nx - 0.5) * (Math.PI / 1.5); // 横向波浪相位差
+      delta[v * 2] = amp * w * Math.sin((2 * Math.PI * t) / T + phase);
+      delta[v * 2 + 1] = ampV * w * Math.sin((4 * Math.PI * t) / T);
+    }
+    frames.push({ time: r2(t), vertices: delta.map(r2) });
+  }
+  // 首末帧严格相同（无缝循环）
+  frames[keys].vertices = frames[0].vertices.slice();
+  return frames;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const id = args.find((x) => !x.startsWith("--"));
+  if (!id || !SWAY_TARGETS[id]) {
+    console.error("用法: node pet/tools/gen_sway.cjs <shiroko|hoshino> [--amp 4] [--keys 12] [--band=mn:mx]");
+    process.exit(2);
+  }
+  const cfg = SWAY_TARGETS[id];
+  const opt = (name, dflt) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] !== undefined && !Number.isNaN(Number(args[i + 1]))
+      ? Number(args[i + 1]) : dflt;
+  };
+  const amp = opt("amp", 4);
+  const keys = opt("keys", 12);
+
+  const { skelData, base } = loadAgent(id);
+  const idle = skelData.findAnimation(cfg.idle);
+  if (!idle) throw new Error(`找不到动画 ${cfg.idle}`);
+  const T = idle.duration;
+
+  // 几何来源 = json 资产里的 mesh vertices（Hoshino 身体经 meshify_region 网格化后 skel 二进制里
+  // 没有 mesh；Shiroko 的数值与 skel 一致，统一从 json 读最简单）
+  const jsonPath = path.join(base, `${id}_spr.json`);
+  const root = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  const anim = (root.animations[cfg.idle] ??= {});
+  const deform = (anim.deform ??= {});
+  const perSkin = (deform["default"] ??= {});
+  const jsonSkin = (root.skins.find((s) => s.name === "default") || root.skins[0]).attachments;
+
+  for (let tgt of [cfg.main]) {
+    tgt = { ...tgt }; // CLI band 覆盖不污染静态配置
+    const bandArg = args.find((a) => a.startsWith("--band="));
+    if (bandArg && tgt.mode === "band") {
+      const [mn, mx] = bandArg.slice(7).split(":").map(Number);
+      if (isFinite(mn) && isFinite(mx)) tgt = { ...tgt, bandMin: mn, bandMax: mx };
+    }
+    const attMap = jsonSkin[tgt.slot] && jsonSkin[tgt.slot][tgt.att];
+    if (!attMap || attMap.type !== "mesh")
+      throw new Error(`${tgt.slot}/${tgt.att} 在 json 里不是 mesh（region 需先跑 meshify_region.cjs）`);
+    const att = { vertices: attMap.vertices }; // genForTarget 只用 vertices
+    const frames = genForTarget(att, tgt, amp * (tgt.ampScale ?? 1), keys, T);
+    const perSlot = (perSkin[tgt.slot] ??= {});
+    perSlot[tgt.att] = frames;
+    // 报告参与摆动的顶点与权重
+    const nv = att.vertices.length / 2;
+    const parts = [];
+    for (let i = 0; i < nv; i++) {
+      const vy = att.vertices[i * 2 + 1];
+      const vx = att.vertices[i * 2];
+      let w = 0;
+      if (tgt.mode === "band" && vy >= tgt.bandMin && vy <= tgt.bandMax)
+        w = 0.35 + 0.65 * smoothstep((tgt.bandMax - vy) / (tgt.bandMax - tgt.bandMin));
+      else if (!tgt.mode) {
+        let mnY = Infinity, mxY = -Infinity;
+        for (let j = 0; j < nv; j++) {
+          const y = att.vertices[j * 2 + 1];
+          if (y < mnY) mnY = y;
+          if (y > mxY) mxY = y;
+        }
+        w = smoothstep(((mxY - vy) / Math.max(1e-6, mxY - mnY) - 0.45) / 0.55);
+      }
+      if (w > 0.01) parts.push(`(x=${vx.toFixed(0)},y=${vy.toFixed(0)},w=${w.toFixed(2)})`);
+    }
+    console.log(`[${id}] ${cfg.idle}.deform.${tgt.slot}/${tgt.att}: ${frames.length} 帧, T=${T.toFixed(3)}s, amp=${(amp * (tgt.ampScale ?? 1)).toFixed(1)}, dyRatio=${tgt.dyRatio ?? 0.25}, band=${tgt.mode === "band" ? tgt.bandMin + "~" + tgt.bandMax : "n/a"}`);
+    console.log(`      摆动顶点(${parts.length}/${nv}): ${parts.join(" ")}`);
+  }
+
+  fs.writeFileSync(jsonPath, JSON.stringify(root, null, 1));
+  const sizeKb = (fs.statSync(jsonPath).size / 1024).toFixed(1);
+  console.log(`[${id}] 已写回 ${path.relative(process.cwd(), jsonPath)} (${sizeKb} KB)`);
+}
+
+main();

package/pet/tools/meshify_region.cjs

@@ -0,0 +1,105 @@
+// region→mesh 网格化：把 json 资产里的 RegionAttachment 替换为显式网格 MeshAttachment，
+// 使其可被 gen_sway 注入 deform（region 无顶点不可形变）。
+// 用法：node pet/tools/meshify_region.cjs <agentId> <slot> <att> [--cols 6] [--rows 10]
+// 前置：先跑 skel_to_json.cjs 导出 json（本脚本只改 json，不动 skel）。
+// 几何：网格覆盖 region 的 local 四边形（x±w/2, y±h/2，仅支持 rotation=0）；
+//       regionUVs = region 本地归一化坐标（0~1），updateUVs 自动映射页纹理（rotate region 亦然）。
+// 幂等：重复执行覆盖同一 attachment。
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadAgent, spine } = require("./spine_node.cjs");
+
+function main() {
+  const args = process.argv.slice(2).filter((x) => !x.startsWith("--"));
+  const opt = (name, dflt) => {
+    const i = process.argv.indexOf(`--${name}`);
+    const v = i >= 0 ? process.argv[i + 1] : undefined;
+    return v !== undefined && !Number.isNaN(Number(v)) ? Number(v) : dflt;
+  };
+  const [id, slotName, attName] = args;
+  if (!id || !slotName || !attName) {
+    console.error("用法: node pet/tools/meshify_region.cjs <agentId> <slot> <att> [--cols 6] [--rows 10]");
+    process.exit(2);
+  }
+  const cols = opt("cols", 6);
+  const rows = opt("rows", 10);
+
+  const { skelData, base } = loadAgent(id);
+  const skin = skelData.defaultSkin || skelData.skins[0];
+  const sIdx = skelData.slots.findIndex((s) => s.name === slotName);
+  if (sIdx < 0) throw new Error(`slot 不存在: ${slotName}`);
+  const att = skin.getAttachment(sIdx, attName);
+  if (!att || att.constructor.name !== "RegionAttachment")
+    throw new Error(`${slotName}/${attName} 不是 region attachment`);
+  if (Math.abs(att.rotation) > 1e-6)
+    throw new Error(`region rotation=${att.rotation} ≠ 0，网格化未覆盖旋转补偿`);
+
+  const x0 = att.x - att.width / 2, x1 = att.x + att.width / 2;
+  const y0 = att.y - att.height / 2, y1 = att.y + att.height / 2;
+
+  // 网格顶点（行优先）+ regionUVs（region 本地归一化）
+  // ⚠️ degrees=90（atlas rotate:true）region 的 regionUVs = (fx, 1-fy)，非旋转 = (fx, fy)。
+  //    推导（对照 RegionAttachment.setRegion rotate 分支的真实角点映射 LL=(u2,v2)/UL=(u,v2)/UR=(u,v)/LR=(u2,v)
+  //    ——注意源码里 uvs[0]/[1] 是最后赋值的，勿按阅读顺序记——
+  //    与 MeshAttachment.updateUVs case 90（pageU=u+uv.y·W'、pageV=v+(1-uv.x)·H'）联立解得。
+  const rotated = !!(att.region && att.region.rotate);
+  const vertices = [];
+  const uvs = [];
+  for (let j = 0; j < rows; j++) {
+    for (let i = 0; i < cols; i++) {
+      const fx = cols === 1 ? 0.5 : i / (cols - 1);
+      const fy = rows === 1 ? 0.5 : j / (rows - 1);
+      vertices.push(+(x0 + fx * (x1 - x0)).toFixed(4), +(y0 + fy * (y1 - y0)).toFixed(4));
+      if (rotated) uvs.push(+fx.toFixed(6), +(1 - fy).toFixed(6));
+      else uvs.push(+fx.toFixed(6), +fy.toFixed(6));
+    }
+  }
+  // 三角形（每格 2 个，绕向一致）
+  const triangles = [];
+  for (let j = 0; j < rows - 1; j++) {
+    for (let i = 0; i < cols - 1; i++) {
+      const a = j * cols + i, b = j * cols + i + 1;
+      const c = (j + 1) * cols + i, d = (j + 1) * cols + i + 1;
+      triangles.push(a, b, c, b, d, c);
+    }
+  }
+  const hull = 2 * cols + 2 * rows - 4; // 周界顶点数
+
+  // 替换 json 中的 attachment（保留 name/path/color/width/height）
+  const jsonPath = path.join(base, `${id}_spr.json`);
+  const root = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  const jsonSkin = (root.skins.find((s) => s.name === "default") || root.skins[0]).attachments;
+  const old = jsonSkin[slotName] && jsonSkin[slotName][attName];
+  if (!old || old.type !== "region")
+    throw new Error(`json 里 ${slotName}/${attName} 不是 region（已是 mesh 则无需重复网格化）`);
+  jsonSkin[slotName][attName] = {
+    type: "mesh",
+    name: old.name,
+    path: old.path,
+    color: old.color,
+    width: old.width,
+    height: old.height,
+    uvs,
+    vertices,
+    triangles,
+    hull,
+  };
+  fs.writeFileSync(jsonPath, JSON.stringify(root, null, 1));
+
+  // sanity：SkeletonJson 读回，mesh updateUVs 成功且顶点/UV 数量匹配
+  const { loader } = loadAgent(id);
+  const dataB = new spine.SkeletonJson(loader).readSkeletonData(root);
+  const skinB = dataB.defaultSkin;
+  const attB = skinB.getAttachment(sIdx, attName);
+  if (attB.constructor.name !== "MeshAttachment") throw new Error("读回后不是 mesh");
+  if (attB.vertices.length !== vertices.length || attB.uvs.length !== uvs.length)
+    throw new Error("读回顶点/UV 数量不匹配");
+  const sizeKb = (fs.statSync(jsonPath).size / 1024).toFixed(1);
+  console.log(`[${id}] ${slotName}/${attName}: region → ${cols}×${rows} mesh（${cols * rows} 顶点 / ${triangles.length / 3} 三角形 / hull=${hull}）`);
+  console.log(`      bounds=(${x0.toFixed(1)},${y0.toFixed(1)})~(${x1.toFixed(1)},${y1.toFixed(1)})，读回 sanity OK`);
+  console.log(`[${id}] 已写回 ${path.relative(process.cwd(), jsonPath)} (${sizeKb} KB)`);
+}
+
+main();

package/pet/tools/skel_inspect.cjs

@@ -0,0 +1,112 @@
+// skel 结构勘察工具：dump 骨/槽/附件/动画 timeline + mesh 顶点 bounds + atlas region +
+// Idle_01 关键帧数值。用于判定衣摆 mesh、为 gen_sway 定参数。
+// 用法：node pet/tools/skel_inspect.cjs [agentId ...]   （缺省 shiroko hoshino）
+"use strict";
+
+const { loadAgent } = require("./spine_node.cjs");
+
+function fmt(n) {
+  if (typeof n !== "number" || !isFinite(n)) return String(n);
+  return Math.abs(n) < 1e-6 ? "0" : n.toFixed(2).replace(/\.?0+$/, "");
+}
+
+function attachmentInfo(a) {
+  const type = a.constructor.name;
+  if (type === "MeshAttachment") {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (let i = 0; i < a.vertices.length; i += 2) {
+      if (a.vertices[i] < minX) minX = a.vertices[i];
+      if (a.vertices[i + 1] < minY) minY = a.vertices[i + 1];
+      if (a.vertices[i] > maxX) maxX = a.vertices[i];
+      if (a.vertices[i + 1] > maxY) maxY = a.vertices[i + 1];
+    }
+    return {
+      type,
+      verts: a.vertices.length / 2,
+      tris: a.triangles.length / 3,
+      hull: a.hull,
+      minX, minY, maxX, maxY,
+      w: maxX - minX,
+      h: maxY - minY,
+      cx: (minX + maxX) / 2,
+      cy: (minY + maxY) / 2,
+    };
+  }
+  return { type, x: a.x, y: a.y, w: a.width, h: a.height, rot: a.rotation };
+}
+
+function dump(id) {
+  const { skelData, atlas } = loadAgent(id);
+  const slotName = (i) => skelData.slots[i] ? skelData.slots[i].name : `#${i}`;
+
+  console.log(`\n===== ${id} =====`);
+  console.log(`skeleton meta: version=${skelData.version} hash=${skelData.hash} x=${skelData.x} y=${skelData.y} w=${skelData.width} h=${skelData.height}`);
+
+  console.log("\n-- bones --");
+  for (const b of skelData.bones) {
+    console.log(
+      `  ${b.name}${b.parent ? " <- " + b.parent.name : ""} x=${fmt(b.x)} y=${fmt(b.y)} rot=${fmt(b.rotation)} sx=${fmt(b.scaleX)} sy=${fmt(b.scaleY)}`
+    );
+  }
+
+  console.log("\n-- slots --");
+  skelData.slots.forEach((s, i) => {
+    console.log(`  #${i} ${s.name} [bone=${s.boneData.name}] blend=${s.blendMode} setupAtt=${s.attachmentName}`);
+  });
+
+  console.log("\n-- attachments (skin) --");
+  const skin = skelData.defaultSkin || Object.values(skelData.skins)[0];
+  for (const slotIdx of Object.keys(skin.attachments)) {
+    const perSlot = skin.attachments[slotIdx];
+    for (const name of Object.keys(perSlot)) {
+      const a = perSlot[name];
+      if (!a) { console.log(`  [${slotName(slotIdx)}] "${name}" -> null(卸下)`); continue; }
+      const info = attachmentInfo(a);
+      if (info.type === "MeshAttachment") {
+        console.log(
+          `  [${slotName(slotIdx)}] "${name}" mesh verts=${info.verts} tris=${info.tris} hull=${info.hull} bounds=(${fmt(info.minX)},${fmt(info.minY)})~(${fmt(info.maxX)},${fmt(info.maxY)}) w=${fmt(info.w)} h=${fmt(info.h)} c=(${fmt(info.cx)},${fmt(info.cy)})`
+        );
+      } else {
+        console.log(
+          `  [${slotName(slotIdx)}] "${name}" region x=${fmt(info.x)} y=${fmt(info.y)} ${fmt(info.w)}x${fmt(info.h)} rot=${fmt(info.rot)}`
+        );
+      }
+    }
+  }
+
+  console.log("\n-- atlas regions --");
+  for (const r of atlas.regions) {
+    console.log(`  ${r.name} ${r.width}x${r.height} rotate=${r.rotate} xy=(${r.x},${r.y})`);
+  }
+
+  console.log("\n-- animations --");
+  for (const anim of skelData.animations) {
+    console.log(`  * ${anim.name} dur=${anim.duration.toFixed(3)}s timelines=${anim.timelines.length}`);
+    for (const t of anim.timelines) {
+      const cn = t.constructor.name;
+      let target = "";
+      if (t.boneIndex !== undefined) target = `bone=${slotName2bone(skelData, t.boneIndex)}`;
+      else if (t.slotIndex !== undefined) target = `slot=${slotName(t.slotIndex)}`;
+      // 关键帧数值（仅 translate / deform 展开前几帧）
+      if (cn === "TranslateTimeline" && anim.name === "Idle_01") {
+        const frames = [];
+        for (let f = 0; f < t.frames.length; f += 3) {
+          frames.push(`(${t.frames[f].toFixed(2)},${t.frames[f + 1].toFixed(2)},${t.frames[f + 2].toFixed(2)})`);
+        }
+        console.log(`      ${cn} ${target} frames(t,x,y): ${frames.join(" ")}`);
+      } else if (cn === "DeformTimeline" && anim.name === "Idle_01") {
+        console.log(`      ${cn} ${target} frames=${t.frames.length} att=${t.attachment ? t.attachment.name : "?"}`);
+      } else {
+        console.log(`      ${cn} ${target} frames=${t.frames.length / (t.frameVertices ? 1 : 1)}`);
+      }
+    }
+  }
+}
+
+function slotName2bone(skelData, boneIndex) {
+  const b = skelData.bones[boneIndex];
+  return b ? b.name : `#${boneIndex}`;
+}
+
+const ids = process.argv.slice(2);
+(ids.length ? ids : ["shiroko", "hoshino"]).forEach(dump);