@playcraft/skills 0.0.2

package/skills/path_animation.aicomponent/ref/AnimationManager3D.ts

@@ -0,0 +1,317 @@
+import * as THREE from "three";
+
+// ─── Easing 函数库 ───
+
+export type EasingFn = (t: number) => number;
+
+export const Easing = {
+  linear: (t: number) => t,
+  easeOutQuad: (t: number) => 1 - (1 - t) * (1 - t),
+  easeInOutQuad: (t: number) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+  easeOutCubic: (t: number) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t: number) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+  easeOutBack: (t: number) => {
+    const c1 = 1.70158;
+    const c3 = c1 + 1;
+    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+  },
+};
+
+// ─── 动画参数接口 ───
+
+export interface SlideOutParams {
+  /** 要滑出的物体列表 */
+  objects: THREE.Object3D[];
+  /** 滑出方向 (dx 控制 X 轴, dz 控制 Z 轴) */
+  direction: { dx: number; dz: number };
+  /** 滑出总距离（世界单位） */
+  distance: number;
+  /** 动画时长 ms（默认 350） */
+  duration?: number;
+  /** 缓动函数（默认 easeOutQuad） */
+  easing?: EasingFn;
+  /** 动画完成回调 */
+  onComplete?: () => void;
+}
+
+export interface FlyUpParams {
+  /** 要飞起的物体 */
+  object: THREE.Object3D;
+  /** 飞起高度（世界单位，默认 3） */
+  height?: number;
+  /** 前移距离（Z 方向，默认 1.5） */
+  forwardDistance?: number;
+  /** 动画时长 ms（默认 400） */
+  duration?: number;
+  /** 是否渐隐（默认 true） */
+  fadeOut?: boolean;
+  /** 缓动函数（默认 easeInOutQuad） */
+  easing?: EasingFn;
+  /** 动画完成回调 */
+  onComplete?: () => void;
+}
+
+/**
+ * Three.js 3D 路径动画管理器
+ *
+ * 基于 requestAnimationFrame 的轻量动画系统（零第三方依赖）。
+ * 提供棋盘游戏常用的动画操作：
+ * - slideOut：物体沿方向滑出（路径推出）
+ * - flyUp：物体升起并渐隐消失（飞入篮子视觉）
+ * - shake：物体抖动反馈（被阻挡）
+ * - scaleOut：物体缩放消失（三消消除）
+ *
+ * 支持物体从 parent group 中 detach 后独立动画（不受 group shake 影响）。
+ */
+export class AnimationManager3D {
+  private scene: THREE.Scene;
+  private activeRAFs: Set<number> = new Set();
+  private detachedObjects: THREE.Object3D[] = [];
+
+  constructor(scene: THREE.Scene) {
+    this.scene = scene;
+  }
+
+  /**
+   * 沿方向滑出一组物体（保持相对位置）。
+   * 动画期间物体会被从当前 parent detach 到 scene 根节点。
+   */
+  slideOut(params: SlideOutParams): void {
+    const {
+      objects,
+      direction,
+      distance,
+      duration = 350,
+      easing = Easing.easeOutQuad,
+      onComplete,
+    } = params;
+
+    if (objects.length === 0) {
+      onComplete?.();
+      return;
+    }
+
+    // Detach objects from their parent, preserve world position
+    const worldPositions = objects.map((obj) => {
+      const wp = new THREE.Vector3();
+      obj.getWorldPosition(wp);
+      return wp;
+    });
+
+    for (let i = 0; i < objects.length; i++) {
+      const obj = objects[i];
+      obj.parent?.remove(obj);
+      obj.position.copy(worldPositions[i]);
+      this.scene.add(obj);
+      this.detachedObjects.push(obj);
+    }
+
+    // Animate
+    const startTime = performance.now();
+
+    const animate = () => {
+      const elapsed = performance.now() - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const eased = easing(progress);
+
+      const offsetX = direction.dx * distance * eased;
+      const offsetZ = direction.dz * distance * eased;
+
+      for (let i = 0; i < objects.length; i++) {
+        objects[i].position.x = worldPositions[i].x + offsetX;
+        objects[i].position.z = worldPositions[i].z + offsetZ;
+      }
+
+      if (progress < 1) {
+        const id = requestAnimationFrame(animate);
+        this.activeRAFs.add(id);
+      } else {
+        // 动画完成，移除物体
+        for (const obj of objects) {
+          this.scene.remove(obj);
+          this.removeFromDetached(obj);
+        }
+        onComplete?.();
+      }
+    };
+
+    const id = requestAnimationFrame(animate);
+    this.activeRAFs.add(id);
+  }
+
+  /**
+   * 物体升起并渐隐消失（飞入篮子 / 收集效果）
+   */
+  flyUp(params: FlyUpParams): void {
+    const {
+      object,
+      height = 3,
+      forwardDistance = 1.5,
+      duration = 400,
+      fadeOut = true,
+      easing = Easing.easeInOutQuad,
+      onComplete,
+    } = params;
+
+    if (!object.parent) {
+      onComplete?.();
+      return;
+    }
+
+    const startPos = object.position.clone();
+    const startScale = object.scale.x;
+    const startTime = performance.now();
+
+    const animate = () => {
+      const elapsed = performance.now() - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const eased = easing(progress);
+
+      // Move up + forward
+      object.position.y = startPos.y + eased * height;
+      object.position.z = startPos.z + eased * forwardDistance;
+
+      // Scale down
+      const scale = startScale * (1 - eased * 0.8);
+      object.scale.set(scale, scale, scale);
+
+      // Fade out
+      if (fadeOut) {
+        object.traverse((child) => {
+          if (child instanceof THREE.Mesh) {
+            const mat = child.material as THREE.MeshStandardMaterial;
+            if (!mat.transparent) mat.transparent = true;
+            mat.opacity = 1 - eased;
+          }
+        });
+      }
+
+      if (progress < 1) {
+        const id = requestAnimationFrame(animate);
+        this.activeRAFs.add(id);
+      } else {
+        object.parent?.remove(object);
+        this.removeFromDetached(object);
+        onComplete?.();
+      }
+    };
+
+    const id = requestAnimationFrame(animate);
+    this.activeRAFs.add(id);
+  }
+
+  /**
+   * 物体抖动反馈（被阻挡效果）
+   */
+  shake(
+    object: THREE.Object3D,
+    intensity: number = 0.08,
+    duration: number = 300,
+  ): void {
+    const originalX = object.position.x;
+    const originalZ = object.position.z;
+    const startTime = performance.now();
+
+    const animate = () => {
+      const elapsed = performance.now() - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+
+      if (progress < 1) {
+        const decay = 1 - progress;
+        object.position.x = originalX + Math.sin(progress * Math.PI * 6) * intensity * decay;
+        object.position.z = originalZ + Math.cos(progress * Math.PI * 4) * intensity * decay * 0.5;
+        const id = requestAnimationFrame(animate);
+        this.activeRAFs.add(id);
+      } else {
+        object.position.x = originalX;
+        object.position.z = originalZ;
+      }
+    };
+
+    const id = requestAnimationFrame(animate);
+    this.activeRAFs.add(id);
+  }
+
+  /**
+   * 物体缩放消失（三消消除效果）
+   */
+  scaleOut(
+    object: THREE.Object3D,
+    duration: number = 300,
+    onComplete?: () => void,
+  ): void {
+    const startScale = object.scale.x;
+    const startTime = performance.now();
+
+    const animate = () => {
+      const elapsed = performance.now() - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+
+      // Scale up briefly then shrink to 0
+      let scale: number;
+      if (progress < 0.3) {
+        scale = startScale * (1 + (progress / 0.3) * 0.3); // expand to 1.3x
+      } else {
+        const t = (progress - 0.3) / 0.7;
+        scale = startScale * 1.3 * (1 - t); // shrink to 0
+      }
+      object.scale.set(scale, scale, scale);
+
+      // Fade
+      object.traverse((child) => {
+        if (child instanceof THREE.Mesh) {
+          const mat = child.material as THREE.MeshStandardMaterial;
+          if (!mat.transparent) mat.transparent = true;
+          mat.opacity = 1 - progress;
+        }
+      });
+
+      if (progress < 1) {
+        const id = requestAnimationFrame(animate);
+        this.activeRAFs.add(id);
+      } else {
+        object.parent?.remove(object);
+        this.removeFromDetached(object);
+        onComplete?.();
+      }
+    };
+
+    const id = requestAnimationFrame(animate);
+    this.activeRAFs.add(id);
+  }
+
+  /**
+   * 取消所有进行中的动画
+   */
+  cancelAll(): void {
+    for (const id of this.activeRAFs) {
+      cancelAnimationFrame(id);
+    }
+    this.activeRAFs.clear();
+  }
+
+  /**
+   * 清理所有被 detach 的物体（用于关卡重置）
+   */
+  cleanupDetached(): void {
+    for (const obj of this.detachedObjects) {
+      this.scene.remove(obj);
+    }
+    this.detachedObjects = [];
+  }
+
+  /**
+   * 销毁
+   */
+  dispose(): void {
+    this.cancelAll();
+    this.cleanupDetached();
+  }
+
+  // ── 内部方法 ──
+
+  private removeFromDetached(obj: THREE.Object3D): void {
+    const idx = this.detachedObjects.indexOf(obj);
+    if (idx >= 0) this.detachedObjects.splice(idx, 1);
+  }
+}

package/skills/path_elimination_rules.aigameplay/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: path_elimination_rules.aigameplay
+description: 路径消除玩法核心规则（PGS）。棋盘上有多条彩色折线路径，末端有方向箭头。玩家点击箭头头部：出口方向空闲则消除路径；被阻挡则扣命。全部路径消除后胜利，生命耗尽或倒计时归零则失败。
+triggers: 需要生成路径消除类玩法的 reducer、PGS schema、关卡规则时触发。
+---
+
+# 路径消除玩法（Path Elimination）
+
+## 玩法说明
+
+棋盘上有若干彩色折线路径（polyline），每条路径末端有一个方向箭头。玩家点击箭头头部尝试消除该路径：
+
+- **成功消除**：箭头方向上到棋盘边界的所有格子均空闲 → 路径滑出动画 → 加入已消除集合 → 连击计数
+- **阻挡失败**：出口方向被其他路径占据 → 阻挡动画 → 扣除 1 条命 → 连击重置
+- **胜利**：所有路径消除（`removedPaths.size >= level.paths.length`）
+- **失败**：生命值归零（`currentLives <= 0`）或倒计时归零（仅当 `levelTime > 0`）
+
+## Recipe
+
+```json
+{
+  "kind": "pgs",
+  "pgsVersion": "1.0",
+  "gameplayType": "path_elimination",
+  "rules": {
+    "gridSizeDynamic": true,
+    "livesInitial": 3,
+    "timerOptional": true,
+    "comboEnabled": true
+  }
+}
+```
+
+完整 PGS Schema 见 `ref/pgs-schema.json`。
+
+## Result
+
+产物为 `ref/pgs-schema.json`，描述完整的路径消除玩法规则，包含：
+
+- 实体定义（grid / path / lives / timer / combo）
+- 规则（命中检测 / 消除逻辑 / 阻挡逻辑 / 连击 / 输入锁）
+- 关卡数据 schema（RawLevelJson 格式）
+- 算法步骤（8 步主循环）
+- 胜负条件
+- 5 个测试用例
+
+## Binding
+
+```json
+{
+  "role": "gameplayRule",
+  "target": "src/game/",
+  "type": "gameplay-module-reference",
+  "constraints": {
+    "requiredComponents": [
+      "arrow_path_data_format.aicomponent",
+      "path_renderer.aicomponent",
+      "path_animation.aicomponent",
+      "path_input_handler.aicomponent",
+      "level_lifecycle.aicomponent"
+    ]
+  }
+}
+```
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - pgsSchema: ref/pgs-schema.json
+outputs:
+  - reducerTemplate: game logic reducer based on PGS schema
+```
+
+## 与旧 arrow_escape_core.aigameplay 的区别
+
+| 维度 | 旧版（已废弃） | 新版 |
+|-----|------------|-----|
+| 玩法描述 | 玩家放置箭头引导角色到出口（roguelike 移动） | 玩家点击路径箭头头部消除（拼图消除） |
+| 网格模型 | 固定 6×6，cell 有 arrow/wall/trap/exit 类型 | 动态尺寸，path 为折线实体，grid 仅作坐标系 |
+| 输入 | 放置/旋转箭头（消耗步数） | 点击路径头部（不消耗步数，有生命值） |
+| 胜负 | 角色到达 exit / 到达 trap 或出界 | 路径全消除 / 生命归零或超时 |
+| 消除机制 | 不存在 | 路径沿方向滑出棋盘（需出口方向空闲） |
+
+旧版 `arrow_escape_core.aigameplay` 已被本 skill 替代，可安全删除。

package/skills/path_elimination_rules.aigameplay/manifest.json

@@ -0,0 +1,119 @@
+{
+  "schemaVersion": 1,
+  "atomId": "path_elimination_rules.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": { "zh": "路径消除核心玩法", "en": "Path elimination core gameplay" },
+  "tags": ["gameplay", "path", "elimination", "arrow", "puzzle", "grid", "core", "swipe"],
+  "bindingRoles": ["gameplayRule"],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "path_elimination",
+    "rules": {
+      "gridSizeDynamic": true,
+      "livesInitial": 3,
+      "timerOptional": true,
+      "comboEnabled": true
+    }
+  },
+  "result": {
+    "outputFile": "ref/pgs-schema.json",
+    "format": "json",
+    "constraints": { "testCasesMustPass": true }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "src/game/",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "requiredComponents": [
+        "arrow_path_data_format.aicomponent",
+        "path_renderer.aicomponent",
+        "path_animation.aicomponent",
+        "path_input_handler.aicomponent",
+        "level_lifecycle.aicomponent"
+      ]
+    }
+  },
+  "imports": [
+    { "slot": "engine",     "pinAtomId": "phaser.aicomponent",               "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "levelData",  "pinAtomId": "arrow_path_data_format.aicomponent","edgeKind": "requires", "bindAs": "levelData" },
+    { "slot": "renderer",   "pinAtomId": "path_renderer.aicomponent",        "edgeKind": "requires", "bindAs": "renderer" },
+    { "slot": "animator",   "pinAtomId": "path_animation.aicomponent",       "edgeKind": "requires", "bindAs": "animator" },
+    { "slot": "input",      "pinAtomId": "path_input_handler.aicomponent",   "edgeKind": "requires", "bindAs": "input" },
+    { "slot": "lifecycle",  "pinAtomId": "level_lifecycle.aicomponent",      "edgeKind": "requires", "bindAs": "lifecycle" },
+    { "slot": "boardLayout","pinAtomId": "grid_board_layout.aicomponent",    "edgeKind": "requires", "bindAs": "boardLayout" },
+    {
+      "slot": "directionalIndicator",
+      "description": "棋盘上每条路径末端的方向指示视觉资源（4 方向箭头），可替换为其他视觉风格",
+      "bindAs": "directionSprite",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["directionalIndicator"],
+      "allowedBundleTypes": ["aiimage"],
+      "constraints": { "directions": 4 },
+      "cardinality": 1
+    },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["bgMusic"],
+      "allowedBundleTypes": ["aiaudio"],
+      "constraints": { "loop": true }
+    },
+    {
+      "slot": "levelDataPack",
+      "description": "关卡数据包（RawLevelJson 数组）",
+      "bindAs": "levels",
+      "required": true,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["levelDataPack"],
+      "allowedBundleTypes": ["aiconfig"]
+    },
+    {
+      "slot": "themeVariant",
+      "description": "主题变体配置（颜色/关卡模式等）",
+      "bindAs": "theme",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["themeVariantConfig"],
+      "allowedBundleTypes": ["aiconfig"]
+    },
+    {
+      "slot": "winPanel",
+      "description": "通关反馈面板视觉",
+      "bindAs": "winPanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["successFeedbackPanel"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "losePanel",
+      "description": "失败反馈面板视觉",
+      "bindAs": "losePanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["failFeedbackPanel"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "background",
+      "description": "游戏背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["backgroundTexture"],
+      "allowedBundleTypes": ["aiimage"]
+    }
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json"
+  }
+}