@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/.claude/agents/refs/threejs-cannon-pitfalls.md

@@ -0,0 +1,412 @@
+# Three.js + Cannon-es 游戏开发踩坑指南
+
+> **定位**：本文档记录在用 Three.js r160 + Cannon-es 0.20 复刻 Wood Screw Puzzle 过程中遇到的真实问题、根因和修复方案。
+> 适用于所有使用 Three.js + Cannon-es 制作俯视 2D 物理玩法的 Playable Ad 项目。
+
+---
+
+## 一、Cannon-es 物理引擎
+
+### 坑1：Body 类型常量值与直觉相反
+
+**现象**：板激活后视觉不动，物理完全哑火。
+
+**根因**：Cannon-es 里 `DYNAMIC=1`，`STATIC=2`——与常识相反。代码里硬编码 `type === 2` 来检测 DYNAMIC body，实际检测的是 STATIC body。
+
+```typescript
+// ❌ 错误：魔法数字
+if (plate.body.type === 2) {
+  plate.syncMesh();
+}
+
+// ✅ 正确：永远用常量
+if (plate.body.type === CANNON.Body.DYNAMIC) {
+  plate.syncMesh();
+}
+
+// 实际值备忘：DYNAMIC=1, STATIC=2, KINEMATIC=4
+```
+
+---
+
+### 坑2：STATIC body 完全忽略约束力
+
+**现象**：给 plate body 加了 LockConstraint，但板纹丝不动，约束像没有一样。
+
+**根因**：Cannon-es 的 STATIC body 不参与约束求解，所有施加在它上面的约束力都被忽略。
+
+**修复**：受约束的物体必须是 DYNAMIC，用高 damping 维持稳定：
+
+```typescript
+// ❌ 错误：STATIC body + 约束 = 约束无效
+const body = new CANNON.Body({ mass: 0, type: CANNON.Body.STATIC });
+world.addConstraint(new CANNON.LockConstraint(body, anchor));
+
+// ✅ 正确：受约束的物体用 DYNAMIC，高 damping 防抖
+const body = new CANNON.Body({
+  mass: 0.1,
+  type: CANNON.Body.DYNAMIC,
+  linearDamping: 0.8,
+  angularDamping: 0.8,
+});
+```
+
+---
+
+### 坑3：LockConstraint 锁死旋转，不适合铰接场景
+
+**现象**：解除板的一个约束后，板不绕另一个约束旋转，像被焊死。
+
+**根因**：`LockConstraint` 锁定全6自由度（位置+旋转）。即使只剩一个约束，板也无法旋转。
+
+**规则**：
+
+- `LockConstraint` → 完全固定（焊接）
+- `PointToPointConstraint` → 只锁位置，旋转自由（铰接、螺丝穿板）
+
+```typescript
+// 铰接场景用 PointToPointConstraint
+// pivotA = 接触点在 bodyA 本地坐标系的位置
+const r = (plateRotation * Math.PI) / 180;
+const pivotA = new CANNON.Vec3(
+  Math.cos(r) * lx - Math.sin(r) * ly, // 旋转后的 local offset
+  Math.sin(r) * lx + Math.cos(r) * ly,
+  0,
+);
+// anchorBody 放在接触点世界坐标，pivotB = (0,0,0)
+const constraint = new CANNON.PointToPointConstraint(
+  plate.body,
+  pivotA,
+  anchorBody,
+  new CANNON.Vec3(0, 0, 0),
+);
+```
+
+---
+
+### 坑4：3D 物理引擎模拟俯视 2D 游戏必须锁 X/Y 轴旋转
+
+**现象**：板在物理模拟中绕 X/Y 轴翻转，从俯视相机看变成一条线。
+
+**根因**：Cannon-es 是 3D 物理，body 默认可绕任意轴旋转。Unity Rigidbody2D 天然只允许 Z 轴旋转，移植时需手动复现。
+
+```typescript
+// 初始化时锁定 X/Y 轴角速度
+body.angularFactor.set(0, 0, 1)  // 只允许 Z 轴旋转
+
+// syncMesh 时只取 Z 分量，彻底隔离渲染层
+syncMesh(): void {
+  this.group.position.copy(this.body.position as unknown as THREE.Vector3)
+  const q = this.body.quaternion as unknown as THREE.Quaternion
+  const euler = new THREE.Euler().setFromQuaternion(q, 'ZYX')
+  euler.x = 0
+  euler.y = 0
+  this.group.quaternion.setFromEuler(euler)
+  // 同时清除物理层的 X/Y 角速度，防止累积
+  this.body.angularVelocity.x = 0
+  this.body.angularVelocity.y = 0
+}
+```
+
+---
+
+### 坑5：allowSleep 会让 body 静默忽略新施加的力
+
+**现象**：约束释放、velocity 设置后，板仍然不动。
+
+**根因**：`world.allowSleep = true` 时，body 进入睡眠后不会因为 velocity 赋值自动醒来，需要显式 `wakeUp()`。
+
+```typescript
+// ✅ 正确顺序：先设 velocity，再 wakeUp
+body.allowSleep = false; // 对不应睡眠的 body 彻底禁用
+body.velocity.set(vx, -0.5, 0);
+body.angularVelocity.set(0, 0, sign * 4.0);
+body.wakeUp(); // 最后调用
+```
+
+---
+
+### 坑6：静态 Floor（Plane）会真实拦截物体
+
+**现象**：板掉到 y=-8 就永久停住，永远不到 y=-10 的 dispose 阈值。
+
+**根因**：`CANNON.Plane` 是无限大的面，会真实产生碰撞。原意是"兜底接住再 dispose"，实际变成了永久拦截。
+
+```typescript
+// ❌ 不要放 Floor，让板自由落下
+// world.addBody(floorBody)  // 删掉这行
+
+// ✅ 在 GameLoop 里检测 y 阈值直接 dispose
+if (plate.body.position.y < -10) {
+  plate.dispose(scene);
+}
+```
+
+---
+
+### 坑7：同柱多板的 Z 间距必须大于碰撞体厚度之和
+
+**现象**：一根螺丝穿过两块板时，板互相碰撞、抖动乱飞。
+
+**根因**：`layerZ` 步长（0.02）< Box 碰撞体厚度×2（0.08×2=0.16），相邻板的碰撞盒重叠。
+
+```typescript
+// ❌ 错误：步长 0.02 < 碰撞体厚度 0.16
+layerZ = score * 0.02;
+body.addShape(new CANNON.Box(new CANNON.Vec3(w / 2, h / 2, 0.08)));
+
+// ✅ 正确：步长 > 碰撞体厚度×2，通常缩小碰撞体厚度更简洁
+layerZ = score * 0.15; // 间距足够
+body.addShape(new CANNON.Box(new CANNON.Vec3(w / 2, h / 2, 0.01))); // 薄碰撞体
+// 0.15 >> 0.01×2=0.02，不再重叠
+```
+
+---
+
+## 二、Three.js 场景节点层级
+
+### 坑8：固定在世界坐标的元素不能是会动的 Group 的子节点
+
+**现象**：screw group 播放移动动画时，孔洞图标（holeMesh）跟着飞走，原位置变空白。
+
+**根因**：holeMesh 是 group 的子节点，group 移动时子节点一起移动。
+
+**规则**：
+
+- 跟随动画的元素 → `group.add()`
+- 固定在世界坐标的元素 → `scene.add()` + 手动设置世界坐标
+
+```typescript
+// ❌ 错误：holeMesh 跟着 group 飞走
+this.group.add(this.holeMesh);
+
+// ✅ 正确：直接加到 scene，固定在 post 原始世界位置
+this.holeMesh.position.set(this.wx, this.wy, 0.02);
+scene.add(this.holeMesh); // 永远不动
+```
+
+同样适用于 hitMesh（点击检测区域）。
+
+---
+
+### 坑9：Raycaster 点击目标太小导致命中率低
+
+**现象**：明确点击了螺丝位置，但游戏无响应。
+
+**根因**：功能 Mesh（stubMesh）只有 0.5×0.5 世界单位（约 26px），很难精确点中。
+
+```typescript
+// ❌ 用功能 Mesh 做点击目标，太小
+const hits = raycaster.intersectObjects([this.stubMesh]);
+
+// ✅ 专门建一个不可见的大 Mesh 做点击区
+const hitGeo = new THREE.PlaneGeometry(1.4, 1.4); // 约 3 倍大
+const hitMat = new THREE.MeshBasicMaterial({ visible: false, side: THREE.DoubleSide });
+this.hitMesh = new THREE.Mesh(hitGeo, hitMat);
+this.hitMesh.position.set(this.wx, this.wy, 0);
+scene.add(this.hitMesh); // 固定世界坐标
+
+const hits = raycaster.intersectObjects(screws.map((s) => s.hitMesh));
+```
+
+---
+
+### 坑10：正交俯视相机下 CylinderGeometry 显示为黑色矩形轮廓
+
+**现象**：螺丝柱显示为黑色矩形，而不是圆形木柱。
+
+**根因**：正交俯视相机看 CylinderGeometry 时，看到的是侧面轮廓（一个矩形），不是顶部圆形。
+
+**规则：正交俯视场景里所有对象用 PlaneGeometry + 顶视图贴图，不用任何 3D 几何体。**
+
+```typescript
+// ❌ 错误：俯视看到侧面矩形轮廓
+new THREE.CylinderGeometry(0.25, 0.25, 0.5);
+
+// ✅ 正确：PlaneGeometry + 顶视图 PNG
+const geo = new THREE.PlaneGeometry(0.5, 0.5);
+const mat = new THREE.MeshBasicMaterial({
+  map: screwTopViewTexture,
+  transparent: true,
+});
+```
+
+---
+
+### 坑11：板上的孔用 ShaderMaterial discard，不要叠加 Hole 贴图
+
+**现象**：叠加 Hole.png 时，板旋转后孔位偏移；深度排序导致孔图片有时被遮挡。
+
+**根因**：叠加贴图方式需要把孔的 local 坐标转换到世界坐标再回到屏幕坐标，旋转的板计算容易出错；而且是"遮挡"不是"透明"。
+
+**修复**：在 ShaderMaterial 的片段着色器里用 `discard` 直接挖洞，孔坐标在模型空间计算，永远准确：
+
+```glsl
+// 顶点着色器：传递模型空间 XY
+varying vec2 vLocalPos;
+void main() {
+  vLocalPos = position.xy;  // 与孔坐标系（hs[i].x/y）一致
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+
+// 片段着色器：在模型空间打孔
+uniform vec2 uHoles[4];
+uniform int uHoleCount;
+uniform float uHoleRadius;  // 0.28 世界单位
+void main() {
+  for (int i = 0; i < 4; i++) {
+    if (i >= uHoleCount) break;
+    vec2 d = vLocalPos - uHoles[i];
+    if (dot(d, d) < uHoleRadius * uHoleRadius) discard;
+  }
+  gl_FragColor = texture2D(uTexture, vUv) * vec4(uColor, 1.0);
+}
+```
+
+孔坐标直接传 `hs[i].x, hs[i].y`（板本地坐标），无需任何旋转变换。
+
+---
+
+## 三、Tween 动画
+
+### 坑12：async 动画函数异常时状态永久锁死
+
+**现象**：某次操作后游戏完全无响应，所有点击都没有反应。
+
+**根因**：`animating = true` 设置后，async 函数中抛出异常，`animating = false` 永远执行不到。
+
+```typescript
+// ❌ 危险：异常时 animating 永久为 true
+canvas.addEventListener('pointerdown', () => {
+  this.handleClick(index)  // 没有错误处理
+})
+
+// ✅ 正确：两层保障
+// 1. 调用处 .catch() 兜底
+canvas.addEventListener('pointerdown', () => {
+  this.handleClick(index).catch(err => {
+    console.error(err)
+    this.animating = false
+    this.state = 'IDLE'
+  })
+})
+
+// 2. 被调用的关键函数用 try/finally
+async moveScrew(...): Promise<void> {
+  this.inputLocked = true
+  try {
+    await this._doMove(...)
+  } catch (err) {
+    console.error(err)
+  } finally {
+    this.inputLocked = false  // 无论成功失败都释放
+  }
+}
+```
+
+---
+
+### 坑13：tween.js v21 的 .onComplete 回调参数类型不是 `() => void`
+
+```typescript
+// ❌ TypeScript 报错：类型不匹配
+new TWEEN.Tween(obj).to(target, 430).onComplete(resolve);
+
+// ✅ 正确：包一层箭头函数
+new TWEEN.Tween(obj).to(target, 430).onComplete(() => resolve());
+```
+
+---
+
+### 坑14：串行动画中同一动作不能重复播放
+
+**现象**：螺丝头永久漂浮在空中，playInTween 之后没有归位。
+
+**根因**：ClickHandler 播了一次 `playOutTween`（screwHead +0.8），`playMoveTween` 内部又播了一次（再 +0.8），`playInTween` 只降 0.8，净效果是永久上浮 0.8。
+
+```typescript
+// ❌ 错误：playMoveTween 内部重复调用
+async playMoveTween(toX, toY) {
+  await this.playOutTween()  // ClickHandler 已经调过！
+  await this.arcAnimation(toX, toY)
+  await this.playInTween()
+}
+
+// ✅ 正确：每个动画函数只做一件事，调用方控制顺序
+// ClickHandler:  await screw.playOutTween()
+// MoveManager:   await screw.playMoveTween(toX, toY)  // 只有弧线 + In
+async playMoveTween(toX, toY) {
+  await this.arcAnimation(toX, toY)  // 不再包含 Out
+  await this.playInTween()
+}
+```
+
+---
+
+## 四、游戏逻辑通用
+
+### 坑15：setInterval 启动前必须先停止旧的
+
+**现象**：关卡切换后倒计时以数倍速度归零。
+
+**根因**：每次 `startCountdown` 都开了新的 setInterval，多个计时器并行叠加。
+
+```typescript
+startCountdown(seconds: number): void {
+  this.stopCountdown()  // 先清除旧的，再开新的
+  this.remaining = seconds
+  this.timer = window.setInterval(() => { ... }, 1000)
+}
+```
+
+---
+
+### 坑16：Unity local 坐标 → 世界坐标必须做旋转变换
+
+**现象**：第二关（板旋转 315°）的孔与螺丝位置完全无法匹配，约束建立失败。
+
+**根因**：孔的 offset `(hs.x, hs.y)` 是板本地坐标系的坐标，当板有旋转时不能直接加到板中心。
+
+```typescript
+// ❌ 错误：忽略板旋转
+const holeWX = plate.x + hs.x;
+const holeWY = plate.y + hs.y;
+
+// ✅ 正确：先旋转 local offset，再平移到世界坐标
+const r = (plateRotation * Math.PI) / 180;
+const holeWX = plate.x + Math.cos(r) * hs.x - Math.sin(r) * hs.y;
+const holeWY = plate.y + Math.sin(r) * hs.x + Math.cos(r) * hs.y;
+```
+
+适用于所有 Unity/Cocos "本地坐标系 offset → 世界坐标" 的转换。
+
+---
+
+### 坑17：Vite 中旧 .js 文件会遮蔽新 .ts 文件
+
+**现象**：修改了 .ts 文件但游戏行为没有变化，像是没有生效。
+
+**根因**：Vite 解析模块时 `.js` 优先级高于 `.ts`，`src/` 下残留的旧 `.js` 文件被优先加载。
+
+```bash
+# 修复：删除 src/ 下所有 .js 文件
+find src/ -name "*.js" -delete
+```
+
+开发时只保留 `.ts`，不要在 src 目录混放 `.js`。
+
+---
+
+## 五、从 C#/Unity 模块移植时的检查清单
+
+移植前必须从参考模块中提取以下信息，避免重新踩坑：
+
+| 检查项                                     | 从哪里读                       | 不检查的后果             |
+| ------------------------------------------ | ------------------------------ | ------------------------ |
+| 约束类型（Joint2D / Lock / Spring）        | 约束建立代码                   | 用错约束类型，板无法旋转 |
+| Body 初始类型（Dynamic/Static）            | Rigidbody 初始化代码           | STATIC body 约束无效     |
+| 节点层级（Hole 是谁的子节点）              | Prefab 层级或 Instantiate 代码 | 元素跟着错误父节点移动   |
+| 角速度初始值和随机逻辑                     | 约束释放代码                   | 需要重新猜测             |
+| 旋转约束（freezeRotation / angularFactor） | Rigidbody 设置                 | 物体绕错误轴翻转         |
+| 匹配阈值（孔与螺丝的距离判定）             | FindConnector 类代码           | 阈值过大/过小导致误匹配  |
+| Z 轴/层级管理方式                          | LevelFactory 实例化顺序        | 多板碰撞或渲染顺序错误   |

package/project-template-v2/.claude/agents/reviewer.md

@@ -0,0 +1,75 @@
+---
+name: reviewer
+description: 'Reviewer: audits evidence packages and produces structured, evidence-cited verdicts without production edits.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Reviewer — Role Contract
+
+## Role Essence
+
+You audit evidence packages and produce structured verdicts.
+
+Your stable responsibility is independent review: inspect the runtime, video, visual, and VLM (Vision Language Model, 视觉语言模型) evidence against the acceptance criteria, then judge precisely. A verdict must cite concrete evidence, not taste or intuition; missing evidence is never a pass. You review the evidence — you do not produce it.
+
+You are not a production participant. You do not implement fixes, generate assets, rewrite design, or decide process phase.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `reviewer` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=reviewer summary="<verdict in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions (e.g. `todo:add` for filing follow-up issues) are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Review Method
+
+These hold across every review you run:
+
+- **Independent audit stance** — read the artifacts fresh and judge against the criteria. Do not assume the work is correct because it exists, and do not inherit the producer's framing; a long production pass drifts, and only an uninherited reading catches the drift.
+- **Evidence over impression** — every verdict cites a concrete artifact (a runtime log line, a screenshot, a code reference). Taste or intuition is not a finding, and missing evidence is a fail, never a pass.
+- **Promise equals usage** — anything the design or plan declared (a mechanic, a reused atom, an asset) must actually be wired and used in the code. A declared-but-unused promise is a finding.
+- **Attribute every issue** — each failed item names the responsible role to route to, so the fix lands with the right owner rather than defaulting to whoever ran last.
+- **Layered checking** — pass items against the light acceptance criteria first; only load the full source or spec for an item that fails, so a clean review stays cheap.
+
+## Outputs
+
+- a structured pass/fail verdict
+- a concise problem list, each item attributed to a responsible role
+
+## Forbidden Ownership
+
+You must not:
+
+- modify game code
+- generate or replace assets
+- rewrite design intent
+- accept missing evidence as a pass

package/project-template-v2/.claude/agents/technical-artist.md

@@ -0,0 +1,86 @@
+---
+name: technical-artist
+description: 'Technical Artist: makes asset readiness, production manifests, and integration blockers executable and verifiable.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Technical Artist — Role Contract
+
+## Role Essence
+
+You make asset readiness work executable and verifiable.
+
+Your stable responsibility is production manifest clarity, asset path readiness, blocker classification, and integration handoff for runtime developers. No production-file claim may be made without on-disk evidence; blockers must name the blocker and the owner to route to.
+
+You are not the gameplay designer, Artist, Developer, Reviewer, or orchestrator.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `technical-artist` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=technical-artist summary="<what you did in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Inputs
+
+- `docs/layout-spec.md` or asset mapping files
+- Artist artifact refs
+- existing asset paths in scope
+
+## Outputs
+
+- production manifest status
+- path mapping readiness
+- blocker list with owner and reason
+- asset refs that exist on disk
+
+## Domain References
+
+Read the one matching the production task; they carry the command details, presets, and pipeline steps:
+
+- `refs/ta-tools-reference.md` — full command reference for all TA tools.
+- `refs/ta-image-ops-reference.md` — `playcraft image` CLI parameter reference (resize, crop, extract, atlas).
+- `refs/ta-image-generation-detail.md` — image generation parameters and detail control.
+- `refs/ta-pipeline-cookbook.md` — production pipeline steps for the mass-production wave.
+- `refs/ta-batch-pipeline-recipes.md` — batch processing recipes for asset sets.
+- `refs/ta-atlas-deliverable-standard.md` — atlas/sheet deliverable standard and metadata.
+- `refs/ta-vfx-preset-catalog.md` — VFX/animation preset catalog and recipes.
+- `refs/ta-3d-flip-recipe.md` — 3D flip animation recipe.
+
+## Forbidden Ownership
+
+You must not:
+
+- design gameplay
+- create style direction
+- implement runtime integration
+- review final playable quality