@playcraft/skills 0.0.2

package/skills/board_entity_sprite.aiimage/ref/ProceduralCar.ts

@@ -0,0 +1,357 @@
+import * as THREE from "three";
+
+/**
+ * 程序化 3D 卡通赛车工厂
+ *
+ * 使用多个基础几何体组装出精致的 Low-Poly 风格赛车模型：
+ * - 车身：圆润 BoxGeometry（边缘 round 处理）+ 车漆材质
+ * - 引擎盖：前部凸起
+ * - 座舱：深色框架 + 半透明蓝色挡风玻璃
+ * - 4 轮子：黑色轮胎 Cylinder + 银色金属轮毂
+ * - 前大灯：白色球体 emissive
+ * - 尾灯：红色方块 emissive
+ * - 后扰流板：赛车尾翼 + 支撑柱
+ * - 地面软阴影
+ *
+ * 多色变体策略：传入不同 color hex，共享几何体缓存，独立材质实例。
+ *
+ * 朝向约定：模型默认车头朝 -Z（即 "up" 方向对应 rotationY = 0）。
+ */
+
+export interface CarStyle {
+  /** 车身比例 (相对于 cellSize * scale) */
+  bodyRatio?: { w: number; h: number; l: number };
+  /** 轮子半径倍率 */
+  wheelRadius?: number;
+  /** 是否有尾翼 */
+  hasSpoiler?: boolean;
+  /** 是否有车灯 */
+  hasLights?: boolean;
+}
+
+const DEFAULT_STYLE: Required<CarStyle> = {
+  bodyRatio: { w: 0.42, h: 0.15, l: 0.72 },
+  wheelRadius: 0.08,
+  hasSpoiler: true,
+  hasLights: true,
+};
+
+/**
+ * 方向 → Y 轴旋转角度映射。
+ * 模型默认车头朝 -Z (ArrowDirection.Up = 0)。
+ */
+export function directionToRotationY(direction: string): number {
+  switch (direction) {
+    case "up": return 0;
+    case "right": return -Math.PI / 2;
+    case "down": return Math.PI;
+    case "left": return Math.PI / 2;
+    default: return 0;
+  }
+}
+
+export class ProceduralCar {
+  // 共享几何体缓存
+  private static wheelGeo: THREE.CylinderGeometry | null = null;
+  private static rimGeo: THREE.CylinderGeometry | null = null;
+  private static headlightGeo: THREE.SphereGeometry | null = null;
+  private static taillightGeo: THREE.BoxGeometry | null = null;
+  private static spoilerGeo: THREE.BoxGeometry | null = null;
+  private static spoilerPostGeo: THREE.CylinderGeometry | null = null;
+
+  /**
+   * 创建一辆 3D 卡通赛车。
+   * @param color 车身颜色 (hex number, 如 0xe74c3c)
+   * @param direction 朝向 ("up"|"down"|"left"|"right")，默认 "up"
+   * @param scale 整体缩放基准（对应 cellSize * carScale），默认 0.7
+   * @param style 可选风格覆盖
+   */
+  static create(
+    color: number,
+    direction: string = "up",
+    scale: number = 0.7,
+    style?: CarStyle,
+  ): THREE.Group {
+    const cfg = { ...DEFAULT_STYLE, ...style };
+    const group = new THREE.Group();
+    const s = scale;
+
+    const bodyW = s * cfg.bodyRatio.w;
+    const bodyH = s * cfg.bodyRatio.h;
+    const bodyL = s * cfg.bodyRatio.l;
+
+    const baseColor = new THREE.Color(color);
+    const darkColor = baseColor.clone().multiplyScalar(0.6);
+    const lightColor = baseColor.clone().lerp(new THREE.Color(0xffffff), 0.3);
+
+    // ─── 车身 ───
+    const body = this.createBody(bodyW, bodyH, bodyL, baseColor);
+    body.position.y = bodyH / 2 + s * 0.08;
+    group.add(body);
+
+    // ─── 引擎盖 ───
+    const hoodGeo = new THREE.BoxGeometry(bodyW * 0.7, bodyH * 0.3, bodyL * 0.2);
+    const hoodMat = new THREE.MeshStandardMaterial({ color: lightColor, roughness: 0.3, metalness: 0.2 });
+    const hood = new THREE.Mesh(hoodGeo, hoodMat);
+    hood.position.set(0, bodyH + s * 0.08, -bodyL * 0.28);
+    hood.castShadow = true;
+    group.add(hood);
+
+    // ─── 座舱 ───
+    const cabinW = bodyW * 0.75;
+    const cabinH = bodyH * 0.7;
+    const cabinL = bodyL * 0.35;
+    const cabin = this.createCabin(cabinW, cabinH, cabinL, darkColor);
+    cabin.position.set(0, bodyH + cabinH / 2 + s * 0.08, bodyL * 0.05);
+    group.add(cabin);
+
+    // ─── 4 轮子 ───
+    const wheelR = s * cfg.wheelRadius;
+    const wheelW = s * 0.05;
+    const wheelOffsetX = bodyW / 2 + wheelW * 0.3;
+    const wheelY = wheelR;
+    const wheelFrontZ = -bodyL * 0.3;
+    const wheelRearZ = bodyL * 0.28;
+
+    const positions: [number, number, number][] = [
+      [-wheelOffsetX, wheelY, wheelFrontZ],
+      [wheelOffsetX, wheelY, wheelFrontZ],
+      [-wheelOffsetX, wheelY, wheelRearZ],
+      [wheelOffsetX, wheelY, wheelRearZ],
+    ];
+    for (const [wx, wy, wz] of positions) {
+      const wheel = this.createWheel(wheelR, wheelW);
+      wheel.position.set(wx, wy, wz);
+      group.add(wheel);
+    }
+
+    // ─── 车灯 ───
+    if (cfg.hasLights) {
+      const hlR = s * 0.035;
+      const hlZ = -bodyL / 2 - hlR * 0.3;
+      const hlY = bodyH * 0.7 + s * 0.08;
+
+      const hlMat = new THREE.MeshStandardMaterial({
+        color: 0xffffee, emissive: 0xffffaa, emissiveIntensity: 0.6,
+        roughness: 0.1, metalness: 0.3,
+      });
+      const hlGeo = this.getHeadlightGeo(hlR);
+
+      const hlL = new THREE.Mesh(hlGeo, hlMat);
+      hlL.position.set(-bodyW * 0.3, hlY, hlZ);
+      group.add(hlL);
+
+      const hlRight = new THREE.Mesh(hlGeo, hlMat.clone());
+      hlRight.position.set(bodyW * 0.3, hlY, hlZ);
+      group.add(hlRight);
+
+      // 尾灯
+      const tlGeo = this.getTaillightGeo(s);
+      const tlMat = new THREE.MeshStandardMaterial({
+        color: 0xff2200, emissive: 0xff0000, emissiveIntensity: 0.4, roughness: 0.2,
+      });
+      const tlL = new THREE.Mesh(tlGeo, tlMat);
+      tlL.position.set(-bodyW * 0.3, hlY * 0.9, bodyL / 2);
+      group.add(tlL);
+
+      const tlR = new THREE.Mesh(tlGeo, tlMat.clone());
+      tlR.position.set(bodyW * 0.3, hlY * 0.9, bodyL / 2);
+      group.add(tlR);
+    }
+
+    // ─── 尾翼 ───
+    if (cfg.hasSpoiler) {
+      const spoiler = this.createSpoiler(s, darkColor);
+      spoiler.position.set(0, bodyH + cabinH * 0.4 + s * 0.08, bodyL * 0.38);
+      group.add(spoiler);
+    }
+
+    // ─── 地面阴影 ───
+    const shadowGeo = new THREE.PlaneGeometry(bodyW * 1.2, bodyL * 1.1);
+    const shadowMat = new THREE.MeshBasicMaterial({
+      color: 0x000000, transparent: true, opacity: 0.2, depthWrite: false,
+    });
+    const shadow = new THREE.Mesh(shadowGeo, shadowMat);
+    shadow.rotation.x = -Math.PI / 2;
+    shadow.position.y = 0.003;
+    group.add(shadow);
+
+    // ─── 方向旋转 ───
+    group.rotation.y = directionToRotationY(direction);
+    group.userData = { type: "car", color };
+
+    return group;
+  }
+
+  /**
+   * 设置阻挡红光效果
+   */
+  static setBlocked(car: THREE.Group, blocked: boolean): void {
+    car.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        const mats = Array.isArray(child.material) ? child.material : [child.material];
+        for (const mat of mats) {
+          if (mat instanceof THREE.MeshStandardMaterial) {
+            if (blocked) {
+              mat.emissive.setHex(0xff0000);
+              mat.emissiveIntensity = 0.6;
+            } else {
+              mat.emissive.setHex(0x000000);
+              mat.emissiveIntensity = 0;
+            }
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * 释放缓存的几何体
+   */
+  static dispose(): void {
+    this.wheelGeo?.dispose(); this.wheelGeo = null;
+    this.rimGeo?.dispose(); this.rimGeo = null;
+    this.headlightGeo?.dispose(); this.headlightGeo = null;
+    this.taillightGeo?.dispose(); this.taillightGeo = null;
+    this.spoilerGeo?.dispose(); this.spoilerGeo = null;
+    this.spoilerPostGeo?.dispose(); this.spoilerPostGeo = null;
+  }
+
+  // ─── 部件构建 ───
+
+  private static createBody(w: number, h: number, l: number, color: THREE.Color): THREE.Mesh {
+    const geo = new THREE.BoxGeometry(w, h, l, 2, 1, 3);
+    this.roundEdges(geo, Math.min(w, h, l) * 0.12);
+    const mat = new THREE.MeshStandardMaterial({ color, roughness: 0.3, metalness: 0.25 });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    return mesh;
+  }
+
+  private static createCabin(w: number, h: number, l: number, color: THREE.Color): THREE.Group {
+    const g = new THREE.Group();
+
+    const frameGeo = new THREE.BoxGeometry(w, h, l);
+    const frameMat = new THREE.MeshStandardMaterial({ color, roughness: 0.4, metalness: 0.2 });
+    const frame = new THREE.Mesh(frameGeo, frameMat);
+    frame.castShadow = true;
+    g.add(frame);
+
+    const glassMat = new THREE.MeshStandardMaterial({
+      color: 0x88ccff, roughness: 0.05, metalness: 0.3, transparent: true, opacity: 0.6,
+    });
+    const glassGeo = new THREE.PlaneGeometry(w * 0.85, h * 0.8);
+
+    const front = new THREE.Mesh(glassGeo, glassMat);
+    front.position.set(0, 0, -l / 2 - 0.001);
+    front.rotation.x = -0.1;
+    g.add(front);
+
+    const rear = new THREE.Mesh(glassGeo, glassMat.clone());
+    rear.position.set(0, 0, l / 2 + 0.001);
+    rear.rotation.y = Math.PI;
+    g.add(rear);
+
+    return g;
+  }
+
+  private static createWheel(radius: number, width: number): THREE.Group {
+    const g = new THREE.Group();
+
+    const tireGeo = this.getWheelGeo(radius, width);
+    const tireMat = new THREE.MeshStandardMaterial({ color: 0x222222, roughness: 0.9, metalness: 0 });
+    const tire = new THREE.Mesh(tireGeo, tireMat);
+    tire.rotation.z = Math.PI / 2;
+    tire.castShadow = true;
+    g.add(tire);
+
+    const rimGeo = this.getRimGeo(radius * 0.6, width * 0.3);
+    const rimMat = new THREE.MeshStandardMaterial({ color: 0xcccccc, roughness: 0.15, metalness: 0.8 });
+    const rim = new THREE.Mesh(rimGeo, rimMat);
+    rim.rotation.z = Math.PI / 2;
+    g.add(rim);
+
+    return g;
+  }
+
+  private static createSpoiler(s: number, color: THREE.Color): THREE.Group {
+    const g = new THREE.Group();
+
+    const wingGeo = this.getSpoilerGeo(s);
+    const wingMat = new THREE.MeshStandardMaterial({ color, roughness: 0.3, metalness: 0.2 });
+    const wing = new THREE.Mesh(wingGeo, wingMat);
+    wing.castShadow = true;
+    g.add(wing);
+
+    const postGeo = this.getSpoilerPostGeo(s);
+    const postMat = new THREE.MeshStandardMaterial({ color: 0x444444, roughness: 0.4, metalness: 0.5 });
+    const pL = new THREE.Mesh(postGeo, postMat);
+    pL.position.set(-s * 0.12, -s * 0.04, 0);
+    g.add(pL);
+
+    const pR = new THREE.Mesh(postGeo, postMat.clone());
+    pR.position.set(s * 0.12, -s * 0.04, 0);
+    g.add(pR);
+
+    return g;
+  }
+
+  // ─── 边缘圆角 ───
+
+  private static roundEdges(geo: THREE.BoxGeometry, radius: number): void {
+    const pos = geo.attributes.position;
+    const params = geo.parameters;
+    const halfW = (params.width ?? 1) / 2;
+    const halfH = (params.height ?? 1) / 2;
+    const halfD = (params.depth ?? 1) / 2;
+
+    for (let i = 0; i < pos.count; i++) {
+      let x = pos.getX(i);
+      let y = pos.getY(i);
+      let z = pos.getZ(i);
+
+      const fx = Math.abs(x) / halfW;
+      const fy = Math.abs(y) / halfH;
+      const fz = Math.abs(z) / halfD;
+      const cornerness = fx * fy + fy * fz + fx * fz;
+
+      if (cornerness > 1.5) {
+        const shrink = 1 - radius * 0.5 * (cornerness - 1.5);
+        x *= shrink;
+        y *= shrink;
+        z *= shrink;
+        pos.setXYZ(i, x, y, z);
+      }
+    }
+    pos.needsUpdate = true;
+    geo.computeVertexNormals();
+  }
+
+  // ─── 几何体缓存 ───
+
+  private static getWheelGeo(r: number, w: number): THREE.CylinderGeometry {
+    if (!this.wheelGeo) this.wheelGeo = new THREE.CylinderGeometry(r, r, w, 12);
+    return this.wheelGeo;
+  }
+  private static getRimGeo(r: number, w: number): THREE.CylinderGeometry {
+    if (!this.rimGeo) this.rimGeo = new THREE.CylinderGeometry(r, r, w, 8);
+    return this.rimGeo;
+  }
+  private static getHeadlightGeo(r: number): THREE.SphereGeometry {
+    if (!this.headlightGeo) this.headlightGeo = new THREE.SphereGeometry(r, 8, 6);
+    return this.headlightGeo;
+  }
+  private static getTaillightGeo(s: number): THREE.BoxGeometry {
+    if (!this.taillightGeo) this.taillightGeo = new THREE.BoxGeometry(s * 0.06, s * 0.03, s * 0.02);
+    return this.taillightGeo;
+  }
+  private static getSpoilerGeo(s: number): THREE.BoxGeometry {
+    if (!this.spoilerGeo) this.spoilerGeo = new THREE.BoxGeometry(s * 0.38, s * 0.02, s * 0.06);
+    return this.spoilerGeo;
+  }
+  private static getSpoilerPostGeo(s: number): THREE.CylinderGeometry {
+    if (!this.spoilerPostGeo) this.spoilerPostGeo = new THREE.CylinderGeometry(s * 0.012, s * 0.012, s * 0.08, 6);
+    return this.spoilerPostGeo;
+  }
+}

package/skills/bottom_ui_bar.aicomponent/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: bottom_ui_bar.aicomponent
+description: 底部 UI 条 Phaser 占位容器，导出 GAME_BOTTOM_UI_BAR_HEIGHT（与 GameConfig 同源）并与棋盘可用高度扣减对齐。布局合同见 playable_hud_layout。
+triggers: 需要底区垂直占位、与顶栏对称的 HUD 区，或避免棋盘侵入底部 CTA/品牌区时触发。
+---
+
+# 底部 UI 条（Bottom UI Bar）
+
+## 说明
+
+- **高度常量** `GAME_BOTTOM_UI_BAR_HEIGHT` 取自 `GameConfig.GAME_BOTTOM_UI_BAR_HEIGHT`，与 `grid_board_layout` / `path_input_handler` 等扣底公式一致。
+- **分区与 z-order** 见 `playable_hud_layout.aicomponent`；**缩放**见 `responsive_2d_layout.aicomponent` 第一节。
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|------|------|
+| `src/game/scenes/GameUI/GameBottomUI.ts` | `ref/GameBottomUI.ts` | 底栏占位 Container + 导出常量 |
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **对称于 TopUI 的占位 Container** | 底部 CTA 区（下载按钮、品牌 logo）需要专属高度预留；与顶栏高度常量对称管理，确保棋盘不侵入两端 UI 区 |
+| **高度从 GameConfig 读取** | 与 `grid_board_layout`、`path_input_handler` 使用同一 `GameConfig.GAME_BOTTOM_UI_BAR_HEIGHT`；单点定义防止底栏高度在多处不一致 |
+
+## Adapter
+
+- **Role**: `bottomUiBar` — 底部 HUD 区域占位容器及高度常量提供者
+- **Provides**: `GameBottomUI` 类、`GAME_BOTTOM_UI_BAR_HEIGHT` 常量（与 GameConfig 同源）
+- **Requires**: `phaser.aicomponent`、`responsive_2d_layout.aicomponent`
+- **Consumed by**: `game_scene.aicomponent`（实例化 BottomUI）、`grid_board_layout.aicomponent`（棋盘可用高度扣减）
+- **Integration point**: `src/game/scenes/GameUI/GameBottomUI.ts` → `Game.create()` 中实例化
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+- `responsive_2d_layout.aicomponent`（硬依赖）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/GameBottomUI.ts
+outputs:
+  - gameBottomUI: GameBottomUI class + GAME_BOTTOM_UI_BAR_HEIGHT constant aligned with GameConfig
+```

package/skills/bottom_ui_bar.aicomponent/manifest.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "atomId": "bottom_ui_bar.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "底部 UI 条", "en": "Bottom UI bar" },
+  "tags": ["ui", "bottom-bar", "hud", "phaser", "layout"],
+  "bindingRoles": ["bottomUiBar"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/GameBottomUI.ts": { "source": "ref/GameBottomUI.ts", "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "layout", "pinAtomId": "responsive_2d_layout.aicomponent", "edgeKind": "requires", "bindAs": "layout" }
+  ],
+  "exports": [
+    { "name": "GameBottomUI", "kind": "class", "location": "src/game/scenes/GameUI/GameBottomUI.ts" },
+    { "name": "GAME_BOTTOM_UI_BAR_HEIGHT", "kind": "constant", "location": "src/game/scenes/GameUI/GameBottomUI.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "bottom band placeholder aligned with GameConfig bottom height; depth above board for future CTA/branding"
+  },
+  "usageHints": [
+    "GAME_BOTTOM_UI_BAR_HEIGHT 与 GameConfig 同源；棋盘计算须扣除同一高度",
+    "屏幕分区与 z-order 优先读 playable_hud_layout.aicomponent"
+  ],
+  "files": { "skill": "SKILL.md", "gameBottomUI": "ref/GameBottomUI.ts" }
+}

package/skills/bottom_ui_bar.aicomponent/ref/GameBottomUI.ts

@@ -0,0 +1,27 @@
+import * as Phaser from "phaser";
+import { computeUiLayout } from "../../utils/UiLayout";
+import { GameConfig } from "../../GameConfig";
+
+/**
+ * 底部 UI 区设计高度（dp），与 `GameConfig.GAME_BOTTOM_UI_BAR_HEIGHT` 同源，
+ * 供棋盘布局、输入边界与本条同时引用，避免魔法数漂移。
+ */
+export const GAME_BOTTOM_UI_BAR_HEIGHT = GameConfig.GAME_BOTTOM_UI_BAR_HEIGHT;
+
+/**
+ * 底部 UI 条占位容器：保留与 `GameConfig` 一致的垂直占位，便于与 `BoardLayout` 扣减对齐。
+ * 可扩展为品牌条、次要 CTA；默认仅透明占位（不占视觉焦点）。
+ */
+export class GameBottomUI extends Phaser.GameObjects.Container {
+  constructor(scene: Phaser.Scene) {
+    super(scene);
+    scene.add.existing(this);
+    this.setDepth(500);
+
+    const { width, height, vScale } = computeUiLayout(scene);
+    const barH = GAME_BOTTOM_UI_BAR_HEIGHT * vScale;
+    const cy = height - barH / 2;
+    const bg = scene.add.rectangle(width / 2, cy, width, barH, 0x000000, 0);
+    this.add(bg);
+  }
+}

package/skills/bubble_shooter.aigameplay/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: bubble_shooter.aigameplay
+description: 泡泡射击消除玩法封包 - 瞄准发射泡泡、消除同色簇、触发悬空掉落的 PGS 实现
+triggers: 泡泡,射击,消除,泡泡龙,bubble,shooter,pop,cluster,aim,cannon,color,弹射,悬空
+---
+
+# bubble_shooter.aigameplay
+
+泡泡射击消除核心玩法封包。实现泡泡射击规则的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer，玩家在底部瞄准发射泡泡，命中相同颜色的连通簇（≥3 个）后整簇消除，与簇相连但悬空的泡泡也随之掉落得分，目标是清空所有泡泡。
+
+## Recipe
+
+- **玩法类型**：bubble_shooter（泡泡射击消除）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `minClusterSize`: 3（≥3 个相连同色泡泡才能触发消除）
+  - `wallBounceEnabled`: true（泡泡可在左右墙壁反弹）
+  - `orphanDropEnabled`: true（失去顶部连接的泡泡自动掉落）
+  - `advanceRowAfterShots`: 5（每发射 5 次后顶部新增一排泡泡）
+  - `colorCount`: 6（泡泡颜色总数）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` 以及**全部分步函数**
+  4. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+  5. 更新 manifest 的 `generation.pgsVersion` 和 `result.outputFile`
+- **可 fork 变体**：
+  - 特殊泡泡：彩虹泡泡（匹配任意颜色）、炸弹泡泡（范围消除）
+  - 六边形网格：将方形网格改为六边形（hex grid）排列
+  - 无限模式：持续生成新排，以 moves 为限制而非清空
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层使用 dispatch() 然后全量重建场景
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+
+// Step 1: 计算弹道轨迹（含反弹）
+const trajectory = calculateTrajectory(state, aimAngle);
+await playBubbleFlyAnimation(trajectory);  // 泡泡沿轨迹飞行动画
+
+// Step 2: 吸附到网格
+const snapPos = snapToGrid(trajectory.landingPosition);
+const boardWithNew = addBubbleToBoard(state.board, snapPos, state.cannon.currentColor);
+
+// Step 3: 查找同色连通簇
+const cluster = findCluster(boardWithNew, snapPos.col, snapPos.row);
+
+if (cluster.length >= state.config.minClusterSize) {
+  // Step 4: 消除整簇
+  const { newState, popped } = popCluster(state, cluster);
+  await playPopAnimation(popped);  // 泡泡爆炸消除动画
+
+  // Step 5: 查找并掉落孤立泡泡
+  const orphans = findOrphans(newState.board);
+  if (orphans.length > 0) {
+    const { finalState, dropped } = dropOrphans(newState, orphans);
+    await playDropAnimation(dropped);  // 泡泡掉落动画
+
+    // Step 6: 计算得分
+    const score = calculateScore(popped.length, dropped.length);
+    updateScoreUI(score);
+  }
+}
+
+// Step 7: 检查推进/胜败
+if (shouldAdvanceBoard(state)) addNewRow();
+if (checkLose(state)) showLosePanel();
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `calculateTrajectory()` | `TrajectoryPoint[]` | 泡泡沿轨迹飞行（含折射点） |
+| `snapToGrid()` | `GridPosition` | 泡泡吸附到最近网格位置 |
+| `findCluster()` | `GridPosition[]` | 高亮显示将要消除的同色簇 |
+| `popCluster()` | `{ newState, popped }` | 泡泡爆炸缩小消失动画 |
+| `findOrphans()` | `GridPosition[]` | 标记将要掉落的孤立泡泡 |
+| `dropOrphans()` | `{ finalState, dropped }` | 孤立泡泡下落消失动画 |
+| `calculateScore()` | `number` | 飘分 + 得分 UI 更新 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/bubble_shooter/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `calculateTrajectory()` / `snapToGrid()` / `findCluster()` / `popCluster()` / `findOrphans()` / `dropOrphans()` / `calculateScore()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a bubble shooter gameplay module following the PGS specification.
+  Write the PGS JSON with entities (board with hex/grid positions, bubbles, cannon with current/next color, score, moves), rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - calculateTrajectory/snapToGrid/findCluster/popCluster/findOrphans/dropOrphans/calculateScore (分步函数，用于渲染层动画驱动)
+  Key constraints:
+    - Bubble trajectory uses angle-based line with wall reflections
+    - Cluster pop requires >= minClusterSize connected same-color bubbles
+    - Orphan detection uses flood-fill from top row; any bubble not reachable = orphan
+    - Win: all bubbles cleared; Lose: any bubble reaches cannon line
+  The step-by-step functions are CRITICAL — the rendering layer (GameScene) must use them to drive animations.
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.