@playcraft/skills 0.0.2

package/skills/big_watermelon.aigameplay/manifest.json

@@ -0,0 +1,155 @@
+{
+  "schemaVersion": 1,
+  "atomId": "big_watermelon.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "合成西瓜玩法",
+    "en": "Big Watermelon (Merge Fruits) gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "merge",
+    "physics",
+    "casual",
+    "drop",
+    "puzzle"
+  ],
+  "bindingRoles": [
+    "gameplayRule"
+  ],
+  "imports": [
+    {
+      "slot": "engine",
+      "pinAtomId": "phaser.aicomponent",
+      "edgeKind": "requires",
+      "bindAs": "engine"
+    },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "bgMusic"
+      ],
+      "allowedBundleTypes": [
+        "aiaudio"
+      ],
+      "constraints": {
+        "loop": true
+      }
+    },
+    {
+      "slot": "background",
+      "description": "游戏背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "backgroundTexture"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "tutorial",
+      "description": "新手引导浮层",
+      "bindAs": "tutorial",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tutorialOverlay"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    },
+    {
+      "slot": "winPanel",
+      "description": "通关反馈面板视觉",
+      "bindAs": "winPanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "successFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "losePanel",
+      "description": "失败反馈面板视觉",
+      "bindAs": "losePanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "failFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "endScreen",
+      "description": "可玩广告结算屏（含 CTA 按钮）",
+      "bindAs": "endScreen",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "playableEndScreenLayout"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "big_watermelon",
+    "rules": {
+      "fruitTiers": 11,
+      "gravity": 980,
+      "containerWidth": 400,
+      "containerHeight": 600,
+      "overflowLine": 80,
+      "nextFruitMaxTier": 5
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/big_watermelon/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "aimFruit(state, x)",
+        "dropFruit(state)",
+        "applyPhysics(state, deltaMs)",
+        "checkMerges(state)",
+        "mergeFruits(state, fruitA, fruitB)",
+        "checkOverflow(state)",
+        "calculateScore(tier)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

package/skills/big_watermelon.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,191 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 合成西瓜玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "big_watermelon",
+  "entities": {
+    "container": {
+      "type": "spatial",
+      "description": "竖向容器，水果在其中下落和堆叠",
+      "fields": {
+        "width": { "type": "number", "default": 400 },
+        "height": { "type": "number", "default": 600 },
+        "overflowLine": { "type": "number", "default": 80, "description": "溢出判定线 y 坐标（从顶部算），水果中心 y < overflowLine 且静止则游戏结束" }
+      }
+    },
+    "fruits": {
+      "type": "entity-list",
+      "description": "容器内所有水果（含下落中和静止的）",
+      "item": {
+        "id": { "type": "string" },
+        "tier": {
+          "type": "number",
+          "range": [1, 11],
+          "description": "水果等级：1=葡萄, 2=樱桃, 3=草莓, 4=橙子, 5=柿子, 6=苹果, 7=梨, 8=桃子, 9=菠萝, 10=椰子, 11=西瓜"
+        },
+        "position": { "type": "vec2", "description": "圆心坐标" },
+        "velocity": { "type": "vec2", "description": "当前速度（px/s）" },
+        "radius": { "type": "number", "description": "碰撞圆半径，随 tier 增大" },
+        "state": { "type": "enum", "values": ["falling", "resting"], "default": "falling" }
+      }
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分"
+    },
+    "nextFruit": {
+      "type": "object",
+      "description": "下一个将要投放的水果预览",
+      "fields": {
+        "tier": { "type": "number", "range": [1, 5], "description": "随机生成，限制在前 5 级" }
+      }
+    },
+    "currentFruit": {
+      "type": "object",
+      "description": "当前正在瞄准（未投放）的水果",
+      "fields": {
+        "tier": { "type": "number" },
+        "x": { "type": "number", "description": "水平瞄准位置" }
+      }
+    }
+  },
+  "rules": {
+    "aim": {
+      "description": "玩家左右移动 currentFruit 的 x 位置",
+      "bounds": "clamp(x, currentFruit.radius, container.width - currentFruit.radius)"
+    },
+    "drop": {
+      "description": "玩家松手投放：currentFruit 转为下落中的 fruit 实体，velocity.y = 0，gravity 开始作用",
+      "effect": "fruits.push(新水果), 生成新的 nextFruit, currentFruit = nextFruit"
+    },
+    "collision_merge": {
+      "description": "两个相同 tier 的水果圆心距 < r1 + r2 时触发合并",
+      "steps": [
+        "1. 移除两个水果（fruits 中删除）",
+        "2. 若 tier < 11：在两圆心中点生成 tier+1 的新水果",
+        "3. 若 tier == 11（西瓜）：score += 特殊大奖励，不生成更大水果",
+        "4. score += calculateScore(tier)"
+      ]
+    },
+    "collision_rest": {
+      "description": "水果碰到容器底部或其他静止水果时速度归零，state 变为 resting",
+      "detection": "简化模拟：position.y + radius >= container.height（触底）或与 resting 水果圆心距 < r1 + r2"
+    },
+    "overflow_check": {
+      "description": "每帧检查：任何 resting 水果圆心 y < overflowLine → gameOver",
+      "note": "falling 状态的水果不触发溢出，只有静止后才检查"
+    },
+    "generate_next": {
+      "description": "投放后随机生成下一个水果",
+      "tierRange": [1, 5],
+      "distribution": "uniform"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：aim → drop → physics → merge → overflow",
+    "steps": [
+      "1. 玩家左右滑动：aimFruit(x) 更新 currentFruit.x",
+      "2. 玩家点击投放：dropFruit() → 创建下落水果，生成 nextFruit",
+      "3. 每帧：applyPhysics(deltaMs)",
+      "   3a. 对所有 falling 水果：velocity.y += gravity * deltaMs / 1000",
+      "   3b. position += velocity * deltaMs / 1000",
+      "   3c. 检测底部碰撞和水果间碰撞，更新 state",
+      "4. checkMerges()：检测所有相同 tier 的两两水果是否碰撞",
+      "   4a. 若碰撞：mergeFruits(fruitA, fruitB)",
+      "5. checkOverflow()：检查是否有 resting 水果超过 overflowLine"
+    ]
+  },
+  "winCondition": {
+    "type": "endless",
+    "description": "无胜利条件，玩法目标为尽可能提高分数"
+  },
+  "loseCondition": {
+    "type": "overflow",
+    "description": "任何静止水果的圆心 y 坐标 < container.overflowLine 时游戏结束"
+  },
+  "testCases": [
+    {
+      "id": "tc_drop_and_rest",
+      "description": "投放水果：水果下落后碰底静止",
+      "initialState": {
+        "container": { "width": 400, "height": 600, "overflowLine": 80 },
+        "fruits": [],
+        "score": 0,
+        "currentFruit": { "tier": 1, "x": 200 },
+        "nextFruit": { "tier": 2 },
+        "config": { "gravity": 980, "fruitRadii": [15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 70] }
+      },
+      "actions": [
+        { "type": "dropFruit" },
+        { "type": "tick", "deltaMs": 1500 }
+      ],
+      "expectedState": {
+        "fruits.length": 1,
+        "fruits[0].state": "resting",
+        "fruits[0].position.y": { "min": 570 },
+        "currentFruit.tier": 2,
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_merge_two_same_tier",
+      "description": "合并同级水果：两个等级1的水果接触后合并为等级2",
+      "initialState": {
+        "container": { "width": 400, "height": 600, "overflowLine": 80 },
+        "fruits": [
+          { "id": "f1", "tier": 1, "position": { "x": 200, "y": 560 }, "velocity": { "x": 0, "y": 0 }, "radius": 15, "state": "resting" },
+          { "id": "f2", "tier": 1, "position": { "x": 226, "y": 560 }, "velocity": { "x": 0, "y": 0 }, "radius": 15, "state": "resting" }
+        ],
+        "score": 0,
+        "currentFruit": { "tier": 3, "x": 100 },
+        "nextFruit": { "tier": 1 }
+      },
+      "actions": [
+        { "type": "checkMerges" }
+      ],
+      "expectedState": {
+        "fruits.length": 1,
+        "fruits[0].tier": 2,
+        "score": { "min": 10 }
+      }
+    },
+    {
+      "id": "tc_overflow_game_over",
+      "description": "溢出失败：静止水果堆积超过顶线，游戏结束",
+      "initialState": {
+        "container": { "width": 400, "height": 600, "overflowLine": 80 },
+        "fruits": [
+          { "id": "f1", "tier": 5, "position": { "x": 200, "y": 60 }, "velocity": { "x": 0, "y": 0 }, "radius": 35, "state": "resting" }
+        ],
+        "score": 500,
+        "currentFruit": { "tier": 1, "x": 200 },
+        "nextFruit": { "tier": 2 }
+      },
+      "actions": [
+        { "type": "checkOverflow" }
+      ],
+      "expectedState": {
+        "gameOver": true,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_aim_clamped",
+      "description": "边界钳制：瞄准位置不能超出容器边界",
+      "initialState": {
+        "container": { "width": 400, "height": 600, "overflowLine": 80 },
+        "fruits": [],
+        "score": 0,
+        "currentFruit": { "tier": 1, "x": 200 },
+        "nextFruit": { "tier": 2 },
+        "config": { "fruitRadii": [15] }
+      },
+      "actions": [
+        { "type": "aimFruit", "x": -50 }
+      ],
+      "expectedState": {
+        "currentFruit.x": 15
+      }
+    }
+  ]
+}

package/skills/big_watermelon.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,202 @@
+/**
+ * big_watermelon.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部跑完整个物理帧 + 合并检测后只返回最终状态，
+ * 中间过程（每帧位置更新、合并特效触发位置、新水果生成点）全部丢失。
+ *
+ * 渲染层需要逐帧同步精灵位置、播放合并特效、实时更新分数，
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间同步物理引擎和渲染状态。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *
+ * ⚠️ 物理集成说明：
+ * 此 reducer 提供简化物理模拟（圆形碰撞体、重力积分）。
+ * 实际项目推荐将物理计算交给 Matter.js 或 Phaser Arcade Physics，
+ * 每帧结束后将物理引擎的位置/速度数据写回 state.fruits。
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type Vec2 = { x: number; y: number };
+
+export type BigWatermelonConfig = {
+  /** 容器宽度（px） */
+  containerWidth: number;
+  /** 容器高度（px） */
+  containerHeight: number;
+  /** 溢出判定线（距顶部 y 坐标，px） */
+  overflowLine: number;
+  /** 重力加速度（px/s²） */
+  gravity: number;
+  /** 每个等级水果的半径（索引 0 = tier 1） */
+  fruitRadii: [number, number, number, number, number, number, number, number, number, number, number];
+  /** 下一个水果的最大等级（随机范围 1~nextFruitMaxTier） */
+  nextFruitMaxTier: number;
+  /** 弹性系数（碰撞时速度保留比例，0~1） */
+  restitution: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type BigWatermelonAction =
+  | { type: 'aimFruit'; x: number }
+  | { type: 'dropFruit' }
+  | { type: 'tick'; deltaMs: number }
+  | { type: 'checkMerges' }
+  | { type: 'checkOverflow' }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type FruitPhysicsState = 'falling' | 'resting';
+
+export type Fruit = {
+  id: string;
+  /** 水果等级 1~11 */
+  tier: number;
+  /** 圆心坐标 */
+  position: Vec2;
+  /** 速度（px/s） */
+  velocity: Vec2;
+  /** 碰撞圆半径 */
+  radius: number;
+  state: FruitPhysicsState;
+};
+
+export type BigWatermelonState = {
+  fruits: Fruit[];
+  score: number;
+  currentFruit: {
+    tier: number;
+    x: number;
+    radius: number;
+  };
+  nextFruit: {
+    tier: number;
+  };
+  gameOver: boolean;
+  win: false;
+  lastMergeEvents: MergeEvent[];
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+export type MergeEvent = {
+  fruitAId: string;
+  fruitBId: string;
+  mergedTier: number;
+  mergePos: Vec2;
+  scoreGained: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: BigWatermelonConfig): BigWatermelonState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: BigWatermelonState, action: BigWatermelonAction): BigWatermelonState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: BigWatermelonState): BigWatermelonState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * aimFruit：玩家左右移动当前水果的水平位置
+ * 场景层根据返回的 currentFruit 更新瞄准线和预览水果精灵 x 坐标
+ *
+ * x 会被钳制在 [radius, containerWidth - radius] 范围内
+ */
+export declare function aimFruit(
+  state: BigWatermelonState,
+  x: number,
+): { currentFruit: BigWatermelonState['currentFruit'] };
+
+/**
+ * dropFruit：投放当前水果，生成下一个预览水果
+ * 场景层创建物理刚体，设置初始速度 y=0，开始受重力影响
+ */
+export declare function dropFruit(
+  state: BigWatermelonState,
+): {
+  droppedFruit: Fruit;
+  nextFruit: BigWatermelonState['nextFruit'];
+};
+
+/**
+ * applyPhysics：推进物理模拟一帧
+ * 对所有 falling 状态的水果：
+ *   - velocity.y += gravity * deltaMs / 1000
+ *   - position += velocity * deltaMs / 1000
+ *   - 检测底部和容器壁碰撞
+ *   - 检测与 resting 水果的碰撞，碰撞后 state = resting
+ *
+ * 场景层根据返回的 fruits 数组逐个更新精灵位置（x, y）
+ */
+export declare function applyPhysics(
+  state: BigWatermelonState,
+  deltaMs: number,
+): Fruit[];
+
+/**
+ * checkMerges：检测所有相同 tier 的水果是否发生碰撞触发合并
+ * 返回所有合并事件，场景层根据 mergePos 播放合并特效
+ *
+ * 合并规则：两个圆心距 < r1 + r2，且 tier 相同
+ * 合并结果：移除两个旧水果，在 mergePos 生成 tier+1 新水果
+ */
+export declare function checkMerges(
+  state: BigWatermelonState,
+): MergeEvent[];
+
+/**
+ * mergeFruits：执行一次具体的合并操作
+ * 场景层在播放合并动画（两球缩小 → 中点生成新球）后调用
+ */
+export declare function mergeFruits(
+  state: BigWatermelonState,
+  fruitAId: string,
+  fruitBId: string,
+): {
+  newFruit: Fruit;
+  score: number;
+};
+
+/**
+ * checkOverflow：检查是否有静止水果超过溢出线
+ * 场景层在每次水果静止后调用
+ * gameOver=true 时场景层触发失败面板动画
+ */
+export declare function checkOverflow(
+  state: BigWatermelonState,
+): { gameOver: boolean; overflowFruitId: string | null };
+
+/**
+ * calculateScore：计算合并该等级水果所得的分数
+ * 公式建议：tier^2 * 10（等级越高得分指数级增长）
+ */
+export declare function calculateScore(tier: number): number;

package/skills/block_puzzle.aigameplay/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: block_puzzle.aigameplay
+description: 方块放置消行玩法封包 - 经典俄罗斯方块变体的 PGS 实现，在网格上放置多米诺方块消除整行/整列
+triggers: 方块放置,block puzzle,消行,消列,方块,polyomino,放置,placement,棋盘,grid,玩法,gameplay
+---
+
+# block_puzzle.aigameplay
+
+方块放置消行玩法封包。实现经典方块放置规则的 PGS JSON 和 reducer，玩家从 3 个候选方块中选择并放置在 10×10 网格上，当一行或一列完全填满时自动消除并得分。
+
+## Recipe
+
+- **玩法类型**：block_puzzle（方块放置消行）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `boardSize`: 10×10（默认网格大小）
+  - `pieceSlots`: 3（每次提供 3 个候选方块）
+  - `rotation`: false（方块不可旋转）
+  - `gravity`: false（方块放下后不下落，固定在放置位置）
+  - `clearFullLines`: true（填满整行立即消除）
+  - `clearFullColumns`: true（填满整列立即消除）
+- **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 变体**：
+  - 更大棋盘：修改 `boardCols`/`boardRows` 至 8×8 或 12×12
+  - 允许旋转：修改 `rotation` 为 true，增加旋转规则
+  - 限时模式：添加 `timeLimitSeconds` 规则
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层使用 dispatch() 然后全量重建棋盘
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 验证放置是否合法（拖拽过程中实时高亮）
+const canPlace = canPlacePiece(state, selectedPiece, position);
+highlightCells(canPlace ? 'valid' : 'invalid', selectedPiece, position);
+
+// Step 2: 放置方块，固定到棋盘
+const { placedCells, newState } = placePiece(state, selectedPiece, position);
+await playPlaceAnimation(placedCells);  // 只对新放置的格子播放落地动画
+
+// Step 3: 检测并消除完整行/列
+const { clearedRows, clearedCols, score } = clearLines(newState);
+if (clearedRows.length > 0 || clearedCols.length > 0) {
+  await playClearAnimation(clearedRows, clearedCols);  // 播放消除闪光动画
+  updateScoreUI(score);
+}
+
+// Step 4: 补充新方块（若已用完 3 个槽位）
+if (newState.pieceQueue.length === 0) {
+  const newPieces = generatePieces(3, config.colorCount);
+  updatePieceTray(newPieces);
+}
+
+// Step 5: 检测游戏结束
+const gameOver = newState.pieceQueue.every(p => !canPlaceAnywhere(newState, p));
+if (gameOver) { playGameOverAnimation(); }
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `canPlacePiece()` | `boolean` | 实时高亮放置区域（绿色/红色遮罩） |
+| `placePiece()` | `{ placedCells, newState }` | 对新放置的格子播放落地震动/缩放动画 |
+| `clearLines()` | `{ clearedRows, clearedCols, score, clearedCells }` | 对被消除的行/列播放消除闪光 + 消失动画 |
+| `generatePieces()` | `Piece[]` | 新方块滑入候选区动画 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/block_puzzle/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(state, action)` / `getState(state)` / `canPlacePiece()` / `placePiece()` / `clearLines()` / `generatePieces()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a block puzzle (placement) core gameplay module following the PGS specification.
+  Write the PGS JSON with entities, rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - canPlacePiece/placePiece/clearLines/generatePieces (分步函数，用于渲染层动画驱动)
+  Key constraints:
+    - Board is 10×10 by default; pieces are polyomino shapes (collections of cells)
+    - No rotation, no gravity — pieces are fixed at placement position
+    - Clear full rows AND full columns simultaneously
+    - Score multiplier when multiple lines cleared at once
+    - Lose when none of the 3 available pieces can be placed anywhere on the board
+    - After all 3 pieces are used, generate 3 new random pieces
+  The step-by-step functions are CRITICAL for drag-to-place and clear animations.
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.