@playcraft/skills 0.0.2

package/skills/theme_state.aicomponent/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: theme_state.aicomponent
+description: 主题状态管理器。管理路径颜色、箭头风格、UI 文本标签、画布背景色等视觉主题配置，供渲染器和 UI 组件读取当前主题值。
+triggers: 需要管理游戏视觉主题、路径颜色方案或主题切换逻辑时触发。
+---
+
+# 主题状态管理器（Theme State Manager）
+
+## 说明
+
+`ThemeManager` 从当前激活的 `ThemeVariantConfig`（`src/theme/index.ts`）中读取主题配置：
+
+- `getPathColor(pathIndex)`：返回指定路径的颜色（十六进制数字）
+- `getArrowStyle()`：返回箭头头部风格
+- `canvasBgColor`：画布背景色
+
+## Scaffold
+
+| 目标路径 | 来源 |
+|---------|-----|
+| `src/game/scenes/GameUI/ThemeManager.ts` | `ref/ThemeManager.ts` |
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/ThemeManager.ts
+outputs:
+  - themeManager: ThemeManager class
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **集中主题查询** | 路径颜色、箭头风格等视觉值分散在多个渲染组件中会导致主题切换时遗漏；ThemeManager 作为单一查询入口，确保视觉一致性 |
+| **无状态适配器设计** | ThemeManager 每次调用时从激活的 ThemeVariantConfig 读取，不缓存；切换主题只需替换配置对象，无需通知所有订阅者 |
+| **颜色 API 返回数字而非字符串** | Phaser Graphics API 接受十六进制数字（`0xff0000`），转换在 ThemeManager 内完成，渲染层不感知颜色格式 |
+
+## Adapter
+
+- **Role**: `themeState` — 视觉主题状态适配器（路径颜色、箭头风格、背景色）
+- **Provides**: `ThemeManager` 类（`getPathColor(pathIndex)`、`getArrowStyle()`、`canvasBgColor` 属性）
+- **Requires**: `phaser.aicomponent`、`theme_variant.aiconfig`（ThemeVariantConfig 数据源）
+- **Consumed by**: `path_renderer.aicomponent`（路径颜色）、`game_scene.aicomponent`（画布背景色）、`top_ui_bar.aicomponent` 等 UI 组件（主题配色）
+- **Integration point**: `src/game/scenes/GameUI/ThemeManager.ts` —— `game_scene` 在初始化时实例化，并传入渲染子系统
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）

package/skills/theme_state.aicomponent/manifest.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "atomId": "theme_state.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "state",
+  "mode": "fixed",
+  "label": { "zh": "主题状态管理器", "en": "Theme state manager" },
+  "tags": ["state", "theme", "color", "style", "arrow-style", "ui-text"],
+  "bindingRoles": ["themeManager"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/ThemeManager.ts": {
+        "source": "ref/ThemeManager.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "ThemeManager", "kind": "class", "location": "src/game/scenes/GameUI/ThemeManager.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "theme configuration provider: path colors, arrow style, UI text labels, canvas background color",
+    "layers": ["theme", "color-scheme", "style"]
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "themeManager": "ref/ThemeManager.ts"
+  }
+}

package/skills/theme_state.aicomponent/ref/ThemeManager.ts

@@ -0,0 +1,174 @@
+import * as Phaser from "phaser";
+import {
+  getCanvasBgColorOverride,
+  getUiBarBgColorOverride,
+} from "../../LevelDataManager";
+
+/** 主题配置接口 */
+export interface ThemeConfig {
+  id: string;
+  textureKey: string;
+  price: number;
+  bgColor: string; // 例如 "#FFFFFF"
+  arrowType: string; // 'draw' | 'snake' | 'snake2' | 'heart' | 'diamond' | 'wave' | 'striped' | 'caterpillar' | 'emoji'
+  arrowColor: string; // 例如 "#000000" 或 "Random"
+  arrowTextureKey: string;
+  previewScale?: number;
+  uiTextColor?: string; // UI 文本主颜色（时钟、进度等），默认 "#50526B"
+  uiLevelTextColor?: string; // 关卡标题颜色，默认 "#6471FA"
+}
+
+/** 默认主题列表 */
+const DEFAULT_THEMES: ThemeConfig[] = [
+  {
+    id: "black",
+    textureKey: "theme_black",
+    price: 0,
+    bgColor: "#FFFFFF",
+    arrowType: "draw",
+    arrowColor: "#000000",
+    arrowTextureKey: "none",
+    previewScale: 1,
+  },
+];
+
+/**
+ * 主题管理器（单例）。
+ * 负责从缓存中读取主题配置、维护当前主题和拥有状态。
+ * Game / ThemePanel 都应通过该单例来获取主题信息。
+ */
+export class ThemeManager {
+  private static _instance: ThemeManager | null = null;
+
+  static get instance(): ThemeManager {
+    if (!this._instance) {
+      this._instance = new ThemeManager();
+    }
+    return this._instance;
+  }
+
+  private themes: ThemeConfig[] = [];
+  private ownedIds = new Set<string>();
+  private currentId: string = "black";
+
+  private constructor() {}
+
+  /**
+   * 从指定场景的缓存中初始化主题配置（只会执行一次）。
+   * @param scene 当前场景
+   */
+  init(scene: Phaser.Scene) {
+    const raw = scene.cache.json.get("themes") as ThemeConfig[] | undefined;
+    if (Array.isArray(raw) && raw.length > 0) {
+      this.themes = raw;
+    } else if (this.themes.length === 0) {
+      this.themes = DEFAULT_THEMES;
+    }
+
+    // 价格为 0 的主题默认视为已拥有
+    if (this.ownedIds.size === 0) {
+      for (const t of this.themes) {
+        if (t.price === 0) this.ownedIds.add(t.id);
+      }
+    }
+
+    // 当前主题必须存在于列表中
+    if (!this.themes.find((t) => t.id === this.currentId)) {
+      this.currentId = this.themes[0]?.id ?? "black";
+    }
+  }
+
+  /**
+   * 从用户档案同步已解锁的主题和当前选中主题。
+   * @param themes 用户档案中的主题数据
+   */
+  syncFromProfile(themes: { unlockedIds: string[]; currentId: string }) {
+    if (!themes) return;
+    if (Array.isArray(themes.unlockedIds)) {
+      for (const id of themes.unlockedIds) {
+        this.ownedIds.add(id);
+      }
+    }
+
+    if (themes.currentId) {
+      this.currentId = themes.currentId;
+    }
+  }
+
+  /** 获取当前选中的主题配置 */
+  get currentTheme(): ThemeConfig {
+    const found = this.themes.find((t) => t.id === this.currentId);
+    if (found !== undefined) {
+      return found;
+    }
+
+    if (this.themes.length > 0) {
+      return this.themes[0]!;
+    }
+
+    return DEFAULT_THEMES[0]!;
+  }
+
+  /**
+   * 获取画布背景颜色（数值格式）。
+   * 优先使用变体配置的 canvasBgColor 覆盖。
+   */
+  getBackgroundColorNumber(): number {
+    const override = getCanvasBgColorOverride();
+    if (override !== undefined) {
+      return override;
+    }
+    return this.parseColorToNumber(this.currentTheme.bgColor, 0xffffff);
+  }
+
+  /**
+   * 获取 UI 菜单栏背景颜色（用于顶部和底部菜单栏）。
+   * 优先使用变体配置的 uiBarBgColor 覆盖。
+   */
+  getUiBarBackgroundColorNumber(): number {
+    const override = getUiBarBgColorOverride();
+    if (override !== undefined) {
+      return override;
+    }
+    return this.parseColorToNumber(this.currentTheme.bgColor, 0xffffff);
+  }
+
+  /**
+   * 获取 UI 关卡标题颜色。
+   * 如果主题未配置则返回默认值 "#6471FA"。
+   */
+  getUiLevelTextColor(): string {
+    return this.currentTheme.uiLevelTextColor || "#6471FA";
+  }
+
+  /**
+   * 获取固定箭头颜色（数值格式）。
+   */
+  getFixedArrowColorNumber(): number {
+    const spec = this.currentTheme.arrowColor;
+    return this.parseColorToNumber(spec, 0x000000);
+  }
+
+  /**
+   * 将颜色字符串解析为数值。
+   * 支持 "#RRGGBB" 和 "0xRRGGBB" 格式。
+   * @param spec 颜色字符串
+   * @param fallback 解析失败时的回退值
+   * @returns 颜色数值
+   */
+  private parseColorToNumber(
+    spec: string | undefined,
+    fallback: number,
+  ): number {
+    if (!spec) return fallback;
+    const s = spec.trim();
+    if (/^#?[0-9a-fA-F]{6}$/.test(s)) {
+      const hex = s.startsWith("#") ? s.slice(1) : s;
+      return parseInt(hex, 16);
+    }
+    if (/^0x[0-9a-fA-F]{6}$/.test(s)) {
+      return parseInt(s, 16);
+    }
+    return fallback;
+  }
+}

package/skills/theme_switcher_build.aicomponent/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: theme_switcher_build.aicomponent
+description: 主题切换构建辅助 skill。提供 src/theme/index.ts 入口文件模板，构建时由 builds.config.js 自动替换为当前激活的主题变体导入。
+triggers: 需要配置多主题构建的主题入口文件时触发。
+---
+
+# 主题切换构建器（Theme Switcher Build Helper）
+
+## 说明
+
+`src/theme/index.ts` 是主题系统的统一入口：
+
+- 运行时和其他模块通过 `import Theme from 'src/theme'` 获取当前主题配置
+- **构建时**由 `builds.config.js` 脚本自动修改此文件，切换到对应主题的导入路径
+- 每个主题目录放在 `src/theme/<主题名>/` 下（见 `theme_variant.aiconfig` skill）
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|-----|
+| `src/theme/index.ts` | `ref/theme-index.ts` | 主题入口文件（默认导入开发主题） |
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **构建时替换而非运行时切换** | 运行时 if/else 主题切换会把所有主题变体打包进产物，增大体积；构建时替换 import 路径使每个主题产物只包含自身变体 |
+| **单入口文件作为换点** | `src/theme/index.ts` 是唯一需要修改的文件；构建脚本只改一行 import，不触碰其他业务代码 |
+| **开发时默认 Dev 主题** | `import Theme from "./Dev"` 是开发时默认；构建脚本在 CI 中替换为对应变体，开发者本地无需操作 |
+
+## Adapter
+
+- **Role**: `themeSwitcherBuild` — 多主题构建入口文件（构建时脚本动态替换导入路径）
+- **Provides**: `src/theme/index.ts` 主题入口模板（`export default Theme`）
+- **Requires**: `playable_scripts_build.aicomponent`（builds.config.js 在构建时修改此文件）
+- **Consumed by**: 所有运行时读取主题配置的组件（`theme_state.aicomponent`、`level_state.aicomponent` 等通过 `import Theme from 'src/theme'` 使用）
+- **Integration point**: `src/theme/index.ts` —— 构建时被 `builds.config.js` 将 `./Dev` 替换为对应变体路径
+
+## Imports
+
+- `playable_scripts_build.aicomponent`（硬依赖：builds.config.js 自动修改此文件）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/theme/index.ts
+outputs:
+  - themeIndex: src/theme/index.ts theme entry file
+```
+
+## 文件内容
+
+```typescript
+// src/theme/index.ts
+// 注意: 构建时由 builds 脚本自动修改，不要手动改
+import Theme from "./Dev";
+export default Theme;
+```

package/skills/theme_switcher_build.aicomponent/manifest.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "atomId": "theme_switcher_build.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "build",
+  "mode": "fixed",
+  "label": { "zh": "主题切换构建器", "en": "Theme switcher build helper" },
+  "tags": ["theme", "build", "switcher", "variant", "multi-theme"],
+  "scaffold": {
+    "files": {
+      "src/theme/index.ts": {
+        "source": "ref/theme-index.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "buildPipeline", "pinAtomId": "playable_scripts_build.aicomponent", "edgeKind": "requires", "bindAs": "buildPipeline" }
+  ],
+  "exports": [
+    { "name": "default", "kind": "module-export", "location": "src/theme/index.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "build-time theme selector that re-exports a single theme variant as the active theme",
+    "layers": ["build-time-config", "theme-selection"],
+    "replaceable": ["active theme variant"]
+  },
+  "usageHints": [
+    "src/theme/index.ts 是当前激活主题的入口，构建时由 builds.config.js 自动修改",
+    "每个主题目录在 src/theme/<主题名>/ 下，包含 ThemeVariantConfig 实例",
+    "不要手动修改 index.ts，除非在本地开发测试特定主题"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "themeIndex": "ref/theme-index.ts"
+  }
+}

package/skills/theme_switcher_build.aicomponent/ref/theme-index.ts

@@ -0,0 +1,8 @@
+/**
+ * 当前激活的主题变体
+ *
+ * 注意: 这个文件会在构建时被 builds 脚本自动修改
+ * 请不要手动修改这个值，除非你在本地开发测试
+ */
+import Theme from "./Test One Mode";
+export default Theme;

package/skills/theme_variant.aiconfig/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: theme_variant.aiconfig
+description: 路径消除玩法的主题变体配置（ThemeVariantConfig）。定义一个完整的投放变体：包含关卡数据包引用、主题 ID、关卡模式、颜色覆盖等。每个 Remix 对应一个主题变体目录。
+triggers: 需要创建新的投放变体配置、定义主题颜色或关卡模式时触发。
+---
+
+# 主题变体配置（Theme Variant Config）
+
+## 说明
+
+每个主题变体是 `src/theme/<变体名>/` 下的一个目录，包含：
+
+- `index.ts`：导出 `ThemeVariantConfig` 实例
+- 关卡数据文件（`levels.json` 或多个 `levelN.json`）
+
+`ThemeVariantConfig` 字段：
+
+| 字段 | 说明 |
+|-----|-----|
+| `levels` | `RawLevelJson[]` 关卡数据数组 |
+| `name` | 变体显示名称 |
+| `themeId` | 使用的视觉主题 ID（`black` / `white` 等）|
+| `levelMode` | 关卡模式（0=闯关 / 1=简单 / 2=复杂 / 3=炸弹）|
+| `segmentsMode?` | 快速胜利模式（消除 N 条即胜利）|
+| `autoHint?` | 自动提示（默认 true）|
+| `canvasBgColor?` | 画布背景色覆盖（十六进制）|
+| `uiBarBgColor?` | UI 条背景色覆盖 |
+
+## Recipe
+
+```json
+{
+  "kind": "theme-config",
+  "params": {
+    "themeId": "black",
+    "levelMode": 1,
+    "canvasBgColor": "0x1a1a2e"
+  }
+}
+```
+
+## Result
+
+`src/theme/<变体名>/index.ts`（TypeScript 模块，默认导出 `ThemeVariantConfig`）
+
+## Binding
+
+被 `theme_switcher_build.aicomponent` 的 `src/theme/index.ts` 通过构建时替换引用。
+
+## Skill Definition
+
+```yaml
+tools:
+  - write_file
+inputs:
+  - schema: ThemeVariantConfig from arrow_path_data_format.aicomponent
+  - levelData: level_data_pack.aiconfig
+outputs:
+  - themeVariant: src/theme/<variant>/index.ts TypeScript module
+```
+
+## 示例
+
+```typescript
+// src/theme/MyTheme/index.ts
+import type { ThemeVariantConfig } from "../../game/levels/LevelTypes";
+import levels from "./levels.json";
+
+export default {
+  levels,
+  name: "MyTheme",
+  themeId: "black",
+  levelMode: 1,
+  autoHint: true,
+  shouldDrawEliminationTrail: true,
+  canvasBgColor: 0x1a1a2e,
+} as ThemeVariantConfig;
+```

package/skills/theme_variant.aiconfig/manifest.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": 1,
+  "atomId": "theme_variant.aiconfig",
+  "bundleType": "aiconfig",
+  "category": "config",
+  "mode": "parametric",
+  "label": { "zh": "主题变体配置", "en": "Theme variant config" },
+  "tags": ["config", "theme", "variant", "color", "level-mode", "style"],
+  "bindingRoles": ["themeVariantConfig"],
+  "generation": {
+    "kind": "theme-config",
+    "schema": "ThemeVariantConfig",
+    "params": {
+      "themeId": "black",
+      "levelMode": 1,
+      "canvasBgColor": "0x1a1a2e",
+      "uiBarBgColor": "0x16213e"
+    }
+  },
+  "result": {
+    "outputFile": "index.ts",
+    "format": "typescript",
+    "constraints": { "schema": "ThemeVariantConfig" }
+  },
+  "binding": {
+    "role": "themeVariantConfig",
+    "target": "src/theme/<variant>/index.ts",
+    "type": "typescript-module-reference",
+    "constraints": { "schema": "ThemeVariantConfig", "defaultExport": true }
+  },
+  "imports": [
+    { "slot": "dataFormat",   "pinAtomId": "arrow_path_data_format.aicomponent", "edgeKind": "requires", "bindAs": "dataFormat" },
+    { "slot": "levelDataPack","pinAtomId": "level_data_pack.aiconfig",           "edgeKind": "requires", "bindAs": "levelDataPack" }
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "exampleTheme": "ref/ExampleTheme/index.ts"
+  }
+}

package/skills/theme_variant.aiconfig/ref/ExampleTheme/index.ts

@@ -0,0 +1,16 @@
+import type { ThemeVariantConfig } from "../../game/levels/LevelTypes";
+
+// 导入简单关卡（开发模式：1关通过）
+import level from "./levelEasy.json";
+
+export default {
+  // 游戏配置
+  config: {
+    levels: [level],
+    name: "EasyMode",
+    themeId: "black",
+    levelMode: 1, // 简单关卡模式：使用 level1 (10x8)
+    autoHint: true,
+    shouldDrawEliminationTrail: true,
+  } as ThemeVariantConfig,
+};

package/skills/theme_variant.aiconfig/ref/ExampleTheme/levelEasy.json

@@ -0,0 +1,141 @@
+{
+    "name": 1,
+    "row": 10,
+    "col": 8,
+    "arrows": [
+        [
+            [
+                7,
+                9
+            ],
+            [
+                6,
+                9
+            ],
+            [
+                6,
+                8
+            ],
+            [
+                7,
+                8
+            ],
+            [
+                7,
+                7
+            ],
+            [
+                6,
+                7
+            ],
+            [
+                6,
+                1
+            ],
+            [
+                0,
+                1
+            ],
+            [
+                0,
+                9
+            ],
+            [
+                2,
+                9
+            ],
+            [
+                2,
+                8
+            ],
+            [
+                3,
+                8
+            ],
+            [
+                3,
+                9
+            ]
+        ],
+        [
+            [
+                2,
+                7
+            ],
+            [
+                2,
+                2
+            ],
+            [
+                1,
+                2
+            ],
+            [
+                1,
+                7
+            ]
+        ],
+        [
+            [
+                3,
+                7
+            ],
+            [
+                4,
+                7
+            ],
+            [
+                4,
+                9
+            ],
+            [
+                5,
+                9
+            ],
+            [
+                5,
+                6
+            ],
+            [
+                3,
+                6
+            ],
+            [
+                3,
+                2
+            ],
+            [
+                4,
+                2
+            ],
+            [
+                4,
+                5
+            ],
+            [
+                5,
+                5
+            ],
+            [
+                5,
+                2
+            ]
+        ],
+        [
+            [
+                0,
+                0
+            ],
+            [
+                7,
+                0
+            ],
+            [
+                7,
+                6
+            ]
+        ]
+    ],
+    "levelTime": 120,
+    "id": 1
+}