@playcraft/skills 0.0.2

package/skills/fail_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fail_sfx.aiaudio
+description: 生命耗尽触发游戏结束时的失败提示音效。
+triggers: 需要生成游戏结束失败音效时触发。
+---
+
+# 失败音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`fail.mp3`
+- 在 Preloader.ts 中作为 `sfxFail` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxFail",
+  "target": "assets/sounds/fail.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "failure sound for game over, not too harsh, brief" \
+     --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/fail.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: fail.mp3
+```

package/skills/fail_sfx.aiaudio/manifest.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "atomId": "fail_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "失败音效",
+    "en": "Fail SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "fail",
+    "game-over"
+  ],
+  "bindingRoles": [
+    "sfxFail"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "failure sound for game over, not too harsh, brief",
+    "duration": 1,
+    "loop": false,
+    "referenceAudio": "ref/fail.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/fail.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 1
+    }
+  },
+  "binding": {
+    "role": "sfxFail",
+    "target": "assets/sounds/fail.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/fail.mp3"
+  }
+}

package/skills/figer_icon.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: figer_icon.aiimage
+description: 新手引导中指示玩家应该点击哪条路径的手指动画图片。
+triggers: 需要生成新手引导手指指示图标时触发。
+---
+
+# 引导手指图标
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`figer.webp`
+- 在 Preloader.ts 中作为 `tutorialPointer` key 加载
+
+## Binding
+
+```json
+{
+  "role": "tutorialPointer",
+  "target": "assets/figer.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "hand with pointing finger icon for game tutorial, cartoon style, transparent background, tap gesture" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/figer.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/figer.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: figer.webp
+```

package/skills/figer_icon.aiimage/manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "atomId": "figer_icon.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "引导手指图标",
+    "en": "Tutorial finger pointer"
+  },
+  "tags": [
+    "visual",
+    "finger",
+    "tutorial",
+    "pointer",
+    "gesture",
+    "tap"
+  ],
+  "bindingRoles": [
+    "tutorialPointer"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "hand with pointing finger icon for game tutorial, cartoon style, transparent background, tap gesture",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/figer.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/figer.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 128,
+      "minHeight": 128
+    }
+  },
+  "binding": {
+    "role": "tutorialPointer",
+    "target": "assets/figer.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/figer.webp",
+    "assetPng": "ref/figer.png"
+  }
+}

package/skills/forest.aiimage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: forest.aiimage
+description: 森林背景图封包 - 热带/温带森林场景，适合休闲消除类游戏的背景贴图生成
+triggers: 森林,forest,背景,background,热带,自然,绿色,nature,casual,tree
+---
+
+# forest.aiimage
+
+森林主题背景图封包。适合休闲消除、跑酷等类型游戏，营造自然清新的视觉氛围。
+
+## Recipe
+
+生成方式：调用 AI 图像生成接口，基于以下参数生成或 fork：
+
+- **基础 prompt**：`lush green forest clearing, dappled sunlight through canopy, casual mobile game style, flat design, vibrant colors`
+- **宽高比**：9:16（竖屏移动端）
+- **风格**：cartoon / flat design
+- **可 fork 的变体方向**：
+  - 热带雨林：在 prompt 中加入 `tropical rainforest, palm trees, exotic flowers`
+  - 秋季森林：替换为 `autumn forest, golden leaves, warm tones`
+  - 夜间森林：替换为 `moonlit forest, bioluminescent plants, dark atmosphere`
+
+**生成步骤：**
+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 层写入 scene 路径
+
+## Binding
+
+- **Binding Role**：`backgroundTexture`
+- **挂载目标**：`scene://entities/Background/element/textureAsset`
+- **引用类型**：`texture-asset-reference`
+- **约束**：format=png，minWidth=1080
+- **从 Prefab 读取 Binding 模板**：`.prefab/manifest.json` → `bindingTemplates.backgroundTexture`
+- **写入路径**：将 `background.png` 的 asset id 写入 scene 对应实体的 textureAsset 字段
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "lush green forest clearing, dappled sunlight through canopy, 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 a forest 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.
+  If forking this skill, modify the prompt in manifest.json to reflect the new visual style before generating.

package/skills/forest.aiimage/manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "atomId": "forest.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "森林背景",
+    "en": "Forest background"
+  },
+  "tags": [
+    "background",
+    "visual",
+    "forest",
+    "nature",
+    "casual",
+    "green"
+  ],
+  "bindingRoles": ["backgroundTexture"],
+  "generation": {
+    "kind": "image",
+    "prompt": "lush green forest clearing, dappled sunlight through canopy, 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/fruit_tile.aiimage/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: fruit_tile.aiimage
+description: 水果牌面贴图组封包 - 卡通水果精灵图集，适合三消/对对碰/连线消除的牌面素材
+triggers: 水果,fruit,牌面,tile,贴图,三消,match3,消除,苹果,草莓,葡萄
+---
+
+# fruit_tile.aiimage
+
+水果主题牌面贴图组封包。提供一套卡通风格水果精灵图，用于三消、对对碰、连线消除等棋盘类玩法的牌面。
+
+## Recipe
+
+- **基础 prompt**：`cute cartoon fruit icons sprite sheet, apple strawberry grape orange lemon watermelon cherry, flat design, vibrant colors, white background, game assets`
+- **宽高比**：1:1（正方形精灵图）
+- **风格**：cartoon / flat design
+- **需包含的水果种类**：苹果、草莓、葡萄、橙子、柠檬、西瓜、樱桃（共 7 种）
+- **可 fork 变体**：
+  - 蔬菜替换：用蔬菜图标替换水果
+  - 暗黑风格：深色背景，光泽质感
+  - 3D 风格：立体渲染水果图标
+
+**生成步骤：**
+1. 确认棋盘牌面所需图标种类和尺寸（每格 ≥ 64×64px）
+2. 生成精灵图集（512×512 或 1024×512）
+3. 写入 `tiles.png`，更新 manifest
+
+## Result
+
+- **产物文件**：`tiles.png`
+- **格式**：PNG（透明背景），最小 512×512
+- **图标排列**：水平排列 7 种，每种 1 帧（可扩展动画帧）
+
+## Binding
+
+- **Binding Role**：`tileTextureSet`
+- **挂载目标**：`scene://entities/Board/tileRenderer/tileAtlas`
+- **引用类型**：`sprite-atlas-reference`
+- **约束**：format=png，minWidth=512
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "cute cartoon fruit icons sprite sheet, apple strawberry grape orange lemon watermelon cherry, flat design, vibrant colors, white 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 fruit tile sprite sheet for a match-3 casual game.
+  Follow the Recipe to generate the sprite sheet with the specified fruit icons.
+  Ensure the output is a proper sprite atlas that can be used as a tile set in the board renderer.
+  After generation, apply the Binding to wire the atlas into the scene's tileRenderer.

package/skills/fruit_tile.aiimage/manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "atomId": "fruit_tile.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "水果牌面贴图组",
+    "en": "Fruit tile set"
+  },
+  "tags": [
+    "tile",
+    "visual",
+    "fruit",
+    "match3",
+    "casual",
+    "colorful"
+  ],
+  "bindingRoles": ["tileTextureSet"],
+  "generation": {
+    "kind": "sprite-sheet",
+    "prompt": "cute cartoon fruit icons sprite sheet, apple strawberry grape orange lemon watermelon cherry, flat design, vibrant colors, white 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/game_over_panel.aicomponent/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: game_over_panel.aicomponent
+description: 游戏结束结果面板。半透明遮罩 + 胜利/失败图片 + 下载 CTA 按钮，在关卡胜利或失败后展示，是试玩广告转化的关键界面。
+triggers: 需要实现游戏结束结果展示面板时触发。
+---
+
+# 游戏结束面板（Game Over Result Panel）
+
+**结算全屏结构、安全区与 CTA 锚点** 见 `playable_end_screen_layout.aicomponent`；底层缩放见 `responsive_2d_layout.aicomponent` 第一节。
+
+## Scaffold
+
+`src/game/scenes/GameUI/GameOverPanel.ts`
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **胜败面板独立于关卡逻辑** | 结果面板是视觉表现层；与 LevelLifecycle（状态机）分离后，不同 Remix 变体可用不同视觉风格的面板，而不改任何游戏逻辑 |
+| **软槽位 win/lose Panel** | 胜败图片是典型的 AI 生成资产，每个 Remix 变体可以有不同画风；软槽位允许通过资产替换实现视觉差异化 |
+| **遵从结算屏布局规范** | 面板布局（遮罩→主视觉→CTA 位置）遵从 `playable_end_screen_layout.aicomponent` 约定，保证转化率关键的 CTA 位置在安全区内 |
+
+## Adapter
+
+- **Role**: `gameOverDialog` — 胜利/失败结果面板（遮罩 + 结果图 + 下载 CTA 按钮）
+- **Provides**: `GameOverPanel` 类（`showWin()`、`showLose()`）
+- **Requires**: `phaser.aicomponent`、`tencent_playable_sdk.aicomponent`（sdk.install()）；软槽位：`winPanel`、`losePanel`
+- **Consumed by**: `level_lifecycle.aicomponent`（关卡胜利/失败时调用 `showWin()`/`showLose()`）
+- **Integration point**: `src/game/scenes/GameUI/GameOverPanel.ts` → LevelLifecycle 内部实例化和触发
+
+## Imports
+
+- `phaser.aicomponent` / `tencent_playable_sdk.aicomponent`（硬依赖）
+- `winPanel`（软槽位：胜利面板图片，可替换）
+- `losePanel`（软槽位：失败面板图片，可替换）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/GameOverPanel.ts
+outputs:
+  - gameOverPanel: GameOverPanel class (win/lose result modal)
+```

package/skills/game_over_panel.aicomponent/manifest.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": 1,
+  "atomId": "game_over_panel.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "游戏结束面板", "en": "Game over result panel" },
+  "tags": ["ui", "game-over", "win", "lose", "result-panel", "modal"],
+  "bindingRoles": ["gameOverDialog"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/GameOverPanel.ts": { "source": "ref/GameOverPanel.ts", "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" },
+    {
+      "slot": "winPanel",
+      "description": "胜利结果面板视觉图片",
+      "bindAs": "winTexture",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["successFeedbackPanel"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "losePanel",
+      "description": "失败结果面板视觉图片",
+      "bindAs": "loseTexture",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["failFeedbackPanel"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "sfxWinAnim",
+      "description": "胜利动画播放时的音效",
+      "bindAs": "sfxWinAnim",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["sfxSuccess"],
+      "allowedBundleTypes": ["aiaudio"]
+    },
+    {
+      "slot": "sfxButtonClick",
+      "description": "面板按钮点击音效",
+      "bindAs": "sfxButtonClick",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["sfxButtonClick"],
+      "allowedBundleTypes": ["aiaudio"]
+    }
+  ],
+  "exports": [
+    { "name": "GameOverPanel", "kind": "class", "location": "src/game/scenes/GameUI/GameOverPanel.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "semi-transparent overlay modal showing win or lose result image with download CTA button, triggered after game ends"
+  },
+  "files": { "skill": "SKILL.md", "gameOverPanel": "ref/GameOverPanel.ts" }
+}

package/skills/game_over_panel.aicomponent/ref/GameOverPanel.ts

@@ -0,0 +1,74 @@
+import * as Phaser from "phaser";
+// import { DOWNLOAD_BUTTON_URL } from '../../DebugConfig';
+
+/** 游戏结束面板的配置选项 */
+export interface GameOverPanelConfig {
+  type: "win" | "lose"; // 'win' 使用 win_panel, 'lose' 使用 lose_panel
+  onClose?: () => void;
+}
+
+/**
+ * 游戏结束面板组件。
+ * 显示胜利或失败的全屏面板，包含半透明遮罩和结果图片。
+ */
+export class GameOverPanel extends Phaser.GameObjects.Container {
+  private readonly config: GameOverPanelConfig;
+
+  constructor(scene: Phaser.Scene, config: GameOverPanelConfig) {
+    super(scene);
+    this.config = config;
+
+    scene.add.existing(this);
+    // Ensure the game-over panel renders above ALL other UI (GameTopUI=500, nomoveHint=1600, back=1702)
+    this.setDepth(2000);
+    this.setScrollFactor(0);
+
+    // 半透明黑色背景遮罩
+    const { width: gameWidth, height: gameHeight } = scene.scale;
+    const overlay = scene.add.rectangle(
+      0,
+      0,
+      gameWidth,
+      gameHeight,
+      0x000000,
+      0.7,
+    );
+    overlay.setOrigin(0, 0);
+    this.add(overlay);
+
+    // 根据类型选择图片
+    const imageKey = config.type === "win" ? "win_panel" : "lose_panel";
+    const gameOverImage = scene.add.image(
+      gameWidth / 2,
+      gameHeight / 2,
+      imageKey,
+    );
+
+    // 根据屏幕大小自适应缩放图片
+    const maxWidth = gameWidth * 0.8;
+    const maxHeight = gameHeight * 0.6;
+    const scaleX = maxWidth / gameOverImage.width;
+    const scaleY = maxHeight / gameOverImage.height;
+    const scale = Math.min(scaleX, scaleY, 1); // 不放大，只缩小
+
+    gameOverImage.setScale(scale);
+    this.add(gameOverImage);
+
+    // 点击任意位置跳转到下载链接
+    overlay.setInteractive({ useHandCursor: true });
+    overlay.on("pointerup", () => {
+      this.handleClick();
+    });
+
+    // 也可以点击图片跳转
+    gameOverImage.setInteractive({ useHandCursor: true });
+    gameOverImage.on("pointerup", () => {
+      this.handleClick();
+    });
+  }
+
+  /** 处理点击事件，触发关闭回调。 */
+  private handleClick() {
+    this.config.onClose?.();
+  }
+}