@playcraft/skills 0.0.2

package/skills/sound_utils.aicomponent/ref/SoundUtils.ts

@@ -0,0 +1,29 @@
+import * as Phaser from 'phaser';
+
+export function safePlaySound(
+  scene: Phaser.Scene,
+  key: string,
+  config?: Phaser.Types.Sound.SoundConfig,
+): void {
+  const soundManager = scene.sound;
+
+  if (!soundManager) {
+    return;
+  }
+
+  try {
+    const audioCache = scene.cache.audio;
+    const hasInCache = audioCache ? audioCache.exists(key) : false;
+
+    const existing = (soundManager as Phaser.Sound.BaseSoundManager).get(key);
+
+    if (!hasInCache && !existing) {
+      console.warn('[SoundUtils] Audio key not found, skip play', { key });
+      return;
+    }
+
+    soundManager.play(key, config);
+  } catch (e) {
+    console.error('[SoundUtils] Failed to play sound', { key, error: e });
+  }
+}

package/skills/sprite-animation-2d.aicomponent/SKILL.md

@@ -0,0 +1,45 @@
+# sprite-animation-2d — 2D Sprite Sheet Animation
+
+Play a sprite sheet animation at a configurable frame rate. Works with any sprite sheet generated by `playcraft image animate` or `playcraft image sprite-sheet`.
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `spriteSheetPath` | string | required | Path to the sprite sheet PNG |
+| `frameWidth` | number | required | Width of each individual frame |
+| `frameHeight` | number | required | Height of each individual frame |
+| `frameCount` | number | required | Total number of frames |
+| `columns` | number | required | Frames per row in the sheet |
+| `fps` | number | 12 | Playback speed in frames per second |
+| `loop` | boolean | true | Whether to loop the animation |
+| `startFrame` | number | 0 | First frame to start playing from |
+| `pingPong` | boolean | false | Reverse direction at end instead of looping |
+
+## Workflow
+
+1. Generate a sprite sheet:
+   ```bash
+   # From static image (built-in presets):
+   playcraft image animate --input coin.png --preset spin --frames 8 --output coin_spin.png
+   
+   # From AI-generated frames:
+   playcraft tools generate-image --prompt "coin sprite sheet 8 frames white background" --output coin_raw.png
+   playcraft image sprite-sheet --inputs frame_*.png --output coin_spin.png --columns 4
+   ```
+
+2. Load in your engine using the reference code below.
+
+## Engine References
+
+- **PlayCanvas**: `ref/playcanvas.js` — uses `pc.Sprite` + `pc.AnimationComponent`
+- **Phaser 3**: `ref/phaser.js` — uses `this.anims.create()` + `sprite.play()`
+- **HTML5 Canvas**: `ref/html5.js` — uses `requestAnimationFrame` + `drawImage()`
+
+## Decision Notes
+
+| Decision | Reason |
+|----------|--------|
+| Sprite sheet over individual frames | Single asset load, better memory locality, no multi-file sync issues |
+| Configurable fps | Different effects need different speeds (coin spin: 12fps, idle: 6fps) |
+| Columns parameter | Flexible layout, not forced to square power-of-2 sheets |

package/skills/sprite-animation-2d.aicomponent/manifest.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "atomId": "sprite-animation-2d.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "animation",
+  "mode": "fixed",
+  "label": { "zh": "2D 精灵序列帧动画", "en": "2D Sprite Sheet Animation" },
+  "tags": ["animation", "sprite-sheet", "2d", "playcanvas", "phaser", "html5"],
+  "generation": {
+    "animationType": "sprite-sheet",
+    "engineSupport": ["playcanvas", "phaser", "threejs", "html5"],
+    "parameters": {
+      "frameWidth": "number — width of each frame in pixels",
+      "frameHeight": "number — height of each frame in pixels",
+      "frameCount": "number — total frames in the sheet",
+      "columns": "number — frames per row",
+      "fps": "number — playback speed (default: 12)",
+      "loop": "boolean — whether to loop (default: true)",
+      "startFrame": "number — first frame index (default: 0)"
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "playcanvas": "ref/playcanvas.js",
+    "phaser": "ref/phaser.js",
+    "html5": "ref/html5.js"
+  }
+}

package/skills/sprite-animation-2d.aicomponent/ref/html5.js

@@ -0,0 +1,83 @@
+// sprite-animation-2d — HTML5 Canvas implementation
+// Works with any 2D canvas rendering context.
+
+class SpriteAnimator {
+  constructor(canvas, {
+    imagePath,
+    frameWidth,
+    frameHeight,
+    frameCount,
+    columns,
+    fps = 12,
+    loop = true,
+    pingPong = false,
+    x = 0,
+    y = 0,
+  }) {
+    this.ctx = canvas.getContext('2d');
+    this.frameWidth = frameWidth;
+    this.frameHeight = frameHeight;
+    this.frameCount = frameCount;
+    this.columns = columns;
+    this.frameDuration = 1000 / fps;
+    this.loop = loop;
+    this.pingPong = pingPong;
+    this.x = x;
+    this.y = y;
+
+    this._frame = 0;
+    this._lastTime = 0;
+    this._direction = 1;
+    this._playing = false;
+
+    this.image = new Image();
+    this.image.onload = () => { this._playing = true; };
+    this.image.src = imagePath;
+  }
+
+  draw(timestamp) {
+    if (!this._playing || !this.image.complete) return;
+
+    const elapsed = timestamp - this._lastTime;
+    if (elapsed >= this.frameDuration) {
+      this._lastTime = timestamp;
+      this._advance();
+    }
+
+    const col = this._frame % this.columns;
+    const row = Math.floor(this._frame / this.columns);
+
+    this.ctx.drawImage(
+      this.image,
+      col * this.frameWidth,
+      row * this.frameHeight,
+      this.frameWidth,
+      this.frameHeight,
+      this.x,
+      this.y,
+      this.frameWidth,
+      this.frameHeight,
+    );
+  }
+
+  _advance() {
+    this._frame += this._direction;
+    if (this._frame >= this.frameCount) {
+      if (this.pingPong) { this._direction = -1; this._frame = this.frameCount - 2; }
+      else if (this.loop) { this._frame = 0; }
+      else { this._frame = this.frameCount - 1; this._playing = false; }
+    } else if (this._frame < 0) {
+      this._direction = 1; this._frame = 1;
+    }
+  }
+}
+
+// Usage:
+// const canvas = document.getElementById('myCanvas');
+// const anim = new SpriteAnimator(canvas, {
+//   imagePath: 'assets/coin_spin.png',
+//   frameWidth: 64, frameHeight: 64,
+//   frameCount: 8, columns: 4, fps: 12,
+// });
+// function loop(t) { ctx.clearRect(0, 0, canvas.width, canvas.height); anim.draw(t); requestAnimationFrame(loop); }
+// requestAnimationFrame(loop);

package/skills/sprite-animation-2d.aicomponent/ref/phaser.js

@@ -0,0 +1,38 @@
+// sprite-animation-2d — Phaser 3 implementation
+// Call setupSpriteAnimation() in your Scene's create() method.
+
+/**
+ * Load a sprite sheet in preload():
+ *   this.load.spritesheet('coin', 'assets/coin_spin.png', {
+ *     frameWidth: 64, frameHeight: 64
+ *   });
+ */
+
+function setupSpriteAnimation(scene, {
+  key,            // texture key (same as load key)
+  frameCount,     // total frames
+  fps = 12,
+  loop = true,
+  pingPong = false,
+  startFrame = 0,
+}) {
+  const frames = scene.anims.generateFrameNumbers(key, {
+    start: startFrame,
+    end: frameCount - 1,
+  });
+
+  scene.anims.create({
+    key: `${key}_play`,
+    frames,
+    frameRate: fps,
+    repeat: loop ? -1 : 0,
+    yoyo: pingPong,
+  });
+
+  return `${key}_play`;
+}
+
+// Usage in create():
+// const animKey = setupSpriteAnimation(this, { key: 'coin', frameCount: 8, fps: 12 });
+// const coinSprite = this.add.sprite(400, 300, 'coin');
+// coinSprite.play(animKey);

package/skills/sprite-animation-2d.aicomponent/ref/playcanvas.js

@@ -0,0 +1,67 @@
+// sprite-animation-2d — PlayCanvas implementation
+// Attach this script to any entity with a Sprite component.
+
+var SpriteAnimator2D = pc.createScript('spriteAnimator2D');
+
+SpriteAnimator2D.attributes.add('fps', { type: 'number', default: 12 });
+SpriteAnimator2D.attributes.add('frameCount', { type: 'number', default: 8 });
+SpriteAnimator2D.attributes.add('columns', { type: 'number', default: 4 });
+SpriteAnimator2D.attributes.add('loop', { type: 'boolean', default: true });
+SpriteAnimator2D.attributes.add('pingPong', { type: 'boolean', default: false });
+SpriteAnimator2D.attributes.add('startFrame', { type: 'number', default: 0 });
+SpriteAnimator2D.attributes.add('autoPlay', { type: 'boolean', default: true });
+
+SpriteAnimator2D.prototype.initialize = function () {
+    this._frame = this.startFrame;
+    this._elapsed = 0;
+    this._playing = this.autoPlay;
+    this._direction = 1;
+    this._frameDuration = 1 / this.fps;
+};
+
+SpriteAnimator2D.prototype.update = function (dt) {
+    if (!this._playing) return;
+
+    this._elapsed += dt;
+    if (this._elapsed >= this._frameDuration) {
+        this._elapsed -= this._frameDuration;
+        this._advance();
+    }
+};
+
+SpriteAnimator2D.prototype._advance = function () {
+    this._frame += this._direction;
+
+    if (this._frame >= this.frameCount) {
+        if (this.pingPong) {
+            this._direction = -1;
+            this._frame = this.frameCount - 2;
+        } else if (this.loop) {
+            this._frame = 0;
+        } else {
+            this._frame = this.frameCount - 1;
+            this._playing = false;
+        }
+    } else if (this._frame < 0) {
+        if (this.pingPong) {
+            this._direction = 1;
+            this._frame = 1;
+        } else {
+            this._frame = this.frameCount - 1;
+        }
+    }
+
+    // Update sprite frame
+    var sprite = this.entity.sprite;
+    if (sprite) {
+        sprite.frame = this._frame;
+    }
+};
+
+SpriteAnimator2D.prototype.play = function () { this._playing = true; };
+SpriteAnimator2D.prototype.stop = function () { this._playing = false; };
+SpriteAnimator2D.prototype.reset = function () {
+    this._frame = this.startFrame;
+    this._elapsed = 0;
+    this._direction = 1;
+};

package/skills/sprite_entity_renderer.aicomponent/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: sprite_entity_renderer.aicomponent
+description: 精灵实体渲染器。用 Phaser Image 精灵替代 Graphics API 手绘，实现更美观的棋盘实体渲染。管理精灵生命周期、方向旋转、缩放、着色和动画临时精灵。
+triggers: 精灵渲染,sprite renderer,Image替代Graphics,实体渲染,旋转方向,sprite rotation,entity render
+---
+
+# 精灵实体渲染器（Sprite Entity Renderer）
+
+## 说明
+
+当棋盘上的实体（汽车、箭头、动物等）使用 AI 生成的图片而非 Graphics API 绘制时，需要管理精灵的**创建/销毁/旋转/缩放/动画**。本 skill 提供标准化的渲染模式。
+
+**核心思路：单图 + 旋转**
+- 只需一张朝固定方向的图片
+- 通过 `setRotation(angle)` 实现任意方向
+- 通过 `setTint(color)` 实现颜色变化（如阻挡时变红）
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `src/game/scenes/GameUI/SpriteEntityRenderer.ts` | `ref/SpriteEntityRenderer.ts` | 完整渲染器 |
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser Image API）
+- `board_entity_sprite.aiimage`（配套：图片资源来源）
+- `grid_board_layout.aicomponent`（硬依赖：格子坐标）
+
+## 核心接口
+
+```typescript
+class SpriteEntityRenderer {
+  constructor(scene: any, textureKey: string, defaultFacing: "up" | "down");
+
+  /** 渲染所有实体（销毁旧精灵 → 创建新精灵） */
+  renderAll(entities: EntityData[], container: Container): void;
+
+  /** 清除所有精灵 */
+  clear(): void;
+
+  /** 创建临时精灵（用于消除动画） */
+  createTempSprite(x: number, y: number, direction: string, container: Container): Image;
+
+  /** 方向→旋转角度 */
+  directionToAngle(direction: string): number;
+}
+
+interface EntityData {
+  x: number;        // 格子列
+  y: number;        // 格子行
+  direction: string; // "up" | "down" | "left" | "right"
+  tint?: number;     // 可选着色
+}
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **单图 + 旋转替代四方向图** | 只需维护一张图，旋转由代码处理；减少资产数量，AI 生图只需一次 |
+| **精灵对象池（clear+rebuild）** | 每帧销毁旧精灵并重建，比跟踪差量更简单可靠；在 Phaser 中精灵创建开销小，试玩广告帧数要求不极端 |
+| **临时精灵用于消除动画** | 消除动画时保留独立精灵放入动画容器，与主渲染层解耦；动画结束后容器销毁，无需回收到对象池 |
+| **替代 Graphics 而非共存** | SpriteEntityRenderer 设计为 PathRenderer 的精灵模式替代品；两者通过同一接口协作，不共存 |
+
+## Adapter
+
+- **Role**: `spriteEntityRenderer` — 棋盘实体（箭头头部）的 Phaser Image 精灵渲染器
+- **Provides**: `SpriteEntityRenderer` 类（`renderAll()`、`clear()`、`createTempSprite()`、`directionToAngle()`），`EntityData` 类型
+- **Requires**: `phaser.aicomponent`（Image API）、`board_entity_sprite.aiimage`（图片资源纹理 key）、`grid_board_layout.aicomponent`（格子坐标→像素坐标）
+- **Consumed by**: `path_renderer.aicomponent`（精灵渲染模式时调用 `renderAll()`）、`path_animation.aicomponent`（消除动画时调用 `createTempSprite()`）
+- **Integration point**: `src/game/scenes/GameUI/SpriteEntityRenderer.ts` → PathRenderer 在 sprite 模式下持有实例
+
+## 与 PathRenderer 的替换关系
+
+**Before（Graphics API）：**
+```typescript
+// 每帧在 Graphics 对象上绘制多边形
+renderGridPaths(level, progress) {
+  g.clear();
+  for (path of level.paths) {
+    drawSegments(g, path);  // 画折线
+    drawArrowHead(g, path); // 画三角形
+  }
+}
+```
+
+**After（Sprite Renderer）：**
+```typescript
+// 管理精灵对象池
+renderGridPaths(level, progress) {
+  this.spriteRenderer.clear();
+  const entities = level.paths
+    .filter(notRemoved)
+    .map(p => ({ x: p.head.x, y: p.head.y, direction: p.direction }));
+  this.spriteRenderer.renderAll(entities, boardContainer);
+}
+```
+
+## 方向映射规则
+
+```typescript
+// 构造函数指定图片默认朝向
+const renderer = new SpriteEntityRenderer(scene, "car", "down");
+
+// 内部映射逻辑：
+// 若 defaultFacing = "down":
+//   down  → 0        (不旋转)
+//   up    → π        (180°)
+//   left  → π/2      (90° 顺时针)
+//   right → -π/2     (-90°)
+//
+// 若 defaultFacing = "up":
+//   up    → 0
+//   down  → π
+//   right → π/2
+//   left  → -π/2
+```
+
+## 动画集成
+
+消除动画时创建临时精灵放入容器：
+
+```typescript
+// 在 AnimationManager 中
+const car = spriteRenderer.createTempSprite(hx, hy, path.direction, container);
+
+scene.tweens.add({
+  targets: container,
+  x: dx * slideDistance,
+  y: dy * slideDistance,
+  alpha: 0,
+  duration: 400,
+  onComplete: () => container.destroy(), // 精灵随容器销毁
+});
+```
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/SpriteEntityRenderer.ts
+outputs:
+  - renderer: SpriteEntityRenderer class
+```

package/skills/sprite_entity_renderer.aicomponent/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "atomId": "sprite_entity_renderer.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "rendering",
+  "mode": "fixed",
+  "label": {
+    "zh": "精灵实体渲染器（替代 Graphics 绘制）",
+    "en": "Sprite entity renderer (replaces Graphics drawing)"
+  },
+  "tags": ["sprite", "renderer", "image", "rotation", "entity", "phaser"],
+  "bindingRoles": ["entityRenderer"],
+  "files": {
+    "skill": "SKILL.md",
+    "ref": ["ref/SpriteEntityRenderer.ts"]
+  }
+}

package/skills/sprite_entity_renderer.aicomponent/ref/SpriteEntityRenderer.ts

@@ -0,0 +1,126 @@
+import * as Phaser from "phaser";
+
+export interface EntityData {
+  x: number;
+  y: number;
+  direction: string;
+  tint?: number;
+}
+
+/**
+ * 精灵实体渲染器
+ * 用 Phaser Image 精灵替代 Graphics API 手绘
+ */
+export class SpriteEntityRenderer {
+  private scene: any;
+  private textureKey: string;
+  private defaultFacing: "up" | "down";
+  private sprites: Phaser.GameObjects.Image[] = [];
+
+  /**
+   * @param scene - Phaser 场景引用
+   * @param textureKey - 精灵纹理 key（在 Preloader 中加载的 key）
+   * @param defaultFacing - 图片默认朝向（"up" 或 "down"）
+   */
+  constructor(scene: any, textureKey: string, defaultFacing: "up" | "down" = "down") {
+    this.scene = scene;
+    this.textureKey = textureKey;
+    this.defaultFacing = defaultFacing;
+  }
+
+  /**
+   * 渲染所有实体（先清除旧精灵，再创建新精灵）
+   */
+  renderAll(entities: EntityData[], container: Phaser.GameObjects.Container): void {
+    this.clear();
+
+    for (const entity of entities) {
+      const { x: cx, y: cy } = this.cellCenter(entity.x, entity.y);
+      const angle = this.directionToAngle(entity.direction);
+      const targetSize = this.scene.cellSize * 0.8;
+
+      const sprite = this.scene.add.image(cx, cy, this.textureKey) as Phaser.GameObjects.Image;
+      sprite.setOrigin(0.5);
+      sprite.setRotation(angle);
+
+      const scale = Math.min(targetSize / sprite.width, targetSize / sprite.height);
+      sprite.setScale(scale);
+
+      if (entity.tint !== undefined) {
+        sprite.setTint(entity.tint);
+      }
+
+      container.add(sprite);
+      this.sprites.push(sprite);
+    }
+  }
+
+  /**
+   * 清除所有管理的精灵
+   */
+  clear(): void {
+    for (const sprite of this.sprites) {
+      sprite.destroy();
+    }
+    this.sprites = [];
+  }
+
+  /**
+   * 创建临时精灵（用于消除动画）
+   * 调用方负责销毁（通常通过销毁容器）
+   */
+  createTempSprite(
+    x: number,
+    y: number,
+    direction: string,
+    container: Phaser.GameObjects.Container,
+  ): Phaser.GameObjects.Image {
+    const angle = this.directionToAngle(direction);
+    const targetSize = this.scene.cellSize * 0.8;
+
+    const sprite = this.scene.add.image(x, y, this.textureKey) as Phaser.GameObjects.Image;
+    sprite.setOrigin(0.5);
+    sprite.setRotation(angle);
+
+    const scale = Math.min(targetSize / sprite.width, targetSize / sprite.height);
+    sprite.setScale(scale);
+
+    container.add(sprite);
+    return sprite;
+  }
+
+  /**
+   * 方向转旋转角度
+   * 根据图片默认朝向计算旋转值
+   */
+  directionToAngle(direction: string): number {
+    if (this.defaultFacing === "down") {
+      switch (direction) {
+        case "down": return 0;
+        case "up": return Math.PI;
+        case "left": return Math.PI / 2;
+        case "right": return -Math.PI / 2;
+        default: return 0;
+      }
+    } else {
+      // defaultFacing === "up"
+      switch (direction) {
+        case "up": return 0;
+        case "down": return Math.PI;
+        case "right": return Math.PI / 2;
+        case "left": return -Math.PI / 2;
+        default: return 0;
+      }
+    }
+  }
+
+  /**
+   * 计算格子中心坐标
+   */
+  private cellCenter(col: number, row: number): { x: number; y: number } {
+    return {
+      x: col * this.scene.cellWidth + this.scene.cellWidth / 2,
+      y: row * this.scene.cellHeight + this.scene.cellHeight / 2,
+    };
+  }
+}

package/skills/success_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: success_sfx.aiaudio
+description: 所有路径消除，关卡通关时的短促胜利音效。
+triggers: 需要生成关卡通关胜利音效时触发。
+---
+
+# 关卡通关音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`success.mp3`
+- 在 Preloader.ts 中作为 `sfxSuccess` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxSuccess",
+  "target": "assets/sounds/success.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "triumphant success jingle for completing a puzzle level, short and satisfying" \
+     --duration 2 \
+     --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/success.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: success.mp3
+```

package/skills/success_sfx.aiaudio/manifest.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": 1,
+  "atomId": "success_sfx.aiaudio",
+  "bundleType": "aiaudio",
+  "category": "audio",
+  "mode": "generative",
+  "label": {
+    "zh": "关卡通关音效",
+    "en": "Level success SFX"
+  },
+  "tags": [
+    "audio",
+    "sfx",
+    "success",
+    "win",
+    "level-complete"
+  ],
+  "bindingRoles": [
+    "sfxSuccess"
+  ],
+  "generation": {
+    "kind": "sfx",
+    "prompt": "triumphant success jingle for completing a puzzle level, short and satisfying",
+    "duration": 2,
+    "loop": false,
+    "referenceAudio": "ref/success.mp3",
+    "platformSkill": "playcraft-audio-generation"
+  },
+  "result": {
+    "outputFile": "ref/success.mp3",
+    "format": "mp3",
+    "constraints": {
+      "maxDuration": 2
+    }
+  },
+  "binding": {
+    "role": "sfxSuccess",
+    "target": "assets/sounds/success.mp3",
+    "type": "audio-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/success.mp3"
+  }
+}