@playcraft/skills 0.0.2

package/dist/src/skills.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.types.js","sourceRoot":"","sources":["../../src/skills.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@playcraft/skills",
+  "version": "0.0.2",
+  "private": false,
+  "type": "module",
+  "description": "Atom-Skill assets and platform skill loaders for PlayCraft Agent.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "skills",
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "echo 'No TS sources to lint in @playcraft/skills'",
+    "release": "node scripts/release.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/2048_core.aigameplay/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: 2048_core.aigameplay
+description: 2048 滑动合并玩法封包 - 标准 4×4 网格滑动合并数字方块直到合成 2048 的 PGS 实现
+triggers: 2048,滑动,合并,数字,slide,merge,grid,number,方块,tile,puzzle
+---
+
+# 2048_core.aigameplay
+
+2048 滑动合并核心玩法封包。实现标准 2048 规则的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer，玩家向四个方向滑动棋盘，相邻同值方块合并一次，每次有效滑动后随机生成新方块，目标是合成出值为 2048 的方块。
+
+## Recipe
+
+- **玩法类型**：2048（滑动合并）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `gridSize`: 4（4×4 网格）
+  - `winValue`: 2048（达到此值即胜利）
+  - `spawnValues`: [2, 4]（随机生成 2 或 4）
+  - `spawnWeights`: [0.9, 0.1]（90% 概率生成 2，10% 概率生成 4）
+  - `mergeOncePerSlide`: true（每次滑动每组同值方块只合并一次）
+- **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 变体**：
+  - 大棋盘：修改 `gridSize` 为 5 或 6
+  - 目标变体：修改 `winValue`（如 4096、8192）
+  - 障碍格：添加固定障碍方块，滑动时不可通过
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层使用 dispatch() 然后全量重建棋盘
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+
+// Step 1: 执行滑动并获取移动/合并信息
+const { moves, merges, boardAfterSlide } = slideBoard(board, direction);
+if (moves.length === 0 && merges.length === 0) {
+  // 无效滑动，不生成新方块
+  return;
+}
+
+// Step 2: 播放方块移动动画（并行 Tween）
+await playTileMoveAnimation(moves);
+
+// Step 3: 播放合并动画（缩放弹跳效果）
+await playTileMergeAnimation(merges);
+
+// Step 4: 生成新方块
+const newTile = spawnTile(boardAfterSlide);
+await playTileSpawnAnimation(newTile);   // 新方块从小到大的出现动画
+
+// Step 5: 检查胜败
+if (!hasValidMoves(boardAfterSlide)) showGameOverPanel();
+const score = calculateScore(merges);
+updateScoreUI(score);
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `slideBoard()` | `{ moves, merges, board }` | 方块平移 Tween |
+| `mergeTiles()` | `MergeResult[]` | 合并方块缩放弹跳 + 数字变更 |
+| `spawnTile()` | `SpawnedTile` | 新方块 scale 0→1 弹出动画 |
+| `hasValidMoves()` | `boolean` | false 时显示游戏结束面板 |
+| `calculateScore()` | `number` | 更新 score UI + 飘分动画 |
+
+### 合并规则关键约束
+
+- 同一次滑动中，合并生成的新方块**不能**再次参与合并
+- 用 `merged` 标志位跟踪每个格子在本次滑动中是否已合并
+- 滑动方向决定合并优先级：向左滑动时最左侧的合并优先
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/2048/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `slideBoard()` / `mergeTiles()` / `spawnTile()` / `hasValidMoves()` / `calculateScore()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a 2048 slide-and-merge gameplay module following the PGS specification.
+  Write the PGS JSON with entities (board 4×4 grid, tiles with 2^n values, score, best_score), rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - slideBoard/mergeTiles/spawnTile/hasValidMoves/calculateScore (分步函数，用于渲染层动画驱动)
+  Key constraints:
+    - Each tile can only merge once per slide (track merged flag per tile)
+    - Spawn 2 (90%) or 4 (10%) in a random empty cell after each valid slide
+    - Win: any tile reaches winValue (default 2048)
+    - Lose: board is full AND no adjacent same-value tiles exist
+  The step-by-step functions are CRITICAL — the rendering layer (GameScene) must use them to drive animations.
+  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/2048_core.aigameplay/manifest.json

@@ -0,0 +1,159 @@
+{
+  "schemaVersion": 1,
+  "atomId": "2048_core.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "2048 滑动合并",
+    "en": "2048 Slide & Merge gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "2048",
+    "slide",
+    "merge",
+    "casual",
+    "grid",
+    "number"
+  ],
+  "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": "2048",
+    "rules": {
+      "gridSize": 4,
+      "winValue": 2048,
+      "spawnValues": [
+        2,
+        4
+      ],
+      "spawnWeights": [
+        0.9,
+        0.1
+      ],
+      "mergeOncePerSlide": true
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/2048/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "slideBoard(board, direction)",
+        "mergeTiles(board, direction)",
+        "spawnTile(board)",
+        "hasValidMoves(board)",
+        "calculateScore(merges)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

package/skills/2048_core.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,194 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 2048 滑动合并玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "2048",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "cols": 4,
+      "rows": 4,
+      "description": "游戏棋盘，4×4 方格，board[row][col]，null 表示空格"
+    },
+    "tile": {
+      "type": "cell-item",
+      "fields": {
+        "value": "number (2 的幂次，如 2/4/8/.../2048/4096)",
+        "merged": "boolean (本次滑动中是否已合并，防止二次合并)"
+      },
+      "description": "数字方块，值为 2 的幂次；同值相邻方块可合并为两倍值"
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分，每次合并得分 = 合并后方块值"
+    },
+    "best_score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "历史最高分，本地持久化"
+    }
+  },
+  "rules": {
+    "slide_direction": {
+      "description": "玩家向上/下/左/右滑动，所有方块沿该方向移动到最远空格",
+      "directions": ["up", "down", "left", "right"],
+      "effectiveIfAnyTileMoves": true,
+      "noMoveIfBoardUnchanged": true
+    },
+    "merge_same_value": {
+      "description": "滑动过程中，沿移动方向相邻且同值的方块合并为两倍值；每个方块本次滑动最多参与一次合并",
+      "mergeOncePerSlide": true,
+      "newValueAfterMerge": "tile.value * 2",
+      "scoreGain": "newValue"
+    },
+    "spawn_new_tile": {
+      "description": "每次有效滑动后（棋盘有任何变化），在随机空格生成新方块",
+      "values": [2, 4],
+      "weights": [0.9, 0.1],
+      "trigger": "after_effective_slide"
+    },
+    "game_over_check": {
+      "description": "棋盘满且无相邻同值方块（无有效移动）时游戏结束",
+      "trigger": "after_spawn",
+      "boardFull": "no empty cells",
+      "noValidMoves": "no adjacent same-value pairs in any direction"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：swipe → slide_and_merge → spawn → win/lose 检测",
+    "steps": [
+      "1. 玩家输入滑动方向（up/down/left/right）",
+      "2. 按滑动方向对每行/列执行滑动和合并：",
+      "   a. 提取行/列中非空方块（按移动方向排列）",
+      "   b. 相邻同值且均未合并过的方块合并（merged = true），生成新值",
+      "   c. 将结果写回行/列，其余位置填 null",
+      "3. 检查棋盘是否发生变化（与滑动前对比）",
+      "4. 若无变化 → 忽略此次操作，不生成新方块",
+      "5. 若有变化 → 在随机空格生成新方块（2: 90%，4: 10%）",
+      "6. 检查胜利：任意方块 value >= winValue（2048）",
+      "7. 检查失败：棋盘满 AND 无相邻同值方块（无合法滑动）"
+    ]
+  },
+  "winCondition": {
+    "type": "tile_value_reached",
+    "value": 2048,
+    "description": "棋盘上出现值 >= 2048 的方块时胜利（可设置为继续游戏模式）"
+  },
+  "loseCondition": {
+    "type": "no_valid_moves",
+    "description": "棋盘已满（无空格）且四个方向均无相邻同值方块（无有效滑动）"
+  },
+  "testCases": [
+    {
+      "id": "tc_basic_slide_merge",
+      "description": "基础滑动合并：左滑，两个相邻同值方块合并",
+      "initialState": {
+        "board": [
+          [null, null, 2,    2   ],
+          [null, null, null, null],
+          [null, null, null, null],
+          [null, null, null, null]
+        ],
+        "score": 0
+      },
+      "actions": [
+        { "type": "slide", "direction": "left" }
+      ],
+      "expectedState": {
+        "board": [
+          [4,    null, null, null],
+          [null, null, null, null],
+          [null, null, null, null],
+          [null, null, null, null]
+        ],
+        "scoreGained": 4,
+        "newTileSpawned": true
+      }
+    },
+    {
+      "id": "tc_slide_no_merge",
+      "description": "滑动但无合并：左滑后方块移位但不合并（不同值），且生成新方块",
+      "initialState": {
+        "board": [
+          [null, 2,    4,    null],
+          [null, null, null, null],
+          [null, null, null, null],
+          [null, null, null, null]
+        ],
+        "score": 0
+      },
+      "actions": [
+        { "type": "slide", "direction": "left" }
+      ],
+      "expectedState": {
+        "board_row0": [2, 4, null, null],
+        "scoreGained": 0,
+        "newTileSpawned": true
+      }
+    },
+    {
+      "id": "tc_merge_once_per_slide",
+      "description": "一次滑动中每组只合并一次：左滑 [2,2,2,2] → [4,4,null,null]，不能合并成 [8]",
+      "initialState": {
+        "board": [
+          [2, 2, 2, 2],
+          [null, null, null, null],
+          [null, null, null, null],
+          [null, null, null, null]
+        ],
+        "score": 0
+      },
+      "actions": [
+        { "type": "slide", "direction": "left" }
+      ],
+      "expectedState": {
+        "board_row0": [4, 4, null, null],
+        "scoreGained": 8,
+        "newTileSpawned": true
+      }
+    },
+    {
+      "id": "tc_game_over_detection",
+      "description": "失败检测：棋盘已满且无相邻同值方块，任何方向滑动均无效",
+      "initialState": {
+        "board": [
+          [2,  4,  2,  4 ],
+          [4,  2,  4,  2 ],
+          [2,  4,  2,  4 ],
+          [4,  2,  4,  2 ]
+        ],
+        "score": 0
+      },
+      "actions": [
+        { "type": "slide", "direction": "left" }
+      ],
+      "expectedState": {
+        "boardUnchanged": true,
+        "gameOver": true,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_win_condition",
+      "description": "胜利条件：合并后出现 2048",
+      "initialState": {
+        "board": [
+          [1024, 1024, null, null],
+          [null, null, null, null],
+          [null, null, null, null],
+          [null, null, null, null]
+        ],
+        "score": 0
+      },
+      "actions": [
+        { "type": "slide", "direction": "left" }
+      ],
+      "expectedState": {
+        "board_row0_col0": 2048,
+        "win": true,
+        "gameOver": true,
+        "scoreGained": 2048
+      }
+    }
+  ]
+}