@playcraft/skills 0.0.2

package/skills/pin_pull.aigameplay/manifest.json

@@ -0,0 +1,164 @@
+{
+  "schemaVersion": 1,
+  "atomId": "pin_pull.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "拔针解谜玩法",
+    "en": "Pin Pull puzzle gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "pin",
+    "pull",
+    "liquid",
+    "physics",
+    "puzzle",
+    "casual"
+  ],
+  "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": "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": "pin_pull",
+    "rules": {
+      "liquidFlowEnabled": true,
+      "multiPinSequencing": true,
+      "dangerZoneEnabled": true,
+      "gravitationalFlow": true
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/pin_pull/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "canPullPin(state, pinId)",
+        "pullPin(state, pinId)",
+        "simulateLiquidFlow(state)",
+        "checkWinLose(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,201 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 拔针解谜玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "pin_pull",
+  "entities": {
+    "pin": {
+      "type": "interactive-item",
+      "fields": {
+        "id": "string",
+        "position": "{ x: number, y: number }",
+        "state": "PinState (inserted|removed)",
+        "blockedChannelIds": "string[] (此销钉封堵的通道列表)"
+      },
+      "description": "销钉，插入状态时封堵关联通道；拔出后通道开放，液体可流过"
+    },
+    "liquid_source": {
+      "type": "source-node",
+      "fields": {
+        "id": "string",
+        "type": "LiquidType (water|blood|acid|lava)",
+        "position": "{ x: number, y: number }",
+        "capacity": "number (总量，-1 = 无限)",
+        "remaining": "number"
+      },
+      "description": "液体来源节点，液体从此节点沿开放通道流动"
+    },
+    "container": {
+      "type": "target-node",
+      "fields": {
+        "id": "string",
+        "role": "ContainerRole (target|danger|neutral)",
+        "acceptedLiquid": "LiquidType | 'any'",
+        "capacity": "number",
+        "filled": "number",
+        "position": "{ x: number, y: number }"
+      },
+      "description": "容器节点：target = 需要被填满（胜利条件）；danger = 触碰则失败；neutral = 中性溢出"
+    },
+    "channel": {
+      "type": "edge",
+      "fields": {
+        "id": "string",
+        "from": "string (node id)",
+        "to": "string (node id)",
+        "state": "ChannelState (open|blocked)",
+        "blockingPinIds": "string[] (封堵此通道的销钉，为空时通道开放)"
+      },
+      "description": "通道（有向边），连接节点；所有封堵销钉被移除后状态变为 open"
+    },
+    "obstacle": {
+      "type": "static-blocker",
+      "fields": {
+        "id": "string",
+        "blockedChannelIds": "string[]"
+      },
+      "description": "静态障碍，永久封堵通道（不可移除）"
+    }
+  },
+  "rules": {
+    "pull_pin": {
+      "description": "玩家点击销钉 → 销钉状态变为 removed → 关联通道的 blockingPinIds 移除此销钉 → 若 blockingPinIds 为空则通道开放",
+      "trigger": "player_tap",
+      "effect": "pin.state = 'removed'; channel.state = 'open' if channel.blockingPinIds.length === 0"
+    },
+    "liquid_flow": {
+      "description": "液体从 source 沿所有 open 通道，按重力方向（BFS/DFS）流向可达节点，填充 container",
+      "trigger": "after_pull_pin",
+      "algorithm": "graph BFS from all active sources through open channels",
+      "effect": "container.filled += flowAmount; liquid_source.remaining -= flowAmount"
+    },
+    "win_check": {
+      "description": "所有 target 容器 filled >= capacity",
+      "trigger": "after_liquid_flow",
+      "effect": "gameOver = true, win = true"
+    },
+    "lose_check": {
+      "description": "液体流入任意 danger 容器（filled > 0）",
+      "trigger": "after_liquid_flow",
+      "effect": "gameOver = true, win = false"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：tap_pin → open_channel → flow_liquid → win/lose 检测",
+    "steps": [
+      "1. 玩家点击目标销钉",
+      "2. 检查销钉是否处于 inserted 状态（未被拔出）",
+      "3. 将销钉状态改为 removed",
+      "4. 更新关联通道的 blockingPinIds，若清空则通道变为 open",
+      "5. 执行液体流动模拟（BFS 从所有 source 出发，经 open 通道到达节点）",
+      "6. 更新所有容器的 filled 值",
+      "7. 检查 lose 条件：any danger container filled > 0",
+      "8. 检查 win 条件：all target containers filled >= capacity",
+      "9. 若 win/lose 均未触发，等待下一次操作"
+    ]
+  },
+  "winCondition": {
+    "type": "all_targets_filled",
+    "description": "所有 role='target' 的容器 filled >= capacity"
+  },
+  "loseCondition": {
+    "type": "danger_zone_reached",
+    "description": "任意 role='danger' 容器的 filled > 0"
+  },
+  "testCases": [
+    {
+      "id": "tc_single_pin_win",
+      "description": "单销钉路径：拔出唯一销钉，液体直达目标容器，立即胜利",
+      "initialState": {
+        "pins": [
+          { "id": "p1", "state": "inserted", "blockedChannelIds": ["c1"] }
+        ],
+        "liquid_sources": [
+          { "id": "src1", "type": "water", "capacity": -1, "remaining": -1 }
+        ],
+        "containers": [
+          { "id": "cup1", "role": "target", "capacity": 100, "filled": 0 }
+        ],
+        "channels": [
+          { "id": "c1", "from": "src1", "to": "cup1", "state": "blocked", "blockingPinIds": ["p1"] }
+        ]
+      },
+      "actions": [
+        { "type": "pull_pin", "pinId": "p1" }
+      ],
+      "expectedState": {
+        "pins": [{ "id": "p1", "state": "removed" }],
+        "channels": [{ "id": "c1", "state": "open" }],
+        "containers": [{ "id": "cup1", "filled": 100 }],
+        "win": true,
+        "gameOver": true
+      }
+    },
+    {
+      "id": "tc_wrong_order_lose",
+      "description": "错误顺序：先拔下方销钉，液体流向危险区，立即失败",
+      "initialState": {
+        "pins": [
+          { "id": "p_top", "state": "inserted", "blockedChannelIds": ["c_safe"] },
+          { "id": "p_bottom", "state": "inserted", "blockedChannelIds": ["c_danger"] }
+        ],
+        "liquid_sources": [
+          { "id": "src1", "type": "water", "capacity": -1, "remaining": -1 }
+        ],
+        "containers": [
+          { "id": "target1", "role": "target", "capacity": 100, "filled": 0 },
+          { "id": "danger1", "role": "danger", "capacity": 999, "filled": 0 }
+        ],
+        "channels": [
+          { "id": "c_safe", "from": "src1", "to": "target1", "state": "blocked", "blockingPinIds": ["p_top"] },
+          { "id": "c_danger", "from": "src1", "to": "danger1", "state": "blocked", "blockingPinIds": ["p_bottom"] }
+        ]
+      },
+      "actions": [
+        { "type": "pull_pin", "pinId": "p_bottom" }
+      ],
+      "expectedState": {
+        "containers": [
+          { "id": "target1", "filled": 0 },
+          { "id": "danger1", "filled": { "min": 1 } }
+        ],
+        "win": false,
+        "gameOver": true,
+        "reason": "danger_zone_reached"
+      }
+    },
+    {
+      "id": "tc_multi_step_sequence",
+      "description": "多步序列：需按顺序拔出 p1、p2，液体绕过危险区到达目标",
+      "initialState": {
+        "pins": [
+          { "id": "p1", "state": "inserted", "blockedChannelIds": ["c1"] },
+          { "id": "p2", "state": "inserted", "blockedChannelIds": ["c2"] }
+        ],
+        "liquid_sources": [
+          { "id": "src1", "type": "water", "capacity": -1, "remaining": -1 }
+        ],
+        "containers": [
+          { "id": "target1", "role": "target", "capacity": 100, "filled": 0 },
+          { "id": "danger1", "role": "danger", "capacity": 999, "filled": 0 }
+        ],
+        "channels": [
+          { "id": "c1", "from": "src1", "to": "node_mid", "state": "blocked", "blockingPinIds": ["p1"] },
+          { "id": "c2", "from": "node_mid", "to": "target1", "state": "blocked", "blockingPinIds": ["p2"] },
+          { "id": "c3", "from": "node_mid", "to": "danger1", "state": "open", "blockingPinIds": [] }
+        ]
+      },
+      "actions": [
+        { "type": "pull_pin", "pinId": "p2" },
+        { "type": "pull_pin", "pinId": "p1" }
+      ],
+      "expectedState": {
+        "containers": [
+          { "id": "target1", "filled": 100 },
+          { "id": "danger1", "filled": 0 }
+        ],
+        "win": true,
+        "gameOver": true
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,216 @@
+/**
+ * pin_pull.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成销钉拔出 + 液体流动模拟后只返回最终状态，
+ * 中间过程（哪些通道开放、液体流向路径、容器填充顺序）全部丢失。
+ *
+ * 渲染层需要分步动画（销钉拔出 → 通道开放 → 液体流动 → 容器填满），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入粒子/流体动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type LiquidType = 'water' | 'blood' | 'acid' | 'lava';
+export type ContainerRole = 'target' | 'danger' | 'neutral';
+export type PinStateValue = 'inserted' | 'removed';
+export type ChannelStateValue = 'open' | 'blocked';
+
+export type PinPullConfig = {
+  pins: Array<{
+    id: string;
+    position: { x: number; y: number };
+    blockedChannelIds: string[];
+  }>;
+  liquidSources: Array<{
+    id: string;
+    type: LiquidType;
+    capacity: number;
+    position: { x: number; y: number };
+  }>;
+  containers: Array<{
+    id: string;
+    role: ContainerRole;
+    acceptedLiquid: LiquidType | 'any';
+    capacity: number;
+    position: { x: number; y: number };
+  }>;
+  channels: Array<{
+    id: string;
+    from: string;
+    to: string;
+    blockingPinIds: string[];
+  }>;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type PinPullAction =
+  | { type: 'pull_pin'; pinId: string }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type PinRecord = {
+  id: string;
+  state: PinStateValue;
+  blockedChannelIds: string[];
+  position: { x: number; y: number };
+};
+
+export type LiquidSource = {
+  id: string;
+  type: LiquidType;
+  capacity: number;
+  remaining: number;
+  position: { x: number; y: number };
+};
+
+export type ContainerRecord = {
+  id: string;
+  role: ContainerRole;
+  acceptedLiquid: LiquidType | 'any';
+  capacity: number;
+  filled: number;
+  position: { x: number; y: number };
+};
+
+export type ChannelRecord = {
+  id: string;
+  from: string;
+  to: string;
+  state: ChannelStateValue;
+  blockingPinIds: string[];
+};
+
+export type PinPullState = {
+  pins: Record<string, PinRecord>;
+  liquidSources: Record<string, LiquidSource>;
+  containers: Record<string, ContainerRecord>;
+  channels: Record<string, ChannelRecord>;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 失败/胜利原因 */
+  reason?: 'all_targets_filled' | 'danger_zone_reached';
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 通道开放信息（用于驱动开关动画） */
+export type OpenedChannel = {
+  channelId: string;
+  from: string;
+  to: string;
+};
+
+/** 液体流动路径（一段从 source 到 container 的流动路径） */
+export type FlowPath = {
+  sourceId: string;
+  liquidType: LiquidType;
+  /** 经过的节点 id 序列（含 source 和 container） */
+  nodePath: string[];
+  /** 流入的容器 id */
+  targetContainerId: string;
+  /** 本次流入量 */
+  flowAmount: number;
+};
+
+/** simulateLiquidFlow 的完整结果 */
+export type FlowResult = {
+  paths: FlowPath[];
+  /** 危险容器是否被触及 */
+  dangerTouched: boolean;
+  /** 所有 target 容器是否已满 */
+  allTargetsFilled: boolean;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: PinPullConfig): PinPullState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - pull_pin：拔出销钉，自动模拟液体流动，检测胜败（一步到位）
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: PinPullState, action: PinPullAction): PinPullState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: PinPullState): PinPullState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * canPullPin：检查指定销钉是否可以被拔出
+ * - 销钉必须存在且处于 inserted 状态
+ * - 游戏未结束
+ *
+ * 场景层在玩家点击时调用：false → 播放锁定/摇晃提示
+ */
+export declare function canPullPin(state: PinPullState, pinId: string): boolean;
+
+/**
+ * pullPin：执行销钉拔出操作
+ * 返回更新后的状态（销钉状态改为 removed，关联通道更新为 open）
+ * 及已开放的通道列表
+ *
+ * 场景层根据 openedChannels 播放：
+ * - 销钉拔出动画
+ * - 通道开放（门/挡板消失）动画
+ *
+ * ⚠️ 调用 pullPin 后必须紧接着调用 simulateLiquidFlow
+ */
+export declare function pullPin(
+  state: PinPullState,
+  pinId: string,
+): {
+  newState: PinPullState;
+  openedChannels: OpenedChannel[];
+};
+
+/**
+ * simulateLiquidFlow：在当前通道图上模拟液体从所有 source 流向可达节点
+ * 返回所有流动路径及胜败判断
+ *
+ * 场景层根据 FlowResult.paths 逐条播放液体流动动画（每段通道依次填充），
+ * 动画完成后检查 dangerTouched / allTargetsFilled 决定胜败面板
+ */
+export declare function simulateLiquidFlow(state: PinPullState): FlowResult;
+
+/**
+ * checkWinLose：根据当前状态判断胜败
+ * - win: 所有 target 容器 filled >= capacity
+ * - lose: 任意 danger 容器 filled > 0
+ *
+ * 通常在 simulateLiquidFlow 后调用，或用于状态轮询
+ */
+export declare function checkWinLose(state: PinPullState): {
+  win: boolean;
+  lose: boolean;
+  reason?: 'all_targets_filled' | 'danger_zone_reached';
+};

package/skills/playable_app_logo.aiimage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: playable_app_logo.aiimage
+description: 试玩广告的应用 Logo 图片，在 Loading 页面中展示，代表该次投放的应用品牌。
+triggers: 需要生成/替换试玩广告的 APP Logo 图片时触发。
+---
+
+# 应用 Logo
+
+## Recipe
+
+生成提示词见 manifest.json generation.prompt。
+- model: google/imagen-3.0-generate-002（默认，见 manifest.json generation.platformSkill）
+- format: webp, 透明背景
+
+## Result
+
+- 产物文件：`logo.webp`
+- 在 Preloader.ts 中作为 `appLogo` key 加载
+
+## Binding
+
+```json
+{
+  "role": "appLogo",
+  "target": "assets/logo.webp",
+  "type": "image-asset-reference"
+}
+```
+
+## 生成方式
+
+Platform Skill: `playcraft-image-generation`
+
+```bash
+# 1. 生成图片（参考 ref/ 中的参考图）
+playcraft tools generate-image \
+     --prompt "app icon logo for a mobile puzzle game, clean and eye-catching, transparent background" \
+     --aspect-ratio 1:1 \
+     --reference-image ${SKILL_DIR}/ref/logo.png \
+     --image-model google/imagen-3.0-generate-002 \
+     --output ta-workspace/raw.png
+
+# 2. 后处理（去白底 + 格式转换）
+playcraft image remove-background --input ta-workspace/raw.png --output ta-workspace/trimmed.png
+playcraft image convert --input ta-workspace/trimmed.png --output ta-workspace/logo.webp --quality 85
+
+# 3. 将产物写入 sandbox 对应路径（见 binding.target）
+```
+## Skill Definition
+
+```yaml
+tools:
+  - generate_image
+inputs:
+  - prompt: see manifest.json
+outputs:
+  - image: logo.webp
+```

package/skills/playable_app_logo.aiimage/manifest.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "atomId": "playable_app_logo.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "应用 Logo",
+    "en": "App Logo"
+  },
+  "tags": [
+    "visual",
+    "logo",
+    "brand",
+    "app-icon",
+    "loading-screen"
+  ],
+  "bindingRoles": [
+    "appLogo"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "app icon logo for a mobile puzzle game, clean and eye-catching, transparent background",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/logo.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/logo.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 256,
+      "minHeight": 256
+    }
+  },
+  "binding": {
+    "role": "appLogo",
+    "target": "assets/logo.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/logo.webp",
+    "assetPng": "ref/logo.png"
+  }
+}