@playcraft/skills 0.0.2

package/skills/board_entity_sprite.aiimage/SKILL.md

@@ -0,0 +1,255 @@
+---
+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 分析 |

package/skills/board_entity_sprite.aiimage/manifest.json

@@ -0,0 +1,153 @@
+{
+  "schemaVersion": 1,
+  "atomId": "board_entity_sprite.aiimage",
+  "bundleType": "aiimage",
+  "category": "visual",
+  "mode": "generative",
+  "label": {
+    "zh": "棋盘实体精灵（单图旋转）",
+    "en": "Board entity sprite (single image + rotation)"
+  },
+  "outputModes": ["2d-sprite", "3d-model"],
+  "tags": [
+    "visual",
+    "sprite",
+    "entity",
+    "board",
+    "direction",
+    "top-down",
+    "puzzle",
+    "car",
+    "vehicle",
+    "arrow-replacement",
+    "directional-indicator",
+    "3d-model",
+    "glb",
+    "threejs"
+  ],
+  "bindingRoles": [
+    "boardEntitySprite",
+    "directionalIndicator"
+  ],
+  "generation3D": {
+    "kind": "3d-model",
+    "methods": ["procedural-geometry", "loaded-glb", "ai-generated"],
+    "colorVariants": {
+      "strategy": "material-color-swap",
+      "description": "一个 geometry + N 种 MeshStandardMaterial.color = 多色变体，无需生成多个模型文件",
+      "colorSet": ["teal", "red", "yellow", "purple", "green", "orange", "blue", "pink", "cyan", "salmon"],
+      "codePattern": "const mat = new THREE.MeshStandardMaterial({ color: CAR_COLORS[i] }); const mesh = new THREE.Mesh(sharedGeo, mat);"
+    },
+    "canonicalFacing": "+Z",
+    "normalize": "fit-unit-cube",
+    "format": "glb",
+    "postProcess": [
+      { "step": "normalize-size", "method": "fit-to-unit-cube", "description": "缩放模型使其 bounding box 适配 1×1×1" },
+      { "step": "verify-orientation", "expected": "+Z", "fallback": "rotate-Y-180" },
+      { "step": "center-origin", "description": "确保模型原点在几何中心底部" }
+    ]
+  },
+  "generation": {
+    "kind": "single-image",
+    "promptTemplate": "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",
+    "variables": {
+      "entity": {
+        "type": "string",
+        "description": "实体类型，替换 prompt 中的 {entity}",
+        "examples": ["car", "race car", "taxi", "bus", "airplane", "rocket", "boat", "ship", "fish", "turtle", "bird", "UFO", "ambulance", "fire truck"]
+      }
+    },
+    "aspectRatio": "1:1",
+    "model": "google/gemini-3.1-flash-image-preview",
+    "style": "cartoon-flat",
+    "platformSkill": "playcraft-image-generation",
+    "postProcess": [
+      { "step": "remove-background", "method": "floodfill" },
+      { "step": "trim" },
+      { "step": "verify-orientation", "expected": "up", "fallback": "rotate-180" },
+      { "step": "convert", "format": "webp", "quality": 90 }
+    ],
+    "variants": {
+      "description": "可选：批量生成多色变体。为同一实体生成 N 种颜色版本。",
+      "colorSet": ["teal", "red", "yellow", "purple", "green", "orange", "blue", "pink", "cyan", "salmon"],
+      "promptTemplate": "top-down bird's eye view of a cute cartoon {entity}, {color} colored body, facing upward, simple flat design, bright vivid colors, game asset, white background, centered on canvas, no shadow, 256x256 icon style",
+      "outputPattern": "{entity}_{color}.webp",
+      "referenceImage": "{entity}.webp"
+    }
+  },
+  "result": {
+    "outputFile": "{entity}.webp",
+    "format": "webp",
+    "usage": "single-image-with-rotation",
+    "constraints": {
+      "transparent": true,
+      "centered": true,
+      "defaultFacing": "declared-in-binding"
+    }
+  },
+  "binding": {
+    "role": "boardEntitySprite",
+    "target": "assets/images/{entity}.webp",
+    "type": "image-asset-reference",
+    "integration": {
+      "pattern": "single-image-rotation",
+      "defaultFacing": "down",
+      "directionToAngle": {
+        "_comment": "旋转角度取决于图片默认朝向。以 defaultFacing=down 为例：",
+        "up": "Math.PI",
+        "right": "-Math.PI / 2",
+        "down": "0",
+        "left": "Math.PI / 2"
+      },
+      "codePattern": {
+        "import": "import entityImg from 'assets/images/{entity}.webp';",
+        "preload": "this.load.image('{entity}', entityImg);",
+        "create": "const sprite = scene.add.image(x, y, '{entity}').setOrigin(0.5).setRotation(angle);",
+        "scale": "sprite.setScale(Math.min(targetSize / sprite.width, targetSize / sprite.height));",
+        "tint": "sprite.setTint(color); // 可选：着色或阻挡变红"
+      }
+    },
+    "integration3D": {
+      "pattern": "single-model-color-swap",
+      "canonicalFacing": "+Z",
+      "directionToAngleY": {
+        "_comment": "Y 轴旋转角度。模型默认朝 +Z（ArrowDirection.Down 对应角度 0）",
+        "up": "Math.PI",
+        "right": "Math.PI / 2",
+        "down": "0",
+        "left": "-Math.PI / 2"
+      },
+      "codePattern": {
+        "import": "import carModelUrl from 'assets/models/car.glb';",
+        "load": "loader.loadAll({ models: [{ key: 'car', url: carModelUrl }] })",
+        "create": "const gltf = loader.getModel('car'); const mesh = gltf.scene.children[0].clone(); mesh.rotation.y = directionToAngleY(direction);",
+        "colorVariant": "const mat = (mesh as THREE.Mesh).material = new THREE.MeshStandardMaterial({ color: colorHex }); ",
+        "scale": "mesh.scale.setScalar(cellSize * 0.8);"
+      }
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "ref": [
+      "ref/car.webp",
+      "ref/car.png",
+      "ref/ProceduralCar.ts"
+    ]
+  },
+  "refAssets": {
+    "car.webp": {
+      "description": "俯视卡通小汽车（默认朝下），24KB webp，已完成去背景+裁切+压缩",
+      "defaultFacing": "down",
+      "size": "380x496",
+      "generatedWith": {
+        "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",
+        "model": "google/gemini-3.1-flash-image-preview",
+        "postProcess": ["remove-background(floodfill)", "trim", "convert(webp,q90)"]
+      }
+    },
+    "car.png": {
+      "description": "同上的 PNG 高清版本（透明背景），409KB，作为备份或需要无损场景使用",
+      "defaultFacing": "down"
+    }
+  }
+}