---
name: board_entity_sprite.aiimage
description: 棋盘实体精灵封包（单图+旋转） - 生成俯视方向实体（汽车/飞机/动物等），通过代码旋转实现4方向，替代传统箭头或4帧精灵图集方案
triggers: 汽车,car,实体,entity,精灵,sprite,方向,direction,俯视,top-down,棋盘,board,替换箭头,arrow replacement,停车,parking,逃脱,escape,puzzle
---

# board_entity_sprite.aiimage

棋盘实体精灵封包。生成一张俯视角度的实体图片（如小汽车），通过运行时旋转实现上/下/左/右四个方向。

**相比旧版 4 帧精灵图集方案的优势：**
- 体积更小（1张 webp vs 4帧 png）
- AI 生图成功率更高（单物体 vs 4物体对齐）
- 代码更灵活（任意角度旋转，不限于4方向）
- 支持 tint 着色（同一图片不同颜色）

## Recipe

### Prompt 模板

```
top-down bird's eye view of a cute cartoon {entity}, facing upward, simple flat design, bright vivid colors, game asset, white background, centered on canvas, no shadow, 256x256 icon style
```

**变量 `{entity}` 示例：**
- 交通工具：`car` / `race car` / `taxi` / `bus` / `airplane` / `rocket` / `boat`
- 动物：`fish` / `turtle` / `bird` / `cat`
- 其他：`UFO` / `finger pointing` / `arrow sign`

### 生成与后处理步骤

```bash
# 1. AI 生成图片
playcraft tools generate-image \
  --prompt "top-down bird's eye view of a cute cartoon car, facing upward, simple flat design, bright vivid colors, game asset, white background, centered on canvas, no shadow, 256x256 icon style" \
  --aspect-ratio 1:1 \
  --image-model google/gemini-3.1-flash-image-preview \
  --output assets/images/car_raw.jpg

# 2. 去除背景（AI 生图通常为白色/浅色背景）
playcraft image remove-background \
  --input assets/images/car_raw.jpg \
  --output assets/images/car.png

# 3. 裁切透明边界
playcraft image trim \
  --input assets/images/car.png \
  --output assets/images/car_trimmed.png

# 4. 转为 webp（压缩 90%+）
playcraft image convert \
  --input assets/images/car_trimmed.png \
  --output assets/images/car.webp \
  --quality 90

# 5. 清理中间文件
rm assets/images/car_raw.jpg assets/images/car_trimmed.png
```

### 风格变体

| 风格 | prompt 后缀 |
|------|------------|
| 卡通可爱 | `cute cartoon, rounded shapes, playful` |
| 像素风 | `pixel art style, 32x32, retro game` |
| 写实 | `realistic 3D render, studio lighting` |
| 霓虹科技 | `neon glowing, cyberpunk style, dark glow` |
| 手绘涂鸦 | `hand-drawn sketch, crayon style, children's drawing` |

## Result

- **产物文件**：`{entity}.webp`
- **格式**：WebP（透明背景），通常 20-50KB
- **图片特征**：
  - 俯视角度（top-down bird's eye view）
  - 居中无阴影
  - 透明背景
  - 默认朝向：需确认（通常朝上或朝下，取决于 AI 输出）

## Binding

- **Binding Role**：`boardEntitySprite`（兼容旧角色 `directionalIndicator`）
- **挂载目标**：`assets/images/{entity}.webp`
- **引用类型**：`image-asset-reference`
- **集成模式**：`single-image-rotation`

### 代码集成模式

#### 1. 导入与加载（Preloader）

```typescript
// 导入
import carImage from "assets/images/car.webp";

// Preloader.preload()
this.load.image("car", carImage);
```

#### 2. 创建精灵（渲染器）

```typescript
// 在棋盘格子中心创建精灵
const sprite = scene.add.image(cellCenterX, cellCenterY, "car");
sprite.setOrigin(0.5);

// 缩放到格子大小
const targetSize = cellSize * 0.8;
const scale = Math.min(targetSize / sprite.width, targetSize / sprite.height);
sprite.setScale(scale);

// 旋转到目标方向
sprite.setRotation(directionToAngle(path.direction));
```

#### 3. 方向角度映射

图片默认朝向决定了旋转映射。**生成后必须确认默认朝向并声明。**

```typescript
// 若图片默认朝下（车头在图片下方）：
function directionToAngle(direction: string): number {
  switch (direction) {
    case "down":  return 0;           // 不旋转
    case "up":    return Math.PI;     // 180°
    case "left":  return Math.PI / 2; // 90°
    case "right": return -Math.PI / 2;// -90°
  }
}

// 若图片默认朝上（车头在图片上方）：
function directionToAngle(direction: string): number {
  switch (direction) {
    case "up":    return 0;
    case "down":  return Math.PI;
    case "right": return Math.PI / 2;
    case "left":  return -Math.PI / 2;
  }
}
```

#### 4. 可选：着色/阻挡反馈

```typescript
// 被阻挡时变红
sprite.setTint(0xff4444);

// 正常状态清除 tint
sprite.clearTint();
```

#### 5. 动画中使用

```typescript
// 消除滑出动画：创建临时精灵放入容器
const container = scene.add.container(0, 0);
const car = scene.add.image(hx, hy, "car").setOrigin(0.5).setRotation(angle).setScale(scale);
container.add(car);

scene.tweens.add({
  targets: container,
  x: dx * slideDistance,
  y: dy * slideDistance,
  alpha: 0,
  duration: 400,
  ease: "Power2",
  onComplete: () => container.destroy(),
});
```

## 与旧版 direction_arrow_sprite 的对比

| 维度 | 旧版（4帧精灵图集） | 新版（单图旋转） |
|------|--------------------|--------------------|
| 图片数量 | 1张含4帧 | 1张单图 |
| 文件体积 | ~100-200KB (png) | ~20-50KB (webp) |
| AI 生图难度 | 高（需4个方向对齐） | 低（只需1个朝向） |
| 方向支持 | 仅4方向 | 任意角度 |
| 颜色变体 | 需重新生成 | setTint() 即时变色 |
| 代码复杂度 | 需 spritesheet + frame index | 简单 image + setRotation |

## Skill Definition

```yaml
tools:
  - bash
  - write
  - read
inputs:
  - entity: string (实体类型，如 "car")
outputs:
  - sprite: assets/images/{entity}.webp
  - integration: Preloader 加载 + Image 精灵 + 旋转方向映射
```

## 注意事项

1. **确认默认朝向**：AI 生成的图片朝向不确定，生成后必须目视确认并在 `directionToAngle` 映射中正确声明
2. **居中对齐**：图片内容必须居中，否则旋转时会偏移
3. **正方形画布**：尽量保持宽高接近（trim 后），旋转才不会出现裁切
4. **Phaser 坐标系**：Phaser 中 rotation 正值为顺时针

## 3D 模型模式（Three.js）

当 DAG 引擎根节点为 `threejs.aicomponent` 时，本 skill 输出 3D 模型而非 2D 图片。

### 多色变体策略

3D 模式下多色变体比 2D 简洁得多——**只需一个模型文件 + 换材质颜色**：

```typescript
import * as THREE from "three";

// 加载一次模型
const gltf = assetLoader.getModel("car");
const baseGeo = (gltf.scene.children[0] as THREE.Mesh).geometry;

// 为每种颜色创建变体（共享 geometry，独立 material）
const CAR_COLORS = [0x00796b, 0xe53935, 0xfdd835, 0x8e24aa, 0x43a047,
                    0xf4511e, 0x1e88e5, 0xd81b60, 0x00acc1, 0xff8a65];

function createCarMesh(colorIndex: number): THREE.Mesh {
  const mat = new THREE.MeshStandardMaterial({ color: CAR_COLORS[colorIndex] });
  const mesh = new THREE.Mesh(baseGeo, mat);
  mesh.castShadow = true;
  mesh.receiveShadow = true;
  return mesh;
}
```

### 朝向约定

- 模型默认朝向 **+Z**（即 `ArrowDirection.Down` 对应角度 0）
- 通过 `mesh.rotation.y = directionToAngleY(path.direction)` 旋转到目标方向
- 如果加载的 .glb 模型朝向不正确，在后处理阶段旋转校正

### 归一化

模型加载后应 fit 到单位立方体（1×1×1），实际渲染时通过 `mesh.scale.setScalar(cellSize * ratio)` 缩放到棋盘格子大小。

### 模型来源

| 方式 | 说明 | 适用场景 |
|------|------|---------|
| `procedural-geometry` | Three.js 内置几何体组合 | 快速原型/简单形状 |
| `loaded-glb` | 加载外部 .glb 文件 | 精细模型/艺术资产 |
| `ai-generated` | AI 生成 3D 模型 | 自动化流水线 |

### 与 2D 模式对比

| 维度 | 2D (sprite) | 3D (model) |
|------|------------|------------|
| 多色变体 | AI 生 N 张图 | 一个模型 + N 种 material.color |
| 朝向问题 | AI 生图方向不一致 | 加载后统一校正 |
| 文件大小 | N × 图片大小 | 1 个 .glb (通常 < 100KB) |
| 朝向验证 | 视觉模型检测 | bounding box 分析 |