@playcraft/skills 0.0.2

package/skills/path_input_handler.aicomponent/ref/InputHandler3D.ts

@@ -0,0 +1,204 @@
+import * as THREE from "three";
+
+/**
+ * Raycaster 射线检测命中结果
+ */
+export interface HitResult {
+  /** 命中物体所属的路径索引（来自 userData.pathIndex） */
+  pathIndex: number;
+  /** 命中物体所属的格子索引（来自 userData.cellIndex，可选） */
+  cellIndex: number;
+  /** 命中点的世界坐标 */
+  worldPoint: THREE.Vector3;
+  /** 命中的原始 Object3D */
+  object: THREE.Object3D;
+}
+
+export type OnCellTapCallback = (hit: HitResult) => void;
+
+/**
+ * Three.js 3D 输入处理器配置
+ */
+export interface InputHandler3DConfig {
+  /** Tap 判定阈值：pointer 移动小于此像素数才算 tap（默认 8） */
+  tapThreshold?: number;
+  /** Tap 最大时长：pointerdown→pointerup 小于此毫秒才算 tap（默认 500） */
+  tapTimeMax?: number;
+}
+
+const DEFAULT_CONFIG: Required<InputHandler3DConfig> = {
+  tapThreshold: 8,
+  tapTimeMax: 500,
+};
+
+/**
+ * Three.js Raycaster 输入处理器。
+ *
+ * 核心功能：
+ * - Pointer 事件 → Raycaster 射线检测 → 命中回调
+ * - **Tap/Drag 区分**：记录 pointerdown 位置，只有移动 < tapThreshold
+ *   且时间 < tapTimeMax 时才视为 tap，避免与 OrbitControls 拖动冲突
+ * - enabled 开关用于 inputLocked 场景
+ *
+ * 与 OrbitControls 共存模式：
+ * - OrbitControls 绑定在 canvas 上处理拖动/旋转
+ * - InputHandler3D 绑定 pointerdown+pointerup，只在 tap 时触发 raycast
+ * - 两者互不干扰
+ */
+export class InputHandler3D {
+  private camera: THREE.PerspectiveCamera;
+  private container: HTMLElement;
+  private config: Required<InputHandler3DConfig>;
+  private raycaster = new THREE.Raycaster();
+  private mouse = new THREE.Vector2();
+  private selectableObjects: THREE.Object3D[] = [];
+  private onCellTap: OnCellTapCallback | null = null;
+  private enabled = true;
+
+  // Tap detection state
+  private pointerDownPos = { x: 0, y: 0 };
+  private pointerDownTime = 0;
+
+  // Bound event handlers (for cleanup)
+  private boundPointerDown: ((e: PointerEvent) => void) | null = null;
+  private boundPointerUp: ((e: PointerEvent) => void) | null = null;
+
+  constructor(
+    camera: THREE.PerspectiveCamera,
+    container: HTMLElement,
+    config?: InputHandler3DConfig,
+  ) {
+    this.camera = camera;
+    this.container = container;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * 设置可点击的物体列表。
+   * 每个物体（或其祖先 Group）的 userData 需包含 { pathIndex: number }。
+   * 可选包含 { cellIndex: number }。
+   */
+  setSelectableObjects(objects: THREE.Object3D[]): void {
+    this.selectableObjects = objects;
+  }
+
+  /**
+   * 注册 tap 回调
+   */
+  setOnCellTap(callback: OnCellTapCallback): void {
+    this.onCellTap = callback;
+  }
+
+  /**
+   * 绑定事件监听（pointerdown + pointerup）
+   */
+  bindEvents(): void {
+    this.boundPointerDown = (e: PointerEvent) => this.handlePointerDown(e);
+    this.boundPointerUp = (e: PointerEvent) => this.handlePointerUp(e);
+    this.container.addEventListener("pointerdown", this.boundPointerDown);
+    this.container.addEventListener("pointerup", this.boundPointerUp);
+  }
+
+  /**
+   * 启用/禁用输入（用于 inputLocked 等场景）
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * 获取启用状态
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * 执行射线检测（可直接调用进行手动 raycast）
+   * @param screenX 屏幕 X 坐标 (clientX)
+   * @param screenY 屏幕 Y 坐标 (clientY)
+   * @returns 命中结果或 null
+   */
+  raycast(screenX: number, screenY: number): HitResult | null {
+    const rect = this.container.getBoundingClientRect();
+    this.mouse.x = ((screenX - rect.left) / rect.width) * 2 - 1;
+    this.mouse.y = -((screenY - rect.top) / rect.height) * 2 + 1;
+
+    this.raycaster.setFromCamera(this.mouse, this.camera);
+
+    // Collect all Meshes from selectable objects (traverse Groups)
+    const meshes: THREE.Mesh[] = [];
+    for (const obj of this.selectableObjects) {
+      obj.traverse((child) => {
+        if (child instanceof THREE.Mesh) {
+          meshes.push(child);
+        }
+      });
+    }
+
+    const intersects = this.raycaster.intersectObjects(meshes, false);
+    if (intersects.length === 0) return null;
+
+    const hit = intersects[0];
+
+    // Walk up the parent chain to find userData with pathIndex
+    let current: THREE.Object3D | null = hit.object;
+    while (current) {
+      if (current.userData && typeof current.userData.pathIndex === "number") {
+        return {
+          pathIndex: current.userData.pathIndex,
+          cellIndex: current.userData.cellIndex ?? -1,
+          worldPoint: hit.point.clone(),
+          object: current,
+        };
+      }
+      current = current.parent;
+    }
+
+    return null;
+  }
+
+  /**
+   * 销毁事件监听
+   */
+  destroy(): void {
+    if (this.boundPointerDown) {
+      this.container.removeEventListener("pointerdown", this.boundPointerDown);
+      this.boundPointerDown = null;
+    }
+    if (this.boundPointerUp) {
+      this.container.removeEventListener("pointerup", this.boundPointerUp);
+      this.boundPointerUp = null;
+    }
+    this.selectableObjects = [];
+    this.onCellTap = null;
+  }
+
+  // ── 内部方法 ──
+
+  private handlePointerDown(e: PointerEvent): void {
+    this.pointerDownPos = { x: e.clientX, y: e.clientY };
+    this.pointerDownTime = performance.now();
+  }
+
+  private handlePointerUp(e: PointerEvent): void {
+    if (!this.enabled) return;
+
+    // Tap/Drag discrimination
+    const dx = e.clientX - this.pointerDownPos.x;
+    const dy = e.clientY - this.pointerDownPos.y;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    const elapsed = performance.now() - this.pointerDownTime;
+
+    // Only treat as tap if pointer barely moved and was quick
+    if (distance > this.config.tapThreshold || elapsed > this.config.tapTimeMax) {
+      return; // It was a drag/orbit, not a tap
+    }
+
+    // It's a tap → raycast
+    const hit = this.raycast(e.clientX, e.clientY);
+    if (hit && this.onCellTap) {
+      this.onCellTap(hit);
+    }
+  }
+}

package/skills/path_renderer.aicomponent/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: path_renderer.aicomponent
+description: 路径消除玩法的棋盘路径批量渲染器。负责将 ParsedLevel.paths 数组绘制为带颜色和方向箭头的折线路径，支持圆角/方角两种线段风格和 sprite-per-cell 实体精灵模式，使用 Phaser Graphics/Image API。
+triggers: 需要在棋盘上绘制或更新彩色折线路径和方向箭头时触发。
+---
+
+# 路径批量渲染器（Path Batch Renderer）
+
+## 说明
+
+将 `ParsedLevel.paths` 绘制到棋盘上，支持两种渲染模式：
+
+### 模式 A：线段模式（`renderMode: "line-segment"`）— 默认
+
+- 路径线段：Phaser Graphics 折线，支持圆角（`rounded`）和方角（`square`）两种拐角风格
+- 箭头头部：`fillRoundedTriangle` 绘制等腰三角形箭头，指向路径 `direction`
+- 颜色：通过 `ThemeManager.getPathColor(pathIndex)` 获取（支持主题替换）
+- 批量绘制：接受 `ParsedLevel` 中的全部路径，单次渲染刷新整个棋盘
+
+### 模式 B：精灵铺满模式（`renderMode: "sprite-per-cell"`）— 新增
+
+- 路径覆盖的**每个格子**都渲染一个实体精灵（如小汽车）
+- 所有精灵统一朝向路径的 `direction`（推出方向）
+- 纹理通过 `colorToTextureKey(path.color)` 映射
+- 适用场景：箭头推出类玩法中路径表现为"车队"效果
+- 需配合 `board_entity_sprite.aiimage` 提供多色纹理
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/game/scenes/GameUI/PathRenderer.ts` | `ref/PathRenderer.ts` | 单条路径的完整渲染逻辑 |
+| `src/game/utils/PathRenderers.ts` | `ref/PathRenderers.ts` | 圆角/方角线段渲染实现 + `fillRoundedTriangle` + `PathTrackCell` 类型 |
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser.GameObjects.Graphics API）
+- `arrow_path_data_format.aicomponent`（硬依赖：ParsedLevel / LevelPath / ArrowDirection 类型）
+- `theme_state.aicomponent`（硬依赖：ThemeManager.getPathColor()）
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **与 GameScene 分离** | 渲染逻辑单独封装后，棋盘绘制可独立刷新（不重跑整个 GameScene 生命周期）；且渲染模式可以切换而不影响业务逻辑 |
+| **两种渲染模式统一 API** | `line-segment` 和 `sprite-per-cell` 通过同一 `drawPath()` 接口暴露，调用方无需感知模式差异 |
+| **颜色通过 ThemeManager 获取** | 路径颜色是主题配置的一部分；PathRenderer 依赖 ThemeManager 而非写死颜色，主题切换时渲染自动跟随 |
+
+## Adapter
+
+- **Role**: `pathBatchRenderer` — 将 ParsedLevel.paths 批量渲染到棋盘的 Graphics/Sprite 渲染器
+- **Provides**: `PathRenderer` 类、`fillRoundedTriangle()` 几何工具函数、`PathTrackCell` 类型
+- **Requires**: `phaser.aicomponent`、`arrow_path_data_format.aicomponent`、`theme_state.aicomponent`
+- **Consumed by**: `game_scene.aicomponent`（持有 PathRenderer 实例，在 `drawPaths()` 中调用）
+- **Integration point**: `src/game/scenes/GameUI/PathRenderer.ts` → `Game.ts` 中 `this.pathRenderer = new PathRenderer(this)`
+
+## 关键接口
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/PathRenderer.ts
+  - source: src/game/utils/PathRenderers.ts
+outputs:
+  - pathRenderer: PathRenderer class
+  - pathRenderers: PathTrackCell type + fillRoundedTriangle function
+```
+
+## 关键接口
+
+```typescript
+class PathRenderer {
+  // 绘制单条路径（线段 + 箭头头部）
+  drawPath(
+    g: Phaser.GameObjects.Graphics,
+    path: LevelPath,
+    cellSize: number,
+    pathIndex: number,
+    removed?: boolean,
+  ): void;
+}
+
+// 格子轨迹单元（用于圆角/方角线段渲染）
+type PathTrackCell = {
+  x: number; y: number;
+  inDir?: string; outDir?: string;
+};
+
+// 绘制圆角等腰三角形箭头
+function fillRoundedTriangle(
+  g: Phaser.GameObjects.Graphics,
+  cx: number, cy: number,
+  angle: number,        // 朝向角度（弧度）
+  color: number,
+  size: number,
+): void;
+```

package/skills/path_renderer.aicomponent/manifest.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "atomId": "path_renderer.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "路径批量渲染器", "en": "Path batch renderer" },
+  "tags": ["renderer", "path", "graphics", "arrow", "phaser", "canvas", "draw", "threejs", "3d", "mesh-per-cell"],
+  "bindingRoles": ["pathBatchRenderer"],
+  "renderModes": ["line-segment", "sprite-per-cell", "mesh-per-cell"],
+  "engineVariants": {
+    "phaser": {
+      "imports": ["phaser.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/scenes/GameUI/PathRenderer.ts": { "source": "ref/PathRenderer.ts", "mode": "full", "weight": 10 },
+        "src/game/utils/PathRenderers.ts": { "source": "ref/PathRenderers.ts", "mode": "full", "weight": 10 }
+      }
+    },
+    "threejs": {
+      "imports": ["threejs.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/ui/PathRenderer3D.ts": { "source": "ref/PathRenderer3D.ts", "mode": "full", "weight": 10 }
+      }
+    }
+  },
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/PathRenderer.ts": {
+        "source": "ref/PathRenderer.ts",
+        "mode": "full",
+        "weight": 10
+      },
+      "src/game/utils/PathRenderers.ts": {
+        "source": "ref/PathRenderers.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",    "pinAtomId": "phaser.aicomponent",      "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "levelData", "pinAtomId": "arrow_path_data_format.aicomponent", "edgeKind": "requires", "bindAs": "levelData" },
+    { "slot": "themeState","pinAtomId": "theme_state.aicomponent", "edgeKind": "requires", "bindAs": "themeState" }
+  ],
+  "exports": [
+    { "name": "PathRenderer",        "kind": "class",    "location": "src/game/scenes/GameUI/PathRenderer.ts" },
+    { "name": "PathRenderers",       "kind": "module",   "location": "src/game/utils/PathRenderers.ts" },
+    { "name": "fillRoundedTriangle", "kind": "function", "location": "src/game/utils/PathRenderers.ts" },
+    { "name": "PathTrackCell",       "kind": "type",     "location": "src/game/utils/PathRenderers.ts" },
+    { "name": "PathRenderer3D",      "kind": "class",    "location": "src/game/ui/PathRenderer3D.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "batch renderer for colored polyline paths with directional arrowheads on a grid canvas",
+    "layers": ["canvas-drawing", "graphics-primitive", "arrow-rendering"],
+    "replaceable": ["arrowhead style (triangle vs sprite)", "corner style (rounded vs square)", "line width ratio"]
+  },
+  "usageHints": [
+    "PathRenderer 负责在 Phaser Graphics 对象上绘制单条路径（线段 + 箭头头部）",
+    "PathRenderers 提供圆角/方角两种线段渲染实现",
+    "fillRoundedTriangle 绘制路径末端的箭头三角形",
+    "通过 ThemeManager 获取路径颜色，支持主题替换"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "pathRenderer": "ref/PathRenderer.ts",
+    "pathRenderers": "ref/PathRenderers.ts",
+    "pathRenderer3D": "ref/PathRenderer3D.ts"
+  }
+}