素材管线 (Asset Pipeline)

素材管线是 AI 世界模拟器项目中，从 AI 生成原始图像到前端 PixiJS 渲染的完整自动化流程。本管线旨在提高素材生产效率，确保视觉风格一致性，并优化前端加载性能。

1. 流程概览

2. 阶段详解

2.1 AI 图像生成

工具：Agnes AI (或其他兼容的图像生成服务)
模型：agnes-image-2.0-flash (推荐，速度快，像素风格表现好)
输入：详细的 Prompt 文本，遵循 docs/zh/art/AIPromptGuide.md 中的规范。
- 关键 Prompt 元素：Dark pixel art style, top-down perspective, transparent background PNG, pixel perfect, game asset, no anti-aliasing, no blur。
输出：通常为 1024x1024 像素的 PNG 图像，可能包含透明背景，但边缘可能不完美。

2.2 素材处理脚本

工具：Python 脚本 (scripts/process_assets.py)
功能：
1. 下载原始图像：从 AI 服务返回的 URL 下载生成的图像。
2. 背景移除/清理：对图像进行精确的背景移除，特别是处理 AI 生成图像可能存在的半透明边缘或“脏像素”。确保像素边缘清晰，符合像素艺术风格。
3. 裁剪与缩放：将图像裁剪到目标内容区域，并等比缩放到规范尺寸（例如，将一个 1024x1024 的原始图缩放并裁剪为 96x128 的建筑精灵图）。确保裁剪后的图像底部边缘与建筑的视觉底部对齐。
4. 保存单张精灵图：将处理后的单张精灵图保存到按类别组织的临时目录中。
输出：符合 docs/zh/art/SpriteSpec.md 规范的单张 PNG 精灵图。

2.3 图集打包

工具：TexturePacker (或其他兼容的精灵图集工具)
功能：将同一类别的所有单张精灵图打包成一个精灵图集，包括一张 PNG 大图和一份 JSON 描述文件。
TexturePacker 配置：
- format: pixijs (生成 PixiJS 兼容的 JSON 格式)
- textureFormat: pngmaxWidth, maxHeight: 根据实际需求设置，例如 2048x2048 或 4096x4096。
- padding: 2 (精灵图之间的间隔，避免边缘像素溢出)
- extrude: 1 (边缘像素复制，避免纹理采样时出现黑边)
- allowRotation: false (像素艺术通常不旋转)
- detectIdentical: true (检测并合并相同的精灵)
- trimMode: trim (裁剪掉透明像素，JSON 中记录原始尺寸和裁剪信息)
输出：{category}.png (精灵大图) 和 {category}.json (精灵帧数据)。

2.4 R2 对象存储

工具：Cloudflare R2 (对象存储服务)
功能：将打包好的精灵图集 (PNG 和 JSON 文件) 上传到 R2 存储桶，并配置 CDN 加速。
目录结构：建议按类别组织，例如 buildings/{category}.png 和 buildings/{category}.json。
优势：利用 Cloudflare 的全球 CDN 网络，确保前端应用能够快速、稳定地加载素材。

2.5 前端应用加载与渲染

工具：PixiJS 8, ai-world-sim-web 项目中的 src/utils/textureAtlas.ts 模块。
加载：前端通过 Assets.load(${R2_BASE}/${category}.json) 加载精灵图集的 JSON 描述文件，PixiJS 会自动处理 PNG 大图的加载。
获取纹理：使用 getAtlasFrame(atlasName, frameName) 从已加载的图集中获取单个精灵的 PIXI.Texture。
渲染：在 src/renderers/ 目录下的各个渲染器组件中，使用 PIXI.Sprite 结合获取到的纹理进行渲染。确保正确设置 sprite.anchor 和 sprite.position，并根据 docs/zh/frontend/RendererDesign.md 中的层级规范进行深度排序。

3. 自动化脚本

整个素材管线将通过一系列自动化脚本 (package.json 中的 scripts) 串联起来，实现一键生成、处理、打包和上传。

json

// package.json (ai-world-sim-docs)
{
  "scripts": {
    "generate:ai": "node scripts/generate-buildings.cjs", // 调用 Agnes AI 生成原始图
    "process:assets": "python3 scripts/process_assets.py", // 处理原始图，生成单张精灵图
    "pack:atlases": "texturepacker --config texturepacker.json", // 打包图集
    "upload:r2": "node scripts/upload-to-r2.cjs", // 上传到 R2
    "build:assets": "npm run generate:ai && npm run process:assets && npm run pack:atlases && npm run upload:r2"
  }
}

注意：generate-buildings.cjs 和 upload-to-r2.cjs 可能会被整合到 process_assets.py 中，以实现更紧密的集成。

作者：Manus AI 日期：2026年7月10日

素材管线 (Asset Pipeline) ​

1. 流程概览 ​

2. 阶段详解 ​

2.1 AI 图像生成 ​

2.2 素材处理脚本 ​

2.3 图集打包 ​

2.4 R2 对象存储 ​

2.5 前端应用加载与渲染 ​

3. 自动化脚本 ​