@playcraft/skills 0.0.2

package/skills/level_lifecycle.aicomponent/ref/LevelLifecycle.ts

@@ -0,0 +1,235 @@
+import * as Phaser from "phaser";
+import { GameOverPanel } from "./GameOverPanel";
+import { LevelManager } from "../../levels/LevelManager";
+import {
+  AUTO_NEXT_LEVEL_ON_WIN,
+  CHALLENGE_LEVEL_MODE,
+} from "../../DebugConfig";
+import { clearActiveRunContext } from "../../run/RunContextRuntime";
+import { safePlaySound } from "../../utils/SoundUtils";
+
+/**
+ * 描述 LevelLifecycle 从 Game 场景中所需内容的最小接口。
+ * 避免模块级别的循环导入。
+ */
+export interface LevelLifecycleGameRef extends Phaser.Scene {
+  level: any; // ParsedLevel | null
+  currentLives: number;
+  maxLives: number;
+  topUI: any; // GameTopUI | null
+  gameOverPanel: GameOverPanel | undefined;
+  isInputLocked: boolean;
+  isTestMode: boolean;
+  runFlags: { kind: string; affectsProgression: boolean };
+  settings: any;
+  winProcessing: boolean;
+  removedPaths: Set<number>;
+  nomoveHintSprite: Phaser.GameObjects.Image | null;
+  nomoveHintTween: Phaser.Tweens.Tween | null;
+}
+
+/**
+ * 关卡生命周期管理器。
+ * 负责处理生命值、游戏结束、胜利、自动进入下一关等逻辑。
+ */
+export class LevelLifecycle {
+  private scene: LevelLifecycleGameRef;
+
+  constructor(scene: LevelLifecycleGameRef) {
+    this.scene = scene;
+  }
+
+  // ── 扣除生命值 ──
+
+  /** 扣除一条生命值。如果生命值归零，触发游戏结束流程。 */
+  loseLife(): void {
+    const s = this.scene;
+    if (s.currentLives <= 0) {
+      return;
+    }
+
+    s.currentLives = Math.max(0, s.currentLives - 1);
+    if (s.topUI) {
+      s.topUI.setLives(s.currentLives);
+    }
+
+    if (s.currentLives <= 0) {
+      // 失去最后一条命后，先播放提示效果
+      safePlaySound(s, "fail", { volume: 2.0 });
+      // 然后延迟显示面板，锁定输入以防误触
+      s.isInputLocked = true;
+      s.time.delayedCall(400, () => {
+        this.handleOutOfLives();
+        s.isInputLocked = false;
+      });
+    } else {
+      safePlaySound(s, "mistake", { volume: 2.0 });
+    }
+  }
+
+  // ── 处理生命值耗尽 ──
+
+  /** 生命值耗尽时的处理逻辑，延迟后显示游戏结束面板。 */
+  private handleOutOfLives(): void {
+    const s = this.scene;
+    if (s.gameOverPanel) {
+      return;
+    }
+
+    s.isInputLocked = true;
+
+    s.time.delayedCall(300, () => {
+      this.showGameOverPanel();
+      s.isInputLocked = false;
+    });
+  }
+
+  // ── 显示游戏结束面板 ──
+
+  /** 显示失败类型的游戏结束面板。 */
+  showGameOverPanel(): void {
+    const s = this.scene;
+    if (s.gameOverPanel) {
+      return;
+    }
+
+    s.gameOverPanel = new GameOverPanel(s as any, {
+      type: "lose",
+      onClose: () => {
+        s.gameOverPanel = undefined;
+        if (!s.runFlags.affectsProgression) {
+          clearActiveRunContext();
+        }
+        if (s.isTestMode) {
+          s.scene.start("Editor");
+        } else {
+          s.scene.start("Game");
+        }
+      },
+    });
+  }
+
+  // ── 显示挑战模式胜利面板 ──
+
+  /** 显示挑战模式的胜利面板，并停止背景音乐。 */
+  showChallengeWinPanel(): void {
+    const s = this.scene;
+    if (s.gameOverPanel) {
+      return;
+    }
+
+    s.settings.stopBgm();
+
+    s.gameOverPanel = new GameOverPanel(s as any, {
+      type: "win",
+      onClose: () => {
+        s.gameOverPanel = undefined;
+      },
+    });
+  }
+
+  // ── 处理关卡通关 ──
+
+  /** 处理关卡通关逻辑，防止重复处理。 */
+  handleLevelSuccess(): void {
+    const s = this.scene;
+    if (s.winProcessing) {
+      return;
+    }
+
+    s.winProcessing = true;
+    void this.processWinAndShowSuccessPanel().finally(() => {
+      s.winProcessing = false;
+    });
+  }
+
+  // ── 处理胜利并显示成功面板 ──
+
+  /** 异步处理胜利逻辑：测试模式返回编辑器，自动进入下一关或显示胜利面板。 */
+  private async processWinAndShowSuccessPanel(): Promise<void> {
+    const s = this.scene;
+
+    // 测试/预览模式：胜利后返回编辑器
+    if (s.isTestMode) {
+      console.log("[Game] 预览模式胜利 - 返回编辑器");
+      clearActiveRunContext();
+      s.scene.start("Editor");
+      return;
+    }
+
+    // 如果启用了自动进入下一关，跳过显示面板
+    if (AUTO_NEXT_LEVEL_ON_WIN) {
+      // 挑战模式：改为显示胜利面板
+      if (CHALLENGE_LEVEL_MODE !== 0) {
+        this.showChallengeWinPanel();
+        return;
+      }
+
+      this.autoProgressToNextLevel();
+      return;
+    }
+
+    // 挑战模式：显示胜利面板
+    if (CHALLENGE_LEVEL_MODE !== 0) {
+      this.showChallengeWinPanel();
+      return;
+    }
+  }
+
+  // ── 自动进入下一关 ──
+
+  /** 自动进入下一关，重置生命值并重启场景。 */
+  autoProgressToNextLevel(): void {
+    const s = this.scene;
+    const mgr = LevelManager.instance;
+    const nextIndex = mgr.getNextIndex();
+
+    mgr.setCurrentIndex(nextIndex);
+    s.currentLives = s.maxLives;
+    s.scene.restart();
+  }
+
+  // ── 播放危险闪烁帧 ──
+
+  /** 播放危险闪烁帧效果（红色边框闪烁），用于错误操作时的视觉反馈。 */
+  playDangerFrame(): void {
+    const s = this.scene;
+    const sprite = s.nomoveHintSprite;
+    if (!sprite) return;
+
+    if (s.nomoveHintTween) {
+      s.nomoveHintTween.stop();
+      s.nomoveHintTween = null;
+    }
+
+    const cam = s.cameras.main;
+    const centerX = cam.width / 2;
+    const centerY = cam.height / 2;
+    sprite.setPosition(centerX, centerY);
+    sprite.setDisplaySize(cam.width, cam.height);
+
+    sprite.setAlpha(0);
+    sprite.setVisible(true);
+
+    s.nomoveHintTween = s.tweens.add({
+      targets: sprite,
+      alpha: { from: 0, to: 1 },
+      duration: 150,
+      ease: "Linear",
+      yoyo: true,
+      repeat: 0,
+      onComplete: () => {
+        sprite.setVisible(false);
+        sprite.setAlpha(0);
+        s.nomoveHintTween = null;
+      },
+    });
+  }
+
+  // ── 处理超时 ──
+
+  /** 处理计时器超时，显示游戏结束面板。 */
+  handleTimeOut(): void {
+    this.showGameOverPanel();
+  }
+}

package/skills/level_solvability_validator.aivalidator/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: level_solvability_validator.aivalidator
+description: 关卡可解性验证器。验证箭头推出三消关卡数据的正确性：无格子冲突、无推出阻挡（或存在合法序列）、颜色分组约束、篮子不溢出。纯逻辑，可在构建时或运行时调用。
+triggers: 需要验证关卡数据正确性、检查可解性、调试关卡设计时触发。
+---
+
+# 关卡可解性验证器（Level Solvability Validator）
+
+## 说明
+
+验证 `arrow_pick_match` 玩法的关卡数据，确保：
+
+1. **无格子冲突**：任意两条路径不共享格子
+2. **推出可达**：每条路径到边界方向上无其他路径占据（或存在合法序列）
+3. **颜色约束**：每种颜色恰好 matchCount(3) 条路径
+4. **篮子不溢出**：存在一个推出顺序使篮子永不超过 capacity
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `src/game/logic/LevelValidator.ts` | `ref/LevelValidator.ts` | 验证器 |
+
+## 关键接口
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+class LevelValidator {
+  static validate(level: ParsedLevel, matchCount?: number, trayCapacity?: number): ValidationResult;
+  static checkNoOverlap(level: ParsedLevel): string[];
+  static checkAllUnblocked(level: ParsedLevel): string[];
+  static checkColorConstraint(level: ParsedLevel, matchCount: number): string[];
+  static checkSolvability(level: ParsedLevel, matchCount: number, trayCapacity: number): string[];
+}
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **静态方法类** | 验证器是无状态纯函数，不需要实例化；静态方法使调用更简洁，且允许独立调用单项检查 |
+| **与 level_data_validator 分离** | `level_data_validator` 检查格式正确性（适用所有玩法），本 skill 检查 arrow_pick_match 的玩法可解性（特定玩法约束）；分离后非此玩法的 Remix 不需要加载本 skill |
+| **支持构建时和运行时两个调用点** | 构建时批量验证关卡包；运行时在加载关卡时即时校验；同一个 `validate()` 函数满足两个场景 |
+
+## Adapter
+
+- **Role**: `levelSolvabilityValidator` — Arrow pick-match 玩法关卡可解性验证器
+- **Provides**: `LevelValidator` 类（`validate()`、`checkNoOverlap()`、`checkAllUnblocked()`、`checkColorConstraint()`、`checkSolvability()`），`ValidationResult` 类型
+- **Requires**: `arrow_path_data_format.aicomponent`（ParsedLevel 类型）
+- **Consumed by**: `gameplay_unit_test.aivalidator`（集成可解性测试）；Agent 在生成新关卡数据后调用验证
+- **Integration point**: `src/game/logic/LevelValidator.ts` —— 构建时批量验证 `LEVELS` 数组，或运行时关卡加载前验证
+
+## Imports
+
+- `arrow_path_data_format.aicomponent`（硬依赖：ParsedLevel 类型）
+
+## 使用方式
+
+```typescript
+// 构建时验证
+import { LevelValidator } from "./logic/LevelValidator";
+for (const raw of LEVELS) {
+  const level = parseLevelJson(raw);
+  const result = LevelValidator.validate(level);
+  if (!result.valid) {
+    console.error(`Level ${level.index} invalid:`, result.errors);
+  }
+}
+```

package/skills/level_solvability_validator.aivalidator/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "atomId": "level_solvability_validator.aivalidator",
+  "bundleType": "aivalidator",
+  "category": "validator",
+  "mode": "fixed",
+  "label": {
+    "zh": "关卡可解性验证器",
+    "en": "Level solvability validator"
+  },
+  "tags": ["logic", "validator", "level", "solvability", "constraint", "debug", "tool"],
+  "bindingRoles": ["levelValidator"],
+  "imports": [],
+  "binding": {
+    "role": "levelValidator",
+    "target": "src/game/logic/LevelValidator.ts",
+    "type": "code-module-reference"
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "ref": ["ref/LevelValidator.ts"]
+  }
+}

package/skills/level_solvability_validator.aivalidator/ref/LevelValidator.ts

@@ -0,0 +1,186 @@
+/**
+ * 关卡可解性验证器
+ * 验证 arrow_pick_match 关卡数据的正确性和可解性
+ */
+
+interface GridPoint { x: number; y: number; }
+interface LevelPath {
+  points: GridPoint[];
+  head: GridPoint;
+  direction: string;
+  color: string;
+  indices: number[];
+  pathIndex: number;
+}
+interface ParsedLevel {
+  rows: number;
+  cols: number;
+  paths: LevelPath[];
+  trayCapacity: number;
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export class LevelValidator {
+  /**
+   * 完整验证
+   */
+  static validate(
+    level: ParsedLevel,
+    matchCount: number = 3,
+    trayCapacity?: number,
+  ): ValidationResult {
+    const cap = trayCapacity ?? level.trayCapacity ?? 7;
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    errors.push(...LevelValidator.checkNoOverlap(level));
+    errors.push(...LevelValidator.checkColorConstraint(level, matchCount));
+    warnings.push(...LevelValidator.checkAllUnblocked(level));
+    errors.push(...LevelValidator.checkSolvability(level, matchCount, cap));
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+
+  /**
+   * 检查无格子冲突
+   */
+  static checkNoOverlap(level: ParsedLevel): string[] {
+    const errors: string[] = [];
+    const occupied = new Map<number, number>(); // index → pathIndex
+
+    for (const path of level.paths) {
+      for (const idx of path.indices) {
+        if (occupied.has(idx)) {
+          const col = idx % level.cols;
+          const row = Math.floor(idx / level.cols);
+          errors.push(
+            `Cell (${col},${row}) occupied by both path ${occupied.get(idx)} and path ${path.pathIndex}`,
+          );
+        } else {
+          occupied.set(idx, path.pathIndex);
+        }
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * 检查所有路径是否可无阻挡推出
+   */
+  static checkAllUnblocked(level: ParsedLevel): string[] {
+    const warnings: string[] = [];
+
+    // 构建全局占据集
+    const occupied = new Set<string>();
+    for (const path of level.paths) {
+      for (const pt of path.points) {
+        occupied.add(`${pt.x},${pt.y}`);
+      }
+    }
+
+    for (const path of level.paths) {
+      const { dx, dy } = LevelValidator.dirToDelta(path.direction);
+      if (dx === 0 && dy === 0) continue;
+
+      let cx = path.head.x;
+      let cy = path.head.y;
+      let blocked = false;
+
+      for (let step = 0; step < Math.max(level.rows, level.cols) + 1; step++) {
+        cx += dx;
+        cy += dy;
+        if (cx < 0 || cy < 0 || cx >= level.cols || cy >= level.rows) break;
+
+        const key = `${cx},${cy}`;
+        // 检查是否被其他路径占据（排除自己的点）
+        const isSelf = path.points.some(p => p.x === cx && p.y === cy);
+        if (!isSelf && occupied.has(key)) {
+          warnings.push(`Path ${path.pathIndex} (${path.color}) is blocked at (${cx},${cy})`);
+          blocked = true;
+          break;
+        }
+      }
+    }
+
+    return warnings;
+  }
+
+  /**
+   * 检查颜色分组约束
+   */
+  static checkColorConstraint(level: ParsedLevel, matchCount: number): string[] {
+    const errors: string[] = [];
+    const colorCounts = new Map<string, number>();
+
+    for (const path of level.paths) {
+      colorCounts.set(path.color, (colorCounts.get(path.color) || 0) + 1);
+    }
+
+    for (const [color, count] of colorCounts) {
+      if (count % matchCount !== 0) {
+        errors.push(
+          `Color "${color}" has ${count} paths, not a multiple of matchCount(${matchCount})`,
+        );
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * 检查是否存在合法推出序列（贪心验证：同色连续推）
+   */
+  static checkSolvability(
+    level: ParsedLevel,
+    matchCount: number,
+    trayCapacity: number,
+  ): string[] {
+    const errors: string[] = [];
+
+    // 按颜色分组
+    const colorGroups = new Map<string, number[]>();
+    for (const path of level.paths) {
+      const list = colorGroups.get(path.color) || [];
+      list.push(path.pathIndex);
+      colorGroups.set(path.color, list);
+    }
+
+    // 贪心策略：逐组推出
+    let traySize = 0;
+    for (const [color, pathIndices] of colorGroups) {
+      // 推出该组所有路径
+      traySize += pathIndices.length;
+      // 消除
+      const matches = Math.floor(pathIndices.length / matchCount);
+      traySize -= matches * matchCount;
+
+      if (traySize > trayCapacity) {
+        errors.push(
+          `Greedy strategy overflows tray at color "${color}" (tray would have ${traySize}/${trayCapacity})`,
+        );
+      }
+    }
+
+    return errors;
+  }
+
+  private static dirToDelta(direction: string): { dx: number; dy: number } {
+    switch (direction) {
+      case "left":  return { dx: -1, dy: 0 };
+      case "right": return { dx: 1, dy: 0 };
+      case "up":    return { dx: 0, dy: -1 };
+      case "down":  return { dx: 0, dy: 1 };
+      default:      return { dx: 0, dy: 0 };
+    }
+  }
+}

package/skills/level_state.aicomponent/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: level_state.aicomponent
+description: 关卡进度状态管理器。管理当前关卡索引、加载并解析下一关数据、处理关卡循环和随机播放逻辑。
+triggers: 需要管理关卡进度、加载关卡数据或实现进关逻辑时触发。
+---
+
+# 关卡进度状态（Level Progress State）
+
+## 说明
+
+`LevelManager` 管理关卡流转：
+
+- 持有关卡数据列表（来自主题配置）
+- 跟踪当前关卡索引
+- `getCurrentLevel()`：返回当前关卡 ParsedLevel
+- `nextLevel()`：进入下一关（支持循环/随机）
+
+## Scaffold
+
+| 目标路径 | 来源 |
+|---------|-----|
+| `src/game/levels/LevelManager.ts` | `ref/LevelManager.ts` |
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/levels/LevelManager.ts
+outputs:
+  - levelManager: LevelManager class
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **状态与渲染分离** | 关卡进度（当前索引、循环模式）与游戏渲染逻辑完全无关；LevelManager 作为纯状态机，GameScene 作为协调器，职责边界清晰 |
+| **支持循环/随机两种进关模式** | 试玩广告的关卡通常数量有限，需要支持循环；随机模式增加重玩多样性；两种模式由 ThemeVariantConfig 的配置决定 |
+| **关卡数据来自主题配置** | 不同 Remix 变体可以有完全不同的关卡集合；LevelManager 从 ThemeVariantConfig.levels 读取，关卡数据随主题一起替换 |
+
+## Adapter
+
+- **Role**: `levelProgressState` — 关卡进度状态机（当前关卡索引 + 进关逻辑）
+- **Provides**: `LevelManager` 类（`getCurrentLevel()`、`nextLevel()`、`reset()`）
+- **Requires**: `phaser.aicomponent`、`arrow_path_data_format.aicomponent`（ParsedLevel 类型 + parseLevelJson）
+- **Consumed by**: `level_lifecycle.aicomponent`（调用 `nextLevel()` 推进进度）、`game_scene.aicomponent`（实例化并持有 LevelManager）
+- **Integration point**: `src/game/levels/LevelManager.ts` —— `game_scene` 在 `create()` 中 `new LevelManager(themeConfig.levels)`
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+- `arrow_path_data_format.aicomponent`（硬依赖：ParsedLevel 类型 + parseLevelJson）

package/skills/level_state.aicomponent/manifest.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "atomId": "level_state.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "state",
+  "mode": "fixed",
+  "label": { "zh": "关卡进度状态", "en": "Level progress state" },
+  "tags": ["state", "level", "progress", "level-manager", "level-data"],
+  "bindingRoles": ["levelProgress"],
+  "scaffold": {
+    "files": {
+      "src/game/levels/LevelManager.ts": {
+        "source": "ref/LevelManager.ts",
+        "mode": "full",
+        "weight": 10
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",    "pinAtomId": "phaser.aicomponent",                    "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "levelData", "pinAtomId": "arrow_path_data_format.aicomponent",    "edgeKind": "requires", "bindAs": "levelData" }
+  ],
+  "exports": [
+    { "name": "LevelManager", "kind": "class", "location": "src/game/levels/LevelManager.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "level progression state: tracks current level index, parses next level data, handles level cycling and shuffle",
+    "layers": ["state-management", "progression", "level-data-access"]
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "levelManager": "ref/LevelManager.ts"
+  }
+}

package/skills/level_state.aicomponent/ref/LevelDataManager.ts

@@ -0,0 +1,26 @@
+export class LevelManager {
+  private static _instance: LevelManager | undefined;
+
+  static get instance(): LevelManager {
+    if (!LevelManager._instance) {
+      LevelManager._instance = new LevelManager();
+    }
+    return LevelManager._instance;
+  }
+
+  private readonly minIndex: number = 1;
+  private currentIndex = 1;
+
+  getCurrentIndex(): number {
+    return this.currentIndex;
+  }
+
+  setCurrentIndex(index: number): void {
+    const clamped = Math.max(this.minIndex, Math.floor(index || 0));
+    this.currentIndex = clamped;
+  }
+
+  getNextIndex(): number {
+    return this.currentIndex + 1;
+  }
+}

package/skills/level_state.aicomponent/ref/LevelManager.ts

@@ -0,0 +1,26 @@
+export class LevelManager {
+  private static _instance: LevelManager | undefined;
+
+  static get instance(): LevelManager {
+    if (!LevelManager._instance) {
+      LevelManager._instance = new LevelManager();
+    }
+    return LevelManager._instance;
+  }
+
+  private readonly minIndex: number = 1;
+  private currentIndex = 1;
+
+  getCurrentIndex(): number {
+    return this.currentIndex;
+  }
+
+  setCurrentIndex(index: number): void {
+    const clamped = Math.max(this.minIndex, Math.floor(index || 0));
+    this.currentIndex = clamped;
+  }
+
+  getNextIndex(): number {
+    return this.currentIndex + 1;
+  }
+}