@playcraft/skills 0.0.2

package/skills/combo_praise_text.aicomponent/ref/ComboManager.ts

@@ -0,0 +1,362 @@
+import * as Phaser from "phaser";
+import { ComboSmallUI } from "./ComboSmallUI";
+import { GAME_TOP_UI_BAR_HEIGHT } from "./GameTopUI";
+import { computeUiLayout } from "../../utils/UiLayout";
+
+/** 连续成功操作计为连击链的时间窗口（毫秒）。 */
+const COMBO_CHAIN_WINDOW_MS = 1400;
+
+export class ComboManager {
+  private scene: Phaser.Scene;
+
+  // ── 连击状态 ──
+  private comboClickCount = 0;
+  private comboLastSuccessAtMs = 0;
+  private comboUi: ComboSmallUI | undefined;
+  private comboUiLastCount = 0;
+  private comboPraiseText: Phaser.GameObjects.Text | undefined;
+  private comboPraiseTween: Phaser.Tweens.Tween | null = null;
+  private comboPraiseTimer: Phaser.Time.TimerEvent | null = null;
+  private comboPraiseLastShownComboCount = 0;
+
+  constructor(scene: Phaser.Scene) {
+    this.scene = scene;
+  }
+
+  // ── 公共 getter / setter ──────────────────────────────
+
+  /** 获取当前连击点击次数 */
+  get clickCount(): number {
+    return this.comboClickCount;
+  }
+
+  /** 设置连击点击次数 */
+  set clickCount(v: number) {
+    this.comboClickCount = v;
+  }
+
+  /** 获取上次成功操作的时间戳（毫秒） */
+  get lastSuccessAtMs(): number {
+    return this.comboLastSuccessAtMs;
+  }
+
+  /** 设置上次成功操作的时间戳（毫秒） */
+  set lastSuccessAtMs(v: number) {
+    this.comboLastSuccessAtMs = v;
+  }
+
+  /** 获取连击链时间窗口（毫秒） */
+  get chainWindowMs(): number {
+    return COMBO_CHAIN_WINDOW_MS;
+  }
+
+  // ── 生命周期 ──────────────────────────────────────────────
+
+  /**
+   * 创建 ComboSmallUI 组件。在场景 create() 中调用一次。
+   * @param layout 包含宽度和UI缩放比例的布局信息
+   */
+  createUi(layout: { width: number; uiScale: number }): void {
+    this.comboUi = new ComboSmallUI(this.scene, layout.width * 0.5, 0, {
+      uiScale: layout.uiScale,
+      progress: 1,
+      comboCount: 1,
+      depth: 1600,
+    });
+    this.comboUi.setScrollFactor(0);
+    this.comboUi.setVisible(false);
+
+    this.refreshComboUiPlacement();
+
+    // 定期刷新倒计时
+    this.scene.time.addEvent({
+      delay: 33,
+      loop: true,
+      callback: () => this.refreshComboUiCountdown(),
+    });
+  }
+
+  /**
+   * 重置所有连击状态。在每关开始时调用。
+   */
+  resetState(): void {
+    this.comboClickCount = 0;
+    this.comboLastSuccessAtMs = 0;
+    this.comboUiLastCount = 0;
+    this.comboPraiseLastShownComboCount = 0;
+    this.clearComboPraiseText();
+  }
+
+  // ── 原先在 Game 上的方法 ─────────────────────────────
+
+  /** 成功消除路径后处理连击UI显示。 */
+  handleComboUiOnSuccess(): void {
+    const comboUi = this.comboUi;
+    if (!comboUi) {
+      return;
+    }
+
+    if (this.comboClickCount < 3) {
+      this.hideComboUi();
+      return;
+    }
+
+    if (!comboUi.visible) {
+      comboUi.setVisible(true);
+      this.refreshComboUiPlacement();
+    }
+
+    comboUi.setProgress(1);
+
+    if (this.comboUiLastCount !== this.comboClickCount) {
+      comboUi.setCombo(this.comboClickCount);
+      comboUi.playComboPulse();
+      this.comboUiLastCount = this.comboClickCount;
+      this.refreshComboUiPlacement();
+    }
+  }
+
+  /** 刷新连击UI倒计时进度条。 */
+  refreshComboUiCountdown(): void {
+    const comboUi = this.comboUi;
+    if (!comboUi || !comboUi.visible) {
+      return;
+    }
+
+    if (this.comboClickCount < 3 || this.comboLastSuccessAtMs <= 0) {
+      this.hideComboUi();
+      return;
+    }
+
+    const now = this.scene.time.now;
+    const elapsed = now - this.comboLastSuccessAtMs;
+    const remain = COMBO_CHAIN_WINDOW_MS - elapsed;
+    if (remain <= 0) {
+      this.comboClickCount = 0;
+      this.comboLastSuccessAtMs = 0;
+      this.comboPraiseLastShownComboCount = 0;
+      this.clearComboPraiseText();
+      this.hideComboUi();
+      return;
+    }
+
+    comboUi.setProgress(remain / COMBO_CHAIN_WINDOW_MS);
+  }
+
+  /** 隐藏连击UI组件。 */
+  hideComboUi(): void {
+    if (this.comboUi) {
+      this.comboUi.setVisible(false);
+      this.comboUi.setProgress(0);
+      this.comboUi.setScale(1);
+    }
+    this.comboUiLastCount = 0;
+  }
+
+  /** 刷新连击UI组件的位置。 */
+  refreshComboUiPlacement(): void {
+    const comboUi = this.comboUi;
+    if (!comboUi) {
+      return;
+    }
+
+    const layout = computeUiLayout(this.scene);
+    const { width, height, uiScale, vScale } = layout;
+
+    const topUiBottom = GAME_TOP_UI_BAR_HEIGHT * vScale;
+
+    const targetComboLeft = 10 * uiScale;
+    const targetTextTop = topUiBottom + 10 * vScale;
+    const marginRight = 12 * uiScale;
+
+    comboUi.setScale(1);
+    comboUi.setPosition(0, 0);
+
+    const glyphLeftLocal = comboUi.getComboGlyphLeftLocal();
+    const glyphTopLocal = comboUi.getTextGlyphTopLocal();
+
+    const baseBounds = comboUi.getBounds();
+    const localRight = baseBounds.right;
+    const distToRight = localRight - glyphLeftLocal;
+    const availableW = Math.max(1, width - marginRight - targetComboLeft);
+    const fitScale =
+      distToRight > 0 ? Math.min(1, availableW / distToRight) : 1;
+
+    comboUi.setScale(fitScale);
+
+    const x = targetComboLeft - glyphLeftLocal * fitScale;
+    const y = targetTextTop - glyphTopLocal * fitScale;
+    comboUi.setPosition(x, y);
+  }
+
+  /** 清除连击表扬文本及其相关动画。 */
+  clearComboPraiseText(): void {
+    if (this.comboPraiseTween) {
+      this.comboPraiseTween.stop();
+      this.comboPraiseTween = null;
+    }
+    if (this.comboPraiseTimer) {
+      this.comboPraiseTimer.remove(false);
+      this.comboPraiseTimer = null;
+    }
+    if (this.comboPraiseText) {
+      this.scene.tweens.killTweensOf(this.comboPraiseText);
+      this.comboPraiseText.destroy();
+      this.comboPraiseText = undefined;
+    }
+  }
+
+  /**
+   * 根据连击次数获取对应的表扬文本。
+   * @param comboCount 连击次数
+   * @returns 表扬文本，如果不需要显示则返回 null
+   */
+  getComboPraiseMessage(comboCount: number): string | null {
+    const c = Math.max(0, Math.floor(comboCount || 0));
+    if (c < 3) {
+      return null;
+    }
+
+    if (c >= 15) {
+      if (c === 15 || (c > 15 && (c - 15) % 3 === 0)) {
+        const tiers = [
+          "LEGENDARY!",
+          "GODLIKE!",
+          "UNREAL!",
+          "PHENOMENAL!",
+          "SUPREME!",
+        ];
+        const tierIndex = Math.floor((c - 15) / 3) % tiers.length;
+        return tiers[tierIndex] ?? "LEGENDARY!";
+      }
+      return null;
+    }
+
+    switch (c) {
+      case 3:
+        return "GOOD!";
+      case 4:
+        return "NICE!";
+      case 5:
+        return "GREAT!";
+      case 6:
+        return "AWESOME!";
+      case 7:
+        return "AMAZING!";
+      case 8:
+        return "UNSTOPPABLE!";
+      case 10:
+        return "INCREDIBLE!";
+      case 12:
+        return "INSANE!";
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * 在点击位置（或屏幕中央）显示连击表扬文本。
+   * @param comboCount 当前连击次数
+   * @param lastTapScreenX 上次点击的屏幕X坐标
+   * @param lastTapScreenY 上次点击的屏幕Y坐标
+   * @param hasLastTapScreenPos 点击位置是否有效
+   */
+  maybeShowComboPraiseText(
+    comboCount: number,
+    lastTapScreenX: number,
+    lastTapScreenY: number,
+    hasLastTapScreenPos: boolean,
+  ): void {
+    const message = this.getComboPraiseMessage(comboCount);
+    if (!message) {
+      return;
+    }
+
+    const c = Math.max(0, Math.floor(comboCount || 0));
+    if (c === this.comboPraiseLastShownComboCount) {
+      return;
+    }
+    this.comboPraiseLastShownComboCount = c;
+
+    this.clearComboPraiseText();
+
+    const layout = computeUiLayout(this.scene);
+    const { centerX, uiScale, vScale } = layout;
+
+    const baseX = hasLastTapScreenPos ? lastTapScreenX : centerX;
+    const baseY = hasLastTapScreenPos
+      ? lastTapScreenY - 30 * uiScale
+      : GAME_TOP_UI_BAR_HEIGHT * vScale + 180 * vScale;
+
+    const hint = this.scene.add.text(baseX, baseY + 14 * uiScale, message, {
+      fontFamily: "Poppins, Arial, sans-serif",
+      fontSize: `${26 * uiScale}px`,
+      color: "#1184ff",
+      fontStyle: "bold",
+      align: "center",
+    });
+
+    hint.setOrigin(0.5, 0.5);
+    hint.setScale(0.6);
+    hint.setScrollFactor(0);
+    hint.setDepth(1700);
+    hint.setAlpha(0.98);
+
+    // 简洁描边
+    hint.setStroke("#FFFFFF", 2 * uiScale);
+
+    // 蓝色发光效果
+    hint.setShadow(0, 0, "#1184ff", 2 * uiScale, true, false);
+
+    this.comboPraiseText = hint;
+
+    /** 清理表扬文本 */
+    const cleanup = () => {
+      if (this.comboPraiseText === hint) {
+        this.comboPraiseText = undefined;
+      }
+      this.comboPraiseTween = null;
+      if (this.comboPraiseTimer) {
+        this.comboPraiseTimer.remove(false);
+        this.comboPraiseTimer = null;
+      }
+      hint.destroy();
+    };
+
+    const finalY = baseY;
+    const popStartY = baseY + 10 * uiScale;
+    hint.y = popStartY;
+
+    // 弹出动画：从下方弹出 -> 缩放回弹 -> 延迟后淡出上移
+    this.comboPraiseTween = this.scene.tweens.add({
+      targets: hint,
+      y: finalY,
+      alpha: 1,
+      scale: 1.12,
+      duration: 90,
+      ease: "Back.Out",
+      onComplete: () => {
+        this.comboPraiseTween = this.scene.tweens.add({
+          targets: hint,
+          scale: 1,
+          duration: 60,
+          ease: "Sine.Out",
+          onComplete: () => {
+            this.comboPraiseTween = null;
+            this.comboPraiseTimer = this.scene.time.delayedCall(260, () => {
+              this.comboPraiseTimer = null;
+              this.comboPraiseTween = this.scene.tweens.add({
+                targets: hint,
+                y: finalY - 70 * uiScale,
+                alpha: 0,
+                duration: 360,
+                ease: "Cubic.In",
+                onComplete: cleanup,
+              });
+            });
+          },
+        });
+      },
+    });
+  }
+}

package/skills/countdown_timer.aicomponent/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: countdown_timer.aicomponent
+description: 倒计时显示器。使用七段数码管风格显示剩余秒数，时间不足时触发闪烁警告动画，归零时通知 LevelLifecycle 触发超时失败。
+triggers: 需要实现倒计时 UI 组件时触发。
+---
+
+# 倒计时显示器（Countdown Timer Display）
+
+## Scaffold
+
+`src/game/scenes/GameUI/CountdownDisplay.ts`
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **封装 display + 计时 + 警告 + 通知** | 倒计时组件的四个职责（显示、计时、闪烁警告、超时回调）高度关联，分开会造成 GameScene 过多编排逻辑 |
+| **依赖 DigitRenderer 而非系统字体** | 七段数码管风格保持视觉一致性；DigitRenderer 是项目内部组件，无字体加载依赖 |
+| **闪烁警告阈值** | 最后 10 秒（可配置）才开始闪烁，避免整个关卡都闪烁让玩家焦虑；阈值可通过 GameConfig 调整 |
+
+## Adapter
+
+- **Role**: `countdownTimer` — 倒计时显示器（七段数码管风格 + 警告闪烁 + 超时通知）
+- **Provides**: `CountdownDisplay` 类（`start(seconds)`、`stop()`、`update(delta)` 每帧调用）
+- **Requires**: `phaser.aicomponent`、`digit_renderer.aicomponent`（七段数码管 Graphics 渲染）
+- **Consumed by**: `game_scene.aicomponent`（在 `update()` 中调用 `countdownDisplay.update(delta)`，接收超时回调）
+- **Integration point**: `src/game/scenes/GameUI/CountdownDisplay.ts` → 顶部 UI 条或 GameScene 中实例化，`game_scene` `update()` 循环中每帧更新
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖）
+- `digit_renderer.aicomponent`（硬依赖：七段数码管绘制）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: src/game/scenes/GameUI/CountdownDisplay.ts
+outputs:
+  - countdownDisplay: CountdownDisplay class
+```

package/skills/countdown_timer.aicomponent/manifest.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 1,
+  "atomId": "countdown_timer.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "倒计时显示器", "en": "Countdown timer display" },
+  "tags": ["ui", "countdown", "timer", "seven-segment", "digit"],
+  "bindingRoles": ["countdownTimer"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/CountdownDisplay.ts": { "source": "ref/CountdownDisplay.ts", "mode": "full", "weight": 10 }
+    }
+  },
+  "imports": [
+    { "slot": "engine",        "pinAtomId": "phaser.aicomponent",         "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "digitRenderer", "pinAtomId": "digit_renderer.aicomponent", "edgeKind": "requires", "bindAs": "digitRenderer" },
+    {
+      "slot": "clockIcon",
+      "description": "倒计时时钟图标",
+      "bindAs": "clockIcon",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["clockIcon"],
+      "allowedBundleTypes": ["aiimage"]
+    }
+  ],
+  "exports": [
+    { "name": "CountdownDisplay", "kind": "class", "location": "src/game/scenes/GameUI/CountdownDisplay.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "countdown timer UI component that displays remaining time in seconds using a seven-segment digit renderer with flash animation when time is low"
+  },
+  "files": { "skill": "SKILL.md", "countdownDisplay": "ref/CountdownDisplay.ts" }
+}

package/skills/countdown_timer.aicomponent/ref/CountdownDisplay.ts

@@ -0,0 +1,213 @@
+import * as Phaser from "phaser";
+import { DigitRenderer } from "./DigitRenderer";
+
+/**
+ * 倒计时显示组件（LED / 七段数码管风格）。
+ * 同时处理视觉渲染和计时器逻辑（启动、停止、经过时间追踪）。
+ */
+export class CountdownDisplay {
+  private scene: Phaser.Scene;
+  private container: Phaser.GameObjects.Container;
+  private digitGraphics: Phaser.GameObjects.Graphics[] = [];
+  private digitWidth: number;
+  private digitHeight: number;
+  private digitSpacing: number;
+  private colonWidth: number;
+
+  // 计时器逻辑（使用毫秒以避免浮点精度漂移）
+  private elapsedMs = 0;
+  private totalMs = 0;
+  private lastTimerUpdateMs: number | undefined;
+  private timerRunning = false;
+  private timeoutTriggered = false;
+  private onTimeoutCallback: (() => void) | undefined;
+
+  constructor(
+    scene: Phaser.Scene,
+    parent: Phaser.GameObjects.Container,
+    options: {
+      xLeft: number;
+      y: number;
+      digitWidth: number;
+      digitHeight: number;
+      digitSpacing: number;
+      colonWidth: number;
+      totalSeconds: number;
+      onTimeout?: () => void;
+    },
+  ) {
+    this.scene = scene;
+    this.digitWidth = options.digitWidth;
+    this.digitHeight = options.digitHeight;
+    this.digitSpacing = options.digitSpacing;
+    this.colonWidth = options.colonWidth;
+    this.totalMs = Math.max(0, Math.floor(options.totalSeconds * 1000));
+    this.onTimeoutCallback = options.onTimeout;
+
+    const totalWidth =
+      this.digitWidth * 4 + this.colonWidth + this.digitSpacing * 4;
+
+    this.container = scene.add.container(
+      options.xLeft + totalWidth / 2,
+      options.y,
+    );
+    this.container.setSize(totalWidth, this.digitHeight);
+    parent.add(this.container);
+
+    // 创建5个图形对象：分钟十位、分钟个位、冒号、秒钟十位、秒钟个位
+    let offsetX = -totalWidth / 2;
+    for (let i = 0; i < 5; i++) {
+      const g = scene.add.graphics();
+
+      const isColon = i === 2;
+      const w = isColon ? this.colonWidth : this.digitWidth;
+
+      g.setPosition(offsetX + w / 2, 0);
+      offsetX += w;
+
+      // 仅在元素之间添加间距（共4个间隔），最后一个元素后不加
+      if (i !== 4) {
+        offsetX += this.digitSpacing;
+      }
+
+      this.digitGraphics.push(g);
+      this.container.add(g);
+    }
+  }
+
+  /** 更新倒计时的视觉显示 */
+  public updateDisplay(remainingOverride?: number): void {
+    if (!this.digitGraphics || this.digitGraphics.length < 5) {
+      return;
+    }
+
+    const remainingMsRaw =
+      remainingOverride !== undefined
+        ? remainingOverride
+        : Math.max(this.totalMs - this.elapsedMs, 0);
+
+    // 以向上取整到整秒来渲染，使显示每秒跳动一次
+    const remainingSeconds = Math.max(0, Math.ceil(remainingMsRaw / 1000));
+
+    const mins = Math.floor(remainingSeconds / 60);
+    const secs = remainingSeconds % 60;
+
+    // 颜色：正常灰色，剩余 ≤ 10秒时显示警告红色
+    const color = remainingSeconds <= 10 ? 0xff3333 : 0x50536b;
+
+    const digitWidth = this.digitWidth || 20;
+    const digitHeight = this.digitHeight || 36;
+
+    // 分钟十位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[0],
+      Math.floor(mins / 10),
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 分钟个位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[1],
+      mins % 10,
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 冒号
+    DigitRenderer.drawColon(this.digitGraphics[2], color, digitWidth);
+    // 秒钟十位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[3],
+      Math.floor(secs / 10),
+      color,
+      digitWidth,
+      digitHeight,
+    );
+    // 秒钟个位
+    DigitRenderer.drawDigit(
+      this.digitGraphics[4],
+      secs % 10,
+      color,
+      digitWidth,
+      digitHeight,
+    );
+  }
+
+  /** 每帧调用以推进计时器 */
+  public updateTimer(deltaMs: number, nowMs?: number): void {
+    const prevRemainingMs = Math.max(this.totalMs - this.elapsedMs, 0);
+
+    if (this.timerRunning && prevRemainingMs > 0) {
+      // 优先使用绝对时间戳以避免帧增量平滑漂移
+      let usedDeltaMs = deltaMs;
+      if (nowMs !== undefined) {
+        if (this.lastTimerUpdateMs === undefined) {
+          this.lastTimerUpdateMs = nowMs;
+          usedDeltaMs = 0;
+        } else {
+          usedDeltaMs = nowMs - this.lastTimerUpdateMs;
+          this.lastTimerUpdateMs = nowMs;
+        }
+      }
+
+      if (Number.isFinite(usedDeltaMs) && usedDeltaMs > 0) {
+        this.elapsedMs += usedDeltaMs;
+      }
+    } else {
+      // 未运行时同步时间戳，避免恢复时出现跳跃
+      if (nowMs !== undefined) {
+        this.lastTimerUpdateMs = nowMs;
+      } else {
+        this.lastTimerUpdateMs = undefined;
+      }
+    }
+
+    const remainingMs = Math.max(this.totalMs - this.elapsedMs, 0);
+
+    if (
+      this.timerRunning &&
+      !this.timeoutTriggered &&
+      prevRemainingMs > 0 &&
+      remainingMs <= 0
+    ) {
+      this.timeoutTriggered = true;
+      if (this.onTimeoutCallback) {
+        this.onTimeoutCallback();
+      }
+    }
+
+    this.updateDisplay(remainingMs);
+  }
+
+  /**
+   * 为倒计时添加额外时间。
+   * @param seconds 要添加的秒数
+   */
+  public addTime(seconds: number): void {
+    if (seconds <= 0) return;
+
+    this.totalMs += seconds * 1000;
+    this.timeoutTriggered = false;
+
+    const remainingMs = Math.max(this.totalMs - this.elapsedMs, 0);
+    this.updateDisplay(remainingMs);
+  }
+
+  /** 启动计时器 */
+  public startTimer(): void {
+    this.timerRunning = true;
+    this.lastTimerUpdateMs = undefined;
+  }
+
+  /** 停止计时器 */
+  public stopTimer(): void {
+    this.timerRunning = false;
+    this.lastTimerUpdateMs = undefined;
+  }
+
+  /** 获取已经过的秒数 */
+  public getElapsedSeconds(): number {
+    return Math.floor(this.elapsedMs / 1000);
+  }
+}