@playcraft/skills 0.0.2

package/skills/block_puzzle.aigameplay/manifest.json

@@ -0,0 +1,154 @@
+{
+  "schemaVersion": 1,
+  "atomId": "block_puzzle.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "方块放置消行玩法",
+    "en": "Block puzzle placement gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "block-puzzle",
+    "placement",
+    "grid",
+    "lines",
+    "casual",
+    "core"
+  ],
+  "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": "block_puzzle",
+    "rules": {
+      "boardCols": 10,
+      "boardRows": 10,
+      "pieceSlots": 3,
+      "rotation": false,
+      "gravity": false,
+      "clearFullLines": true,
+      "clearFullColumns": true
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/block_puzzle/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(state, action)",
+        "getState(state)",
+        "canPlacePiece(state, piece, position)",
+        "placePiece(state, piece, position)",
+        "clearLines(state)",
+        "generatePieces(count, colorCount)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,170 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 方块放置消行玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "block_puzzle",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "cols": 10,
+      "rows": 10,
+      "description": "游戏棋盘，默认 10×10 格子"
+    },
+    "piece": {
+      "type": "polyomino",
+      "description": "可放置的方块形状，由多个格子组成的多联骨牌",
+      "examples": [
+        { "name": "L", "cells": [[0,0],[1,0],[1,1]] },
+        { "name": "line3", "cells": [[0,0],[1,0],[2,0]] },
+        { "name": "square2x2", "cells": [[0,0],[1,0],[0,1],[1,1]] },
+        { "name": "single", "cells": [[0,0]] }
+      ]
+    },
+    "pieceQueue": {
+      "type": "slot-array",
+      "slotCount": 3,
+      "description": "当前 3 个候选方块槽位，3 个都用完后补充新的"
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分"
+    }
+  },
+  "rules": {
+    "place_piece": {
+      "description": "将候选方块放置到棋盘指定位置（以方块左上角为锚点）。放置时所有格子必须在棋盘内且未被占用",
+      "collisionCheck": true,
+      "boundaryCheck": true
+    },
+    "clear_full_lines": {
+      "description": "放置后立即检查所有行与列，若某行或某列全部被占用则消除并得分",
+      "clearRows": true,
+      "clearCols": true,
+      "scorePerLine": 100,
+      "multiLineBonusMultiplier": 1.5
+    },
+    "generate_pieces": {
+      "description": "3 个槽位的方块全部用完后，同时生成 3 个新的随机方块",
+      "batchSize": 3,
+      "distribution": "uniform_shapes"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：选择方块 → 放置 → 消行 → 检测失败 → 补充方块",
+    "steps": [
+      "1. 玩家从 3 个候选槽位中拖拽选择一个方块",
+      "2. 拖拽到目标位置，实时高亮可放置区域（canPlacePiece 检测）",
+      "3. 放下方块（place_piece），从槽位移除该方块",
+      "4. 检测所有行和列是否完整（clearLines），一次性消除所有完整行/列并计分",
+      "5. 若 3 个槽位全部为空，生成 3 个新的随机方块（generatePieces）",
+      "6. 检测失败条件：若剩余 3 个方块都无法放入棋盘，游戏结束"
+    ]
+  },
+  "winCondition": {
+    "type": "endless",
+    "description": "无尽模式，无胜利条件，追求最高得分"
+  },
+  "loseCondition": {
+    "type": "no_valid_placement",
+    "description": "当前 3 个候选方块都无法放入棋盘任意位置时，游戏结束"
+  },
+  "testCases": [
+    {
+      "id": "tc_place_single_cell",
+      "description": "放置单格方块到空棋盘",
+      "initialState": {
+        "board": "10×10 全空棋盘",
+        "pieceQueue": [{ "id": 0, "cells": [[0,0]], "color": 1 }, null, null],
+        "score": 0
+      },
+      "action": { "type": "place", "pieceIndex": 0, "position": { "col": 5, "row": 5 } },
+      "expectedState": {
+        "board": "棋盘 [5][5] 被占用，其余空",
+        "pieceQueue": [null, null, null],
+        "score": 0,
+        "clearedRows": [],
+        "clearedCols": []
+      }
+    },
+    {
+      "id": "tc_clear_row",
+      "description": "放置一个 1×1 方块完成整行消除",
+      "initialState": {
+        "board": "棋盘第 9 行有 9 个格子被占满（只差 col=9 空着）",
+        "pieceQueue": [{ "id": 0, "cells": [[0,0]], "color": 2 }, null, null],
+        "score": 0
+      },
+      "action": { "type": "place", "pieceIndex": 0, "position": { "col": 9, "row": 9 } },
+      "expectedState": {
+        "clearedRows": [9],
+        "clearedCols": [],
+        "score": 100,
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_clear_row_and_col",
+      "description": "同一个放置动作同时消除一行和一列",
+      "initialState": {
+        "board": "第 5 行第 0-9 列全满（第 5 行完整），第 3 列第 0-9 行全满（第 3 列完整），在 [3][5] 处放置则同时消除",
+        "pieceQueue": [{ "id": 0, "cells": [[0,0]], "color": 3 }, null, null],
+        "score": 0
+      },
+      "action": { "type": "place", "pieceIndex": 0, "position": { "col": 3, "row": 5 } },
+      "expectedState": {
+        "clearedRows": [5],
+        "clearedCols": [3],
+        "score": { "min": 200 },
+        "gameOver": false
+      }
+    },
+    {
+      "id": "tc_invalid_placement_overlap",
+      "description": "非法放置：目标位置与已有方块重叠",
+      "initialState": {
+        "board": "棋盘 [2][2] 已被占用",
+        "pieceQueue": [{ "id": 0, "cells": [[0,0],[1,0]], "color": 1 }, null, null],
+        "score": 50
+      },
+      "action": { "type": "place", "pieceIndex": 0, "position": { "col": 2, "row": 2 } },
+      "expectedState": {
+        "placementRejected": true,
+        "score": 50,
+        "boardUnchanged": true
+      }
+    },
+    {
+      "id": "tc_generate_new_pieces",
+      "description": "3 个槽位全部用完后，自动生成 3 个新方块",
+      "initialState": {
+        "board": "10×10 基本空棋盘",
+        "pieceQueue": [{ "id": 0, "cells": [[0,0]], "color": 1 }, null, null],
+        "score": 200
+      },
+      "action": { "type": "place", "pieceIndex": 0, "position": { "col": 0, "row": 0 } },
+      "expectedState": {
+        "pieceQueueLength": 3,
+        "allSlotsRefilled": true,
+        "score": 200
+      }
+    },
+    {
+      "id": "tc_game_over",
+      "description": "游戏结束：所有候选方块都无法放入棋盘",
+      "initialState": {
+        "board": "棋盘几乎填满，仅剩零散不连续的单格空位，无法容纳任何 L 形或线形方块",
+        "pieceQueue": [
+          { "id": 0, "cells": [[0,0],[1,0],[2,0]], "color": 1 },
+          { "id": 1, "cells": [[0,0],[0,1],[1,1]], "color": 2 },
+          { "id": 2, "cells": [[0,0],[1,0],[0,1],[1,1]], "color": 3 }
+        ],
+        "score": 5000
+      },
+      "action": { "type": "check_game_over" },
+      "expectedState": {
+        "gameOver": true,
+        "noValidPlacements": true
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,182 @@
+/**
+ * block_puzzle.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成放置、消行、生成全流程后
+ * 只返回最终状态，中间过程（哪些行被消除、哪些格子是新放置的）丢失。
+ *
+ * 渲染层需要分步动画（放置落地 → 消行闪光 → 方块消失），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、自动求解等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type BlockPuzzleConfig = {
+  /** 棋盘列数，默认 10 */
+  cols: number;
+  /** 棋盘行数，默认 10 */
+  rows: number;
+  /** 候选方块槽位数量，默认 3 */
+  pieceSlots: number;
+  /** 方块颜色数量，默认 5 */
+  colorCount: number;
+  /** 是否允许旋转，默认 false */
+  rotation: boolean;
+  /** 每行/列消除基础分，默认 100 */
+  scorePerLine: number;
+  /** 同时消除多行/列的倍率，默认 1.5 */
+  multiLineBonusMultiplier: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type BlockPuzzleAction =
+  | { type: 'place'; pieceIndex: number; position: { col: number; row: number } }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+/** 棋盘单格，null 表示空，number 表示颜色 ID */
+export type BoardCell = number | null;
+
+/** 方块形状：相对于锚点（左上角）的格子偏移集合 */
+export type PieceShape = Array<{ dc: number; dr: number }>;
+
+/** 候选方块 */
+export type Piece = {
+  id: number;
+  cells: PieceShape;
+  color: number;
+};
+
+export type BlockPuzzleState = {
+  /** 棋盘，board[col][row] */
+  board: BoardCell[][];
+  /** 当前 3 个（或更多）候选方块，null 表示已使用的槽位 */
+  pieceQueue: (Piece | null)[];
+  /** 当前得分 */
+  score: number;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 放置方块的结果 */
+export type PlaceResult = {
+  /** 被放置的格子坐标列表 */
+  placedCells: Array<{ col: number; row: number; color: number }>;
+  /** 新状态（放置后，消行前） */
+  newState: BlockPuzzleState;
+};
+
+/** 消行结果 */
+export type ClearResult = {
+  /** 被消除的行索引列表 */
+  clearedRows: number[];
+  /** 被消除的列索引列表 */
+  clearedCols: number[];
+  /** 被消除的格子坐标集合（用于动画） */
+  clearedCells: Array<{ col: number; row: number }>;
+  /** 本次消除获得的分数 */
+  score: number;
+  /** 新状态 */
+  newState: BlockPuzzleState;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ * - 创建空棋盘
+ * - 生成初始 pieceSlots 个候选方块
+ */
+export declare function init(config: BlockPuzzleConfig): BlockPuzzleState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - place：放置方块到指定位置，消行，更新候选
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: BlockPuzzleState, action: BlockPuzzleAction): BlockPuzzleState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: BlockPuzzleState): BlockPuzzleState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * canPlacePiece：检测方块是否可以放置到指定位置
+ *
+ * 合法条件：
+ * 1. 方块所有格子都在棋盘边界内
+ * 2. 方块所有格子对应的棋盘位置均为空
+ *
+ * 场景层在拖拽过程中实时调用，用于高亮可放置区域。
+ */
+export declare function canPlacePiece(
+  state: BlockPuzzleState,
+  piece: Piece,
+  position: { col: number; row: number },
+): boolean;
+
+/**
+ * placePiece：将方块放置到棋盘（不做合法性验证，调用前请先确认 canPlacePiece）
+ *
+ * 场景层在放置确认后调用，播放落地动画。
+ * 不执行消行逻辑，消行由 clearLines 单独处理。
+ */
+export declare function placePiece(
+  state: BlockPuzzleState,
+  piece: Piece,
+  position: { col: number; row: number },
+): PlaceResult;
+
+/**
+ * clearLines：检测并消除所有完整的行和列
+ *
+ * 同一次放置可能同时触发多行/多列消除，返回完整的消除信息。
+ * 场景层在放置落地动画结束后调用，播放消除闪光动画。
+ */
+export declare function clearLines(state: BlockPuzzleState): ClearResult;
+
+/**
+ * generatePieces：生成指定数量的随机方块
+ *
+ * 当所有槽位的方块都用完（pieceQueue 全为 null）时调用。
+ * 场景层在获得新方块后播放方块滑入候选区动画。
+ */
+export declare function generatePieces(
+  count: number,
+  colorCount: number,
+): Piece[];
+
+/**
+ * canPlaceAnywhere：检测某个方块是否能放置在棋盘的任意位置
+ *
+ * 场景层在每次放置后检测，若所有候选方块都无法放置则触发游戏结束。
+ */
+export declare function canPlaceAnywhere(
+  state: BlockPuzzleState,
+  piece: Piece,
+): boolean;