@playcraft/skills 0.0.2

package/skills/arrow_path_data_format.aicomponent/ref/LevelParser.ts

@@ -0,0 +1,188 @@
+import {
+  ArrowDirection,
+  GridPoint,
+  LevelPath,
+  ParsedLevel,
+  RawLevelJson,
+} from "./LevelTypes";
+
+/**
+ * 解析 Cocos JsonAsset 导出的关卡 json（例如 level1.json）。
+ *
+ * 该 json 的结构大致为一个数组：
+ * [
+ *   1, 0, 0,
+ *   [["cc.JsonAsset", ["_name", "json"], 1]],
+ *   [[0, 0, 1, 3]],
+ *   [[0, "level_new_1", { ...关卡对象... }]],
+ *   0, 0, [], [], []
+ * ]
+ *
+ * 实际关卡对象位于 root[5][0][2]。
+ */
+export function parseLevelJson(raw: unknown): ParsedLevel {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("Invalid level json: expected object");
+  }
+
+  // Some level assets are exported as Cocos JsonAsset array wrappers.
+  // The actual level object is typically located at root[5][0][2].
+  let target: unknown = raw;
+  if (Array.isArray(target)) {
+    const root = target as unknown[];
+    const maybe = root[5];
+    if (
+      Array.isArray(maybe) &&
+      Array.isArray(maybe[0]) &&
+      (maybe[0] as unknown[]).length >= 3
+    ) {
+      target = (maybe[0] as unknown[])[2];
+    }
+  }
+
+  if (typeof target !== "object" || target === null) {
+    throw new Error("Invalid level json: expected object");
+  }
+
+  const obj = target as Partial<RawLevelJson>;
+
+  const index: number = typeof obj.name === "number" ? obj.name : 0;
+  const rows: number = typeof obj.row === "number" ? obj.row : 0;
+  const cols: number = typeof obj.col === "number" ? obj.col : 0;
+  const levelTime: number =
+    typeof obj.levelTime === "number" && obj.levelTime > 0 ? obj.levelTime : 0;
+
+  const rawArrows: unknown = obj.arrows ?? [];
+
+  if (!Array.isArray(rawArrows)) {
+    throw new Error("Invalid level json: arrows must be an array");
+  }
+
+  const paths: LevelPath[] = (rawArrows as unknown[]).map(
+    (rawPath, pathIndex) => {
+      if (!Array.isArray(rawPath)) {
+        throw new Error(
+          `Invalid level json: elements[${pathIndex}] is not an array`,
+        );
+      }
+
+      // arrows：第一个点的第三个元素为颜色字符串（可选）
+      const firstPoint = (rawPath as unknown[])[0];
+      let pathColor: string | undefined;
+      if (Array.isArray(firstPoint) && firstPoint.length >= 3) {
+        const maybeColor = firstPoint[2];
+        if (typeof maybeColor === "string") {
+          pathColor = maybeColor;
+        }
+      }
+
+      const points: GridPoint[] = (rawPath as unknown[]).map(
+        (p, pointIndex) => {
+          if (!Array.isArray(p) || p.length < 2) {
+            throw new Error(
+              `Invalid level json: elements[${pathIndex}][${pointIndex}] not [x,y]`,
+            );
+          }
+          const [x, cocosY] = p as [number, number];
+          // Cocos 的关卡坐标以底部为 y=0，向上递增；
+          // Phaser 中我们使用传统屏幕坐标：y 从上往下递增。
+          // 因此在解析阶段进行一次上下翻转，统一成“0 在顶部”的行列索引。
+          const phaserY = rows > 0 ? rows - 1 - cocosY : cocosY;
+          return { x, y: phaserY };
+        },
+      );
+
+      if (points.length === 0) {
+        return {
+          points: [],
+          head: { x: 0, y: 0 },
+          direction: ArrowDirection.Right,
+          indices: [],
+        };
+      }
+
+      const head = points[points.length - 1]!;
+      const beforeHead = points[Math.max(0, points.length - 2)]!;
+
+      const dx = head.x - beforeHead.x;
+      const dy = head.y - beforeHead.y;
+
+      let direction: ArrowDirection;
+      if (Math.abs(dx) >= Math.abs(dy)) {
+        // 水平为主
+        direction = dx < 0 ? ArrowDirection.Left : ArrowDirection.Right;
+      } else {
+        // 垂直为主
+        direction = dy < 0 ? ArrowDirection.Up : ArrowDirection.Down;
+      }
+
+      // 将路径离散成覆盖到的所有网格索引（含端点），方便构建棋盘格子
+      const indices: number[] = [];
+
+      const pushIndex = (x: number, y: number) => {
+        if (x < 0 || y < 0 || x >= cols || y >= rows) return;
+        const idx = y * cols + x;
+        if (!indices.includes(idx)) {
+          indices.push(idx);
+        }
+      };
+
+      for (let i = 0; i < points.length - 1; i++) {
+        const a = points[i]!;
+        const b = points[i + 1]!;
+
+        if (a.x === b.x) {
+          // 垂直线段
+          const step = b.y > a.y ? 1 : -1;
+          for (let y = a.y; y !== b.y + step; y += step) {
+            pushIndex(a.x, y);
+          }
+        } else if (a.y === b.y) {
+          // 水平线段
+          const step = b.x > a.x ? 1 : -1;
+          for (let x = a.x; x !== b.x + step; x += step) {
+            pushIndex(x, a.y);
+          }
+        } else {
+          // 理论上不会出现斜线，如果有就只记录端点，避免崩溃
+          pushIndex(a.x, a.y);
+          pushIndex(b.x, b.y);
+        }
+      }
+
+      return {
+        points,
+        head,
+        direction,
+        indices,
+        ...(pathColor !== undefined ? { color: pathColor } : {}),
+      };
+    },
+  );
+
+  const timeSeconds = levelTime;
+
+  return {
+    index,
+    rows,
+    cols,
+    paths,
+    timeSeconds,
+    ...(obj.background !== undefined ? { background: obj.background } : {}),
+  };
+}
+
+/**
+ * 将关卡 JSON 解析为 Three.js XZ 平面坐标。
+ *
+ * 坐标映射关系：
+ * - Phaser GridPoint.x → Three.js position.x（向右）
+ * - Phaser GridPoint.y → Three.js position.z（向下 / 屏幕内）
+ * - Three.js position.y 固定为 0（地面高度）
+ *
+ * 由于 Phaser 的 (x, y_down) 和 Three.js 俯视的 (x, z_down) 语义一致，
+ * 实际上复用 parseLevelJson 即可，无需额外翻转。
+ */
+export function parseLevelFor3D(raw: unknown): ParsedLevel {
+  return parseLevelJson(raw);
+}

package/skills/arrow_path_data_format.aicomponent/ref/LevelTypes.ts

@@ -0,0 +1,131 @@
+export type GridPoint = {
+  x: number;
+  y: number;
+};
+
+export enum ArrowDirection {
+  Left = "left",
+  Right = "right",
+  Up = "up",
+  Down = "down",
+}
+
+export type LevelPath = {
+  /** 原始路径点序列（网格坐标） */
+  points: GridPoint[];
+  /** 箭头所在的终点格子（我们约定为路径最后一个点） */
+  head: GridPoint;
+  /** 箭头朝向：由倒数第二个点指向最后一个点推导 */
+  direction: ArrowDirection;
+  /** 该路径覆盖的所有格子索引（row-major: index = y * cols + x） */
+  indices: number[];
+  /** 线段颜色（十六进制字符串，如 '#ff0000'），无则为黑色 */
+  color?: string;
+};
+
+/**
+ * 与新生成的关卡 JSON 文件一一对应的原始数据结构。
+ * 示例（level1.json）：
+ * {
+ *   "name": 1,
+ *   "row": 10,
+ *   "col": 8,
+ *   "arrows": [...],
+ *   "levelTime": 300,
+ * }
+ */
+export type RawLevelJson = {
+  name: number | string;
+  row: number;
+  col: number;
+  /** 旧格式线段数据，每条线段为拐角点数组，第一个点可含第三个元素作为颜色字符串 */
+  arrows: (number | string)[][][];
+  levelTime: number;
+  /** 背景图片配置 */
+  background?: {
+    imageKey: string;
+    dataUrl?: string; // 图片数据URL，用于在游戏场景中重新创建纹理
+    opacity?: number;
+  };
+};
+
+/**
+ * 经过解析和坐标转换后，供游戏逻辑使用的规范化关卡结构。
+ */
+export type ParsedLevel = {
+  /** 关卡序号，例如 1、2、3（来自 RawLevelJson.name） */
+  index: number;
+  /** 行数 / 列数 */
+  rows: number;
+  cols: number;
+  /** 解析后的所有路径 */
+  paths: LevelPath[];
+  /** 关卡总时间（秒） */
+  timeSeconds: number;
+  /** 背景图片配置 */
+  background?: {
+    imageKey: string;
+    dataUrl?: string; // 图片数据URL，用于在游戏场景中重新创建纹理
+    opacity?: number;
+  };
+};
+
+export interface ThemeVariantConfig {
+  levels: RawLevelJson[];
+
+  // 基础信息
+  name: string; // 变体显示名称
+  themeId: string; // 使用的主题ID（对应 ThemeManager）
+
+  // 关卡配置
+  levelMode: number; // 关卡模式: 0=闯关(level1-314), 1=简单(level1), 2=复杂(level2), 3=炸弹(level3),
+  //         999=轻松(level999), 1000=爱心(level1000), 1002=钻石(level1002), 1003=笑脸(level1003)
+  segmentsMode?: number; // 快速胜利模式: 消除N条线段即胜利 (0或undefined=关闭)
+  autoHint?: boolean; // 自动提示 (默认true)
+  shouldDrawEliminationTrail?: boolean; // 是否应绘制消除轨迹 (默认true)
+
+  // 颜色覆盖（覆盖主题的默认颜色）
+  canvasBgColor?: number; // 画布背景色 (十六进制, 如 0xf7d37f)
+  uiBarBgColor?: number; // UI栏背景色 (十六进制)
+}
+
+// ─── 3D 坐标系支持（Three.js） ───
+
+/** 坐标系声明，用于 Agent 组装时选择正确的解析和渲染方式 */
+export type CoordinateSystem = "phaser-y-down" | "threejs-xz";
+
+/** 3D 网格点：X 向右，Z 向下（俯视），Y 固定为 0（地面高度） */
+export type GridPoint3D = {
+  x: number;
+  z: number;
+};
+
+/**
+ * Three.js Y 轴旋转角度映射。
+ * 假设模型默认朝向 +Z（即 ArrowDirection.Down 对应角度 0）。
+ * - Up (向 -Z)：π
+ * - Down (向 +Z)：0
+ * - Left (向 -X)：-π/2
+ * - Right (向 +X)：π/2
+ */
+export function directionToAngleY(dir: ArrowDirection): number {
+  switch (dir) {
+    case ArrowDirection.Up: return Math.PI;
+    case ArrowDirection.Down: return 0;
+    case ArrowDirection.Left: return -Math.PI / 2;
+    case ArrowDirection.Right: return Math.PI / 2;
+  }
+}
+
+/**
+ * 3D 方向到世界位移向量（XZ 平面）。
+ * 用于计算滑出方向。
+ */
+export function directionToDelta3D(dir: ArrowDirection): { dx: number; dz: number } {
+  switch (dir) {
+    case ArrowDirection.Up: return { dx: 0, dz: -1 };
+    case ArrowDirection.Down: return { dx: 0, dz: 1 };
+    case ArrowDirection.Left: return { dx: -1, dz: 0 };
+    case ArrowDirection.Right: return { dx: 1, dz: 0 };
+  }
+}

package/skills/arrow_pick_match_rules.aigameplay/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: arrow_pick_match_rules.aigameplay
+description: 箭头推出三消玩法核心规则（PGS）。棋盘上有多条带颜色和方向的路径（每条路径占据若干连续格子），玩家点击路径触发沿方向推出。路径滑出棋盘后飞入底部篮子，篮子中凑齐 3 条同色路径即自动消除。所有路径推出且篮子清空为胜利；篮子满溢或超时为失败。
+triggers: 需要生成箭头推出三消、arrow pick match、方向推出+篮子消除、车队推出收集 类玩法时触发。
+---
+
+# 箭头推出三消玩法（Arrow Pick & Match）
+
+## 玩法说明
+
+棋盘上有若干路径，每条路径由**多个连续格子**组成，占据一定长度。每条路径有一个**颜色**和一个**推出方向**（由路径形状推导：最后两个点的走向）。
+
+路径用小汽车（或其他实体精灵）表示，路径覆盖的每个格子都放置一辆同色、同朝向的汽车，形成"车队"效果。
+
+### 核心循环
+
+1. 玩家点击某条路径（命中路径上任意格子）
+2. 系统检测该路径推出方向上是否有其他路径阻挡
+3. **无阻挡** → 整条路径沿方向滑出棋盘边界 → head 汽车飞入底部篮子
+4. **有阻挡** → 棋盘抖动 + 路径短暂变红，不推出
+5. 飞入篮子后，同色物品自动聚合排列
+6. 凑齐 3 个同色 → 自动消除
+7. 重复直到胜利或失败
+
+### 与父玩法的关系
+
+本玩法是 `path_elimination_rules` 和 `pick_and_match_rules` 的**融合**：
+
+| 机制 | 来源 | 本玩法中的表现 |
+|------|------|--------------|
+| 路径方向 + 阻挡检测 + 滑出动画 | `path_elimination_rules` | 点击→检测→滑出 |
+| 篮子容器 + 同类聚合 + 3消 | `pick_and_match_rules` | 飞入→聚合→消除 |
+| 匹配维度 | 简化 | 单维度（仅颜色），不含形状 |
+| 堆叠层级 | 不使用 | 所有路径在同一层 |
+
+## Recipe
+
+```json
+{
+  "kind": "pgs",
+  "pgsVersion": "1.0",
+  "gameplayType": "arrow_pick_match",
+  "rules": {
+    "matchCount": 3,
+    "trayCapacity": 7,
+    "matchDimension": "color_only",
+    "layerStacking": false,
+    "blockingModel": "path_direction_check",
+    "pickTrigger": "slide_out"
+  }
+}
+```
+
+## Result
+
+产物为 `ref/pgs-schema.json`，描述完整规则。
+
+## 核心机制详解
+
+### 1. 路径数据模型
+
+每条路径包含：
+- **points[]**: 路径覆盖的格子坐标列表
+- **head**: 最后一个点（车头位置）
+- **direction**: 推出方向（由最后两个点推导）
+- **color**: 颜色标识（用于篮子匹配）
+- **indices[]**: 覆盖的所有格子索引（用于碰撞检测）
+
+### 2. 阻挡检测
+
+从 head 位置出发，沿 direction 逐格检测：
+- 如果遇到其他未移除路径占据的格子 → 阻挡
+- 如果到达棋盘边界 → 可推出，记录 stepsToExit
+
+### 3. 同色聚合插入
+
+新物品进入篮子时，自动插到最后一个同色物品旁边（而非追加末尾），方便玩家观察凑齐进度。
+
+### 4. 关卡设计约束
+
+- 每种颜色的路径数量**必须恰好为 3**（matchCount）
+- 路径不得共享格子（无重叠）
+- 必须存在合法的推出序列使篮子不溢出（由 `level_solvability_validator` 验证）
+
+## Binding
+
+```json
+{
+  "role": "gameplayRule",
+  "target": "src/game/",
+  "type": "gameplay-module-reference",
+  "constraints": {
+    "requiredComponents": [
+      "tray_container.aicomponent",
+      "match_engine.aicomponent",
+      "slide_out_to_tray_animation.aicomponent",
+      "path_input_handler.aicomponent",
+      "grid_board_layout.aicomponent",
+      "board_entity_sprite.aiimage",
+      "level_solvability_validator.aivalidator"
+    ]
+  }
+}
+```
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - pgsSchema: ref/pgs-schema.json
+outputs:
+  - gameScene: Game.ts 主场景协调逻辑
+  - levelData: 关卡数据（arrows 格式）
+```

package/skills/arrow_pick_match_rules.aigameplay/manifest.json

@@ -0,0 +1,105 @@
+{
+  "schemaVersion": 1,
+  "atomId": "arrow_pick_match_rules.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "箭头推出三消玩法（Arrow + Pick & Match）",
+    "en": "Arrow slide-out + tray match-3 gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "arrow",
+    "slide-out",
+    "pick-and-match",
+    "tray",
+    "match-3",
+    "puzzle",
+    "direction",
+    "path",
+    "car"
+  ],
+  "bindingRoles": [
+    "gameplayRule"
+  ],
+  "imports": [
+    { "slot": "engine",      "pinAtomId": "phaser.aicomponent",                "edgeKind": "requires",      "bindAs": "engine" },
+    { "slot": "boardLayout", "pinAtomId": "grid_board_layout.aicomponent",     "edgeKind": "requires",      "bindAs": "boardLayout" },
+    { "slot": "input",       "pinAtomId": "path_input_handler.aicomponent",    "edgeKind": "requires",      "bindAs": "input" },
+    { "slot": "levelData",   "pinAtomId": "arrow_path_data_format.aicomponent","edgeKind": "requires",      "bindAs": "levelData" },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["bgMusic"],
+      "allowedBundleTypes": ["aiaudio"],
+      "constraints": { "loop": true }
+    },
+    {
+      "slot": "background",
+      "description": "游戏背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["backgroundTexture"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "entitySprite",
+      "description": "棋盘实体精灵（箭头/车辆方向指示）",
+      "bindAs": "entitySprite",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["boardEntitySprite"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "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"]
+    }
+  ],
+  "binding": {
+    "role": "gameplayRule",
+    "target": "src/game/",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "requiredComponents": [
+        "tray_container.aicomponent",
+        "match_engine.aicomponent",
+        "slide_out_to_tray_animation.aicomponent",
+        "path_input_handler.aicomponent",
+        "grid_board_layout.aicomponent",
+        "board_entity_sprite.aiimage",
+        "level_solvability_validator.aivalidator"
+      ]
+    }
+  },
+  "pgs": {
+    "gameplayType": "arrow_pick_match",
+    "parentTypes": ["path_elimination", "pick_and_match"],
+    "fusionDescription": "融合 path_elimination 的方向推出机制和 pick_and_match 的篮子三消机制"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "ref": [
+      "ref/pgs-schema.json"
+    ]
+  }
+}