@playcraft/skills 0.0.2

package/skills/top_ui_bar.aicomponent/ref/GameTopUI.ts

@@ -0,0 +1,229 @@
+import * as Phaser from "phaser";
+import { computeUiLayout } from "../../utils/UiLayout";
+import {
+  ENABLE_GAME_TOP_PROGRESS_DISPLAY,
+  GAME_UI_BAR_BACKGROUND_COLOR,
+} from "../../DebugConfig";
+import { ThemeManager } from "./ThemeManager";
+import { HeartDisplay } from "./HeartDisplay";
+import { CountdownDisplay } from "./CountdownDisplay";
+import { ProgressDisplay } from "./ProgressDisplay";
+
+/** 顶部UI栏的设计高度常量 */
+export const GAME_TOP_UI_BAR_HEIGHT = 150;
+
+/** 顶部UI的配置选项 */
+export interface GameTopUIConfig {
+  levelText: string;
+  initialLives: number;
+  maxLives: number;
+  initialTimeSeconds: number;
+  onTimeout?: () => void;
+}
+
+/**
+ * 游戏顶部UI组件。
+ * 包含关卡标题、生命值显示、倒计时器和进度显示。
+ * 布局为上下垂直结构，顺序：生命值 → 关卡标题 → 倒计时 → 进度。
+ */
+export class GameTopUI extends Phaser.GameObjects.Container {
+  private levelLabel!: Phaser.GameObjects.Text;
+  private heartDisplay!: HeartDisplay;
+  private countdownDisplay!: CountdownDisplay;
+  private progressDisplay?: ProgressDisplay;
+
+  constructor(scene: Phaser.Scene, config: GameTopUIConfig) {
+    super(scene);
+    scene.add.existing(this);
+    // Ensure top UI renders above the board container
+    this.setDepth(500);
+
+    const layout = computeUiLayout(scene);
+    const { width, height, uiScale, vScale } = layout;
+
+    // 获取栏背景颜色：优先使用配置，否则使用主题颜色
+    const themeBarColor = ThemeManager.instance.getUiBarBackgroundColorNumber();
+    const barBgColor =
+      GAME_UI_BAR_BACKGROUND_COLOR >= 0
+        ? GAME_UI_BAR_BACKGROUND_COLOR
+        : themeBarColor;
+
+    const barHeight = GAME_TOP_UI_BAR_HEIGHT * vScale;
+    const bg = scene.add.rectangle(
+      width / 2,
+      barHeight / 2,
+      width,
+      barHeight,
+      barBgColor,
+    );
+    this.add(bg);
+
+    // --- Vertical layout: top-to-bottom ---
+    // All vertical sizes use vScale so total height fits within barHeight.
+    // Horizontal sizes (spacing, widths) still use uiScale for proper proportions.
+    const rowGap = 6 * vScale;
+    const topPadding = 10 * vScale;
+    let currentY = topPadding;
+
+    // --- Row 1: Hearts (lives) ---
+    const heartSpacing = 45 * uiScale;
+    const heartsGroupWidth = config.maxLives * heartSpacing;
+    const heartStartX = (width - heartsGroupWidth) / 2 + heartSpacing / 2;
+    const heartDrawSize = 16 * uiScale;
+    const heartRowHeight = 30 * vScale;
+    const heartsY = currentY + heartRowHeight / 2;
+
+    this.heartDisplay = new HeartDisplay(scene, this, {
+      startX: heartStartX,
+      y: heartsY,
+      spacing: heartSpacing,
+      drawSize: heartDrawSize,
+      maxLives: config.maxLives,
+      initialLives: config.initialLives,
+    });
+    currentY += heartRowHeight + rowGap;
+
+    // --- Row 2: Level label ---
+    const hasLevelText = config.levelText && config.levelText.trim().length > 0;
+    const levelFontSize = 28 * uiScale;
+    const levelRowHeight = 30 * vScale;
+
+    if (hasLevelText) {
+      this.levelLabel = scene.add
+        .text(width / 2, currentY + levelRowHeight / 2, config.levelText, {
+          fontFamily: "Poppins",
+          fontSize: `${levelFontSize}px`,
+          color: ThemeManager.instance.getUiLevelTextColor(),
+          fontStyle: "bold",
+        })
+        .setOrigin(0.5, 0.5);
+      this.add(this.levelLabel);
+      currentY += levelRowHeight + rowGap;
+    } else {
+      this.levelLabel = scene.add
+        .text(0, 0, "", {
+          fontFamily: "Poppins",
+          fontSize: `${levelFontSize}px`,
+          color: ThemeManager.instance.getUiLevelTextColor(),
+          fontStyle: "bold",
+        })
+        .setOrigin(0.5, 0.5)
+        .setVisible(false);
+      this.add(this.levelLabel);
+      // No row height added when hidden
+    }
+
+    // --- Row 3: Countdown (icon + digits) ---
+    const timeIconSize = 36 * uiScale;
+    const iconTextGap = 8 * uiScale;
+    const digitWidth = 20 * uiScale;
+    const digitHeight = 36 * uiScale;
+    const digitSpacing = 4 * uiScale;
+    const colonWidth = 10 * uiScale;
+    const timerDisplayWidth = digitWidth * 4 + colonWidth + digitSpacing * 4;
+    const timerGroupWidth = timeIconSize + iconTextGap + timerDisplayWidth;
+    const timerRowHeight = 36 * vScale;
+    const timerY = currentY + timerRowHeight / 2;
+
+    // Center the timer group horizontally
+    const timerGroupStartX = (width - timerGroupWidth) / 2;
+    const timeIconX = timerGroupStartX + timeIconSize / 2;
+
+    const timeIcon = scene.add.image(timeIconX, timerY, "time");
+    timeIcon.setScale(uiScale * 0.2).setOrigin(0.5);
+    this.add(timeIcon);
+
+    this.countdownDisplay = new CountdownDisplay(scene, this, {
+      xLeft: timeIconX + timeIconSize / 2 + iconTextGap,
+      y: timerY + vScale - 1,
+      digitWidth,
+      digitHeight,
+      digitSpacing,
+      colonWidth,
+      totalSeconds: config.initialTimeSeconds,
+      onTimeout: config.onTimeout,
+    });
+    this.countdownDisplay.updateDisplay();
+    currentY += timerRowHeight + rowGap;
+
+    // --- Row 4: Progress display (controlled by config) ---
+    if (ENABLE_GAME_TOP_PROGRESS_DISPLAY) {
+      const progressDigitWidth = 18 * uiScale;
+      const progressDigitHeight = 36 * uiScale;
+      const progressDigitSpacing = 3 * uiScale;
+      const percentWidth = 14 * uiScale;
+      // Approximate total width: 3 digits + percent sign + spacing
+      const progressTotalWidth =
+        progressDigitWidth * 3 + progressDigitSpacing * 3 + percentWidth;
+      const progressStartX = (width - progressTotalWidth) / 2;
+      const progressRowHeight = 36 * vScale;
+      const progressY = currentY + progressRowHeight / 2;
+
+      this.progressDisplay = new ProgressDisplay(scene, this, {
+        xLeft: progressStartX,
+        y: progressY + vScale,
+        digitWidth: progressDigitWidth,
+        digitHeight: progressDigitHeight,
+        digitSpacing: progressDigitSpacing,
+        percentWidth,
+      });
+
+      // Initialize to 0%
+      this.progressDisplay.updateProgress(0, 0);
+      currentY += progressRowHeight + rowGap;
+    }
+  }
+
+  // --- 委托公共API（为外部调用者保持相同接口） ---
+
+  /**
+   * 设置当前生命值。
+   * @param lives 生命值数量
+   */
+  public setLives(lives: number): void {
+    this.heartDisplay.setLives(lives);
+  }
+
+  /**
+   * 更新计时器。
+   * @param deltaMs 帧间隔时间（毫秒）
+   * @param nowMs 当前时间戳（毫秒，可选）
+   */
+  public updateTimer(deltaMs: number, nowMs?: number): void {
+    this.countdownDisplay.updateTimer(deltaMs, nowMs);
+  }
+
+  /**
+   * 为倒计时添加额外时间。
+   * @param seconds 要添加的秒数
+   */
+  public addTime(seconds: number): void {
+    this.countdownDisplay.addTime(seconds);
+  }
+
+  /** 启动计时器 */
+  public startTimer(): void {
+    this.countdownDisplay.startTimer();
+  }
+
+  /** 停止计时器 */
+  public stopTimer(): void {
+    this.countdownDisplay.stopTimer();
+  }
+
+  /** 获取已经过的秒数 */
+  public getElapsedSeconds(): number {
+    return this.countdownDisplay.getElapsedSeconds();
+  }
+
+  /**
+   * 更新进度显示。
+   * @param removed 已消除的路径数
+   * @param total 总路径数
+   */
+  public updateProgress(removed: number, total: number): void {
+    if (this.progressDisplay) {
+      this.progressDisplay.updateProgress(removed, total);
+    }
+  }
+}

package/skills/tower_defence.aigameplay/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: tower_defence.aigameplay
+description: 经典塔防核心玩法封包 - 波次敌人、格子放塔、自动攻击、金币经济的 PGS 实现
+triggers: 塔防,tower defence,tower defense,防御,波次,waves,enemy,敌人,炮塔,tower,strategy,策略,grid,格子
+---
+
+# tower_defence.aigameplay
+
+经典塔防核心玩法封包。实现标准塔防玩法的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer。敌人沿预设路径前进，玩家在路径旁放置防御塔自动攻击，消灭敌人获金币，敌人到达终点扣生命。全波次通关则胜利，生命归零则失败。
+
+## Recipe
+
+- **玩法类型**：tower_defence（经典塔防）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板
+- **核心规则**：
+  - `initialLives`: 20（初始生命值）
+  - `initialGold`: 150（初始金币）
+  - `tickRateMs`: 100（游戏逻辑帧率，每帧 100ms）
+  - `towerTypes`: `["arrow", "cannon", "magic"]`（弓箭塔/炮塔/魔法塔）
+  - `enemyTypes`: `["basic", "fast", "armored", "boss"]`（普通/快速/装甲/Boss）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出所有必需函数
+  4. 路径表示：`path` 是格子坐标序列 `{x, y}[]`，敌人维护 `pathIndex`（当前目标路径点索引）和 `progress`（到下一路径点的进度 0~1）
+  5. 塔攻击：每次 tick 检查攻击冷却，范围内有敌人则攻击
+  6. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+- **塔属性**：
+  - `arrow`：低伤害，高攻速，低造价，攻击单体
+  - `cannon`：高伤害，低攻速，高造价，范围攻击
+  - `magic`：中等伤害，减速效果，对装甲有额外伤害
+- **敌人属性**：
+  - `basic`：标准属性
+  - `fast`：速度 2x，血量 0.5x
+  - `armored`：速度 0.7x，血量 3x，物理伤害减半
+  - `boss`：速度 0.5x，血量 10x，每波最多 1 个
+- **可 fork 变体**：
+  - 经济难度调整：修改 `initialGold` 和塔造价
+  - 多路径地图：path 改为多条，敌人随机选路
+  - 英雄技能：玩家可放置限定次数的超级技能（冰冻/轰炸）
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：游戏循环驱动渲染
+
+```ts
+// ✅ 正确做法：固定 tick 循环
+function gameLoop(deltaMs: number) {
+  // Step 1: tick 游戏逻辑（敌人移动 + 塔攻击 + 波次生成）
+  const prevState = state;
+  state = tickGameLoop(state, deltaMs);
+
+  // Step 2: 渲染敌人移动
+  const movedEnemies = diffEnemyPositions(prevState.enemies, state.enemies);
+  movedEnemies.forEach(e => updateEnemySprite(e.id, e.position));
+
+  // Step 3: 渲染攻击特效
+  state.lastAttackEvents.forEach(evt => {
+    playAttackEffect(evt.towerId, evt.enemyId, evt.towerType);
+  });
+
+  // Step 4: 渲染敌人死亡
+  state.lastDeathEvents.forEach(evt => {
+    playDeathAnimation(evt.enemyId);
+    showGoldPopup(evt.reward);
+    removeEnemySprite(evt.enemyId);
+  });
+
+  // Step 5: 渲染敌人逃跑（到达终点）
+  state.lastEscapeEvents.forEach(evt => {
+    removeEnemySprite(evt.enemyId);
+    updateLivesUI(state.resources.lives);
+  });
+}
+
+// 放塔（玩家点击）
+function onPlaceTower(gridPos, towerType) {
+  const newState = placeTower(state, gridPos, towerType);
+  if (newState !== state) {
+    state = newState;
+    createTowerSprite(gridPos, towerType);
+    updateGoldUI(state.resources.gold);
+  }
+}
+```
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/tower_defence/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `placeTower()` / `upgradeTower()` / `tickGameLoop()` / `processAttacks()` / `moveEnemies()` / `spawnNextWave()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a classic tower defence gameplay module following the PGS specification.
+  Write the PGS JSON with entities, rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - placeTower/upgradeTower/tickGameLoop/processAttacks/moveEnemies/spawnNextWave (分步函数)
+  Enemy movement: enemies follow a predefined path (array of grid positions), advance by speed*deltaMs per tick.
+  Tower attack: each tick, tower attacks nearest enemy within range if cooldown elapsed.
+  Wave spawning: new enemies spawn at path entrance per wave definition at set intervals.
+  Run the testCases to verify the logic before finalizing.

package/skills/tower_defence.aigameplay/manifest.json

@@ -0,0 +1,175 @@
+{
+  "schemaVersion": 1,
+  "atomId": "tower_defence.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "经典塔防玩法",
+    "en": "Classic tower defence gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "tower-defence",
+    "strategy",
+    "waves",
+    "grid",
+    "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": "background",
+      "description": "地图背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "backgroundTexture"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "levelDataPack",
+      "description": "关卡地图与波次数据包",
+      "bindAs": "levels",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "levelDataPack"
+      ],
+      "allowedBundleTypes": [
+        "aiconfig"
+      ]
+    },
+    {
+      "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": "tower_defence",
+    "rules": {
+      "initialLives": 20,
+      "initialGold": 150,
+      "tickRateMs": 100,
+      "towerTypes": [
+        "arrow",
+        "cannon",
+        "magic"
+      ],
+      "enemyTypes": [
+        "basic",
+        "fast",
+        "armored",
+        "boss"
+      ]
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/tower_defence/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(action)",
+        "getState()",
+        "placeTower(state, position, towerType)",
+        "upgradeTower(state, towerId)",
+        "tickGameLoop(state, deltaMs)",
+        "processAttacks(state)",
+        "moveEnemies(state, deltaMs)",
+        "spawnNextWave(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}