@playcraft/skills 0.0.2

package/skills/combo_display.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/combo_display.aicomponent/ref/ComboSmallUI.ts

@@ -0,0 +1,232 @@
+import * as Phaser from "phaser";
+
+/** ComboSmallUI 组件的配置选项 */
+export interface ComboSmallUIConfig {
+  uiScale?: number;
+  barWidth?: number;
+  barHeight?: number;
+  progress?: number;
+  comboCount?: number;
+  depth?: number;
+}
+
+/**
+ * 连击小型UI组件，显示 "COMBO X数字" 文本。
+ * 包含动画效果（呼吸缩放、脉冲等）。
+ */
+export class ComboSmallUI extends Phaser.GameObjects.Container {
+  private readonly uiScale: number;
+  private readonly textPad: number;
+  private readonly textPadRight: number;
+  private readonly textGap: number;
+  private readonly strokeThickness: number;
+
+  private progress = 0;
+
+  private readonly comboText: Phaser.GameObjects.Text;
+  private readonly xText: Phaser.GameObjects.Text;
+  private xTween: Phaser.Tweens.Tween | undefined;
+
+  constructor(
+    scene: Phaser.Scene,
+    x: number,
+    y: number,
+    config: ComboSmallUIConfig = {},
+  ) {
+    super(scene, x, y);
+
+    scene.add.existing(this);
+
+    this.uiScale = config.uiScale ?? 1;
+
+    const fontSize = 40 * this.uiScale;
+    const strokeThickness = 8 * this.uiScale;
+    this.strokeThickness = strokeThickness;
+    const pad = Math.ceil(strokeThickness * 3 + fontSize * 0.1);
+    const padRight = Math.ceil(strokeThickness * 6 + fontSize * 0.4);
+    this.textPad = pad;
+    this.textPadRight = padRight;
+
+    // 创建 "COMBO" 文本
+    const comboText = scene.add.text(0, 0, "COMBO", {
+      fontFamily: "Poppins",
+      fontSize: `${fontSize + 6}px`,
+      color: "#007AFF", // 蓝色主色调
+      fontStyle: "bold",
+    });
+
+    // 描边效果
+    comboText.setStroke("#FFFFFF", strokeThickness + 3); // 白色描边
+    comboText.setShadow(0, 0, "#007AFF", 8, true, false); // 蓝色外发光
+
+    // 轻微倾斜角度
+    comboText.angle = -3;
+
+    comboText.setPadding(
+      this.textPad + 4,
+      this.textPad,
+      this.textPadRight + 4,
+      this.textPad,
+    );
+    comboText.setOrigin(1, 0.5);
+
+    // COMBO 文本呼吸动画
+    scene.tweens.add({
+      targets: comboText,
+      scaleX: 1.1,
+      scaleY: 1.1,
+      angle: 3,
+      duration: 300,
+      yoyo: true,
+      repeat: -1,
+      ease: "Sine.easeInOut",
+    });
+
+    // 创建 "X数字" 文本
+    const xText = scene.add.text(0, 0, "X1", {
+      fontFamily: "Poppins",
+      fontSize: `${fontSize}px`,
+      color: "#007AFF", // 蓝色主色调
+      fontStyle: "bold italic",
+    });
+    xText.setResolution(2);
+    xText.setStroke("#FFFFFF", strokeThickness + 3); // 白色描边
+    xText.setShadow(0, 0, "#007AFF", 4, true, true); // 蓝色外发光
+    xText.setPadding(
+      this.textPad,
+      this.textPad,
+      this.textPadRight,
+      this.textPad,
+    );
+    xText.setOrigin(0, 0.5);
+
+    this.textGap = 2 * this.uiScale;
+
+    this.comboText = comboText;
+    this.xText = xText;
+
+    this.add(comboText);
+    this.add(xText);
+
+    this.layoutComboText();
+    this.recomputeSize();
+
+    if (typeof config.comboCount === "number") {
+      this.setCombo(config.comboCount);
+    }
+    if (typeof config.progress === "number") {
+      this.setProgress(config.progress);
+    }
+
+    if (typeof config.depth === "number") {
+      this.setDepth(config.depth);
+    }
+  }
+
+  /**
+   * 设置连击进度（控制整体透明度）。
+   * @param progress 进度值（0~1）
+   */
+  public setProgress(progress: number): void {
+    this.progress = Phaser.Math.Clamp(progress, 0, 1);
+    const minAlpha = 0.25;
+    const alpha = minAlpha + (1 - minAlpha) * this.progress;
+    this.setAlpha(alpha);
+  }
+
+  /**
+   * 设置连击计数并更新显示文本。
+   * @param count 连击次数
+   */
+  public setCombo(count: number): void {
+    const safeCount = Math.max(1, Math.floor(count));
+    this.xText.setText(`X${safeCount}`);
+    this.xText.setPadding(
+      this.textPad,
+      this.textPad,
+      this.textPadRight,
+      this.textPad,
+    );
+    this.layoutComboText();
+    this.recomputeSize();
+  }
+
+  /** 获取 COMBO 文字图形的本地左边界X坐标。 */
+  public getComboGlyphLeftLocal(): number {
+    const comboW = this.comboText.displayWidth || 0;
+    const comboPadL = this.textPad * this.comboText.scaleX;
+    return this.comboText.x - comboW + comboPadL;
+  }
+
+  /** 获取文字图形的本地顶部Y坐标。 */
+  public getTextGlyphTopLocal(): number {
+    const topFor = (t: Phaser.GameObjects.Text) => {
+      const padTop = this.textPad * t.scaleY;
+      const h = t.displayHeight || 0;
+      return t.y - h / 2 + padTop;
+    };
+    return Math.min(topFor(this.comboText), topFor(this.xText));
+  }
+
+  /** 播放连击脉冲缩放动画。 */
+  public playComboPulse(): void {
+    const scene = this.scene;
+    if (!scene) {
+      return;
+    }
+
+    if (this.xTween) {
+      this.xTween.stop();
+      scene.tweens.remove(this.xTween);
+      this.xTween = undefined;
+    }
+
+    this.xText.setScale(1);
+    this.xTween = scene.tweens.add({
+      targets: this.xText,
+      scale: 1.18,
+      duration: 140,
+      yoyo: true,
+      ease: "Sine.easeOut",
+      onComplete: () => {
+        this.xText.setScale(1);
+        this.xTween = undefined;
+      },
+    });
+  }
+
+  /** 重新布局 COMBO 和 X数字 文本的水平位置。 */
+  private layoutComboText(): void {
+    const comboW = this.comboText.displayWidth || 0;
+    const xW = this.xText.displayWidth || 0;
+
+    const comboPadL = this.textPad * this.comboText.scaleX;
+    const comboPadR = this.textPadRight * this.comboText.scaleX;
+    const xPadL = this.textPad * this.xText.scaleX;
+    const xPadR = this.textPadRight * this.xText.scaleX;
+
+    const comboGlyphW = Math.max(0, comboW - comboPadL - comboPadR);
+    const xGlyphW = Math.max(0, xW - xPadL - xPadR);
+
+    const totalW = comboGlyphW + this.textGap + xGlyphW;
+    const startX = -totalW / 2;
+    const seamX = startX + comboGlyphW;
+
+    this.comboText.setPosition(seamX + comboPadR, 0);
+    this.xText.setPosition(seamX + this.textGap - xPadL, 0);
+  }
+
+  /** 重新计算容器的整体尺寸。 */
+  private recomputeSize(): void {
+    const strokePadding = this.strokeThickness * 2;
+    const textGroupW =
+      (this.comboText.displayWidth || 0) +
+      this.textGap +
+      (this.xText.displayWidth || 0);
+    const totalWidth = textGroupW + strokePadding;
+    const totalHeight =
+      Math.max(this.comboText.displayHeight, this.xText.displayHeight) +
+      strokePadding;
+    this.setSize(totalWidth, totalHeight);
+  }
+}

package/skills/combo_praise_text.aicomponent/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: combo_praise_text.aicomponent
+description: 连击表扬文案弹出动画。在点击成功消除路径时，根据连击数在点击位置弹出 GOOD/NICE/GREAT/AWESOME/INCREDIBLE/LEGENDARY 文字动画，给玩家正向反馈。
+triggers: 需要实现连击正向反馈文字弹出动画时触发。
+---
+
+# 连击表扬文案弹出（Combo Praise Text Popup）
+
+## 说明
+
+当玩家连续成功消除路径时，在点击位置弹出表扬文案：
+
+| 连击数 | 文案 |
+|-----|-----|
+| 1 | GOOD |
+| 2 | NICE |
+| 3 | GREAT |
+| 4 | AWESOME |
+| 5 | INCREDIBLE |
+| 6+ | LEGENDARY |
+
+## Scaffold
+
+`src/game/scenes/GameUI/ComboPraiseText.ts`（从 ComboManager.ts 提取 `maybeShowComboPraiseText` 方法）
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **从 ComboManager 提取** | 表扬文字弹出是纯视觉反馈，与连击计数逻辑耦合度低；提取为独立函数后，可在不使用 ComboManager 的场景中单独复用 |
+| **位置跟随点击点** | 文字在玩家点击位置弹出，强化操作→反馈的直接关联；固定位置的文字反馈感觉"延迟" |
+| **LEGENDARY 封顶** | 超过 6 连击后文案不再升级，避免需要维护过长的文案列表 |
+
+## Adapter
+
+- **Role**: `comboPraiseText` — 连击正向反馈文字弹出动画
+- **Provides**: `maybeShowComboPraiseText(scene, comboCount, x, y)` 函数
+- **Requires**: `phaser.aicomponent`（Tween + Text API）
+- **Consumed by**: `combo_display.aicomponent`（ComboManager 在连击计数变化时调用）
+- **Integration point**: `src/game/scenes/GameUI/ComboPraiseText.ts` → ComboManager.addCombo() 内部触发
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Tween + Text API）
+
+## Skill Definition
+
+```yaml
+tools:
+  - read_file
+  - write_file
+inputs:
+  - source: ref/ComboManager.ts
+outputs:
+  - comboPraiseText: maybeShowComboPraiseText function
+```

package/skills/combo_praise_text.aicomponent/manifest.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "atomId": "combo_praise_text.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "component",
+  "mode": "fixed",
+  "label": { "zh": "连击表扬文案弹出", "en": "Combo praise text popup" },
+  "tags": ["ui", "combo", "praise", "text", "popup", "animation", "GOOD", "NICE", "GREAT"],
+  "bindingRoles": ["comboPraiseText"],
+  "scaffold": {
+    "files": {
+      "src/game/scenes/GameUI/ComboPraiseText.ts": {
+        "source": "ref/ComboManager.ts",
+        "mode": "full",
+        "weight": 8
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine", "pinAtomId": "phaser.aicomponent", "edgeKind": "requires", "bindAs": "engine" }
+  ],
+  "exports": [
+    { "name": "maybeShowComboPraiseText", "kind": "function", "location": "src/game/scenes/GameUI/ComboManager.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "animated praise text popup appearing at tap position for consecutive successful actions: GOOD → NICE → GREAT → AWESOME → INCREDIBLE → LEGENDARY"
+  },
+  "usageHints": [
+    "表扬文案 popup 在每次成功消除路径时触发，level 由连击数决定",
+    "文案序列：GOOD(1) → NICE(2) → GREAT(3) → AWESOME(4) → INCREDIBLE(5) → LEGENDARY(6+)",
+    "弹出位置来自点击坐标（lastTapScreenX/Y）"
+  ],
+  "files": { "skill": "SKILL.md", "comboPraiseText": "ref/ComboManager.ts" }
+}