@playcraft/skills 0.0.2

package/skills/slot_machine.aigameplay/manifest.json

@@ -0,0 +1,166 @@
+{
+  "schemaVersion": 1,
+  "atomId": "slot_machine.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "老虎机转轮玩法",
+    "en": "Slot Machine Reel gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "slot",
+    "casino",
+    "reel",
+    "spin",
+    "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": "symbolTextures",
+      "description": "符号贴图集",
+      "bindAs": "symbols",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tileTextureSet"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "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": "slot_machine",
+    "rules": {
+      "reelCount": 3,
+      "symbolsPerReel": 3,
+      "paylineCount": 5,
+      "wildSymbol": "WILD",
+      "scatterSymbol": "SCATTER",
+      "scatterMinCount": 3,
+      "rngType": "uniform"
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/slot_machine/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(state, action)",
+        "getState(state)",
+        "spin(state)",
+        "evaluatePaylines(result, paylines, symbols)",
+        "calculatePayout(matches, bet)",
+        "checkScatter(result)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,212 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 老虎机转轮玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "slot_machine",
+  "entities": {
+    "reels": {
+      "type": "array",
+      "count": 3,
+      "description": "转轮数组，每个转轮显示 symbolsPerReel（默认3）个符号",
+      "fields": {
+        "symbolPool": "string[]，每个转轮的符号池（决定随机权重）",
+        "visibleSymbols": "string[]，当前显示的符号列表（从上到下）"
+      }
+    },
+    "paylines": {
+      "type": "array",
+      "description": "连线定义，每条连线是各转轮的行索引",
+      "defaultPatterns": [
+        { "id": 0, "name": "top_row", "rows": [0, 0, 0] },
+        { "id": 1, "name": "middle_row", "rows": [1, 1, 1] },
+        { "id": 2, "name": "bottom_row", "rows": [2, 2, 2] },
+        { "id": 3, "name": "diagonal_down", "rows": [0, 1, 2] },
+        { "id": 4, "name": "diagonal_up", "rows": [2, 1, 0] }
+      ]
+    },
+    "symbol": {
+      "type": "enum",
+      "values": ["SEVEN", "BAR", "CHERRY", "BELL", "LEMON", "WILD", "SCATTER"],
+      "description": "符号类型定义",
+      "fields": {
+        "type": "string，符号名称",
+        "multiplier": "number，3连同符号的赔率倍数",
+        "isWild": "boolean，是否为通配符（可替代任意非SCATTER符号）",
+        "isScatter": "boolean，是否为散布符号（不受连线限制，≥3个即触发）"
+      },
+      "symbolTable": [
+        { "type": "SEVEN",   "multiplier": 20, "isWild": false, "isScatter": false },
+        { "type": "BAR",     "multiplier": 10, "isWild": false, "isScatter": false },
+        { "type": "BELL",    "multiplier": 8,  "isWild": false, "isScatter": false },
+        { "type": "CHERRY",  "multiplier": 5,  "isWild": false, "isScatter": false },
+        { "type": "LEMON",   "multiplier": 3,  "isWild": false, "isScatter": false },
+        { "type": "WILD",    "multiplier": 0,  "isWild": true,  "isScatter": false },
+        { "type": "SCATTER", "multiplier": 0,  "isWild": false, "isScatter": true  }
+      ]
+    },
+    "bet": {
+      "type": "counter",
+      "description": "当前下注金额，每次 spin 从 balance 扣除",
+      "min": 1,
+      "max": 100,
+      "default": 10
+    },
+    "balance": {
+      "type": "counter",
+      "initial": 1000,
+      "description": "玩家余额，spin 扣除 bet，中奖则增加 payout"
+    },
+    "spinResult": {
+      "type": "snapshot",
+      "description": "最近一次 spin 的结果",
+      "fields": {
+        "reels": "string[][]，各转轮停止后的符号矩阵 [reelIdx][rowIdx]",
+        "matches": "PaylineMatch[]，中奖的连线列表",
+        "totalPayout": "number，本次 spin 总奖励",
+        "scatterCount": "number，scatter 符号总数",
+        "scatterTriggered": "boolean，是否触发 scatter 奖励"
+      }
+    }
+  },
+  "rules": {
+    "spin": {
+      "description": "玩家触发旋转，每个转轮独立随机（RNG）选取符号",
+      "precondition": "balance >= bet",
+      "effect": "balance -= bet；为每个转轮随机生成 symbolsPerReel 个符号",
+      "rngType": "uniform（可换为 weighted 权重随机）"
+    },
+    "evaluate_paylines": {
+      "description": "遍历所有连线，检测是否有 ≥3 个相同符号（考虑 Wild 替换）",
+      "wildSubstitution": "WILD 可替代任意非 SCATTER 符号参与连线匹配",
+      "minMatchCount": 3,
+      "result": "返回命中的 PaylineMatch[] 列表，包含连线 ID、匹配符号、数量"
+    },
+    "wild_substitution": {
+      "description": "在连线评估中，WILD 符号视为任意普通符号",
+      "note": "若连线全为 WILD，按连线上 WILD 的最高赔率计算；WILD 不替代 SCATTER"
+    },
+    "scatter_bonus": {
+      "description": "统计所有转轮中 SCATTER 符号的总数，不受连线限制",
+      "triggerCondition": "scatterCount >= 3",
+      "reward": "scatterCount === 3: bet×5；scatterCount === 4: bet×20；scatterCount >= 5: bet×100"
+    },
+    "payout_calculation": {
+      "description": "计算本次 spin 总奖励 = 各命中连线奖励之和 + scatter 奖励",
+      "formula": "paylineReward = bet × symbol.multiplier（每条中奖连线独立计算）",
+      "balanceUpdate": "balance += totalPayout"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：下注 → 旋转 → 结算 → 胜败检测",
+    "steps": [
+      "1. 玩家设置 bet 金额（1 ~ balance）",
+      "2. 玩家点击 spin，检验 balance >= bet",
+      "3. balance -= bet",
+      "4. 为每个转轮独立 RNG 生成 symbolsPerReel 个符号",
+      "5. 调用 evaluatePaylines(reels, paylines, symbolDefs) 检测中奖连线",
+      "6. 调用 calculatePayout(matches, bet) 计算总奖励",
+      "7. 调用 checkScatter(reels) 检测 scatter 触发",
+      "8. balance += totalPayout（包含连线奖励和 scatter 奖励）",
+      "9. 更新 spinResult 快照",
+      "10. 检测 balance <= 0 → gameOver（可选）"
+    ]
+  },
+  "winCondition": {
+    "type": "payline_hit_or_scatter",
+    "description": "任意连线有 ≥3 相同符号（含 Wild 替换），或 ≥3 个 Scatter 出现"
+  },
+  "loseCondition": {
+    "type": "balance_depleted",
+    "description": "balance <= 0 且无法继续下注"
+  },
+  "testCases": [
+    {
+      "id": "tc_three_match_win",
+      "description": "3连中奖：中间行3个 SEVEN，赔率×20",
+      "initialState": {
+        "balance": 1000,
+        "bet": 10,
+        "reels": [
+          ["CHERRY", "SEVEN", "LEMON"],
+          ["BAR",    "SEVEN", "BELL"],
+          ["LEMON",  "SEVEN", "CHERRY"]
+        ]
+      },
+      "actions": [
+        { "type": "evaluate_result" }
+      ],
+      "expectedState": {
+        "matches": [{ "paylineId": 1, "symbol": "SEVEN", "count": 3 }],
+        "totalPayout": 200,
+        "balance": 1190,
+        "note": "balance = 1000 - 10(bet) + 200(10×20) = 1190"
+      }
+    },
+    {
+      "id": "tc_no_match",
+      "description": "无中奖：所有连线均无3连相同符号",
+      "initialState": {
+        "balance": 1000,
+        "bet": 10,
+        "reels": [
+          ["SEVEN", "BAR",    "CHERRY"],
+          ["LEMON", "CHERRY", "SEVEN"],
+          ["BAR",   "SEVEN",  "BELL"]
+        ]
+      },
+      "actions": [
+        { "type": "evaluate_result" }
+      ],
+      "expectedState": {
+        "matches": [],
+        "totalPayout": 0,
+        "balance": 990,
+        "note": "balance = 1000 - 10 = 990，无中奖"
+      }
+    },
+    {
+      "id": "tc_scatter_bonus",
+      "description": "Scatter 触发奖励：3个 SCATTER 出现在任意位置",
+      "initialState": {
+        "balance": 1000,
+        "bet": 10,
+        "reels": [
+          ["SCATTER", "BAR",     "CHERRY"],
+          ["LEMON",   "SCATTER", "SEVEN"],
+          ["BAR",     "SEVEN",   "SCATTER"]
+        ]
+      },
+      "actions": [
+        { "type": "evaluate_result" }
+      ],
+      "expectedState": {
+        "scatterCount": 3,
+        "scatterTriggered": true,
+        "scatterBonus": 50,
+        "balance": 1040,
+        "note": "balance = 1000 - 10 + 50(bet×5) = 1040"
+      }
+    },
+    {
+      "id": "tc_wild_substitution",
+      "description": "Wild 替换：连线中一个 WILD 替换为 CHERRY，形成3连 CHERRY",
+      "initialState": {
+        "balance": 1000,
+        "bet": 10,
+        "reels": [
+          ["BAR",    "CHERRY", "LEMON"],
+          ["SEVEN",  "WILD",   "BELL"],
+          ["LEMON",  "CHERRY", "CHERRY"]
+        ]
+      },
+      "actions": [
+        { "type": "evaluate_result" }
+      ],
+      "expectedState": {
+        "matches": [{ "paylineId": 1, "symbol": "CHERRY", "count": 3, "wildUsed": true }],
+        "totalPayout": 50,
+        "balance": 1040,
+        "note": "WILD 替代 CHERRY，中间行3连CHERRY，10×5=50"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,212 @@
+/**
+ * slot_machine.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部执行完整的旋转+结算逻辑后只返回最终状态，
+ * 中间过程（各转轮停止时机、中奖连线高亮、奖励特效）全部丢失。
+ *
+ * 渲染层需要分步驱动转轮停止动画和结算特效，因此必须使用下方「分步函数」。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速验证赔率计算。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type SlotSymbolDef = {
+  type: string;
+  /** 3连同符号的赔率倍数（payout = bet × multiplier） */
+  multiplier: number;
+  /** 是否为通配符（Wild，可替代任意非 Scatter 符号） */
+  isWild: boolean;
+  /** 是否为散布符号（Scatter，不受连线限制） */
+  isScatter: boolean;
+};
+
+export type Payline = {
+  /** 连线唯一 ID */
+  id: number;
+  /** 连线名称（如 'middle_row'） */
+  name: string;
+  /** 各转轮对应的行索引（rows[reelIdx] = rowIdx） */
+  rows: number[];
+};
+
+export type SlotMachineConfig = {
+  /** 转轮数量，默认 3 */
+  reelCount: number;
+  /** 每轮可见符号行数，默认 3 */
+  symbolsPerReel: number;
+  /** 连线定义 */
+  paylines: Payline[];
+  /** 符号定义表 */
+  symbolDefs: SlotSymbolDef[];
+  /** 各转轮的符号池（决定随机概率）*/
+  reelSymbolPools: string[][];
+  /** Scatter 触发所需最少数量，默认 3 */
+  scatterMinCount: number;
+  /** Scatter 奖励倍率表 { count: multiplier }（如 {3: 5, 4: 20, 5: 100}） */
+  scatterMultipliers: Record<number, number>;
+  /** 初始余额 */
+  initialBalance: number;
+  /** 默认下注金额 */
+  defaultBet: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type SlotMachineAction =
+  | { type: 'spin' }
+  | { type: 'set_bet'; amount: number }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type SlotMachineState = {
+  /** 各转轮当前显示的符号矩阵：reels[reelIdx][rowIdx] */
+  reels: string[][];
+  /** 当前下注金额 */
+  currentBet: number;
+  /** 玩家余额 */
+  balance: number;
+  /** 最近一次 spin 的结果快照 */
+  lastSpinResult: SpinResult | null;
+  /** 游戏是否结束（余额耗尽且无法下注） */
+  gameOver: boolean;
+  /** 总旋转次数 */
+  totalSpins: number;
+};
+
+/** spin() 返回值：本次旋转的原始结果 */
+export type SpinResult = {
+  /** 各转轮停止后的符号矩阵 */
+  reels: string[][];
+  /** 本次旋转扣除的下注金额 */
+  betAmount: number;
+};
+
+/** evaluatePaylines 返回的单条连线命中结果 */
+export type PaylineMatch = {
+  /** 命中的连线 ID */
+  paylineId: number;
+  /** 连线名称 */
+  paylineName: string;
+  /** 匹配的符号（Wild 替换后的实际符号） */
+  symbol: string;
+  /** 连续匹配数量 */
+  count: number;
+  /** 是否使用了 Wild 替换 */
+  wildUsed: boolean;
+  /** 该连线的奖励金额（bet × symbol.multiplier） */
+  payout: number;
+};
+
+/** checkScatter 返回值 */
+export type ScatterCheckResult = {
+  /** Scatter 符号在所有转轮中的总数量 */
+  count: number;
+  /** 是否达到触发条件（count >= scatterMinCount） */
+  triggered: boolean;
+  /** 散布奖励金额（bet × scatterMultipliers[count]） */
+  bonus: number;
+  /** Scatter 符号的位置列表 */
+  positions: Array<{ reelIdx: number; rowIdx: number }>;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: SlotMachineConfig): SlotMachineState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - spin：执行完整旋转（扣注、RNG、结算、更新余额）一步到位
+ * - set_bet：修改下注金额
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: SlotMachineState, action: SlotMachineAction): SlotMachineState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: SlotMachineState): SlotMachineState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * spin：执行旋转逻辑（RNG），返回各转轮停止结果，但暂不更新 balance。
+ *
+ * 场景层在玩家点击 SPIN 按钮后调用：
+ * 1. 调用 spin(state) 获取 SpinResult（同时从 balance 扣除 bet）
+ * 2. 逐个转轮播放滚动→停止动画（每个转轮间隔约500ms）
+ * 3. 全部转轮停止后，调用 evaluatePaylines + calculatePayout + checkScatter
+ * 4. 播放中奖特效，然后更新 balance
+ *
+ * @param state   当前游戏状态（balance >= currentBet 才可执行）
+ * @returns       包含各转轮结果的 SpinResult（balance 已扣除 bet）
+ */
+export declare function spin(state: SlotMachineState): { state: SlotMachineState; result: SpinResult };
+
+/**
+ * evaluatePaylines：评估所有连线，检测中奖情况（考虑 Wild 替换）。
+ *
+ * 场景层在所有转轮停止动画完成后调用。
+ *
+ * @param result    spin() 返回的转轮结果
+ * @param paylines  连线定义配置
+ * @param symbols   符号定义表
+ * @param bet       当前下注金额（用于计算各连线奖励）
+ * @returns         命中的连线列表（含奖励金额）
+ */
+export declare function evaluatePaylines(
+  result: SpinResult,
+  paylines: Payline[],
+  symbols: SlotSymbolDef[],
+  bet: number,
+): PaylineMatch[];
+
+/**
+ * calculatePayout：汇总所有中奖连线的总奖励金额。
+ *
+ * @param matches   evaluatePaylines() 返回的命中连线列表
+ * @param bet       当前下注金额（散布奖励也需要 bet 参数，故传入）
+ * @returns         连线总奖励金额（不含 scatter bonus）
+ */
+export declare function calculatePayout(matches: PaylineMatch[], bet: number): number;
+
+/**
+ * checkScatter：检测散布符号数量是否触发奖励。
+ *
+ * Scatter 不受连线限制，出现在任意转轮任意行均计入总数。
+ *
+ * @param result    spin() 返回的转轮结果
+ * @param symbols   符号定义表
+ * @param bet       当前下注金额
+ * @param scatterMinCount   触发所需最少 Scatter 数量
+ * @param scatterMultipliers  Scatter 奖励倍率表
+ * @returns         散布检测结果（是否触发、数量、奖励金额、位置列表）
+ */
+export declare function checkScatter(
+  result: SpinResult,
+  symbols: SlotSymbolDef[],
+  bet: number,
+  scatterMinCount: number,
+  scatterMultipliers: Record<number, number>,
+): ScatterCheckResult;

package/skills/sniper_shot.aigameplay/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: sniper_shot.aigameplay
+description: 狙击射击玩法封包 - 瞄准镜瞄准、呼吸抖动、风力修正、命中检测的 PGS 实现，支持敌军/平民目标分类
+triggers: 狙击,sniper,射击,shooting,瞄准,aim,狙击手,枪战,射手,gunshot,scope,瞄准镜,风力,wind,弹道
+---
+
+# sniper_shot.aigameplay
+
+狙击射击玩法封包。实现标准狙击玩法的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer，玩家通过瞄准镜调整瞄准位置，考虑呼吸抖动与风力修正，在合适时机射击消灭所有敌方目标。
+
+## Recipe
+
+- **玩法类型**：sniper_shot（狙击射击）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `scopeDriftEnabled`: true（开启呼吸抖动，瞄准镜周期性漂移）
+  - `breathCycleMs`: 3000（每 3 秒一个呼吸周期）
+  - `windEnabled`: true（风力影响弹道，需要提前修正）
+  - `friendlyFirePenalty`: true（误伤平民扣分或失败）
+  - `maxFriendlyFireHits`: 1（最多允许 1 次误伤）
+- **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 变体**：
+  - 无限子弹模式：将 `ammoCount` 设置为 Infinity，改为时间限制胜负
+  - 移动靶场：将所有目标设为移动，增加难度
+  - 多镜头：增加 `zoomLevel` 切换（2x / 4x / 8x），不同倍镜影响视野范围与抖动幅度
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据用于动画驱动 |
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `aimScope(dx, dy)` | `{ scopePos }` | 移动瞄准镜 overlay 到新位置 |
+| `applyBreathDrift(deltaMs)` | `{ driftOffset }` | 叠加抖动偏移到瞄准镜显示位置 |
+| `shoot()` | `{ hit, targetId, isCivilian, score }` | 播放枪声、命中/穿透特效、更新 HUD |
+| `hitDetection(scopePos)` | `HitResult` | 判断瞄准镜中心是否命中目标 |
+| `updateTargets(deltaMs)` | `Target[]` | 按运动模式更新目标位置，驱动精灵移动 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/sniper_shot/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `aimScope()` / `applyBreathDrift()` / `shoot()` / `hitDetection()` / `updateTargets()` / `calculateScore()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a sniper shooting gameplay module following the PGS specification.
+  Write the PGS JSON with entities (scope, targets, wind, ammo, score), rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - aimScope/applyBreathDrift/shoot/hitDetection/updateTargets/calculateScore (分步函数，用于渲染层驱动)
+  The breath drift must be sinusoidal over breathCycleMs, with amplitude scaling by zoom level.
+  Hit detection must combine: scope center position + breath drift offset + wind correction offset.
+  Friendly fire (civilian hit) must trigger penalty immediately and check maxFriendlyFireHits.
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.