@playcraft/skills 0.0.2

package/skills/bubble_shooter.aigameplay/manifest.json

@@ -0,0 +1,181 @@
+{
+  "schemaVersion": 1,
+  "atomId": "bubble_shooter.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "泡泡射击消除",
+    "en": "Bubble Shooter gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "bubble",
+    "shooter",
+    "eliminate",
+    "casual",
+    "color",
+    "aim"
+  ],
+  "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": "bubbleTextures",
+      "description": "泡泡颜色贴图集",
+      "bindAs": "bubbles",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tileTextureSet"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "levelDataPack",
+      "description": "关卡数据包",
+      "bindAs": "levels",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "levelDataPack"
+      ],
+      "allowedBundleTypes": [
+        "aiconfig"
+      ]
+    },
+    {
+      "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": "bubble_shooter",
+    "rules": {
+      "minClusterSize": 3,
+      "wallBounceEnabled": true,
+      "orphanDropEnabled": true,
+      "advanceRowAfterShots": 5,
+      "colorCount": 6
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/bubble_shooter/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "calculateTrajectory(state, angle)",
+        "snapToGrid(position)",
+        "findCluster(board, col, row)",
+        "popCluster(state, cluster)",
+        "findOrphans(board)",
+        "dropOrphans(state, orphans)",
+        "calculateScore(popped, dropped)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,226 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 泡泡射击消除玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "bubble_shooter",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "layout": "rectangular",
+      "cols": 9,
+      "rows": 12,
+      "description": "泡泡网格，奇数行与偶数行可以错位（六边形布局），board[row][col]，null 表示空格"
+    },
+    "bubble": {
+      "type": "cell-item",
+      "fields": {
+        "color": "BubbleColor (0..colorCount-1)",
+        "row": "number",
+        "col": "number"
+      },
+      "description": "泡泡，有颜色，占据网格的一个格子"
+    },
+    "cannon": {
+      "type": "shooter",
+      "fields": {
+        "currentColor": "BubbleColor (当前待发射的泡泡颜色)",
+        "nextColor": "BubbleColor (下一颗泡泡颜色，供玩家预判)",
+        "position": "{ x: number, y: number } (炮口位置，固定在底部中央)"
+      },
+      "description": "发射炮，持有当前和下一颗泡泡颜色"
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分"
+    },
+    "moves": {
+      "type": "counter",
+      "initial": 0,
+      "description": "已发射次数，每发射 advanceRowAfterShots 次后推进一排"
+    }
+  },
+  "rules": {
+    "aim_and_shoot": {
+      "description": "玩家指定瞄准角度，泡泡从炮口沿直线飞出，可在左右墙壁反弹",
+      "trajectory": "angle-based ray with wall reflection",
+      "wallBounce": true,
+      "maxBounces": 3
+    },
+    "snap_to_grid": {
+      "description": "飞行中的泡泡命中已有泡泡或顶部墙壁时，吸附到最近的空网格位置",
+      "snapLogic": "find nearest empty cell adjacent to hit position"
+    },
+    "cluster_pop": {
+      "description": "泡泡落定后，检测与落点颜色相同的连通区域（BFS）；若连通数量 >= minClusterSize，整簇消除",
+      "minClusterSize": 3,
+      "connectivity": "4-connected (or 6-connected for hex layout)",
+      "scorePerBubble": 100
+    },
+    "orphan_drop": {
+      "description": "消除后，从顶部行出发做 BFS；无法到达顶部的泡泡即为孤立泡泡，自动掉落",
+      "trigger": "after_cluster_pop",
+      "scorePerOrphan": 200,
+      "dropAnimation": "fall-off-screen"
+    },
+    "advance_board": {
+      "description": "每发射 advanceRowAfterShots 次后，顶部新增一排随机颜色泡泡，整体下移一行",
+      "trigger": "shots_count % advanceRowAfterShots === 0",
+      "newRowColors": "random from existing colors on board"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：aim → shoot → snap → cluster_check → pop → orphan_drop → advance_check → win/lose",
+    "steps": [
+      "1. 玩家输入瞄准角度",
+      "2. 计算弹道轨迹（含墙壁反弹），确定落点",
+      "3. 泡泡吸附到最近空网格位置",
+      "4. 更新发射次数（moves += 1）",
+      "5. 以落点为起始，BFS 查找同色连通簇",
+      "6. 若簇大小 >= minClusterSize → 整簇消除，计分",
+      "7. 从顶部行 BFS，标记所有不可达泡泡为孤立泡泡",
+      "8. 孤立泡泡掉落，计分",
+      "9. 更新 cannon：currentColor = nextColor，随机生成新 nextColor",
+      "10. 检查推进条件：moves % advanceRowAfterShots === 0 → 新增顶部一排",
+      "11. 检查失败：最低泡泡行 >= cannon 所在行（泡泡触底）",
+      "12. 检查胜利：棋盘所有泡泡已清空"
+    ]
+  },
+  "winCondition": {
+    "type": "board_cleared",
+    "description": "棋盘上所有泡泡均已消除（board 全为 null）"
+  },
+  "loseCondition": {
+    "type": "bubbles_reach_cannon_line",
+    "description": "任意泡泡的 row >= loseRow（炮台所在行），游戏结束"
+  },
+  "testCases": [
+    {
+      "id": "tc_basic_3pop",
+      "description": "基础三消：发射与已有同色泡泡相邻，凑成3个连通，整簇消除",
+      "initialState": {
+        "board": {
+          "rows": [
+            { "row": 0, "bubbles": [{ "col": 4, "color": 0 }, { "col": 5, "color": 0 }] }
+          ]
+        },
+        "cannon": { "currentColor": 0, "nextColor": 1 },
+        "score": 0,
+        "moves": 0
+      },
+      "actions": [
+        { "type": "shoot", "angle": 90, "_comment": "竖直向上，落在 row=0, col=4 附近" }
+      ],
+      "expectedState": {
+        "poppedCount": 3,
+        "scoreGained": 300,
+        "boardEmpty": false,
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_wall_bounce_pop",
+      "description": "墙壁反弹后命中泡泡并触发消除",
+      "initialState": {
+        "board": {
+          "rows": [
+            { "row": 0, "bubbles": [
+              { "col": 8, "color": 2 },
+              { "col": 7, "color": 2 }
+            ]}
+          ]
+        },
+        "cannon": { "currentColor": 2, "nextColor": 0 },
+        "score": 0,
+        "moves": 0
+      },
+      "actions": [
+        { "type": "shoot", "angle": 45, "_comment": "斜向右上，反弹右壁后命中右侧同色泡泡" }
+      ],
+      "expectedState": {
+        "poppedCount": { "min": 3 },
+        "scoreGained": { "min": 300 },
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_orphan_drop",
+      "description": "孤立掉落：消除支撑簇后，上方失去连接的泡泡自动掉落",
+      "initialState": {
+        "board": {
+          "rows": [
+            { "row": 0, "bubbles": [
+              { "col": 4, "color": 0 },
+              { "col": 5, "color": 0 }
+            ]},
+            { "row": 1, "bubbles": [
+              { "col": 4, "color": 1 },
+              { "col": 5, "color": 0 }
+            ]},
+            { "row": 2, "bubbles": [
+              { "col": 4, "color": 0 }
+            ]}
+          ]
+        },
+        "cannon": { "currentColor": 0, "nextColor": 1 },
+        "score": 0,
+        "moves": 0
+      },
+      "actions": [
+        { "type": "shoot", "angle": 90 }
+      ],
+      "expectedState": {
+        "poppedCount": { "min": 3 },
+        "orphanDropped": { "min": 1 },
+        "scoreGained": { "min": 500 },
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_lose_condition",
+      "description": "失败条件：泡泡推进后触碰炮台行",
+      "initialState": {
+        "board": {
+          "rows": [
+            { "row": 10, "bubbles": [{ "col": 0, "color": 3 }, { "col": 1, "color": 3 }, { "col": 2, "color": 3 }] },
+            { "row": 11, "bubbles": [{ "col": 0, "color": 4 }] }
+          ]
+        },
+        "cannon": { "currentColor": 5, "nextColor": 1 },
+        "score": 0,
+        "moves": 4,
+        "loseRow": 12
+      },
+      "actions": [
+        { "type": "shoot", "angle": 90 }
+      ],
+      "expectedState": {
+        "gameOver": true,
+        "win": false,
+        "reason": "bubbles_reach_cannon_line"
+      }
+    },
+    {
+      "id": "tc_win_board_cleared",
+      "description": "胜利条件：消除最后一组泡泡，棋盘清空",
+      "initialState": {
+        "board": {
+          "rows": [
+            { "row": 0, "bubbles": [{ "col": 4, "color": 1 }, { "col": 5, "color": 1 }] }
+          ]
+        },
+        "cannon": { "currentColor": 1, "nextColor": 2 },
+        "score": 0,
+        "moves": 0
+      },
+      "actions": [
+        { "type": "shoot", "angle": 90 }
+      ],
+      "expectedState": {
+        "boardEmpty": true,
+        "win": true,
+        "gameOver": true,
+        "poppedCount": 3
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,228 @@
+/**
+ * bubble_shooter.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成发射 + 吸附 + 消除 + 掉落后只返回最终状态，
+ * 中间过程（弹道轨迹、消除簇坐标、孤立泡泡掉落路径）全部丢失。
+ *
+ * 渲染层需要分步动画（泡泡飞行 → 吸附 → 消除爆炸 → 孤立掉落），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween / 粒子动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type BubbleColor = number;  // 0 ~ colorCount-1
+
+export type BubbleShooterConfig = {
+  /** 棋盘列数，默认 9 */
+  cols: number;
+  /** 棋盘初始行数，默认 8 */
+  initialRows: number;
+  /** 泡泡颜色总数，默认 6 */
+  colorCount: number;
+  /** 触发消除的最小连通数，默认 3 */
+  minClusterSize: number;
+  /** 是否允许墙壁反弹，默认 true */
+  wallBounceEnabled: boolean;
+  /** 最大反弹次数，默认 3 */
+  maxBounces: number;
+  /** 每发射多少次后推进一排，默认 5 */
+  advanceRowAfterShots: number;
+  /** 失败行（泡泡到达此行时失败），默认 = initialRows + 2 */
+  loseRow: number;
+  /** 每消除一颗泡泡的得分，默认 100 */
+  scorePerPop: number;
+  /** 每掉落一颗孤立泡泡的得分，默认 200 */
+  scorePerDrop: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type BubbleShooterAction =
+  | { type: 'shoot'; angle: number }  // angle: 度数，0=向右，90=向上，180=向左
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type GridPosition = {
+  row: number;
+  col: number;
+};
+
+/** 棋盘：board[row][col]，null 表示空格 */
+export type BubbleBoard = (BubbleColor | null)[][];
+
+export type CannonState = {
+  currentColor: BubbleColor;
+  nextColor: BubbleColor;
+  position: { x: number; y: number };
+};
+
+export type BubbleShooterState = {
+  board: BubbleBoard;
+  cannon: CannonState;
+  score: number;
+  /** 已发射次数 */
+  moves: number;
+  gameOver: boolean;
+  win: boolean;
+  loseReason?: 'bubbles_reach_cannon_line';
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 弹道轨迹点（含反弹折射点） */
+export type TrajectoryPoint = {
+  x: number;
+  y: number;
+  /** 是否为墙壁反弹点 */
+  isBounce: boolean;
+};
+
+/** 弹道计算结果 */
+export type TrajectoryResult = {
+  /** 轨迹关键点列表（起点 → 反弹点1 → ... → 落点） */
+  points: TrajectoryPoint[];
+  /** 最终落点网格坐标（吸附前的世界坐标） */
+  landingPosition: { x: number; y: number };
+};
+
+/** 消除簇信息 */
+export type ClusterInfo = {
+  /** 连通的同色格子坐标列表 */
+  cells: GridPosition[];
+  /** 颜色 */
+  color: BubbleColor;
+};
+
+/** popCluster 结果 */
+export type PopResult = {
+  newState: BubbleShooterState;
+  /** 被消除的格子列表 */
+  popped: GridPosition[];
+  /** 本次消除得分 */
+  scoreGained: number;
+};
+
+/** dropOrphans 结果 */
+export type DropResult = {
+  finalState: BubbleShooterState;
+  /** 掉落的孤立格子列表 */
+  dropped: GridPosition[];
+  /** 本次掉落得分 */
+  scoreGained: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态，随机生成初始泡泡排列
+ */
+export declare function init(config: BubbleShooterConfig): BubbleShooterState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - shoot：发射泡泡，自动执行吸附/消除/掉落/推进一步（一步到位）
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: BubbleShooterState, action: BubbleShooterAction): BubbleShooterState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: BubbleShooterState): BubbleShooterState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * calculateTrajectory：根据瞄准角度计算泡泡弹道轨迹
+ * 返回包含反弹折射点的轨迹关键点列表及最终落点世界坐标
+ *
+ * 场景层根据 TrajectoryResult.points 绘制弹道预览线，
+ * 并驱动泡泡精灵沿轨迹飞行动画
+ */
+export declare function calculateTrajectory(
+  state: BubbleShooterState,
+  angle: number,
+): TrajectoryResult;
+
+/**
+ * snapToGrid：将世界坐标映射到最近的空网格格子
+ * 返回目标格子的行列坐标
+ *
+ * 场景层在泡泡飞行动画结束后调用，确定最终落点
+ */
+export declare function snapToGrid(
+  state: BubbleShooterState,
+  position: { x: number; y: number },
+): GridPosition;
+
+/**
+ * findCluster：从指定格子出发，BFS 查找同色连通区域
+ * 返回包含起始格子的完整连通簇信息
+ *
+ * 场景层在泡泡落定后调用，size >= minClusterSize 则触发消除
+ */
+export declare function findCluster(
+  board: BubbleBoard,
+  col: number,
+  row: number,
+): ClusterInfo;
+
+/**
+ * popCluster：消除指定簇，更新棋盘和得分
+ * 返回消除结果（含更新后的状态和被消除格子列表）
+ *
+ * 场景层根据 PopResult.popped 播放各泡泡爆炸/缩小消失动画
+ */
+export declare function popCluster(
+  state: BubbleShooterState,
+  cluster: ClusterInfo,
+): PopResult;
+
+/**
+ * findOrphans：从顶部行出发做 BFS，返回所有不可达（孤立）泡泡的坐标列表
+ * 孤立泡泡 = 无法通过连通路径到达第 0 行的泡泡
+ *
+ * 场景层在 popCluster 后调用，对孤立泡泡播放悬空抖动 → 掉落动画
+ */
+export declare function findOrphans(board: BubbleBoard): GridPosition[];
+
+/**
+ * dropOrphans：从棋盘移除孤立泡泡，更新得分
+ * 返回掉落结果（含更新后的状态和掉落格子列表）
+ *
+ * 场景层根据 DropResult.dropped 播放泡泡掉落消失动画
+ */
+export declare function dropOrphans(
+  state: BubbleShooterState,
+  orphans: GridPosition[],
+): DropResult;
+
+/**
+ * calculateScore：根据消除数量和掉落数量计算得分
+ * score = popped * scorePerPop + dropped * scorePerDrop
+ */
+export declare function calculateScore(
+  popped: number,
+  dropped: number,
+  config: Pick<BubbleShooterConfig, 'scorePerPop' | 'scorePerDrop'>,
+): number;

package/skills/button_click_sfx.aiaudio/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: button_click_sfx.aiaudio
+description: UI 按钮（设置/下载等）点击时的干净点击音效。
+triggers: 需要生成 UI 按钮通用点击音效时触发。
+---
+
+# 按钮点击音效
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: Google Lyria 3（平台默认，见 manifest.json generation.platformSkill）
+- format: mp3
+- loop: false
+
+## Result
+
+- 产物文件：`button_click.mp3`
+- 在 Preloader.ts 中作为 `sfxButtonClick` key 加载
+
+## Binding
+
+```json
+{
+  "role": "sfxButtonClick",
+  "target": "assets/sounds/button_click.mp3",
+  "type": "audio-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-audio-generation`
+
+```bash
+# 1. 生成 SFX（--prompt 必须英文）
+playcraft tools generate-sfx \
+     --prompt "clean button tap sound for UI buttons in mobile game" \
+     --duration 1 \
+     --output ta-workspace/raw_sfx.mp3
+
+# 2. 归一化音量
+playcraft audio normalize --input ta-workspace/raw_sfx.mp3 --output ta-workspace/raw_sfx.mp3 --target-loudness -16
+
+# 3. 压缩（SFX 目标 ≤15KB）
+playcraft audio compress --input ta-workspace/raw_sfx.mp3 --output ta-workspace/button_click.mp3 --target-size 15KB
+
+# 4. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_audio
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - audio: button_click.mp3
+```