---
name: path_renderer.aicomponent
description: 路径消除玩法的棋盘路径批量渲染器。负责将 ParsedLevel.paths 数组绘制为带颜色和方向箭头的折线路径，支持圆角/方角两种线段风格和 sprite-per-cell 实体精灵模式，使用 Phaser Graphics/Image API。
triggers: 需要在棋盘上绘制或更新彩色折线路径和方向箭头时触发。
---

# 路径批量渲染器（Path Batch Renderer）

## 说明

将 `ParsedLevel.paths` 绘制到棋盘上，支持两种渲染模式：

### 模式 A：线段模式（`renderMode: "line-segment"`）— 默认

- 路径线段：Phaser Graphics 折线，支持圆角（`rounded`）和方角（`square`）两种拐角风格
- 箭头头部：`fillRoundedTriangle` 绘制等腰三角形箭头，指向路径 `direction`
- 颜色：通过 `ThemeManager.getPathColor(pathIndex)` 获取（支持主题替换）
- 批量绘制：接受 `ParsedLevel` 中的全部路径，单次渲染刷新整个棋盘

### 模式 B：精灵铺满模式（`renderMode: "sprite-per-cell"`）— 新增

- 路径覆盖的**每个格子**都渲染一个实体精灵（如小汽车）
- 所有精灵统一朝向路径的 `direction`（推出方向）
- 纹理通过 `colorToTextureKey(path.color)` 映射
- 适用场景：箭头推出类玩法中路径表现为"车队"效果
- 需配合 `board_entity_sprite.aiimage` 提供多色纹理

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|-----|
| `src/game/scenes/GameUI/PathRenderer.ts` | `ref/PathRenderer.ts` | 单条路径的完整渲染逻辑 |
| `src/game/utils/PathRenderers.ts` | `ref/PathRenderers.ts` | 圆角/方角线段渲染实现 + `fillRoundedTriangle` + `PathTrackCell` 类型 |

## Imports

- `phaser.aicomponent`（硬依赖：Phaser.GameObjects.Graphics API）
- `arrow_path_data_format.aicomponent`（硬依赖：ParsedLevel / LevelPath / ArrowDirection 类型）
- `theme_state.aicomponent`（硬依赖：ThemeManager.getPathColor()）

## Recipe

| 决策 | 原因 |
|------|------|
| **与 GameScene 分离** | 渲染逻辑单独封装后，棋盘绘制可独立刷新（不重跑整个 GameScene 生命周期）；且渲染模式可以切换而不影响业务逻辑 |
| **两种渲染模式统一 API** | `line-segment` 和 `sprite-per-cell` 通过同一 `drawPath()` 接口暴露，调用方无需感知模式差异 |
| **颜色通过 ThemeManager 获取** | 路径颜色是主题配置的一部分；PathRenderer 依赖 ThemeManager 而非写死颜色，主题切换时渲染自动跟随 |

## Adapter

- **Role**: `pathBatchRenderer` — 将 ParsedLevel.paths 批量渲染到棋盘的 Graphics/Sprite 渲染器
- **Provides**: `PathRenderer` 类、`fillRoundedTriangle()` 几何工具函数、`PathTrackCell` 类型
- **Requires**: `phaser.aicomponent`、`arrow_path_data_format.aicomponent`、`theme_state.aicomponent`
- **Consumed by**: `game_scene.aicomponent`（持有 PathRenderer 实例，在 `drawPaths()` 中调用）
- **Integration point**: `src/game/scenes/GameUI/PathRenderer.ts` → `Game.ts` 中 `this.pathRenderer = new PathRenderer(this)`

## 关键接口

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: src/game/scenes/GameUI/PathRenderer.ts
  - source: src/game/utils/PathRenderers.ts
outputs:
  - pathRenderer: PathRenderer class
  - pathRenderers: PathTrackCell type + fillRoundedTriangle function
```

## 关键接口

```typescript
class PathRenderer {
  // 绘制单条路径（线段 + 箭头头部）
  drawPath(
    g: Phaser.GameObjects.Graphics,
    path: LevelPath,
    cellSize: number,
    pathIndex: number,
    removed?: boolean,
  ): void;
}

// 格子轨迹单元（用于圆角/方角线段渲染）
type PathTrackCell = {
  x: number; y: number;
  inDir?: string; outDir?: string;
};

// 绘制圆角等腰三角形箭头
function fillRoundedTriangle(
  g: Phaser.GameObjects.Graphics,
  cx: number, cy: number,
  angle: number,        // 朝向角度（弧度）
  color: number,
  size: number,
): void;
```