@playcraft/skills 0.0.2

package/skills/tower_defence.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,247 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 经典塔防玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "tower_defence",
+  "entities": {
+    "grid": {
+      "type": "tile-map",
+      "description": "游戏地图格子",
+      "fields": {
+        "width":           { "type": "integer", "description": "地图列数" },
+        "height":          { "type": "integer", "description": "地图行数" },
+        "cells":           { "type": "array",   "description": "格子类型数组 CellType[][]，path=路径，buildable=可建，empty=不可建" },
+        "path":            { "type": "array",   "description": "敌人行进路径坐标序列 {x, y}[]，从入口到出口" },
+        "path_entry":      { "type": "vector2", "description": "敌人入口坐标" },
+        "path_exit":       { "type": "vector2", "description": "敌人出口坐标" }
+      }
+    },
+    "tower": {
+      "type": "defense-unit",
+      "description": "防御塔",
+      "fields": {
+        "id":           { "type": "string",  "description": "唯一ID" },
+        "type":         { "type": "enum",    "values": ["arrow", "cannon", "magic"] },
+        "position":     { "type": "vector2", "description": "格子坐标 {x, y}" },
+        "level":        { "type": "integer", "range": [1, 3], "default": 1 },
+        "damage":       { "type": "number",  "description": "每次攻击伤害" },
+        "range":        { "type": "number",  "description": "攻击范围（格子数）" },
+        "attack_speed": { "type": "number",  "description": "攻击间隔（毫秒）" },
+        "last_attack_ms":{ "type": "number", "description": "上次攻击时间戳" },
+        "splash_radius": { "type": "number", "default": 0, "description": "范围伤害半径（仅 cannon）" },
+        "slow_factor":  { "type": "number",  "default": 1.0, "description": "减速因子（仅 magic，< 1.0）" },
+        "cost":         { "type": "integer", "description": "建造费用（金币）" },
+        "upgrade_cost": { "type": "integer", "description": "升级费用" },
+        "sell_value":   { "type": "integer", "description": "出售返还金币（约建造价 50%）" }
+      }
+    },
+    "enemy": {
+      "type": "moving-unit",
+      "description": "敌人单位，沿路径行进",
+      "fields": {
+        "id":           { "type": "string",  "description": "唯一ID" },
+        "type":         { "type": "enum",    "values": ["basic", "fast", "armored", "boss"] },
+        "hp":           { "type": "number",  "description": "当前血量" },
+        "max_hp":       { "type": "number",  "description": "最大血量" },
+        "speed":        { "type": "number",  "description": "移动速度（格子/秒）" },
+        "path_index":   { "type": "integer", "description": "当前目标路径点索引" },
+        "progress":     { "type": "number",  "range": [0, 1], "description": "到下一路径点的进度" },
+        "position":     { "type": "vector2", "description": "当前插值位置（用于渲染）" },
+        "reward":       { "type": "integer", "description": "击杀奖励金币" },
+        "armor":        { "type": "number",  "default": 0, "description": "装甲值，减少物理伤害百分比" },
+        "slow_until_ms":{ "type": "number",  "default": 0, "description": "减速效果持续到的时间戳" },
+        "alive":        { "type": "boolean", "default": true }
+      }
+    },
+    "waves": {
+      "type": "spawn-config",
+      "description": "波次定义列表",
+      "fields": {
+        "wave_index":      { "type": "integer", "description": "当前波次索引（0-based）" },
+        "total_waves":     { "type": "integer" },
+        "wave_in_progress":{ "type": "boolean" },
+        "spawn_queue":     { "type": "array",   "description": "当前波次待生成的敌人队列 {type, count, interval_ms}[]" },
+        "last_spawn_ms":   { "type": "number" },
+        "definitions":     {
+          "type": "array",
+          "description": "每波次定义 [{enemies: [{type, count}], spawn_interval_ms}]"
+        }
+      }
+    },
+    "resources": {
+      "type": "player-resources",
+      "fields": {
+        "gold":  { "type": "integer", "initial": 150, "description": "当前金币" },
+        "lives": { "type": "integer", "initial": 20,  "description": "剩余生命" }
+      }
+    }
+  },
+  "rules": {
+    "place_tower": {
+      "description": "在可建格子放置防御塔",
+      "conditions": [
+        "目标格子类型 == buildable",
+        "目标格子没有已有塔",
+        "resources.gold >= tower_type.cost"
+      ],
+      "effect": "resources.gold -= cost; grid.cell = occupied; towers.push(new_tower)"
+    },
+    "upgrade_tower": {
+      "description": "升级已有防御塔（最高3级）",
+      "conditions": [
+        "tower.level < 3",
+        "resources.gold >= tower.upgrade_cost"
+      ],
+      "effect": "resources.gold -= upgrade_cost; tower.level++; tower.damage *= 1.5; tower.range += 0.5"
+    },
+    "sell_tower": {
+      "description": "出售防御塔，返还部分金币",
+      "effect": "resources.gold += tower.sell_value; 移除塔; 格子恢复 buildable"
+    },
+    "auto_attack": {
+      "description": "每次 tick，塔检查冷却时间，若冷却结束则攻击范围内最近的敌人",
+      "target_priority": "nearest_enemy_in_range",
+      "cooldown_check": "current_ms - tower.last_attack_ms >= tower.attack_speed",
+      "damage_formula": {
+        "arrow":  "damage（单体，穿甲弱）",
+        "cannon": "damage × (1 - armor_reduction)，splash_radius 范围内所有敌人受 50% 伤害",
+        "magic":  "damage × (1 + armor_bonus_factor if armored)，命中后施加减速效果 slow_factor"
+      }
+    },
+    "enemy_move": {
+      "description": "每 tick 敌人按速度沿路径推进",
+      "formula": {
+        "advance": "progress += speed × (1 if not slowed else slow_factor) × dt / path_segment_length",
+        "next_point": "if progress >= 1: path_index++; progress -= 1",
+        "escape": "if path_index >= path.length: 敌人到达出口"
+      }
+    },
+    "enemy_death": {
+      "description": "hp <= 0 时敌人死亡，掉落金币",
+      "effect": "enemy.alive = false; resources.gold += enemy.reward"
+    },
+    "enemy_escape": {
+      "description": "敌人到达路径终点（出口），扣除生命",
+      "effect": "resources.lives -= 1; remove enemy"
+    },
+    "wave_spawn": {
+      "description": "按波次配置定时生成敌人到路径入口",
+      "interval": "spawn_queue.current.interval_ms"
+    }
+  },
+  "algorithm": {
+    "description": "固定 tick 主循环（每 100ms）",
+    "steps": [
+      "1. 波次生成：若 wave_in_progress，按 spawn_interval 从 spawn_queue 取出敌人，添加到 path 入口",
+      "2. 敌人移动：每个存活敌人按速度（含减速状态）沿路径推进",
+      "3. 逃跑检测：到达出口的敌人扣除生命 lives--，检测是否 lives<=0 → 失败",
+      "4. 塔攻击：检查每个塔的冷却，对范围内最近存活敌人发动攻击（含范围/减速效果）",
+      "5. 死亡结算：hp<=0 的敌人标记 dead，掉落金币，从列表移除",
+      "6. 波次完成检测：所有敌人死亡或逃跑 → 当前波次结束，准备下一波",
+      "7. 胜利检测：all waves 完成 且 lives > 0 → 胜利"
+    ]
+  },
+  "winCondition": {
+    "type": "survive_all_waves",
+    "description": "所有波次的敌人全部被消灭或逃跑处理完毕，且 resources.lives > 0"
+  },
+  "loseCondition": {
+    "type": "lives_depleted",
+    "description": "resources.lives <= 0（敌人到达出口次数超过初始生命值）"
+  },
+  "testCases": [
+    {
+      "id": "tc_place_tower_kills_enemy",
+      "description": "放置弓箭塔后，敌人进入范围内被击杀，获得金币奖励",
+      "initialState": {
+        "grid": {
+          "path": [{"x":0,"y":2},{"x":1,"y":2},{"x":2,"y":2},{"x":3,"y":2},{"x":4,"y":2}],
+          "cells": "3x5 地图，path在y=2，buildable在y=1和y=3"
+        },
+        "towers": [],
+        "enemies": [
+          { "id": "e1", "type": "basic", "hp": 100, "max_hp": 100, "speed": 1, "path_index": 0, "progress": 0, "reward": 20, "armor": 0, "alive": true }
+        ],
+        "resources": { "gold": 150, "lives": 20 },
+        "waves": { "wave_index": 0, "wave_in_progress": false }
+      },
+      "actions": [
+        { "type": "place_tower", "position": {"x": 2, "y": 1}, "tower_type": "arrow" },
+        { "type": "tick_game_loop", "times": 30, "deltaMs": 100 }
+      ],
+      "expectedState": {
+        "enemies[e1].alive": false,
+        "resources.gold": { "greaterThan": 100 },
+        "resources.lives": 20
+      }
+    },
+    {
+      "id": "tc_enemy_escapes_loses_life",
+      "description": "无塔时敌人到达出口，生命-1",
+      "initialState": {
+        "grid": {
+          "path": [{"x":0,"y":2},{"x":1,"y":2},{"x":2,"y":2}]
+        },
+        "towers": [],
+        "enemies": [
+          { "id": "e1", "type": "basic", "hp": 100, "max_hp": 100, "speed": 3, "path_index": 0, "progress": 0.9, "reward": 20, "armor": 0, "alive": true }
+        ],
+        "resources": { "gold": 150, "lives": 20 }
+      },
+      "actions": [
+        { "type": "tick_game_loop", "times": 5, "deltaMs": 100 }
+      ],
+      "expectedState": {
+        "resources.lives": 19,
+        "enemies": []
+      }
+    },
+    {
+      "id": "tc_wave_completion",
+      "description": "波次通过：所有敌人被消灭，波次计数推进",
+      "initialState": {
+        "grid": {
+          "path": [{"x":0,"y":2},{"x":1,"y":2},{"x":2,"y":2},{"x":3,"y":2}]
+        },
+        "towers": [
+          { "id": "t1", "type": "arrow", "position": {"x":2,"y":1}, "level": 1, "damage": 30, "range": 2, "attack_speed": 500, "last_attack_ms": 0 }
+        ],
+        "enemies": [
+          { "id": "e1", "type": "basic", "hp": 60, "max_hp": 100, "speed": 1, "path_index": 1, "progress": 0, "reward": 20, "armor": 0, "alive": true }
+        ],
+        "resources": { "gold": 100, "lives": 20 },
+        "waves": { "wave_index": 0, "total_waves": 3, "wave_in_progress": true }
+      },
+      "actions": [
+        { "type": "tick_game_loop", "times": 20, "deltaMs": 100 }
+      ],
+      "expectedState": {
+        "enemies": [],
+        "waves.wave_index": 1,
+        "waves.wave_in_progress": false,
+        "resources.gold": { "greaterThan": 100 }
+      }
+    },
+    {
+      "id": "tc_game_over_lives_zero",
+      "description": "失败：生命值耗尽",
+      "initialState": {
+        "grid": {
+          "path": [{"x":0,"y":2},{"x":1,"y":2}]
+        },
+        "towers": [],
+        "enemies": [
+          { "id": "e1", "type": "basic", "hp": 100, "max_hp": 100, "speed": 5, "path_index": 0, "progress": 0.9, "reward": 20, "armor": 0, "alive": true }
+        ],
+        "resources": { "gold": 0, "lives": 1 }
+      },
+      "actions": [
+        { "type": "tick_game_loop", "times": 5, "deltaMs": 100 }
+      ],
+      "expectedState": {
+        "resources.lives": 0,
+        "gameOver": true,
+        "win": false
+      }
+    }
+  ]
+}

package/skills/tower_defence.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,239 @@
+/**
+ * tower_defence.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * 塔防游戏的核心是固定帧率的游戏循环（tickGameLoop），
+ * 渲染层必须每帧（或每 tickRateMs）调用 tickGameLoop，
+ * 然后根据返回的 lastAttackEvents/lastDeathEvents/lastEscapeEvents
+ * 播放对应的视觉效果（攻击特效、死亡动画、逃跑动画）。
+ *
+ * 不要在每帧全量重建所有精灵——只更新有变化的对象。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、关卡预演等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type TowerDefenceConfig = {
+  /** 初始生命值，默认 20 */
+  initialLives: number;
+  /** 初始金币，默认 150 */
+  initialGold: number;
+  /** 游戏逻辑帧率（毫秒/帧），默认 100 */
+  tickRateMs: number;
+  /** 地图格子数组（宽×高） */
+  gridWidth: number;
+  gridHeight: number;
+  /** 敌人路径坐标序列 */
+  path: Vector2[];
+  /** 波次定义列表 */
+  waves: WaveDefinition[];
+};
+
+// ─── 核心类型 ─────────────────────────────────────────────────────────────────
+
+export type Vector2 = { x: number; y: number };
+export type CellType = 'path' | 'buildable' | 'occupied' | 'empty';
+
+export type TowerType = 'arrow' | 'cannon' | 'magic';
+export type EnemyType = 'basic' | 'fast' | 'armored' | 'boss';
+
+export type TowerStats = {
+  damage: number;
+  range: number;        // 攻击范围（格子数）
+  attackSpeed: number;  // 攻击间隔（毫秒）
+  cost: number;
+  upgradeCost: number;
+  sellValue: number;
+  splashRadius: number; // 范围伤害半径（仅 cannon > 0）
+  slowFactor: number;   // 减速因子（仅 magic < 1.0，其他为 1.0）
+  slowDurationMs: number;
+};
+
+export type Tower = {
+  id: string;
+  type: TowerType;
+  position: Vector2;
+  level: 1 | 2 | 3;
+  stats: TowerStats;
+  lastAttackMs: number;  // 上次攻击的游戏时间戳
+};
+
+export type Enemy = {
+  id: string;
+  type: EnemyType;
+  hp: number;
+  maxHp: number;
+  speed: number;       // 格子/秒
+  pathIndex: number;   // 当前目标路径点索引
+  progress: number;    // 到下一路径点的进度 [0, 1)
+  position: Vector2;   // 当前插值位置（用于渲染）
+  reward: number;      // 击杀奖励金币
+  armor: number;       // 装甲减伤百分比 [0, 1)
+  slowUntilMs: number; // 减速效果结束时间戳
+  alive: boolean;
+};
+
+export type WaveDefinition = {
+  enemies: Array<{ type: EnemyType; count: number }>;
+  spawnIntervalMs: number;  // 每个敌人之间的生成间隔
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type TowerDefenceAction =
+  | { type: 'place_tower'; position: Vector2; towerType: TowerType }
+  | { type: 'upgrade_tower'; towerId: string }
+  | { type: 'sell_tower'; towerId: string }
+  | { type: 'tick'; deltaMs: number }   // 游戏循环帧
+  | { type: 'start_wave' }              // 开始下一波次
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type TowerDefenceState = {
+  grid: CellType[][];        // grid[x][y]
+  path: Vector2[];
+  towers: Tower[];
+  enemies: Enemy[];
+  resources: { gold: number; lives: number };
+  waves: {
+    waveIndex: number;
+    totalWaves: number;
+    waveInProgress: boolean;
+    spawnQueue: Array<{ type: EnemyType; count: number }>;
+    lastSpawnMs: number;
+    spawnIntervalMs: number;
+  };
+  currentTimeMs: number;   // 游戏逻辑时间（累计毫秒）
+  gameOver: boolean;
+  win: boolean;
+  /** 本帧攻击事件（渲染层播放特效） */
+  lastAttackEvents: AttackEvent[];
+  /** 本帧死亡事件（渲染层播放死亡动画） */
+  lastDeathEvents: DeathEvent[];
+  /** 本帧逃跑事件（渲染层扣血UI） */
+  lastEscapeEvents: EscapeEvent[];
+};
+
+// ─── 事件类型（渲染层驱动） ──────────────────────────────────────────────────
+
+export type AttackEvent = {
+  towerId: string;
+  towerType: TowerType;
+  targetEnemyId: string;
+  damage: number;
+  isSplash: boolean;
+  splashTargets?: string[];  // cannon 范围伤害的其他目标 id
+  appliedSlow: boolean;      // magic 是否施加了减速
+};
+
+export type DeathEvent = {
+  enemyId: string;
+  enemyType: EnemyType;
+  position: Vector2;
+  reward: number;
+};
+
+export type EscapeEvent = {
+  enemyId: string;
+  livesAfter: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据关卡配置初始化游戏状态
+ */
+export declare function init(config: TowerDefenceConfig): TowerDefenceState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数）
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: TowerDefenceState, action: TowerDefenceAction): TowerDefenceState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: TowerDefenceState): TowerDefenceState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * placeTower：在指定格子放置防御塔
+ * 验证：格子为 buildable、金币充足
+ * 若不合法则返回原 state（不抛出异常）
+ *
+ * 渲染层在玩家点击放塔时调用，若 state 发生变化则创建新塔精灵
+ */
+export declare function placeTower(
+  state: TowerDefenceState,
+  position: Vector2,
+  towerType: TowerType,
+): TowerDefenceState;
+
+/**
+ * upgradeTower：升级指定防御塔
+ * 验证：塔存在、level < 3、金币充足
+ * 升级后 damage × 1.5，range += 0.5
+ *
+ * 渲染层调用后更新塔精灵的视觉
+ */
+export declare function upgradeTower(
+  state: TowerDefenceState,
+  towerId: string,
+): TowerDefenceState;
+
+/**
+ * tickGameLoop：执行一个完整的游戏逻辑帧
+ * 按顺序执行：波次生成 → 敌人移动 → 逃跑检测 → 塔攻击 → 死亡结算 → 胜负检测
+ * 返回含 lastAttackEvents/lastDeathEvents/lastEscapeEvents 的新状态
+ *
+ * 渲染层每帧调用（或按 tickRateMs 节流调用）
+ */
+export declare function tickGameLoop(
+  state: TowerDefenceState,
+  deltaMs: number,
+): TowerDefenceState;
+
+/**
+ * processAttacks：仅执行塔的攻击阶段（不移动敌人，不生成波次）
+ * 渲染层可用于精细控制各步骤的执行顺序
+ */
+export declare function processAttacks(
+  state: TowerDefenceState,
+): TowerDefenceState;
+
+/**
+ * moveEnemies：仅执行敌人移动阶段
+ * - 敌人按速度（含减速）沿路径推进
+ * - 到达出口的敌人触发逃跑事件
+ * - 更新所有敌人的插值位置（供渲染层同步精灵）
+ */
+export declare function moveEnemies(
+  state: TowerDefenceState,
+  deltaMs: number,
+): TowerDefenceState;
+
+/**
+ * spawnNextWave：手动触发下一波次生成（若上一波已结束）
+ * 更新 waves.waveIndex，初始化 spawnQueue
+ */
+export declare function spawnNextWave(
+  state: TowerDefenceState,
+): TowerDefenceState;

package/skills/tray_container.aicomponent/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: tray_container.aicomponent
+description: 底部篮子/托盘 UI 组件。提供 N 格槽位容器，支持同类聚合插入动画、消除动画（放大淡出）、满溢抖动、重新排列。通过 textureKeyFn 回调注入纹理映射，可用于任何需要收集+消除的玩法。
+triggers: 需要底部篮子、托盘、收集槽、物品容器 UI 时触发。
+---
+
+# 底部篮子/托盘容器（Tray Container）
+
+## 说明
+
+固定在屏幕底部的 N 格槽位容器，用于收集从棋盘进入的物品。支持：
+
+- **同类聚合插入**：新物品自动插到最后一个同色物品旁边
+- **消除动画**：匹配成功时物品放大+淡出消失
+- **重新排列**：物品增删后自动滑动到正确位置
+- **满溢抖动**：篮子满时水平震动反馈
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `src/game/ui/TrayRenderer.ts` | `ref/TrayRenderer.ts` | 完整的篮子渲染器 |
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **三模式统一接口** | Phaser 精灵、HTML CSS、Three.js Mesh 三种实现对 GameScene 暴露相同方法（`addItem`、`rearrangeItems`、`removeMatchedItems`、`shake`），GameScene 无需感知底层模式 |
+| **textureKeyFn 回调注入** | 纹理/颜色映射由调用方提供，TrayRenderer 不绑定具体资产；不同 Remix 变体可用不同颜色映射，组件可复用 |
+| **同类聚合插入位置** | 新物品插到最后一个同类旁边（非末尾），视觉上更直观地表达"同类靠近"语义，是三消类游戏标准 UX |
+| **HTML Overlay 在 Three.js 中** | 3D 项目中 2D UI 用 DOM 比 Three.js Plane Mesh 更简单（CSS transition 动画免费），不占 WebGL 渲染管线 |
+
+## Adapter
+
+- **Role**: `trayContainerRenderer` — 底部 N 格槽位篮子 UI（Phaser/HTML/Three.js 三模式）
+- **Provides**: `TrayRenderer`（Phaser 精灵）、`TrayRendererHtmlOverlay`（CSS DOM）、`TrayRenderer3D`（Three.js Mesh）
+- **Requires**: `phaser.aicomponent`（Phaser 模式）；`threejs.aicomponent`（3D Mesh 模式）
+- **Consumed by**: `game_scene.aicomponent`（持有 trayRenderer 实例）、`slide_out_to_tray_animation.aicomponent`（飞入动画的目标槽位）
+- **Integration point**: `src/game/ui/TrayRenderer.ts` → `Game.ts` 初始化后调用 `setup(areaRect, capacity)`
+
+## Imports
+
+- `phaser.aicomponent`（硬依赖：Phaser.Scene, Phaser.GameObjects, Phaser.Tweens）
+
+## 关键接口
+
+```typescript
+class TrayRenderer {
+  setup(areaRect: Rect, capacity: number): void;
+  getSlotWorldPos(index: number): { x: number; y: number };
+  addItemSprite(item: TrayItem, index: number): Phaser.GameObjects.Image;
+  rearrangeItems(tray: TrayItem[], animate?: boolean): void;
+  removeMatchedItems(matchedIds: string[], onComplete: () => void): void;
+  shake(): void;
+  destroy(): void;
+}
+```
+
+## 配置参数
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| capacity | 7 | 槽位数量 |
+| matchDuration | 300ms | 消除动画时长 |
+| rearrangeDuration | 200ms | 重排动画时长 |
+| shakeAmount | 8px | 抖动幅度 |
+
+## 集成模式
+
+```typescript
+// 初始化
+const trayRenderer = new TrayRenderer(scene);
+trayRenderer.setup({ x, y, width, height }, 7);
+
+// 物品飞入后
+const sprite = trayRenderer.addItemSprite(item, insertIndex);
+trayRenderer.rearrangeItems(currentTray, true);
+
+// 匹配消除
+trayRenderer.removeMatchedItems(matchedIds, () => {
+  trayRenderer.rearrangeItems(newTray, true);
+});
+
+// 满溢
+trayRenderer.shake();
+```
+
+## HTML Overlay 模式（Three.js 推荐）
+
+用 CSS + DOM 实现的篮子，固定在屏幕底部。适用于 Three.js 3D 项目中不需要 3D 深度的 UI 组件。
+
+**优点**：不占用 WebGL 渲染管线 / CSS transition 动画流畅 / 不受 3D 相机变换影响
+
+```typescript
+import { TrayRendererHtmlOverlay } from "../ui/TrayRendererHtmlOverlay";
+
+const tray = new TrayRendererHtmlOverlay({
+  capacity: 7,
+  colorToHex: (color) => CAR_COLOR_CSS_MAP[color],
+});
+tray.setup("game-container");
+
+// 物品飞入后
+tray.addItem(item, insertIndex);
+tray.rearrangeItems(currentTray);
+
+// 消除
+tray.removeMatchedItems(matchedIds, () => {
+  tray.rearrangeItems(newTray);
+});
+```
+
+## 3D Mesh 模式（完全沉浸式）
+
+在 Three.js 场景内用 3D Mesh 排列表示物品。需要每帧调用 `update(dt)` 驱动动画。
+
+```typescript
+import { TrayRenderer3D } from "../ui/TrayRenderer3D";
+
+const tray = new TrayRenderer3D(scene, {
+  capacity: 7,
+  cellSize: 1.0,
+  colorToHex: (color) => CAR_COLOR_HEX_MAP[color],
+});
+tray.setup(new THREE.Vector3(boardCenterX, 0, boardHeight + 2));
+
+// 每帧更新
+onUpdate(dt) { tray.update(dt); }
+
+// 物品飞入后
+tray.addItem(item, insertIndex);
+tray.rearrangeItems(currentTray);
+```
+
+## 模式对比
+
+| 维度 | phaser-sprite | html-overlay | threejs-mesh |
+|------|--------------|-------------|-------------|
+| 引擎 | Phaser 3 | 任意（DOM） | Three.js |
+| 性能 | 好 | 最好 | 中等 |
+| 沉浸感 | 2D | 2D（覆盖） | 完全 3D |
+| 动画 | Phaser Tween | CSS transition | 手写插值 |
+| 复杂度 | 低 | 低 | 中 |