@playcraft/skills 0.0.2

package/skills/particle-confetti.aicomponent/ref/html5-spritesheet.js

@@ -0,0 +1,17 @@
+// particle-confetti — HTML5 Canvas sprite sheet approach
+// Uses the bundled confetti.png VFX sprite sheet.
+// Import SpritesheetEffect from particle-explosion html5-spritesheet.js
+
+// Load:
+// const confettiImg = new Image();
+// confettiImg.src = 'assets/vfx/confetti.png';
+
+// Play centered:
+// const fx = new SpritesheetEffect(ctx, {
+//   image: confettiImg,
+//   frameW: 96, frameH: 96,
+//   frames: 12, columns: 4,
+//   fps: 12,
+//   x: canvas.width / 2,
+//   y: canvas.height / 2,
+// });

package/skills/particle-confetti.aicomponent/ref/phaser.js

@@ -0,0 +1,38 @@
+// particle-confetti — Phaser 3 implementation
+
+function celebrationConfetti(scene, {
+  count = 80,
+  duration = 2000,
+  colors = [0xFF4444, 0x44AAFF, 0x44DD44, 0xFFD700, 0xCC44FF],
+  gravity = 300,
+} = {}) {
+  const { width } = scene.cameras.main;
+
+  const emitter = scene.add.particles(0, -20, '__DEFAULT', {
+    x: { min: 0, max: width },
+    speedX: { min: -100, max: 100 },
+    speedY: { min: 50, max: 200 },
+    gravityY: gravity,
+    lifespan: duration * 1.2,
+    quantity: Math.ceil(count / (duration / 100)),
+    frequency: 100,
+    scale: { min: 0.5, max: 1.5 },
+    alpha: { start: 1, end: 0 },
+    tint: colors,
+    rotate: { min: 0, max: 360 },
+    angularVelocity: { min: -200, max: 200 },
+    blendMode: 'NORMAL',
+  }).setDepth(100);
+
+  // Stop emitting after duration, let existing particles finish
+  scene.time.delayedCall(duration, () => {
+    emitter.stop();
+    scene.time.delayedCall(duration * 1.5, () => emitter.destroy());
+  });
+
+  return emitter;
+}
+
+// Usage:
+// celebrationConfetti(this);  // full screen confetti shower
+// celebrationConfetti(this, { count: 40, duration: 1000 });  // shorter burst

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

@@ -0,0 +1,37 @@
+# particle-explosion — Particle Explosion VFX
+
+Burst of particles radiating outward from a point, with gravity falloff. Used for match clears, impact feedback, coin bursts, and destruction effects.
+
+## Two Approaches
+
+### Approach A: Sprite Sheet (Cross-Engine, Recommended)
+Use the bundled `explosion_small.png` VFX sprite sheet:
+```bash
+playcraft image use-vfx --preset explosion_small --output assets/vfx/explosion.png
+```
+Combine with `sprite-animation-2d.aicomponent` to play the sequence.
+
+**Pros**: Works in any engine, no particle system needed, consistent look, small file size.
+
+### Approach B: Runtime Particles (Engine-Native)
+Use the engine's particle system for fully dynamic, physics-based explosions.
+
+**Pros**: Randomized, interactive, physics-accurate. **Cons**: More complex, engine-specific.
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `count` | 12 | Number of particles |
+| `lifetime` | 0.6s | How long each particle lives |
+| `speed` | 150px/s | Initial outward velocity |
+| `gravity` | 200px/s² | Downward acceleration |
+| `size` | 6px | Particle size |
+| `colorRange` | warm colors | Color palette |
+
+## Engine References
+
+- **Sprite sheet** (recommended): Use `sprite-animation-2d.aicomponent` + `explosion_small` VFX preset
+- **Phaser 3 particles**: `ref/phaser.js`
+- **PlayCanvas**: `ref/playcanvas.js`
+- **HTML5 Canvas**: `ref/html5-spritesheet.js`

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

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "atomId": "particle-explosion.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "vfx",
+  "mode": "fixed",
+  "label": { "zh": "粒子爆炸特效", "en": "Particle Explosion VFX" },
+  "tags": ["vfx", "particle", "explosion", "impact", "playcanvas", "phaser", "html5"],
+  "generation": {
+    "animationType": "particle",
+    "engineSupport": ["playcanvas", "phaser", "html5-spritesheet"],
+    "parameters": {
+      "count": "number — particle count (default: 12)",
+      "lifetime": "number — particle lifetime in seconds (default: 0.6)",
+      "speed": "number — initial particle speed (default: 150)",
+      "gravity": "number — downward gravity (default: 200)",
+      "colorRange": "string[] — color palette for particles",
+      "size": "number — particle size in pixels (default: 6)",
+      "x": "number — spawn X position",
+      "y": "number — spawn Y position"
+    }
+  },
+  "files": { "skill": "SKILL.md", "playcanvas": "ref/playcanvas.js", "phaser": "ref/phaser.js", "html5": "ref/html5-spritesheet.js" }
+}

package/skills/particle-explosion.aicomponent/ref/html5-spritesheet.js

@@ -0,0 +1,40 @@
+// particle-explosion — HTML5 Canvas sprite sheet approach
+// Play the explosion_small.png sprite sheet at a given position.
+
+class SpritesheetEffect {
+  constructor(ctx, { image, frameW, frameH, frames, columns, fps = 16, x, y }) {
+    this.ctx = ctx;
+    this.image = image;
+    this.frameW = frameW;
+    this.frameH = frameH;
+    this.frames = frames;
+    this.columns = columns;
+    this.fps = fps;
+    this.x = x - frameW / 2;
+    this.y = y - frameH / 2;
+    this._frame = 0;
+    this._elapsed = 0;
+    this._done = false;
+  }
+
+  update(dt) {
+    if (this._done) return;
+    this._elapsed += dt;
+    const frameDuration = 1 / this.fps;
+    while (this._elapsed >= frameDuration) {
+      this._elapsed -= frameDuration;
+      this._frame++;
+      if (this._frame >= this.frames) { this._done = true; return; }
+    }
+    const col = this._frame % this.columns;
+    const row = Math.floor(this._frame / this.columns);
+    this.ctx.drawImage(this.image, col * this.frameW, row * this.frameH, this.frameW, this.frameH, this.x, this.y, this.frameW, this.frameH);
+  }
+
+  get done() { return this._done; }
+}
+
+// Usage:
+// const img = new Image(); img.src = 'assets/vfx/explosion_small.png';
+// const fx = new SpritesheetEffect(ctx, { image: img, frameW: 64, frameH: 64, frames: 8, columns: 4, fps: 16, x: 200, y: 300 });
+// // In game loop: fx.update(dt); if (fx.done) removeFromScene(fx);

package/skills/particle-explosion.aicomponent/ref/phaser.js

@@ -0,0 +1,46 @@
+// particle-explosion — Phaser 3 implementation
+// Uses Phaser 3.60+ Particle Emitter API.
+
+function createExplosion(scene, { x, y, count = 12, speed = 150, lifetime = 600, colors = [0xFFAA00, 0xFF6600, 0xFF2200, 0xFFFF00] } = {}) {
+  // Approach A: Sprite sheet (preferred if explosion_small.png is available)
+  if (scene.textures.exists('vfx_explosion')) {
+    const sprite = scene.add.sprite(x, y, 'vfx_explosion').setDepth(50);
+    sprite.play('vfx_explosion_play');
+    sprite.on('animationcomplete', () => sprite.destroy());
+    return sprite;
+  }
+
+  // Approach B: Runtime particles (fallback)
+  const particles = scene.add.particles(x, y, '__DEFAULT', {
+    speed: { min: speed * 0.3, max: speed },
+    lifespan: lifetime,
+    quantity: count,
+    gravityY: 200,
+    scale: { start: 1, end: 0 },
+    alpha: { start: 1, end: 0 },
+    tint: colors,
+    blendMode: 'ADD',
+    emitting: false,
+  });
+
+  particles.explode(count, x, y);
+  scene.time.delayedCall(lifetime + 200, () => particles.destroy());
+  return particles;
+}
+
+// Setup animation (call in preload + create):
+function setupExplosionAnim(scene) {
+  if (scene.textures.exists('vfx_explosion') && !scene.anims.exists('vfx_explosion_play')) {
+    scene.anims.create({
+      key: 'vfx_explosion_play',
+      frames: scene.anims.generateFrameNumbers('vfx_explosion', { start: 0, end: 7 }),
+      frameRate: 16,
+      repeat: 0,
+    });
+  }
+}
+
+// Usage:
+// preload: this.load.spritesheet('vfx_explosion', 'assets/vfx/explosion_small.png', { frameWidth: 64, frameHeight: 64 });
+// create:  setupExplosionAnim(this);
+// trigger: createExplosion(this, { x: tile.x, y: tile.y });

package/skills/particle-explosion.aicomponent/ref/playcanvas.js

@@ -0,0 +1,33 @@
+// particle-explosion — PlayCanvas implementation
+// Uses PlayCanvas ParticleSystem component.
+
+// Entity setup (via editor or code):
+// - Add ParticleSystem component
+// - Set texture to explosion sprite sheet
+// - Configure as one-shot (numParticles, loop: false)
+
+var ExplosionVFX = pc.createScript('explosionVFX');
+ExplosionVFX.attributes.add('particleAsset', { type: 'asset', assetType: 'texture' });
+ExplosionVFX.attributes.add('count', { type: 'number', default: 12 });
+ExplosionVFX.attributes.add('speed', { type: 'number', default: 150 });
+ExplosionVFX.attributes.add('lifetime', { type: 'number', default: 0.6 });
+
+ExplosionVFX.prototype.initialize = function () {
+    var ps = this.entity.particlesystem;
+    if (ps) {
+        ps.numParticles = this.count;
+        ps.startSpeed = new pc.CurveSet([[0, this.speed], [1, 0]]);
+        ps.lifetime = this.lifetime;
+        ps.loop = false;
+        ps.autoPlay = false;
+    }
+};
+
+ExplosionVFX.prototype.burst = function (x, y, z) {
+    this.entity.setLocalPosition(x, y, z ?? 0);
+    var ps = this.entity.particlesystem;
+    if (ps) {
+        ps.reset();
+        ps.play();
+    }
+};

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

@@ -0,0 +1,25 @@
+# particle-trail — Particle Trail VFX
+
+A continuous stream of fading particles that follows a moving object. Creates motion blur / wake effects for projectiles, power-ups, and dashing characters.
+
+## Use Cases
+
+- **Projectile trail**: Arrow, bullet, fireball — follow the projectile
+- **Dash trail**: Character dashing — brief trail on rapid movement
+- **Collectible glow**: Coin/gem with ambient sparkle trail
+- **Boss aura**: Constant particle aura around boss entity
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `count` | 20 | Max simultaneous particles |
+| `lifetime` | 0.4s | How long each particle fades |
+| `size` | 8px | Starting particle size |
+| `color` | gold | Particle tint color |
+| `emitRate` | 30/s | Particles emitted per second |
+| `fadeOut` | true | Particles fade as they age |
+
+## Engine References
+
+- **Phaser 3**: `ref/phaser.js` — uses `scene.add.particles` with `follow()` mode

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

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "atomId": "particle-trail.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "vfx",
+  "mode": "fixed",
+  "label": { "zh": "粒子拖尾特效", "en": "Particle Trail VFX" },
+  "tags": ["vfx", "particle", "trail", "follow", "movement", "playcanvas", "phaser"],
+  "generation": {
+    "animationType": "particle",
+    "engineSupport": ["playcanvas", "phaser"],
+    "parameters": {
+      "target": "entity — object to follow",
+      "count": "number — max particles (default: 20)",
+      "lifetime": "number — particle lifetime in seconds (default: 0.4)",
+      "size": "number — particle start size (default: 8)",
+      "color": "string — particle color (default: '#FFD700')",
+      "offset": "number[] — [x, y] spawn offset from target center"
+    }
+  },
+  "files": { "skill": "SKILL.md", "phaser": "ref/phaser.js" }
+}

package/skills/particle-trail.aicomponent/ref/phaser.js

@@ -0,0 +1,31 @@
+// particle-trail — Phaser 3 implementation
+
+function createTrail(scene, target, {
+  count = 20,
+  lifetime = 400,
+  size = 8,
+  color = 0xFFD700,
+  emitRate = 30,
+} = {}) {
+  const particles = scene.add.particles(0, 0, '__DEFAULT', {
+    lifespan: lifetime,
+    quantity: 1,
+    frequency: 1000 / emitRate,
+    scale: { start: size / 32, end: 0 },
+    alpha: { start: 0.8, end: 0 },
+    tint: color,
+    blendMode: 'ADD',
+    follow: target,
+    followOffset: { x: 0, y: 0 },
+  });
+
+  return {
+    emitter: particles,
+    stop: () => { particles.stop(); scene.time.delayedCall(lifetime, () => particles.destroy()); },
+    destroy: () => particles.destroy(),
+  };
+}
+
+// Usage:
+// const trail = createTrail(this, projectileSprite, { color: 0xFF6600, size: 10 });
+// // On hit: trail.stop();

package/skills/path_animation.aicomponent/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: path_animation.aicomponent
+description: 路径消除玩法的动画导演。负责消除成功的路径滑出动画、被阻挡时的抖动/闪光动画、以及胜利时的钻石粒子动画。
+triggers: 需要为路径消除/阻挡/胜利事件添加视觉动画反馈时触发。
+---
+
+# 路径动画导演（Path Animation Director）
+
+## 说明
+
+`AnimationManager` 管理三类路径动画：
+
+1. **消除滑出**（`animatePathOffBoard`）：路径成功消除后，沿 `direction` 方向用 Tween 动画将路径整体滑出棋盘边界，最后从棋盘移除
+2. **阻挡震动**（`animateBlockedPath`）：路径被阻挡时，播放路径抖动 + 颜色闪红的反馈动画
+3. **胜利钻石**（`playWinDiamondAnimation`）：所有路径消除后，播放全屏钻石粒子爆炸效果
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/scenes/GameUI/AnimationManager.ts` | `ref/AnimationManager.ts` | 完整动画管理类 |
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser Tweens + GameObjects API）
+- `path_renderer.aicomponent`（硬依赖：PathRenderer / PathTrackCell 类型）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/AnimationManager.ts
+outputs:
+  - animationManager: AnimationManager class (animatePathOffBoard / animateBlockedPath / playWinDiamondAnimation)
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **动画与游戏状态分离** | AnimationManager 通过回调（`onComplete`）通知游戏状态变更，不直接修改 `removedPaths` 等状态；状态变更时机由回调决定，动画完成后才生效 |
+| **动画中锁定输入** | 路径滑出期间如允许新点击，可能导致状态不一致；`animatingPaths` Set 由 InputHandler 检查，AnimationManager 只管理动画本身 |
+| **钻石粒子用 Graphics 实现** | 胜利粒子效果无需精灵资产，用 Graphics 随机绘制菱形；保持单一 skill 文件，零资产依赖 |
+
+## Adapter
+
+- **Role**: `pathAnimationDirector` — 路径消除/阻挡/胜利动画导演（Phaser Tweens 编排）
+- **Provides**: `AnimationManager` 类（`animatePathOffBoard()`、`animateBlockedPath()`、`playWinDiamondAnimation()`、`resetBoardViewForWin()`）
+- **Requires**: `phaser.aicomponent`（Tween + Graphics API）、`path_renderer.aicomponent`（PathRenderer / PathTrackCell 类型）
+- **Consumed by**: `game_scene.aicomponent`（持有 AnimationManager，在消除/阻挡时调用对应方法）
+- **Integration point**: `src/game/scenes/GameUI/AnimationManager.ts` → `Game.ts` 实例化并传给 InputHandler
+
+## 关键接口
+
+```typescript
+class AnimationManager {
+  // 路径成功消除的滑出动画
+  animatePathOffBoard(
+    pathIndex: number,
+    dx: number, dy: number,       // 消除方向增量
+    stepsToExit: number,          // 滑出步数
+    isLastPath: boolean,          // 是否是最后一条路径
+    onComplete: () => void,
+  ): void;
+
+  // 路径被阻挡的震动动画
+  animateBlockedPath(
+    pathIndex: number,
+    dx: number, dy: number,
+    stepsUntilBlock: number,
+  ): void;
+
+  // 全部路径消除后的钻石粒子动画
+  playWinDiamondAnimation(): void;
+
+  // 胜利前重置棋盘缩放和位置
+  resetBoardViewForWin(): void;
+}
+```

package/skills/path_animation.aicomponent/manifest.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 1,
+  "atomId": "path_animation.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "路径动画导演", "en": "Path animation director" },
+  "tags": ["animation", "path", "tween", "phaser", "elimination", "blocked", "victory", "threejs", "3d", "raf"],
+  "bindingRoles": ["pathAnimationDirector"],
+  "renderBackend": ["phaser", "threejs"],
+  "engineVariants": {
+    "phaser": {
+      "imports": ["phaser.aicomponent", "path_renderer.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/scenes/GameUI/AnimationManager.ts": { "source": "ref/AnimationManager.ts", "mode": "full", "weight": 10 }
+      }
+    },
+    "threejs": {
+      "imports": ["threejs.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/rendering/AnimationManager3D.ts": { "source": "ref/AnimationManager3D.ts", "mode": "full", "weight": 10 }
+      }
+    }
+  },
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/AnimationManager.ts": {
+        "source": "ref/AnimationManager.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",   "pinAtomId": "phaser.aicomponent",          "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "renderer", "pinAtomId": "path_renderer.aicomponent",   "edgeKind": "requires", "bindAs": "renderer" },
+    {
+      "slot": "normalParticleAsset",
+      "description": "普通消除粒子特效图片资产",
+      "bindAs": "normalParticle",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["particleAsset"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "winParticleAsset",
+      "description": "胜利钻石粒子特效图片资产",
+      "bindAs": "winParticle",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["particleAsset"],
+      "allowedBundleTypes": ["aiimage"]
+    }
+  ],
+  "exports": [
+    { "name": "AnimationManager", "kind": "class", "location": "src/game/scenes/GameUI/AnimationManager.ts" },
+    { "name": "AnimationManager3D", "kind": "class", "location": "src/game/rendering/AnimationManager3D.ts" },
+    { "name": "Easing", "kind": "object", "location": "src/game/rendering/AnimationManager3D.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "animation director for grid path objects: sliding exit animation, blocked flash animation, victory diamond particle animation",
+    "layers": ["tween", "particle-effect", "easing"],
+    "replaceable": ["exit animation style", "blocked animation style", "victory effect"]
+  },
+  "usageHints": [
+    "animatePathOffBoard：路径成功消除时沿方向滑出棋盘的动画",
+    "animateBlockedPath：路径被阻挡时的震动/闪红动画",
+    "playWinDiamondAnimation：全部路径消除后的胜利钻石粒子动画",
+    "resetBoardViewForWin：胜利时重置棋盘缩放/位置以适配动画"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "animationManager": "ref/AnimationManager.ts",
+    "animationManager3D": "ref/AnimationManager3D.ts"
+  }
+}