@playcraft/skills 0.0.2

package/skills/candy_tile.aiimage/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: candy_tile.aiimage
+description: 糖果牌面贴图组封包 - 卡通糖果甜品精灵图集，适合休闲三消/对对碰的可爱风格牌面
+triggers: 糖果,candy,甜品,sweet,棒棒糖,lollipop,牌面,tile,三消,可爱,cute,pastel
+---
+
+# candy_tile.aiimage
+
+糖果主题牌面贴图组封包。可爱的糖果甜品图标精灵集，适合女性向休闲游戏。
+
+## Recipe
+
+- **基础 prompt**：`cute candy sweet icons sprite sheet, lollipop gummy bear chocolate cake cupcake cookie ice cream, flat design, pastel colors, transparent background, game assets`
+- **宽高比**：1:1
+- **风格**：cartoon / pastel
+- **图标种类**：棒棒糖、小熊软糖、巧克力、蛋糕、杯子蛋糕、饼干、冰淇淋（共 7 种）
+- **可 fork 变体**：
+  - 节日糖果：圣诞/万圣节主题甜品
+  - 高端甜品：精致马卡龙风格
+
+**生成步骤：**
+1. 生成 512×512 精灵图集
+2. 写入 `tiles.png`，更新 manifest
+
+## Result
+
+- **产物文件**：`tiles.png`
+- **格式**：PNG（透明背景），最小 512×512
+
+## Binding
+
+- **Binding Role**：`tileTextureSet`
+- **挂载目标**：`scene://entities/Board/tileRenderer/tileAtlas`
+- **引用类型**：`sprite-atlas-reference`
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "cute candy sweet icons sprite sheet, lollipop gummy bear chocolate cake cupcake cookie ice cream, flat design, pastel colors, transparent background, game assets" \
+     --aspect-ratio 1:1 \
+     --image-model google/imagen-3.0-generate-002 \
+     --output ta-workspace/raw.png
+
+# 2. 后处理（去白底 + 格式转换）
+playcraft image remove-background --input ta-workspace/raw.png --output ta-workspace/trimmed.png
+playcraft image convert --input ta-workspace/trimmed.png --output ta-workspace/tiles.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are generating a candy/sweet tile sprite sheet for a casual match-3 game.
+  Follow the Recipe to generate cute candy icons as a sprite atlas. Apply the Binding.

package/skills/candy_tile.aiimage/manifest.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "atomId": "candy_tile.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "糖果牌面贴图组",
+    "en": "Candy tile set"
+  },
+  "tags": [
+    "tile",
+    "visual",
+    "candy",
+    "sweet",
+    "match3",
+    "cute",
+    "colorful"
+  ],
+  "bindingRoles": ["tileTextureSet"],
+  "generation": {
+    "kind": "sprite-sheet",
+    "prompt": "cute candy sweet icons sprite sheet, lollipop gummy bear chocolate cake cupcake cookie ice cream, flat design, pastel colors, transparent background, game assets",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "style": "cartoon",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "tiles.png",
+    "format": "png",
+    "constraints": {
+      "minWidth": 512,
+      "minHeight": 512
+    }
+  },
+  "binding": {
+    "role": "tileTextureSet",
+    "target": "scene://entities/Board/tileRenderer/tileAtlas",
+    "type": "sprite-atlas-reference",
+    "constraints": {
+      "format": "png",
+      "minWidth": 512
+    }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/car_parking.aigameplay/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: car_parking.aigameplay
+description: 停车场解谜玩法封包 - 网格滑动解谜，玩家移动车辆解除阻塞，将目标红车移至出口
+triggers: 停车,parking,车,car,滑动,slide,解谜,puzzle,网格,grid,移动,move,阻塞,block,出口,exit
+---
+
+# car_parking.aigameplay
+
+停车场解谜玩法封包。实现停车场滑块解谜规则的 PGS JSON 和 reducer，玩家在网格棋盘上滑动各色车辆（只能沿自身朝向移动），目标是将指定红色目标车移至右侧出口。
+
+## Recipe
+
+- **玩法类型**：car_parking（停车场滑块解谜）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `gridSize`: 6×6（默认，可 config 覆盖）
+  - `slideAxis`: 车辆只能沿自身朝向方向（水平 H / 垂直 V）滑动
+  - `blockedBy`: 其他车辆和棋盘边界均阻挡移动
+  - `targetCarId`: 目标车（红色），抵达右侧出口列则胜利
+  - `exitSide`: right（右侧出口，固定在目标车所在行最右处）
+- **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 变体**：
+  - 更大棋盘：修改 `gridSize` 为 8×8，增加关卡难度
+  - 多出口：在 rules 中添加 multi_exit 支持不同朝向的出口
+  - 有限步数模式：添加 `maxMoves` 限制玩家操作次数
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层直接调用 dispatch() 后全量重建棋盘
+
+正确做法是**分步驱动动画**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 查询车辆可移动范围
+const range = getCarMoveRange(state, carId);
+// range = { minSteps: -2, maxSteps: 3 } 表示可向负方向移2格、正方向移3格
+
+// Step 2: 玩家拖动，计算目标 steps
+const steps = clamp(dragDelta, range.minSteps, range.maxSteps);
+
+// Step 3: 执行移动并播放滑动动画
+const newState = moveCar(state, carId, steps);
+await playSlideAnimation(carId, steps);  // 对该车精灵播放位移 Tween
+
+// Step 4: 检测胜利
+if (checkWin(newState)) { showWinPanel(); }
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `getCarMoveRange()` | `{ minSteps, maxSteps }` | 限制拖动范围，显示可移动提示 |
+| `moveCar()` | `CarParkingState` | 对目标车精灵播放 x/y 位移 Tween |
+| `checkWin()` | `boolean` | 触发红车驶出动画 + 胜利面板 |
+| `isBlocked()` | `boolean` | 显示碰撞反馈（抖动动画） |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/car_parking/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(state, action)` / `getState(state)` / `getCarMoveRange(carId)` / `moveCar(carId, steps)` / `checkWin()` / `isBlocked(carId, direction)`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a car parking puzzle gameplay module following the PGS specification.
+  Write the PGS JSON with entities (board, cars, exit, target_car_id), rules (slide_car, win_check),
+  algorithm, and testCases (at least 3: direct exit, one obstacle, multi-move).
+  Implement reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - getCarMoveRange/moveCar/checkWin/isBlocked (分步函数，用于渲染层动画驱动)
+  Cars can only move along their orientation axis (H=horizontal, V=vertical).
+  Movement is blocked by other cars and board boundaries.
+  Win condition: target car's rightmost cell reaches or passes the exit column.
+  Run all testCases to verify logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.

package/skills/car_parking.aigameplay/manifest.json

@@ -0,0 +1,164 @@
+{
+  "schemaVersion": 1,
+  "atomId": "car_parking.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "停车场解谜玩法",
+    "en": "Car Parking Puzzle gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "puzzle",
+    "parking",
+    "sliding",
+    "grid",
+    "casual"
+  ],
+  "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": "levelDataPack",
+      "description": "关卡数据包",
+      "bindAs": "levels",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "levelDataPack"
+      ],
+      "allowedBundleTypes": [
+        "aiconfig"
+      ]
+    },
+    {
+      "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": "car_parking",
+    "rules": {
+      "gridSize": "6x6",
+      "slideAxis": "orientation",
+      "blockedByWallsAndCars": true,
+      "targetCarId": "red",
+      "exitSide": "right"
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/car_parking/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(state, action)",
+        "getState(state)",
+        "getCarMoveRange(state, carId)",
+        "moveCar(state, carId, steps)",
+        "checkWin(state)",
+        "isBlocked(state, carId, direction)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,163 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 停车场解谜玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "car_parking",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "cols": 6,
+      "rows": 6,
+      "description": "游戏棋盘，默认 6×6 格子，可通过 config 覆盖"
+    },
+    "car": {
+      "type": "sliding-piece",
+      "description": "棋盘上的车辆，占据1×2或1×3格子，水平(H)或垂直(V)朝向",
+      "fields": {
+        "id": "string，车辆唯一标识（如 'red'、'car_1'）",
+        "orientation": "'H'（水平）| 'V'（垂直）",
+        "cells": "Array<{col, row}>，车辆占据的格子坐标列表",
+        "color": "string，车辆颜色/类型",
+        "isTarget": "boolean，是否为目标车（需移至出口）"
+      }
+    },
+    "exit": {
+      "type": "fixed-position",
+      "description": "出口位置，固定在棋盘右侧（col = cols），对应目标车所在行",
+      "fields": {
+        "col": "number，出口列（通常为 cols，即棋盘右边界外）",
+        "row": "number，出口行（与目标车相同行）"
+      }
+    },
+    "targetCarId": {
+      "type": "reference",
+      "description": "目标车的 id，通常为 'red'，需要移动到出口"
+    }
+  },
+  "rules": {
+    "slide_car": {
+      "description": "玩家滑动一辆车，只能沿车辆朝向方向移动（H车只能左右，V车只能上下）",
+      "constraints": [
+        "只能沿自身朝向轴移动",
+        "移动路径上不能有其他车辆",
+        "不能移出棋盘边界（出口方向除外：目标车可移至出口）"
+      ],
+      "steps": 1,
+      "description_detail": "每次操作移动指定格数（steps 可为正负整数，正为右/下，负为左/上）"
+    },
+    "win_check": {
+      "description": "检测目标车是否已到达出口",
+      "condition": "目标车最右端格子（H车）或最下端（V车）的下一格 == exit 位置",
+      "result": "win=true，游戏结束"
+    },
+    "block_check": {
+      "description": "检测某辆车在某方向是否被阻挡",
+      "blockedBy": ["其他车辆占据的格子", "棋盘边界（非出口侧）"]
+    }
+  },
+  "algorithm": {
+    "description": "主循环：玩家选车 → 查询可移动范围 → 滑动 → 胜利检测",
+    "steps": [
+      "1. 玩家选择一辆车",
+      "2. 调用 getCarMoveRange(carId) 获取该车可移动的最大负步数和正步数",
+      "3. 玩家拖动/点击确定移动步数",
+      "4. 调用 moveCar(carId, steps) 执行移动，返回新状态",
+      "5. 调用 checkWin(state) 检测目标车是否抵达出口",
+      "6. 若胜利则显示通关动画；否则继续等待玩家操作"
+    ]
+  },
+  "winCondition": {
+    "type": "target_car_exit",
+    "description": "目标车（isTarget=true）的末端格子越过出口边界"
+  },
+  "loseCondition": {
+    "type": "none_runtime",
+    "description": "无运行时失败条件（解谜设计保证有解）；可选：达到最大步数限制"
+  },
+  "testCases": [
+    {
+      "id": "tc_direct_exit",
+      "description": "直接出口：目标车前方无阻挡，一步移至出口",
+      "initialState": {
+        "board": { "cols": 6, "rows": 6 },
+        "cars": [
+          { "id": "red", "orientation": "H", "cells": [{"col": 3, "row": 2}, {"col": 4, "row": 2}], "color": "red", "isTarget": true }
+        ],
+        "exit": { "col": 6, "row": 2 }
+      },
+      "actions": [
+        { "type": "move_car", "carId": "red", "steps": 2 }
+      ],
+      "expectedState": {
+        "win": true,
+        "cars": [
+          { "id": "red", "cells": [{"col": 5, "row": 2}, {"col": 6, "row": 2}] }
+        ]
+      }
+    },
+    {
+      "id": "tc_one_obstacle",
+      "description": "单障碍：目标车前方有一辆垂直车阻挡，需先移开障碍",
+      "initialState": {
+        "board": { "cols": 6, "rows": 6 },
+        "cars": [
+          { "id": "red", "orientation": "H", "cells": [{"col": 0, "row": 2}, {"col": 1, "row": 2}], "color": "red", "isTarget": true },
+          { "id": "blue", "orientation": "V", "cells": [{"col": 3, "row": 0}, {"col": 3, "row": 1}, {"col": 3, "row": 2}], "color": "blue", "isTarget": false }
+        ],
+        "exit": { "col": 6, "row": 2 }
+      },
+      "actions": [
+        { "type": "move_car", "carId": "blue", "steps": -3 },
+        { "type": "move_car", "carId": "red", "steps": 4 }
+      ],
+      "expectedState": {
+        "win": true,
+        "cars": [
+          { "id": "red", "cells": [{"col": 4, "row": 2}, {"col": 5, "row": 2}] }
+        ]
+      }
+    },
+    {
+      "id": "tc_multi_move",
+      "description": "多步移动：需要移动多辆车才能解开，验证连锁移动逻辑",
+      "initialState": {
+        "board": { "cols": 6, "rows": 6 },
+        "cars": [
+          { "id": "red", "orientation": "H", "cells": [{"col": 0, "row": 2}, {"col": 1, "row": 2}], "color": "red", "isTarget": true },
+          { "id": "car_a", "orientation": "V", "cells": [{"col": 2, "row": 1}, {"col": 2, "row": 2}], "color": "green", "isTarget": false },
+          { "id": "car_b", "orientation": "H", "cells": [{"col": 3, "row": 1}, {"col": 4, "row": 1}], "color": "yellow", "isTarget": false }
+        ],
+        "exit": { "col": 6, "row": 2 }
+      },
+      "actions": [
+        { "type": "move_car", "carId": "car_b", "steps": 1 },
+        { "type": "move_car", "carId": "car_a", "steps": -2 },
+        { "type": "move_car", "carId": "red", "steps": 4 }
+      ],
+      "expectedState": {
+        "win": true
+      }
+    },
+    {
+      "id": "tc_blocked_move",
+      "description": "阻挡移动：车辆无法移动超过障碍物位置",
+      "initialState": {
+        "board": { "cols": 6, "rows": 6 },
+        "cars": [
+          { "id": "red", "orientation": "H", "cells": [{"col": 0, "row": 2}, {"col": 1, "row": 2}], "color": "red", "isTarget": true },
+          { "id": "blocker", "orientation": "V", "cells": [{"col": 3, "row": 2}, {"col": 3, "row": 3}], "color": "purple", "isTarget": false }
+        ],
+        "exit": { "col": 6, "row": 2 }
+      },
+      "actions": [
+        { "type": "move_car", "carId": "red", "steps": 5 }
+      ],
+      "expectedState": {
+        "win": false,
+        "cars": [
+          { "id": "red", "cells": [{"col": 1, "row": 2}, {"col": 2, "row": 2}] }
+        ],
+        "note": "红车只能移到 blocker 左边，最多移动1格到col1-2，而非请求的5格"
+      }
+    }
+  ]
+}