@playcraft/skills 0.0.2

package/skills/win_result_panel.aiimage/manifest.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "atomId": "win_result_panel.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "胜利结果面板",
+    "en": "Win result panel"
+  },
+  "tags": [
+    "visual",
+    "win",
+    "success",
+    "result-panel",
+    "game-over"
+  ],
+  "bindingRoles": [
+    "successFeedbackPanel"
+  ],
+  "generation": {
+    "kind": "image",
+    "prompt": "winning celebration panel for a mobile game, bright and exciting, trophy or star icons, positive energy",
+    "aspectRatio": "1:1",
+    "model": "google/imagen-3.0-generate-002",
+    "referenceImage": "ref/win.png",
+    "platformSkill": "playcraft-image-generation"
+  },
+  "result": {
+    "outputFile": "ref/win.webp",
+    "format": "webp",
+    "constraints": {
+      "minWidth": 600,
+      "minHeight": 400
+    }
+  },
+  "binding": {
+    "role": "successFeedbackPanel",
+    "target": "assets/win.webp",
+    "type": "image-asset-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "asset": "ref/win.webp",
+    "assetPng": "ref/win.png"
+  }
+}

package/skills/word_connect.aigameplay/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: word_connect.aigameplay
+description: 单词连线玩法封包 - 字母网格滑动拼词、8方向连接、词库验证的 PGS 实现，支持计时和消除模式
+triggers: 单词,word,connect,连线,字母,letter,拼词,spelling,grid,网格,滑动,swipe,词库,dictionary,找词,wordsearch
+---
+
+# word_connect.aigameplay
+
+单词连线玩法封包。实现字母网格滑词玩法的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer，玩家在字母方格中滑动手指，连接相邻字母（支持 8 方向）拼出目标单词。
+
+## Recipe
+
+- **玩法类型**：word_connect（单词连线）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `gridSize`: 5（5×5 字母网格，可配置覆盖）
+  - `directions`: 8（上下左右和四个斜方向均可连接）
+  - `allowDiagonal`: true（允许斜方向连线）
+  - `eliminateFoundLetters`: false（找到单词后默认不消除字母，可配置）
+  - `timedMode`: false（默认无时限，可配置开启倒计时）
+  - `minWordLength`: 3（单词最短 3 个字母）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` 以及**全部分步函数**
+  4. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+  5. 更新 manifest 的 `generation.pgsVersion` 和 `result.outputFile`
+- **可 fork 变体**：
+  - 消除模式：开启 `eliminateFoundLetters`，找到单词后字母消失并补充
+  - 计时竞速：开启 `timedMode`，设置 60 秒内找到尽量多单词
+  - 主题词库：替换 `wordList` 为特定主题单词（动物、颜色、食物等）
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，实时反馈滑动路径与验证结果 |
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `startTrace(row, col)` | `{ path, letters }` | 高亮起始格子，开始绘制连线 |
+| `extendTrace(row, col)` | `{ path, letters, valid }` | 实时绘制连线到新格子，高亮选中格 |
+| `completeTrace()` | `{ word, isValid, score }` | 验证结果：有效则播放消除动画，无效则闪红清除 |
+| `validateWord(letters, wordList)` | `boolean` | 内部校验，不直接驱动动画 |
+| `markWordFound(word, path)` | `{ foundWords, score }` | 标记格子为已找到，更新单词列表 UI |
+| `checkWin()` | `{ win }` | 触发胜利动画和统计面板 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/word_connect/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `startTrace()` / `extendTrace()` / `completeTrace()` / `validateWord()` / `markWordFound()` / `checkWin()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a word-connect grid gameplay module following the PGS specification.
+  Write the PGS JSON with entities (grid, word_list, found_words, current_path, score, timer), rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - startTrace/extendTrace/completeTrace/validateWord/markWordFound/checkWin (分步函数，用于渲染层驱动)
+  Adjacency check: a cell is adjacent if |dr| <= 1 && |dc| <= 1 and not the same cell.
+  Path validation: no cell can appear twice in the same trace.
+  Word validation: joined letters must exist in wordList (case-insensitive).
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.

package/skills/word_connect.aigameplay/manifest.json

@@ -0,0 +1,154 @@
+{
+  "schemaVersion": 1,
+  "atomId": "word_connect.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "单词连线玩法",
+    "en": "Word Connect gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "word",
+    "puzzle",
+    "grid",
+    "casual",
+    "education"
+  ],
+  "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": "word_connect",
+    "rules": {
+      "gridSize": 5,
+      "directions": 8,
+      "allowDiagonal": true,
+      "eliminateFoundLetters": false,
+      "timedMode": false,
+      "minWordLength": 3
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/word_connect/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "startTrace(state, row, col)",
+        "extendTrace(state, row, col)",
+        "completeTrace(state)",
+        "validateWord(letters, wordList)",
+        "markWordFound(state, word, path)",
+        "checkWin(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,212 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 单词连线玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "word_connect",
+  "entities": {
+    "grid": {
+      "type": "2d-grid",
+      "description": "字母网格",
+      "fields": {
+        "rows": { "type": "number", "default": 5 },
+        "cols": { "type": "number", "default": 5 },
+        "cells": {
+          "type": "cell[][]",
+          "description": "二维数组，每个 cell = { letter: string, found: boolean }，found 表示已作为某单词的一部分"
+        }
+      }
+    },
+    "wordList": {
+      "type": "string[]",
+      "description": "目标单词列表（全大写），玩家需要找出其中所有单词"
+    },
+    "foundWords": {
+      "type": "string[]",
+      "description": "已找到的单词列表"
+    },
+    "currentPath": {
+      "type": "cell-path",
+      "description": "当前正在滑动的路径",
+      "fields": {
+        "cells": { "type": "array", "item": "{ row: number, col: number }", "description": "路径经过的格子（按顺序）" },
+        "letters": { "type": "string", "description": "路径格子组成的字母串（实时更新）" }
+      }
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分，每找到一个单词得 word.length * 10 分"
+    },
+    "timer": {
+      "type": "counter",
+      "description": "剩余时间（ms，仅 timedMode=true 时有效）"
+    }
+  },
+  "rules": {
+    "start_trace": {
+      "description": "玩家按下格子，开始连线路径",
+      "effect": "currentPath = { cells: [{ row, col }], letters: grid[row][col].letter }"
+    },
+    "extend_trace": {
+      "description": "玩家滑动到相邻格子，延伸路径",
+      "conditions": [
+        "目标格子与路径末尾格子相邻（|dr| ≤ 1 && |dc| ≤ 1，不含自身）",
+        "目标格子不在 currentPath.cells 中（同一路径不重复使用）"
+      ],
+      "effect": "currentPath.cells.push({ row, col }); currentPath.letters += grid[row][col].letter"
+    },
+    "complete_word": {
+      "description": "玩家抬起手指，验证当前路径组成的单词",
+      "steps": [
+        "1. word = currentPath.letters（大写）",
+        "2. 若 word.length < minWordLength：视为无效，清除路径",
+        "3. 若 word 不在 wordList 中 且不在字典（若配置字典模式）：无效，清除路径",
+        "4. 若 word 已在 foundWords 中：无效，清除路径",
+        "5. 否则：有效，markWordFound(word, path)"
+      ]
+    },
+    "valid_word_reward": {
+      "description": "找到有效单词后奖励",
+      "effect": "foundWords.push(word); score += word.length * 10; 对应格子标记 found=true（eliminateFoundLetters 模式下移除并补充）"
+    },
+    "win_check": {
+      "description": "检查是否找到所有目标单词",
+      "condition": "foundWords.length >= wordList.length"
+    }
+  },
+  "algorithm": {
+    "description": "主流程：trace → validate → reward → win",
+    "steps": [
+      "1. 玩家触摸格子：startTrace(row, col)",
+      "2. 玩家滑动：extendTrace(row, col)，实时检查相邻性和路径唯一性",
+      "3. 玩家抬手：completeTrace()",
+      "   3a. validateWord(currentPath.letters, wordList)",
+      "   3b. 有效：markWordFound(word, path)，更新 score，检查 checkWin()",
+      "   3c. 无效：清除 currentPath",
+      "4. （计时模式）每帧：timer -= deltaMs，timer ≤ 0 且未胜利则 gameOver"
+    ]
+  },
+  "winCondition": {
+    "type": "all_target_words_found",
+    "description": "找到 wordList 中的所有单词"
+  },
+  "loseCondition": {
+    "type": "timer_expired",
+    "description": "（计时模式）时间耗尽前未找到所有目标单词"
+  },
+  "testCases": [
+    {
+      "id": "tc_valid_word_found",
+      "description": "找到有效单词：路径拼出 wordList 中的单词，得分增加",
+      "initialState": {
+        "grid": {
+          "rows": 3, "cols": 3,
+          "cells": [
+            [{ "letter": "C", "found": false }, { "letter": "A", "found": false }, { "letter": "T", "found": false }],
+            [{ "letter": "D", "found": false }, { "letter": "O", "found": false }, { "letter": "G", "found": false }],
+            [{ "letter": "X", "found": false }, { "letter": "Y", "found": false }, { "letter": "Z", "found": false }]
+          ]
+        },
+        "wordList": ["CAT", "DOG"],
+        "foundWords": [],
+        "currentPath": { "cells": [], "letters": "" },
+        "score": 0
+      },
+      "actions": [
+        { "type": "startTrace", "row": 0, "col": 0 },
+        { "type": "extendTrace", "row": 0, "col": 1 },
+        { "type": "extendTrace", "row": 0, "col": 2 },
+        { "type": "completeTrace" }
+      ],
+      "expectedState": {
+        "foundWords": ["CAT"],
+        "score": 30,
+        "currentPath.cells.length": 0,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_invalid_word_rejected",
+      "description": "无效单词：路径拼出的字母不在 wordList 中，路径被清除，分数不变",
+      "initialState": {
+        "grid": {
+          "rows": 3, "cols": 3,
+          "cells": [
+            [{ "letter": "X", "found": false }, { "letter": "Y", "found": false }, { "letter": "Z", "found": false }],
+            [{ "letter": "D", "found": false }, { "letter": "O", "found": false }, { "letter": "G", "found": false }],
+            [{ "letter": "C", "found": false }, { "letter": "A", "found": false }, { "letter": "T", "found": false }]
+          ]
+        },
+        "wordList": ["CAT", "DOG"],
+        "foundWords": [],
+        "currentPath": { "cells": [], "letters": "" },
+        "score": 10
+      },
+      "actions": [
+        { "type": "startTrace", "row": 0, "col": 0 },
+        { "type": "extendTrace", "row": 0, "col": 1 },
+        { "type": "extendTrace", "row": 0, "col": 2 },
+        { "type": "completeTrace" }
+      ],
+      "expectedState": {
+        "foundWords": [],
+        "score": 10,
+        "currentPath.cells.length": 0
+      }
+    },
+    {
+      "id": "tc_all_words_found_win",
+      "description": "全部找到：找到所有目标单词后游戏胜利",
+      "initialState": {
+        "grid": {
+          "rows": 3, "cols": 3,
+          "cells": [
+            [{ "letter": "C", "found": false }, { "letter": "A", "found": false }, { "letter": "T", "found": false }],
+            [{ "letter": "D", "found": false }, { "letter": "O", "found": false }, { "letter": "G", "found": false }],
+            [{ "letter": "X", "found": false }, { "letter": "Y", "found": false }, { "letter": "Z", "found": false }]
+          ]
+        },
+        "wordList": ["CAT", "DOG"],
+        "foundWords": ["CAT"],
+        "currentPath": { "cells": [], "letters": "" },
+        "score": 30
+      },
+      "actions": [
+        { "type": "startTrace", "row": 1, "col": 0 },
+        { "type": "extendTrace", "row": 1, "col": 1 },
+        { "type": "extendTrace", "row": 1, "col": 2 },
+        { "type": "completeTrace" }
+      ],
+      "expectedState": {
+        "foundWords": ["CAT", "DOG"],
+        "score": 60,
+        "win": true,
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_non_adjacent_rejected",
+      "description": "非相邻格子：尝试滑向不相邻的格子，路径不延伸",
+      "initialState": {
+        "grid": {
+          "rows": 3, "cols": 3,
+          "cells": [
+            [{ "letter": "C", "found": false }, { "letter": "A", "found": false }, { "letter": "T", "found": false }],
+            [{ "letter": "D", "found": false }, { "letter": "O", "found": false }, { "letter": "G", "found": false }],
+            [{ "letter": "X", "found": false }, { "letter": "Y", "found": false }, { "letter": "Z", "found": false }]
+          ]
+        },
+        "wordList": ["CAT"],
+        "foundWords": [],
+        "currentPath": { "cells": [{ "row": 0, "col": 0 }], "letters": "C" },
+        "score": 0
+      },
+      "actions": [
+        { "type": "extendTrace", "row": 2, "col": 2 }
+      ],
+      "expectedState": {
+        "currentPath.cells.length": 1,
+        "currentPath.letters": "C"
+      }
+    }
+  ]
+}