@playcraft/cli 0.1.40-beta → 0.1.42

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

@@ -1,412 +0,0 @@
-# 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

@@ -1,75 +0,0 @@
----
-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

@@ -1,86 +0,0 @@
----
-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