@playcraft/skills 0.0.2

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

@@ -0,0 +1,235 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 螺丝拆解玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "screw_puzzle",
+  "entities": {
+    "board": {
+      "type": "layered-scene",
+      "layers": 3,
+      "description": "多层场景，每层有若干固定位置的零件槽，layer 0 为最底层"
+    },
+    "screw": {
+      "type": "interactive-item",
+      "fields": {
+        "id": "string",
+        "color": "ScrewColor (red|blue|green|yellow|purple|orange)",
+        "itemId": "string (所属零件)",
+        "holeId": "string | null (当前插入的螺孔，null 表示在缓冲区)"
+      },
+      "description": "螺丝，有颜色标记，固定零件到对应螺孔；只能被移入同色螺孔"
+    },
+    "item": {
+      "type": "multi-cell-object",
+      "fields": {
+        "id": "string",
+        "layer": "number (所在层级，越小越底层)",
+        "screwIds": "string[] (固定此零件的螺丝列表，全部移除后零件释放)",
+        "state": "ItemState (fixed|releasing|released)"
+      },
+      "description": "零件/木板，占据一个或多个格子，被若干螺丝固定，所有螺丝拆除后因重力释放"
+    },
+    "screw_hole": {
+      "type": "slot",
+      "fields": {
+        "id": "string",
+        "color": "ScrewColor",
+        "itemId": "string (所属零件)",
+        "screwId": "string | null (当前插入的螺丝)"
+      },
+      "description": "螺孔（接收槽），有颜色标记，只接受同色螺丝"
+    },
+    "buffer": {
+      "type": "queue",
+      "capacity": 3,
+      "description": "临时缓冲区，存放已拆但尚未插入螺孔的螺丝；超出容量且无法匹配时触发失败"
+    }
+  },
+  "rules": {
+    "remove_screw": {
+      "description": "玩家点击螺丝 → 螺丝从当前螺孔拔出，进入缓冲区或直接移入同色空螺孔",
+      "trigger": "player_tap",
+      "steps": [
+        "1. 从螺孔拔出螺丝（screwHole.screwId = null）",
+        "2. 查找任意一个同色且为空的螺孔（非当前零件上的）",
+        "3. 若找到 → 螺丝直接进入该螺孔（screwHole.screwId = screwId）",
+        "4. 若未找到 → 螺丝进入 buffer",
+        "5. buffer 中的螺丝在每次操作后尝试自动匹配空螺孔（先入先出）"
+      ]
+    },
+    "gravity_release": {
+      "description": "零件上所有螺丝均被移除 → 零件释放（下落/退出场景）",
+      "trigger": "item.screwIds.every(id => screwNotInHole)",
+      "effect": "item.state = 'releasing' → 播放下落动画 → item.state = 'released' → 从场景移除"
+    },
+    "buffer_overflow": {
+      "description": "缓冲区满（3 个螺丝）且当前操作的螺丝无同色空螺孔时，触发失败",
+      "trigger": "buffer.length >= buffer.capacity AND no_matching_hole",
+      "effect": "gameOver = true, win = false"
+    },
+    "cascade_match": {
+      "description": "每次操作结束后，缓冲区内的螺丝自动尝试匹配空螺孔并插入（先入先出）",
+      "trigger": "after_any_action",
+      "effect": "auto-fill matching screw holes from buffer"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：tap_screw → remove → match_hole / buffer → release_item → gravity → win/lose 检测",
+    "steps": [
+      "1. 玩家点击目标螺丝",
+      "2. 检查螺丝是否可拆（当前状态合法）",
+      "3. 将螺丝从螺孔拔出",
+      "4. 查找同色空螺孔（优先非当前零件），有则直接插入，无则进入 buffer",
+      "5. 检查 buffer 是否已满且无法匹配 → 失败",
+      "6. 检查 buffer 中所有螺丝，自动匹配并插入空螺孔",
+      "7. 检查所有零件：若某零件的全部螺丝都已被移除（不在任何螺孔），则触发释放",
+      "8. 对已释放零件执行重力模拟（上层零件下移）",
+      "9. 检测胜利条件：所有零件 state = 'released'"
+    ]
+  },
+  "winCondition": {
+    "type": "all_items_released",
+    "description": "所有零件 state = 'released'（已下落退出场景）"
+  },
+  "loseCondition": {
+    "type": "buffer_overflow",
+    "description": "缓冲区已满（3 个螺丝）且当前移除的螺丝无法匹配任何空螺孔"
+  },
+  "testCases": [
+    {
+      "id": "tc_basic_remove",
+      "description": "基础移除：点击螺丝，直接飞入同色空螺孔，缓冲区不变",
+      "initialState": {
+        "screws": [
+          { "id": "s1", "color": "red", "itemId": "item1", "holeId": "h1" }
+        ],
+        "screwHoles": [
+          { "id": "h1", "color": "red", "itemId": "item1", "screwId": "s1" },
+          { "id": "h2", "color": "red", "itemId": "item2", "screwId": null }
+        ],
+        "items": [
+          { "id": "item1", "layer": 1, "screwIds": ["s1"], "state": "fixed" },
+          { "id": "item2", "layer": 0, "screwIds": [], "state": "fixed" }
+        ],
+        "buffer": []
+      },
+      "actions": [
+        { "type": "remove_screw", "screwId": "s1" }
+      ],
+      "expectedState": {
+        "screws": [
+          { "id": "s1", "holeId": "h2" }
+        ],
+        "screwHoles": [
+          { "id": "h1", "screwId": null },
+          { "id": "h2", "screwId": "s1" }
+        ],
+        "buffer": [],
+        "items": [
+          { "id": "item1", "state": "released" }
+        ],
+        "gameOver": false,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_gravity_release",
+      "description": "重力释放：移除零件所有螺丝后，零件状态变为 releasing/released",
+      "initialState": {
+        "screws": [
+          { "id": "s1", "color": "blue", "itemId": "item1", "holeId": "h1" },
+          { "id": "s2", "color": "blue", "itemId": "item1", "holeId": "h2" }
+        ],
+        "screwHoles": [
+          { "id": "h1", "color": "blue", "itemId": "item1", "screwId": "s1" },
+          { "id": "h2", "color": "blue", "itemId": "item1", "screwId": "s2" },
+          { "id": "h3", "color": "blue", "itemId": "item2", "screwId": null },
+          { "id": "h4", "color": "blue", "itemId": "item2", "screwId": null }
+        ],
+        "items": [
+          { "id": "item1", "layer": 1, "screwIds": ["s1", "s2"], "state": "fixed" },
+          { "id": "item2", "layer": 0, "screwIds": [], "state": "released" }
+        ],
+        "buffer": []
+      },
+      "actions": [
+        { "type": "remove_screw", "screwId": "s1" },
+        { "type": "remove_screw", "screwId": "s2" }
+      ],
+      "expectedState": {
+        "items": [
+          { "id": "item1", "state": "released" }
+        ],
+        "buffer": [],
+        "win": true,
+        "gameOver": true
+      }
+    },
+    {
+      "id": "tc_color_mismatch_buffer",
+      "description": "颜色不匹配：螺丝无法插入异色螺孔，进入缓冲区",
+      "initialState": {
+        "screws": [
+          { "id": "s1", "color": "red", "itemId": "item1", "holeId": "h1" }
+        ],
+        "screwHoles": [
+          { "id": "h1", "color": "red", "itemId": "item1", "screwId": "s1" },
+          { "id": "h2", "color": "blue", "itemId": "item2", "screwId": null }
+        ],
+        "items": [
+          { "id": "item1", "layer": 1, "screwIds": ["s1"], "state": "fixed" },
+          { "id": "item2", "layer": 0, "screwIds": ["s2"], "state": "fixed" }
+        ],
+        "buffer": []
+      },
+      "actions": [
+        { "type": "remove_screw", "screwId": "s1" }
+      ],
+      "expectedState": {
+        "buffer": [{ "screwId": "s1", "color": "red" }],
+        "screwHoles": [
+          { "id": "h1", "screwId": null },
+          { "id": "h2", "screwId": null }
+        ],
+        "gameOver": false,
+        "win": false
+      }
+    },
+    {
+      "id": "tc_buffer_overflow_lose",
+      "description": "缓冲区溢出失败：缓冲区已满3个，再拆一颗无同色空孔的螺丝 → 失败",
+      "initialState": {
+        "screws": [
+          { "id": "s1", "color": "red", "itemId": "item1", "holeId": "h1" },
+          { "id": "s2", "color": "green", "itemId": "item2", "holeId": "h2" },
+          { "id": "s3", "color": "yellow", "itemId": "item3", "holeId": "h3" },
+          { "id": "s4", "color": "purple", "itemId": "item4", "holeId": "h4" }
+        ],
+        "screwHoles": [
+          { "id": "h1", "color": "red", "itemId": "item1", "screwId": "s1" },
+          { "id": "h2", "color": "green", "itemId": "item2", "screwId": "s2" },
+          { "id": "h3", "color": "yellow", "itemId": "item3", "screwId": "s3" },
+          { "id": "h4", "color": "purple", "itemId": "item4", "screwId": "s4" }
+        ],
+        "items": [
+          { "id": "item1", "layer": 2, "screwIds": ["s1"], "state": "fixed" },
+          { "id": "item2", "layer": 2, "screwIds": ["s2"], "state": "fixed" },
+          { "id": "item3", "layer": 1, "screwIds": ["s3"], "state": "fixed" },
+          { "id": "item4", "layer": 1, "screwIds": ["s4"], "state": "fixed" }
+        ],
+        "buffer": [
+          { "screwId": "sx1", "color": "orange" },
+          { "screwId": "sx2", "color": "orange" },
+          { "screwId": "sx3", "color": "orange" }
+        ]
+      },
+      "actions": [
+        { "type": "remove_screw", "screwId": "s1" }
+      ],
+      "expectedState": {
+        "gameOver": true,
+        "win": false,
+        "reason": "buffer_overflow"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,213 @@
+/**
+ * screw_puzzle.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部跑完整个操作链后只返回最终状态，
+ * 中间过程（螺丝移动轨迹、零件释放顺序、重力下落路径）全部丢失。
+ *
+ * 渲染层需要分步动画（螺丝拔出 → 飞入螺孔 → 零件下落 → 重力压缩），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type ScrewColor = 'red' | 'blue' | 'green' | 'yellow' | 'purple' | 'orange';
+
+export type ScrewPuzzleConfig = {
+  /** 场景层数，默认 3 */
+  layers: number;
+  /** 缓冲区最大容量，默认 3 */
+  bufferCapacity: number;
+  /** 初始螺丝列表 */
+  screws: Array<{
+    id: string;
+    color: ScrewColor;
+    itemId: string;
+    holeId: string;
+  }>;
+  /** 初始零件列表 */
+  items: Array<{
+    id: string;
+    layer: number;
+    screwIds: string[];
+  }>;
+  /** 螺孔列表 */
+  screwHoles: Array<{
+    id: string;
+    color: ScrewColor;
+    itemId: string;
+  }>;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type ScrewPuzzleAction =
+  | { type: 'remove_screw'; screwId: string }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type ItemState = 'fixed' | 'releasing' | 'released';
+
+export type ScrewState = {
+  id: string;
+  color: ScrewColor;
+  itemId: string;
+  /** 当前所在螺孔 id，null 表示在缓冲区 */
+  holeId: string | null;
+};
+
+export type ItemRecord = {
+  id: string;
+  layer: number;
+  screwIds: string[];
+  state: ItemState;
+};
+
+export type ScrewHoleRecord = {
+  id: string;
+  color: ScrewColor;
+  itemId: string;
+  /** 当前插入的螺丝 id，null 表示空闲 */
+  screwId: string | null;
+};
+
+export type ScrewPuzzleState = {
+  screws: Record<string, ScrewState>;
+  items: Record<string, ItemRecord>;
+  screwHoles: Record<string, ScrewHoleRecord>;
+  /** 缓冲区中的螺丝 id 列表（先入先出） */
+  buffer: string[];
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 失败原因 */
+  loseReason?: 'buffer_overflow' | 'deadlock';
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 螺丝移动信息（用于驱动飞行动画） */
+export type ScrewMove = {
+  screwId: string;
+  color: ScrewColor;
+  /** 来源螺孔 id */
+  fromHoleId: string;
+  /** 目标螺孔 id，null 表示进入缓冲区 */
+  toHoleId: string | null;
+  /** 是否直接入孔（true = 直接匹配；false = 先入缓冲再匹配） */
+  directMatch: boolean;
+};
+
+/** 缓冲区自动匹配结果 */
+export type BufferAutoMatch = {
+  screwId: string;
+  toHoleId: string;
+};
+
+/** 零件释放信息（用于驱动下落动画） */
+export type ReleasedItem = {
+  itemId: string;
+  layer: number;
+};
+
+/** 重力压缩：上方零件下移 */
+export type FallMove = {
+  itemId: string;
+  fromLayer: number;
+  toLayer: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: ScrewPuzzleConfig): ScrewPuzzleState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - remove_screw：移除螺丝，触发匹配、零件释放、重力（一步到位）
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: ScrewPuzzleState, action: ScrewPuzzleAction): ScrewPuzzleState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: ScrewPuzzleState): ScrewPuzzleState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * canRemoveScrew：检查指定螺丝是否可以被拆除
+ * - 螺丝必须存在且当前插在某螺孔中（不在缓冲区）
+ * - 游戏未结束
+ *
+ * 场景层在玩家点击时调用：false → 播放禁止/摇晃提示
+ */
+export declare function canRemoveScrew(state: ScrewPuzzleState, screwId: string): boolean;
+
+/**
+ * removeScrew：执行螺丝拆除操作
+ * 返回更新后的状态及螺丝移动轨迹（含缓冲区自动匹配结果）
+ *
+ * 场景层根据 screwMove 和 bufferAutoMatches 分别播放：
+ * - 螺丝旋转拔出动画
+ * - 螺丝飞向目标螺孔或飞入缓冲区动画
+ * - 缓冲区螺丝自动飞入匹配螺孔动画
+ */
+export declare function removeScrew(
+  state: ScrewPuzzleState,
+  screwId: string,
+): {
+  newState: ScrewPuzzleState;
+  screwMove: ScrewMove;
+  bufferAutoMatches: BufferAutoMatch[];
+  overflowed: boolean;
+};
+
+/**
+ * checkItemRelease：检查哪些零件在当前状态下满足释放条件（所有螺丝均已离开螺孔）
+ * 返回待释放零件列表
+ *
+ * 场景层根据 ReleasedItem[] 播放零件下落动画
+ */
+export declare function checkItemRelease(
+  state: ScrewPuzzleState,
+  changedItemIds?: string[],
+): ReleasedItem[];
+
+/**
+ * applyGravity：在若干零件释放后，计算上方零件向下压缩的位移
+ * 返回需要移动的零件列表
+ *
+ * 场景层根据 FallMove[] 播放零件向下移动动画
+ */
+export declare function applyGravity(state: ScrewPuzzleState): FallMove[];
+
+/**
+ * findValidMoves：返回当前所有合法可拆螺丝的 id 列表
+ * 场景层可用此函数高亮可操作螺丝（引导提示）
+ * 若返回空数组且游戏未结束，则为死锁
+ */
+export declare function findValidMoves(state: ScrewPuzzleState): string[];

package/skills/settings_state.aicomponent/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: settings_state.aicomponent
+description: 用户设置状态管理器。管理音乐/音效开关和拖拽速度倍率等用户偏好，提供 get/set 接口供其他组件读取。
+triggers: 需要管理用户音频设置、拖拽速度等游戏偏好设置时触发。
+---
+
+# 用户设置状态（Settings State）
+
+## 说明
+
+`SettingsManager` 管理用户偏好设置：
+
+- `soundOn` / `musicOn`：音效/音乐开关
+- `getDragSpeedMultiplier()`：拖拽棋盘速度倍率（0.5~1.5）
+
+## Scaffold
+
+| 目标路径 | 来源 |
+|---------|-----|
+| `src/game/scenes/GameUI/SettingsManager.ts` | `ref/SettingsManager.ts` |
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/SettingsManager.ts
+outputs:
+  - settingsManager: SettingsManager class
+```
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **独立 Manager 而非分散状态** | 多个组件（SoundUtils、InputHandler）需要读取同一份偏好设置；集中在 SettingsManager 避免重复读取和不一致 |
+| **轮询而非事件订阅** | 音效开关在播放时检查即可，拖拽速度在每帧输入处理时读取；轮询模式实现更简单，偏好变化低频 |
+
+## Adapter
+
+- **Role**: `settingsState` — 用户偏好设置管理器（音效/音乐开关、拖拽速度）
+- **Provides**: `SettingsManager` 类（`soundOn`、`musicOn`、`getDragSpeedMultiplier()`）
+- **Requires**: `phaser.aicomponent`（硬依赖）
+- **Consumed by**: `sound_utils.aicomponent`（检查 `soundOn` 决定是否播放）、`path_input_handler.aicomponent`（读取拖拽速度倍率）、`game_scene.aicomponent`（持有实例并传递给子系统）
+- **Integration point**: `src/game/scenes/GameUI/SettingsManager.ts` —— `game_scene` 初始化后传递给需要的子系统
+
+## 关键接口
+
+```typescript
+class SettingsManager {
+  soundOn: boolean;
+  musicOn: boolean;
+  getDragSpeedMultiplier(): number;
+}
+```

package/skills/settings_state.aicomponent/manifest.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "atomId": "settings_state.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "state",
+  "mode": "fixed",
+  "label": { "zh": "用户设置状态管理", "en": "User settings state manager" },
+  "tags": ["state", "settings", "music", "sound", "drag-speed", "preferences"],
+  "bindingRoles": ["userSettings"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/SettingsManager.ts": {
+        "source": "ref/SettingsManager.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "SettingsManager", "kind": "class", "location": "src/game/scenes/GameUI/SettingsManager.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "persistent user preferences store: audio toggles and drag speed multiplier",
+    "layers": ["state-management", "user-preferences"]
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "settingsManager": "ref/SettingsManager.ts"
+  }
+}

package/skills/settings_state.aicomponent/ref/SettingsManager.ts

@@ -0,0 +1,130 @@
+import * as Phaser from "phaser";
+import {
+  DRAG_SPEED_MIN_MULTIPLIER,
+  DRAG_SPEED_MAX_MULTIPLIER,
+} from "../../GameConfig";
+import { safePlaySound } from "../../utils/SoundUtils";
+import { ENABLE_BACKGROUND_MUSIC } from "../../DebugConfig";
+
+/** 拖拽速度值类型，范围 0.0 ~ 1.0 */
+export type DragSpeedValue = number;
+
+/**
+ * 设置管理器（单例）。
+ * 管理音乐、音效开关、拖拽速度和背景音乐播放。
+ */
+export class SettingsManager {
+  private static _instance: SettingsManager | null = null;
+
+  public musicOn = true;
+  public soundOn = true;
+  /** 拖拽速度：0.0 = 慢, 1.0 = 快 */
+  public dragSpeed: DragSpeedValue = 0.5;
+  private bgm: Phaser.Sound.BaseSound | null = null;
+  private isBgmLoading = false;
+
+  static get instance(): SettingsManager {
+    if (!this._instance) {
+      this._instance = new SettingsManager();
+    }
+    return this._instance;
+  }
+
+  private constructor() {}
+
+  /**
+   * 播放按钮点击音效。
+   * @param scene 当前场景
+   */
+  public playButtonClick(scene: Phaser.Scene) {
+    if (!this.soundOn) return;
+    safePlaySound(scene, "button_click", { volume: 0.8 });
+  }
+
+  /**
+   * 播放背景音乐。如果音频尚未加载，会动态加载后再播放。
+   * @param scene 当前场景
+   */
+  public playBgm(scene: Phaser.Scene) {
+    // 如果配置禁用背景音乐，直接返回
+    if (!ENABLE_BACKGROUND_MUSIC) {
+      return;
+    }
+
+    if (!this.musicOn) {
+      this.stopBgm();
+      return;
+    }
+
+    const soundManager = scene.sound;
+
+    /** 开始播放背景音乐 */
+    const startPlay = () => {
+      if (!this.musicOn) {
+        return;
+      }
+      if (!this.bgm) {
+        this.bgm = soundManager.add("bg");
+      }
+      if (!this.bgm) {
+        return;
+      }
+      this.bgm.stop();
+      this.bgm.play({ loop: true, volume: 0.45 });
+    };
+
+    // 如果音频已经在缓存中，直接播放
+    if (scene.cache.audio.exists("bg")) {
+      startPlay();
+      return;
+    }
+
+    // 尚未加载且已经在加载中：避免重复发起请求
+    if (this.isBgmLoading) {
+      return;
+    }
+
+    // 动态加载 bg.mp3，加载完成后根据当前开关决定是否播放
+    this.isBgmLoading = true;
+    scene.load.once(Phaser.Loader.Events.COMPLETE, () => {
+      this.isBgmLoading = false;
+      if (this.musicOn) {
+        startPlay();
+      }
+    });
+    scene.load.start();
+  }
+
+  /** 停止背景音乐 */
+  public stopBgm() {
+    if (this.bgm) {
+      this.bgm.stop();
+    }
+  }
+
+  /**
+   * 将当前的音乐/音效设置应用到指定场景的声音系统。
+   * 通过 mute / volume 控制整体开关。
+   * @param scene 当前场景
+   */
+  public applyToSceneSound(scene: Phaser.Scene) {
+    const soundManager = scene.sound;
+    // musicOn 控制全局背景音乐是否允许播放；这里用 mute 简单实现
+    soundManager.mute = !this.soundOn && !this.musicOn;
+  }
+
+  /**
+   * 根据 dragSpeed（0~1）返回拖拽速度倍率：
+   * - dragSpeed = 0   -> 最小倍率
+   * - dragSpeed = 0.5 -> 默认速度
+   * - dragSpeed = 1   -> 最大倍率
+   * @returns 拖拽速度倍率
+   */
+  public getDragSpeedMultiplier(): number {
+    const t = Phaser.Math.Clamp(this.dragSpeed, 0, 1);
+    const factor =
+      DRAG_SPEED_MIN_MULTIPLIER +
+      t * (DRAG_SPEED_MAX_MULTIPLIER - DRAG_SPEED_MIN_MULTIPLIER);
+    return factor;
+  }
+}