@playcraft/skills 0.0.2

package/skills/app_metadata.aiconfig/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: app_metadata.aiconfig
+description: 应用元数据配置。定义试玩广告 Loading 页面中展示的应用标题、描述文案、评分、评论数量等文本信息。
+triggers: 需要定制 Loading 页面文案信息或应用品牌描述时触发。
+---
+
+# 应用元数据配置（App Metadata Config）
+
+## 说明
+
+Loading 页面展示的应用文案信息：
+
+- `APP_TITLE`：应用名称（如 "Arrow Puzzle"）
+- `APP_DESC`：应用描述（如 "Match all the arrows to win!"）
+- `APP_STARS`：星评（如 "4.8"）
+- `APP_REVIEWS_COUNT`：评论数（如 "10K+"）
+
+## Recipe
+
+```json
+{
+  "kind": "config-patch",
+  "params": {
+    "APP_TITLE": "Arrow Puzzle",
+    "APP_DESC": "Match all the arrows to win!",
+    "APP_STARS": "4.8"
+  }
+}
+```
+
+## Result
+
+写入 `src/game/scenes/LoadingConfig.ts` 中对应常量。
+
+## Binding
+
+```json
+{
+  "role": "appMetadata",
+  "target": "src/game/scenes/LoadingConfig.ts"
+}
+```
+
+## Skill Definition
+
+```yaml
+tools:
+  - write_file
+inputs:
+  - params: APP_TITLE, APP_DESC, APP_STARS, APP_REVIEWS_COUNT
+outputs:
+  - config: app metadata constants for loading screen
+```

package/skills/app_metadata.aiconfig/manifest.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "atomId": "app_metadata.aiconfig",
+  "bundleType": "aiconfig",
+  "category": "config",
+  "mode": "parametric",
+  "label": { "zh": "应用元数据配置", "en": "App metadata config" },
+  "tags": ["config", "metadata", "app-title", "app-desc", "stars", "loading-page"],
+  "bindingRoles": ["appMetadata"],
+  "generation": {
+    "kind": "config-patch",
+    "params": {
+      "APP_TITLE": "Arrow Puzzle",
+      "APP_DESC": "Match all the arrows to win!",
+      "APP_STARS": "4.8",
+      "APP_REVIEWS_COUNT": "10K+"
+    }
+  },
+  "result": {
+    "configKey": "app.metadata",
+    "format": "json-patch",
+    "constraints": { "requiredKeys": ["APP_TITLE", "APP_DESC", "APP_STARS"] }
+  },
+  "binding": {
+    "role": "appMetadata",
+    "target": "src/game/scenes/LoadingConfig.ts",
+    "type": "config-key-value"
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/appear_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: appear_sfx.aiaudio
+description: 关卡加载时路径出现在棋盘上的音效。
+triggers: 需要生成路径出现动画音效时触发。
+---
+
+# 路径出现音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`appear.mp3`
+- 在 Preloader.ts 中作为 `sfxAppear` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxAppear",
+  "target": "assets/sounds/appear.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "whoosh or spawn sound for game path appearing on board" \
+     --duration 1 \
+     --output ta-workspace/raw_sfx.mp3
+
+# 2. 归一化音量
+playcraft audio normalize --input ta-workspace/raw_sfx.mp3 --output ta-workspace/raw_sfx.mp3 --target-loudness -16
+
+# 3. 压缩（SFX 目标 ≤15KB）
+playcraft audio compress --input ta-workspace/raw_sfx.mp3 --output ta-workspace/appear.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: appear.mp3
+```

package/skills/appear_sfx.aiaudio/manifest.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "atomId": "appear_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "路径出现音效",
+    "en": "Path appear SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "appear",
+    "spawn",
+    "path"
+  ],
+  "bindingRoles": [
+    "sfxAppear"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "whoosh or spawn sound for game path appearing on board",
+    "duration": 1,
+    "loop": false,
+    "referenceAudio": "ref/appear.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/appear.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 1
+    }
+  },
+  "binding": {
+    "role": "sfxAppear",
+    "target": "assets/sounds/appear.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/appear.mp3"
+  }
+}

package/skills/arrow_move_error_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: arrow_move_error_sfx.aiaudio
+description: 无效的路径操作时的轻微错误提示音效。
+triggers: 需要生成箭头/路径操作无效提示音效时触发。
+---
+
+# 箭头移动错误音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`arrow_move_error.mp3`
+- 在 Preloader.ts 中作为 `sfxArrowMoveError` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxArrowMoveError",
+  "target": "assets/sounds/arrow_move_error.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "subtle error sound for invalid arrow interaction in puzzle game" \
+     --duration 1 \
+     --output ta-workspace/raw_sfx.mp3
+
+# 2. 归一化音量
+playcraft audio normalize --input ta-workspace/raw_sfx.mp3 --output ta-workspace/raw_sfx.mp3 --target-loudness -16
+
+# 3. 压缩（SFX 目标 ≤15KB）
+playcraft audio compress --input ta-workspace/raw_sfx.mp3 --output ta-workspace/arrow_move_error.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: arrow_move_error.mp3
+```

package/skills/arrow_move_error_sfx.aiaudio/manifest.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "atomId": "arrow_move_error_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "箭头移动错误音效",
+    "en": "Arrow move error SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "arrow",
+    "error",
+    "invalid"
+  ],
+  "bindingRoles": [
+    "sfxArrowMoveError"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "subtle error sound for invalid arrow interaction in puzzle game",
+    "duration": 1,
+    "loop": false,
+    "referenceAudio": "ref/arrow_move_error.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/arrow_move_error.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 1
+    }
+  },
+  "binding": {
+    "role": "sfxArrowMoveError",
+    "target": "assets/sounds/arrow_move_error.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/arrow_move_error.mp3"
+  }
+}

package/skills/arrow_path_data_format.aicomponent/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: arrow_path_data_format.aicomponent
+description: 路径消除玩法的关卡数据格式定义（TypeScript 类型）和解析器。定义 RawLevelJson（Cocos 导出格式）→ ParsedLevel（Phaser 可用格式）的转换，包含坐标系翻转和路径离散化。
+triggers: 需要定义或解析路径消除类玩法的关卡数据结构时触发。
+---
+
+# 箭头路径关卡数据格式（Arrow Path Data Format）
+
+## 说明
+
+本 skill 提供路径消除玩法所需的全套关卡数据类型和解析逻辑：
+
+- `RawLevelJson`：关卡原始 JSON 格式（从 Cocos Creator 导出，y 轴向上）
+- `ParsedLevel`：解析后供 Phaser 使用的规范化格式（y 轴向下）
+- `LevelPath`：解析后的单条路径（含离散格子索引、方向箭头）
+- `parseLevelJson()`：负责坐标翻转、路径离散化、颜色提取
+
+## Scaffold
+
+向 Remix 项目贡献以下文件：
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/levels/LevelTypes.ts` | `ref/LevelTypes.ts` | 全套类型定义（GridPoint / ArrowDirection / LevelPath / RawLevelJson / ParsedLevel / ThemeVariantConfig） |
+| `src/game/levels/LevelParser.ts` | `ref/LevelParser.ts` | `parseLevelJson()` 解析函数 |
+
+## Imports
+
+本 skill 无外部依赖（纯数据结构，不依赖 Phaser 或其他 skill）。
+
+## 关键类型
+
+### RawLevelJson（原始关卡格式）
+
+```typescript
+type RawLevelJson = {
+  name: number | string;       // 关卡序号
+  row: number;                 // 棋盘行数
+  col: number;                 // 棋盘列数
+  arrows: (number | string)[][][]; // 路径点数组（Cocos 格式，y 向上）
+  levelTime: number;           // 关卡时限（秒，0 = 无时限）
+  background?: { imageKey, dataUrl?, opacity? };
+};
+```
+
+### ParsedLevel（规范化格式）
+
+```typescript
+type ParsedLevel = {
+  index: number;               // 关卡序号
+  rows: number;
+  cols: number;
+  paths: LevelPath[];          // 解析后的所有路径
+  timeSeconds: number;         // 关卡时限
+  background?: { imageKey, dataUrl?, opacity? };
+};
+
+type LevelPath = {
+  points: GridPoint[];         // 路径拐角点坐标（Phaser 坐标系，y 向下）
+  head: GridPoint;             // 箭头末端格子
+  direction: ArrowDirection;   // 箭头方向（从末段方向推导）
+  indices: number[];           // 覆盖的所有格子的 row-major 索引（y * cols + x）
+  color?: string;              // 路径颜色（十六进制字符串）
+};
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **两格式设计** | `RawLevelJson`（Cocos 导出格式）与 `ParsedLevel`（游戏可用格式）分离，保留原始数据可溯源；`parseLevelJson()` 在边界统一处理坐标翻转和离散化，不让业务层感知格式差异 |
+| **Y 轴翻转集中在解析层** | Cocos 坐标系 y 向上，Phaser/Three.js 坐标系 y 向下；在解析器统一翻转，其他所有组件只需使用 Phaser 坐标系，不再各自处理 |
+| **路径离散化（indices 数组）** | 预计算路径覆盖的所有格子索引，避免碰撞检测时重复计算；`indices` 是 row-major 线性索引，方便 Set 查找 |
+| **纯数据结构，无引擎依赖** | 类型定义和解析器不依赖 Phaser；可在 Node.js 测试环境（vitest）中直接使用 |
+
+## Adapter
+
+- **Role**: `levelDataFormat` — 路径消除玩法关卡数据类型定义与解析器
+- **Provides**: `RawLevelJson`、`ParsedLevel`、`LevelPath`、`GridPoint`、`ArrowDirection` 类型，`parseLevelJson()` / `parseLevelFor3D()` 函数
+- **Requires**: 无（纯数据结构，无运行时依赖）
+- **Consumed by**: `level_state.aicomponent`（LevelManager 加载关卡）、`path_renderer.aicomponent`（绘制 ParsedLevel.paths）、`path_input_handler.aicomponent`（输入判断）、`level_data_validator.aivalidator`、`gameplay_unit_test.aivalidator`
+- **Integration point**: `src/game/levels/LevelTypes.ts` + `src/game/levels/LevelParser.ts` —— 所有使用关卡数据的组件从此处 import 类型
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/levels/LevelTypes.ts
+  - source: src/game/levels/LevelParser.ts
+outputs:
+  - levelTypes: GridPoint / ArrowDirection / LevelPath / RawLevelJson / ParsedLevel / ThemeVariantConfig
+  - levelParser: parseLevelJson() function
+```
+
+## 注意事项
+
+- Cocos 坐标系 y 轴向上（0 在底部），Phaser 坐标系 y 轴向下（0 在顶部）
+- `parseLevelJson()` 在解析时自动完成翻转：`phaserY = rows - 1 - cocosY`
+- `indices` 数组包含路径覆盖的所有格子（含中间格），用于碰撞检测
+
+## 3D 坐标系支持（Three.js）
+
+本 skill 支持两种坐标系输出：
+
+| 坐标系 | 适用引擎 | 说明 |
+|--------|---------|------|
+| `phaser-y-down` | Phaser 3 | 2D 屏幕坐标，y 轴向下，单位为像素 |
+| `threejs-xz` | Three.js | 3D XZ 平面坐标，X 向右 / Z 向下（俯视），Y=0 |
+
+### 坐标映射关系
+
+由于 Phaser 的 `(x, y_down)` 和 Three.js 俯视的 `(x, z_down)` 语义一致：
+- Phaser `GridPoint.x` → Three.js `position.x`
+- Phaser `GridPoint.y` → Three.js `position.z`
+- Three.js `position.y` 固定为 0（地面高度）
+
+### 方向角度映射
+
+| Direction | 2D (rotation, 图片朝上) | 3D (rotation.y, 模型朝+Z) |
+|-----------|----------------------|--------------------------|
+| Up | 0 | π |
+| Right | π/2 | π/2 |
+| Down | π | 0 |
+| Left | -π/2 | -π/2 |
+
+### 使用示例（Three.js）
+
+```typescript
+import { parseLevelFor3D } from "./LevelParser";
+import { directionToAngleY, directionToDelta3D } from "./LevelTypes";
+import type { GridPoint, LevelPath } from "./LevelTypes";
+
+const level = parseLevelFor3D(rawJson);
+const cellSize = 1.0; // Three.js 世界单位
+
+// 将 GridPoint 转为世界坐标
+function cellToWorld(pt: GridPoint): { x: number; y: number; z: number } {
+  return { x: pt.x * cellSize, y: 0, z: pt.y * cellSize };
+}
+
+// 设置模型方向
+mesh.rotation.y = directionToAngleY(path.direction);
+
+// 计算滑出位移
+const delta = directionToDelta3D(path.direction);
+const slideDistance = stepsToExit * cellSize;
+mesh.position.x += delta.dx * slideDistance;
+mesh.position.z += delta.dz * slideDistance;
+```

package/skills/arrow_path_data_format.aicomponent/manifest.json

@@ -0,0 +1,57 @@
+{
+  "schemaVersion": 1,
+  "atomId": "arrow_path_data_format.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": { "zh": "箭头路径关卡数据格式", "en": "Arrow path level data format" },
+  "tags": ["level-data", "parser", "types", "json", "path", "arrow", "cocos-format", "threejs", "3d", "xz-plane"],
+  "bindingRoles": ["levelDataFormat"],
+  "coordinateSystems": ["phaser-y-down", "threejs-xz"],
+  "scaffold": {
+    "files": {
+      "src/game/levels/LevelTypes.ts": {
+        "source": "ref/LevelTypes.ts",
+        "mode": "full",
+        "weight": 10
+      },
+      "src/game/levels/LevelParser.ts": {
+        "source": "ref/LevelParser.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "exports": [
+    { "name": "GridPoint",         "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "ArrowDirection",    "kind": "enum",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "LevelPath",         "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "RawLevelJson",      "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "ParsedLevel",       "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "ThemeVariantConfig","kind": "interface","location": "src/game/levels/LevelTypes.ts" },
+    { "name": "parseLevelJson",    "kind": "function", "location": "src/game/levels/LevelParser.ts" },
+    { "name": "CoordinateSystem",  "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "GridPoint3D",       "kind": "type",     "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "directionToAngleY", "kind": "function", "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "directionToDelta3D","kind": "function", "location": "src/game/levels/LevelTypes.ts" },
+    { "name": "parseLevelFor3D",   "kind": "function", "location": "src/game/levels/LevelParser.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "structured data types for a grid-based level format with polyline paths and directional arrowheads",
+    "layers": ["data-schema", "json-parser", "coordinate-transform"],
+    "replaceable": ["coordinate system convention", "JSON format flavor"]
+  },
+  "usageHints": [
+    "RawLevelJson 是从 Cocos Creator 导出的原始关卡 JSON 格式（y 轴向上）",
+    "parseLevelJson() 负责将 Cocos 坐标翻转为 Phaser 坐标（y 从上往下）",
+    "ParsedLevel.paths 是已经离散化的路径，包含 indices（格子索引）和 direction",
+    "支持两种坐标系：phaser-y-down（2D 屏幕）和 threejs-xz（3D XZ 平面），通过 parseLevelFor3D() 解析",
+    "directionToAngleY() 提供 Three.js Y 轴旋转角度映射，假设模型默认朝向 +Z",
+    "directionToDelta3D() 提供 3D 方向位移向量，用于计算滑出路径"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "levelTypes": "ref/LevelTypes.ts",
+    "levelParser": "ref/LevelParser.ts"
+  }
+}