@playcraft/skills 0.0.2

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

@@ -0,0 +1,179 @@
+/**
+ * merge_core.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成合并、升级、自动生成全流程后
+ * 只返回最终状态，中间过程（哪两个物品合并了、升级动画坐标、
+ * 新生成的物品位置）全部丢失。
+ *
+ * 渲染层需要分步动画（拖动飞向目标 → 合并升级光效 → 新物品弹出），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、自动求解等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type MergeConfig = {
+  /** 棋盘列数，默认 5 */
+  cols: number;
+  /** 棋盘行数，默认 5 */
+  rows: number;
+  /** 最高等级（达到后胜利），默认 9 */
+  maxTier: number;
+  /** 是否在每次合并后自动生成新物品 */
+  autoSpawn: boolean;
+  /** 自动生成的物品等级，默认 1 */
+  spawnTier: number;
+  /** 相邻方式：正交（上下左右）或全方向（含斜角） */
+  adjacency: 'orthogonal' | 'all';
+  /** 目标分数（score_goal 模式），可选 */
+  goalScore?: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type MergeAction =
+  | { type: 'merge'; from: { col: number; row: number }; to: { col: number; row: number } }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+/** 棋盘格子：null 表示空，number 表示物品等级（1 ~ maxTier） */
+export type GridCell = number | null;
+
+export type MergeState = {
+  /** 棋盘，board[col][row] */
+  board: GridCell[][];
+  /** 当前得分 */
+  score: number;
+  /** 已操作次数 */
+  moves: number;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 上一次合并是否被拒绝 */
+  lastMergeRejected: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 格子坐标 */
+export type GridPos = { col: number; row: number };
+
+/** 合并结果 */
+export type MergeResult = {
+  /** 被移除的源格子坐标 */
+  removedFrom: GridPos;
+  /** 升级后的目标格子坐标和新等级 */
+  mergedItem: { pos: GridPos; tier: number };
+  /** 新状态 */
+  newState: MergeState;
+};
+
+/** 自动生成的物品 */
+export type SpawnedItem = {
+  pos: GridPos;
+  tier: number;
+} | null;
+
+/** 可合并对 */
+export type MergePair = {
+  from: GridPos;
+  to: GridPos;
+  tier: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ * - 创建空棋盘
+ * - 随机在部分空格生成 spawnTier 物品（初始填充约 1/3 棋盘）
+ */
+export declare function init(config: MergeConfig): MergeState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - merge：验证并执行合并，自动生成新物品，检测胜败
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: MergeState, action: MergeAction): MergeState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: MergeState): MergeState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * canMerge：检测 from 格子的物品是否可以合并到 to 格子
+ *
+ * 合法条件：
+ * 1. from 和 to 都有物品（非 null）
+ * 2. from 和 to 的物品等级相同
+ * 3. from 和 to 在配置允许的相邻范围内（正交或全方向）
+ * 4. 合并后等级不超过 maxTier（或恰好 = maxTier 触发胜利）
+ *
+ * 场景层在拖拽过程中实时调用，用于高亮合法/非法目标格子。
+ */
+export declare function canMerge(
+  state: MergeState,
+  from: GridPos,
+  to: GridPos,
+  config: MergeConfig,
+): boolean;
+
+/**
+ * mergeItems：执行合并（不做合法性验证，调用前请先确认 canMerge）
+ *
+ * 合并逻辑：移除 from 格子的物品，将 to 格子的物品等级 +1。
+ * 场景层在拖拽释放后调用，播放飞入合并动画。
+ */
+export declare function mergeItems(
+  state: MergeState,
+  from: GridPos,
+  to: GridPos,
+  config: MergeConfig,
+): MergeResult;
+
+/**
+ * spawnItem：在棋盘随机空格生成 spawnTier 等级的新物品
+ *
+ * 若棋盘没有空格，返回 null。
+ * 场景层根据返回值在对应格子播放物品弹出缩放动画。
+ */
+export declare function spawnItem(
+  state: MergeState,
+  config: MergeConfig,
+): SpawnedItem;
+
+/**
+ * findMergablePairs：返回当前棋盘上所有可合并的物品对
+ *
+ * 场景层用途：
+ * - 空数组 + 棋盘满 → 触发游戏结束
+ * - Hint 功能：高亮推荐的下一步合并对
+ */
+export declare function findMergablePairs(
+  state: MergeState,
+  config: MergeConfig,
+): MergePair[];

package/skills/mistake_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: mistake_sfx.aiaudio
+description: 路径被阻挡时的错误提示音效（较轻，非扣命音效）。
+triggers: 需要生成路径阻挡错误提示音效时触发。
+---
+
+# 阻挡错误音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`mistake.mp3`
+- 在 Preloader.ts 中作为 `sfxMistake` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxMistake",
+  "target": "assets/sounds/mistake.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "error buzzer sound for hitting a blocked path 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/mistake.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: mistake.mp3
+```

package/skills/mistake_sfx.aiaudio/manifest.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "atomId": "mistake_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "阻挡失败音效",
+    "en": "Blocked path mistake SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "mistake",
+    "blocked",
+    "error"
+  ],
+  "bindingRoles": [
+    "sfxMistake"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "error buzzer sound for hitting a blocked path in puzzle game",
+    "duration": 1,
+    "loop": false,
+    "referenceAudio": "ref/mistake.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/mistake.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 1
+    }
+  },
+  "binding": {
+    "role": "sfxMistake",
+    "target": "assets/sounds/mistake.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/mistake.mp3"
+  }
+}

package/skills/nomove_hint_overlay.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nomove_hint_overlay.aiimage
+description: 点击阻挡路径扣命时的全屏红色警告闪光遮罩图片。
+triggers: 需要生成危险警告全屏遮罩图片时触发。
+---
+
+# 危险闪光全屏遮罩
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`nomove_hint.webp`
+- 在 Preloader.ts 中作为 `dangerFlashOverlay` key 加载
+
+## Binding
+
+```json
+{
+  "role": "dangerFlashOverlay",
+  "target": "assets/nomove_hint.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "full screen red danger flash overlay, semi-transparent, warning indicator for game failure" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/nomove_hint.png \
+     --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/nomove_hint.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: nomove_hint.webp
+```

package/skills/nomove_hint_overlay.aiimage/manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "atomId": "nomove_hint_overlay.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "危险闪光全屏遮罩",
+    "en": "Danger flash overlay"
+  },
+  "tags": [
+    "visual",
+    "danger",
+    "flash",
+    "overlay",
+    "warning",
+    "full-screen"
+  ],
+  "bindingRoles": [
+    "dangerFlashOverlay"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "full screen red danger flash overlay, semi-transparent, warning indicator for game failure",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/nomove_hint.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/nomove_hint.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 750,
+      "minHeight": 1334
+    }
+  },
+  "binding": {
+    "role": "dangerFlashOverlay",
+    "target": "assets/nomove_hint.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/nomove_hint.webp",
+    "assetPng": "ref/nomove_hint.png"
+  }
+}

package/skills/normal_dot.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: normal_dot.aiimage
+description: 路径消除轨迹动画中使用的普通粒子图片。
+triggers: 需要生成路径消除轨迹粒子图片时触发。
+---
+
+# 普通粒子
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`normal_dot.webp`
+- 在 Preloader.ts 中作为 `normalParticleAsset` key 加载
+
+## Binding
+
+```json
+{
+  "role": "normalParticleAsset",
+  "target": "assets/normal_dot.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "small neutral dot particle for path elimination trail animation" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/normal_dot.png \
+     --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/normal_dot.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: normal_dot.webp
+```

package/skills/normal_dot.aiimage/manifest.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": 1,
+  "atomId": "normal_dot.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "普通粒子",
+    "en": "Normal particle dot"
+  },
+  "tags": [
+    "visual",
+    "particle",
+    "dot",
+    "trail"
+  ],
+  "bindingRoles": [
+    "normalParticleAsset"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "small neutral dot particle for path elimination trail animation",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/normal_dot.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/normal_dot.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 32,
+      "minHeight": 32
+    }
+  },
+  "binding": {
+    "role": "normalParticleAsset",
+    "target": "assets/normal_dot.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/normal_dot.webp",
+    "assetPng": "ref/normal_dot.png"
+  }
+}

package/skills/ocean.aiimage/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ocean.aiimage
+description: 海洋背景图封包 - 热带海洋/珊瑚礁场景，适合休闲游戏的清凉蓝色背景贴图生成
+triggers: 海洋,ocean,大海,sea,背景,background,蓝色,coral,珊瑚,水下,underwater
+---
+
+# ocean.aiimage
+
+海洋主题背景图封包。适合休闲消除、泡泡龙等类型游戏，营造清凉愉快的海洋氛围。
+
+## Recipe
+
+生成方式：调用 AI 图像生成接口，基于以下参数生成或 fork：
+
+- **基础 prompt**：`calm tropical ocean, turquoise water, underwater coral reef, casual mobile game style, flat design, vibrant colors`
+- **宽高比**：9:16（竖屏移动端）
+- **风格**：cartoon / flat design
+- **可 fork 的变体方向**：
+  - 深海：`deep ocean, bioluminescent sea creatures, dark blue, mysterious`
+  - 海滩：`tropical beach, white sand, palm trees, sunset sky`
+  - 暴风海：`stormy ocean, dramatic waves, dark clouds, tension`
+
+**生成步骤：**
+1. 确认 Prefab 容器对背景贴图的尺寸约束（默认 1080×1920 PNG）
+2. 调用图像生成 API，传入 prompt 和宽高比
+3. 验证输出尺寸 ≥ 1080px 宽
+4. 将生成图写入封包目录为 `background.png`
+5. 更新 `manifest.json` 中 `generation.prompt` 和 `generation.seed` 字段
+
+## Result
+
+- **产物文件**：`background.png`
+- **格式**：PNG
+- **最小分辨率**：1080×1920
+- **引用方式**：通过 `manifest.json.result.outputFile` 引用
+
+## Binding
+
+- **Binding Role**：`backgroundTexture`
+- **挂载目标**：`scene://entities/Background/element/textureAsset`
+- **引用类型**：`texture-asset-reference`
+- **约束**：format=png，minWidth=1080
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "calm tropical ocean, turquoise water, underwater coral reef, casual mobile game style, flat design, vibrant colors" \
+     --aspect-ratio 9:16 \
+     --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/background.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are generating an ocean background image for a mobile casual game.
+  Follow the Recipe section to call the image generation API with the specified prompt and parameters.
+  After generation, verify the output meets the Result constraints, then apply the Binding to wire it into the scene.

package/skills/ocean.aiimage/manifest.json

@@ -0,0 +1,49 @@
+{
+  "schemaVersion": 1,
+  "atomId": "ocean.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "海洋背景",
+    "en": "Ocean background"
+  },
+  "tags": [
+    "background",
+    "visual",
+    "ocean",
+    "sea",
+    "water",
+    "casual",
+    "blue"
+  ],
+  "bindingRoles": ["backgroundTexture"],
+  "generation": {
+    "kind": "image",
+    "prompt": "calm tropical ocean, turquoise water, underwater coral reef, casual mobile game style, flat design, vibrant colors",
+    "aspectRatio": "9:16",
+    "model": "google/imagen-3.0-generate-002",
+    "style": "cartoon",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "background.png",
+    "format": "png",
+    "constraints": {
+      "minWidth": 1080,
+      "minHeight": 1920
+    }
+  },
+  "binding": {
+    "role": "backgroundTexture",
+    "target": "scene://entities/Background/element/textureAsset",
+    "type": "texture-asset-reference",
+    "constraints": {
+      "format": "png",
+      "minWidth": 1080
+    }
+  },
+  "files": {
+    "skill": "SKILL.md"
+  }
+}

package/skills/particle-confetti.aicomponent/SKILL.md

@@ -0,0 +1,32 @@
+# particle-confetti — Celebration Confetti VFX
+
+Falling confetti shower for level complete, win screens, and achievement moments.
+
+## Two Approaches
+
+### Approach A: Sprite Sheet (Cross-Engine, Recommended)
+```bash
+playcraft image use-vfx --preset confetti --output assets/vfx/confetti.png
+```
+
+### Approach B: Runtime Particles (Phaser 3)
+Colorful rectangles with gravity, rotation, and wind drift.
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `count` | 80 | Total confetti pieces |
+| `duration` | 2000ms | Emitter active time |
+| `colors` | rainbow | Confetti color palette |
+| `gravity` | 300 | Downward fall speed |
+| `spread` | full width | Horizontal spawn width |
+| `rotation` | random | Per-piece rotation speed |
+
+## Decision Notes
+
+| Decision | Reason |
+|----------|--------|
+| Top-edge spawn | Confetti should fall from above, creating natural rain effect |
+| Multiple colors | Celebration requires visual richness; single color looks monotone |
+| 2s duration | Long enough to feel festive; not so long it interrupts next scene |

package/skills/particle-confetti.aicomponent/manifest.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "atomId": "particle-confetti.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "vfx",
+  "mode": "fixed",
+  "label": { "zh": "彩色纸屑庆祝特效", "en": "Celebration Confetti VFX" },
+  "tags": ["vfx", "confetti", "celebration", "level-complete", "reward", "phaser"],
+  "generation": {
+    "animationType": "particle",
+    "engineSupport": ["phaser", "html5-spritesheet"],
+    "parameters": {
+      "count": "number — confetti piece count (default: 80)",
+      "duration": "number — emitter active time in ms (default: 2000)",
+      "colors": "string[] — color palette for confetti pieces",
+      "gravity": "number — downward gravity (default: 300)",
+      "spread": "number — horizontal spread (default: full screen width)"
+    }
+  },
+  "files": { "skill": "SKILL.md", "phaser": "ref/phaser.js", "html5": "ref/html5-spritesheet.js" }
+}