@playcraft/skills 0.0.2

package/skills/ball_sort.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,192 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 球排序核心玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "ball_sort",
+  "entities": {
+    "tube": {
+      "type": "container",
+      "count": 8,
+      "capacity": 4,
+      "description": "球的容器（试管），默认 8 根，每根最多容纳 4 个球（由 config 覆盖）"
+    },
+    "ball": {
+      "type": "stackable-item",
+      "colorCount": 6,
+      "description": "彩色球，共 6 种颜色，每种颜色有 4 个球（恰好填满 1 根管子）"
+    },
+    "emptyTubes": {
+      "type": "counter",
+      "initial": 2,
+      "description": "额外的空管子数量，作为缓冲区（由 config 覆盖）"
+    },
+    "moves": {
+      "type": "counter",
+      "initial": 0,
+      "description": "已使用步数（无限制模式）"
+    }
+  },
+  "rules": {
+    "move_top_ball": {
+      "description": "只能移动管子最顶层的球",
+      "source": "top_of_tube_only"
+    },
+    "valid_move_check": {
+      "description": "合法移动的两个条件：1. 目标管顶部颜色与被移动球相同，或目标管为空；2. 目标管未满",
+      "conditions": [
+        "same_color_or_empty_target",
+        "capacity_check"
+      ],
+      "rejectIfFail": true
+    },
+    "optimization": {
+      "description": "优化规则：不允许将一根颜色单一的管子的球移入另一根空管（无意义移动）",
+      "skipPureTubeToEmpty": true
+    }
+  },
+  "algorithm": {
+    "description": "主循环：选择 → 移动 → 胜利/死锁检测",
+    "steps": [
+      "1. 玩家点击源管子，选中最顶层的球",
+      "2. 玩家点击目标管子",
+      "3. 执行 valid_move_check：若不合法则取消选中并提示",
+      "4. 合法则将球从源管顶部移入目标管顶部，moves + 1",
+      "5. 检测胜利条件：每根管子内的球颜色全部相同（或管子为空）",
+      "6. 检测死锁：遍历所有合法移动，若为空则触发失败/提示"
+    ]
+  },
+  "winCondition": {
+    "type": "all_tubes_sorted",
+    "description": "每根非空管子内的球颜色完全相同（一根管子一种颜色）"
+  },
+  "loseCondition": {
+    "type": "deadlock",
+    "description": "当前棋盘上不存在任何合法移动（死锁）"
+  },
+  "testCases": [
+    {
+      "id": "tc_valid_move_same_color",
+      "description": "合法移动：目标管顶部颜色与被移动球相同",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["red", "blue", "red"] },
+          { "id": 1, "balls": ["red"] },
+          { "id": 2, "balls": [] }
+        ],
+        "tubeCapacity": 4,
+        "moves": 0
+      },
+      "action": { "type": "move", "from": 0, "to": 1 },
+      "expectedState": {
+        "tubes": [
+          { "id": 0, "balls": ["red", "blue"] },
+          { "id": 1, "balls": ["red", "red"] },
+          { "id": 2, "balls": [] }
+        ],
+        "moves": 1,
+        "win": false,
+        "deadlock": false
+      }
+    },
+    {
+      "id": "tc_valid_move_to_empty",
+      "description": "合法移动：移入空管",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["blue", "red"] },
+          { "id": 1, "balls": [] },
+          { "id": 2, "balls": ["blue"] }
+        ],
+        "tubeCapacity": 4,
+        "moves": 0
+      },
+      "action": { "type": "move", "from": 0, "to": 1 },
+      "expectedState": {
+        "tubes": [
+          { "id": 0, "balls": ["blue"] },
+          { "id": 1, "balls": ["red"] },
+          { "id": 2, "balls": ["blue"] }
+        ],
+        "moves": 1,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_invalid_move_wrong_color",
+      "description": "非法移动：目标管顶部颜色不同",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["red"] },
+          { "id": 1, "balls": ["blue"] }
+        ],
+        "tubeCapacity": 4,
+        "moves": 0
+      },
+      "action": { "type": "move", "from": 0, "to": 1 },
+      "expectedState": {
+        "tubes": [
+          { "id": 0, "balls": ["red"] },
+          { "id": 1, "balls": ["blue"] }
+        ],
+        "moves": 0,
+        "moveRejected": true
+      }
+    },
+    {
+      "id": "tc_invalid_move_full_tube",
+      "description": "非法移动：目标管已满（容量 4，已有 4 球）",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["red"] },
+          { "id": 1, "balls": ["red", "red", "red", "red"] }
+        ],
+        "tubeCapacity": 4,
+        "moves": 2
+      },
+      "action": { "type": "move", "from": 0, "to": 1 },
+      "expectedState": {
+        "moves": 2,
+        "moveRejected": true
+      }
+    },
+    {
+      "id": "tc_win",
+      "description": "胜利：所有管子排序完成",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["red", "red", "red"] },
+          { "id": 1, "balls": ["blue", "blue", "blue", "red"] },
+          { "id": 2, "balls": [] }
+        ],
+        "tubeCapacity": 4,
+        "moves": 5
+      },
+      "action": { "type": "move", "from": 1, "to": 0 },
+      "expectedState": {
+        "tubes": [
+          { "id": 0, "balls": ["red", "red", "red", "red"] },
+          { "id": 1, "balls": ["blue", "blue", "blue"] },
+          { "id": 2, "balls": [] }
+        ],
+        "moves": 6,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_deadlock_detection",
+      "description": "死锁检测：没有任何合法移动",
+      "initialState": {
+        "tubes": [
+          { "id": 0, "balls": ["red", "blue"] },
+          { "id": 1, "balls": ["blue", "red"] }
+        ],
+        "tubeCapacity": 2,
+        "moves": 10
+      },
+      "action": { "type": "check" },
+      "expectedState": {
+        "deadlock": true,
+        "validMoves": []
+      }
+    }
+  ]
+}

package/skills/ball_sort.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,156 @@
+/**
+ * ball_sort.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成移动逻辑后返回最终状态，
+ * 中间过程（哪个球从哪根管移入哪根管）丢失。
+ *
+ * 渲染层需要分步驱动球的弧线移动动画，因此必须使用下方的
+ * 「分步函数」逐步驱动，每步之间插入 Tween 动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type BallSortConfig = {
+  /** 颜色数量（等于有色管子的数量），默认 6 */
+  colorCount: number;
+  /** 每根管子的容量（球的最大数量），默认 4 */
+  tubeCapacity: number;
+  /** 额外空管子数量（缓冲区），默认 2 */
+  emptyTubeCount: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type BallSortAction =
+  | { type: 'move'; from: number; to: number }  // 将 from 管顶部的球移入 to 管
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+/** 球的颜色，0 ~ colorCount-1 */
+export type BallColor = number;
+
+/** 单根管子的状态，balls[0] 是底部，balls[length-1] 是顶部 */
+export type Tube = BallColor[];
+
+export type BallSortState = {
+  /** 所有管子，tubes[i] 是第 i 根管 */
+  tubes: Tube[];
+  /** 总步数 */
+  moves: number;
+  /** 游戏是否结束（死锁或胜利） */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 上一次移动是否被拒绝 */
+  lastMoveRejected: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 移动球的结果 */
+export type MoveResult = {
+  /** 被移动的球的颜色 */
+  ball: BallColor;
+  /** 源管子索引 */
+  fromTube: number;
+  /** 目标管子索引 */
+  toTube: number;
+  /** 移动后的新状态 */
+  newState: BallSortState;
+};
+
+/** 合法移动描述 */
+export type ValidMove = {
+  from: number;
+  to: number;
+  ball: BallColor;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置生成随机初始状态
+ * - 生成 colorCount 根有色管子（每管随机混色球，共 tubeCapacity 个）
+ * - 再添加 emptyTubeCount 根空管
+ * - 确保初始状态不是已胜利状态
+ */
+export declare function init(config: BallSortConfig): BallSortState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - move：尝试将 from 管顶部的球移入 to 管，验证合法性并执行
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: BallSortState, action: BallSortAction): BallSortState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: BallSortState): BallSortState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * isValidMove：检测从 from 管将顶球移入 to 管是否合法
+ *
+ * 合法条件：
+ * 1. from 管非空
+ * 2. to 管未满
+ * 3. to 管为空 OR to 管顶部颜色 === from 管顶部颜色
+ *
+ * 场景层在玩家点击目标管时调用，决定高亮效果与是否执行移动。
+ */
+export declare function isValidMove(
+  state: BallSortState,
+  from: number,
+  to: number,
+): boolean;
+
+/**
+ * moveBall：执行移动（不做合法性验证，调用前请先调用 isValidMove）
+ *
+ * 场景层在合法性确认后调用，播放球的弧线移动动画。
+ * 返回被移动球的颜色和新状态，用于动画 + 状态同步。
+ */
+export declare function moveBall(
+  state: BallSortState,
+  from: number,
+  to: number,
+): MoveResult;
+
+/**
+ * checkWin：检测当前状态是否满足胜利条件
+ *
+ * 胜利条件：每根非空管子内的球颜色完全相同。
+ * 场景层在每次 moveBall 后调用。
+ */
+export declare function checkWin(state: BallSortState): boolean;
+
+/**
+ * findValidMoves：返回当前状态下所有合法移动列表
+ *
+ * 场景层用途：
+ * - 空列表 → 触发死锁提示
+ * - 非空列表 → Hint 功能高亮推荐的下一步
+ */
+export declare function findValidMoves(state: BallSortState): ValidMove[];

package/skills/basketball_shot.aigameplay/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: basketball_shot.aigameplay
+description: 篮球投篮核心玩法封包 - 抛物线轨迹投篮、连击加分、次数限制的 PGS 实现
+triggers: 篮球,basketball,投篮,射篮,篮筐,抛物线,trajectory,parabola,sports,体育,combo,连击,arc
+---
+
+# basketball_shot.aigameplay
+
+篮球投篮核心玩法封包。实现标准篮球投篮玩法的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer。玩家在不同位置调整投篮角度和力度，球沿抛物线轨迹飞向篮筐，连续命中触发连击加分，每关有投篮次数限制。
+
+## Recipe
+
+- **玩法类型**：basketball_shot（篮球投篮）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板
+- **核心规则**：
+  - `gravity`: 9.8（重力加速度，单位 m/s²）
+  - `maxPower`: 100（最大力度）
+  - `comboMultiplierStep`: 0.5（每次连击分数倍数增加值，如 1x→1.5x→2x）
+  - `rimTolerance`: 0.15（入筐容差，球心距筐中心 ≤ radius×(1+tolerance) 算入）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` 以及**全部分步函数**
+  4. 抛物线模拟：`x(t) = x₀ + vx·t`，`y(t) = y₀ + vy·t - ½g·t²`
+  5. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+- **弹框判定**（rim check）：
+  - 球从上方穿过筐平面（y 从筐上方 → 筐下方）
+  - 穿过时球心 x 坐标在 `[hoop.x - hoop.radius, hoop.x + hoop.radius]` 范围内（含 rimTolerance）
+- **可 fork 变体**：
+  - 多点位挑战：不同距离/角度的投篮点，每个点位有独立分值
+  - 障碍物模式：添加风力、障碍板等干扰元素
+  - 定时挑战：取消次数限制，改为倒计时模式
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：轨迹预览与实际投篮分离
+
+```ts
+// ✅ 正确做法：分步驱动
+// Step 1: 预览轨迹（用户拖动时实时计算）
+const trajectory = calculateTrajectory(startPos, angle, power);
+renderTrajectoryDots(trajectory.points);  // 渲染轨迹预测点
+
+// Step 2: 实际投篮（用户松手/确认）
+const shotResult = simulateShot(state, angle, power);
+
+// Step 3: 逐帧渲染球的位置
+for (const point of shotResult.trajectoryPoints) {
+  await renderBallAt(point);
+  await sleep(frameMs);
+}
+
+// Step 4: 判断是否入筐
+const hoopResult = checkHoop(shotResult.finalBall, state.hoop);
+if (hoopResult.scored) {
+  const newState = updateScore(state, true);
+  await playScoreAnimation(newState.comboCount, newState.score);
+} else {
+  const newState = updateScore(state, false);
+  await playMissAnimation();
+}
+```
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/basketball_shot/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `calculateTrajectory()` / `checkHoop()` / `updateScore()` / `simulateShot()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a basketball shot gameplay module following the PGS specification.
+  Write the PGS JSON with entities, rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - calculateTrajectory/checkHoop/updateScore/simulateShot (分步函数，用于渲染层)
+  Trajectory follows standard projectile physics: x(t)=x0+vx*t, y(t)=y0+vy*t-0.5*g*t².
+  Hoop detection: ball passes through hoop plane from above, center x within hoop radius + rim tolerance.
+  Combo multiplier increases by comboMultiplierStep for each consecutive hit, resets on miss.
+  Run the testCases to verify the logic before finalizing.

package/skills/basketball_shot.aigameplay/manifest.json

@@ -0,0 +1,150 @@
+{
+  "schemaVersion": 1,
+  "atomId": "basketball_shot.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "篮球投篮玩法",
+    "en": "Basketball shot gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "basketball",
+    "sports",
+    "trajectory",
+    "aim",
+    "combo"
+  ],
+  "bindingRoles": [
+    "gameplayRule"
+  ],
+  "imports": [
+    {
+      "slot": "engine",
+      "pinAtomId": "phaser.aicomponent",
+      "edgeKind": "requires",
+      "bindAs": "engine"
+    },
+    {
+      "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": "tutorial",
+      "description": "新手引导浮层",
+      "bindAs": "tutorial",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tutorialOverlay"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    },
+    {
+      "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": "endScreen",
+      "description": "可玩广告结算屏（含 CTA 按钮）",
+      "bindAs": "endScreen",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "playableEndScreenLayout"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "basketball_shot",
+    "rules": {
+      "gravity": 9.8,
+      "maxPower": 100,
+      "comboMultiplierStep": 0.5,
+      "rimTolerance": 0.15
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/basketball_shot/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "calculateTrajectory(startPos, angle, power)",
+        "checkHoop(ball, hoop)",
+        "updateScore(state, isHit)",
+        "simulateShot(state, angle, power)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}