精灵图规范 (Sprite Specification)
本规范详细定义了 AI 世界模拟器项目中所有精灵图（Sprite）的尺寸、格式、内容和处理要求，旨在确保所有视觉资产在前端 PixiJS 渲染时能够正确显示，并符合整体美术风格。
1. 通用规范
- 文件格式：所有精灵图必须为 PNG 格式，支持 Alpha 透明通道。
- 背景：所有精灵图必须具有透明背景。在素材处理阶段，应确保背景完全透明，无半透明像素残留。
- 像素完美：所有精灵图应保持像素完美，无抗锯齿 (anti-aliasing) 或模糊 (blur) 效果。
- 尺寸单位：所有尺寸均以像素 (px) 为单位。
- 命名规范：
- 单张精灵图：
{id}.png(例如house_a.png,npc_programmer_walk_down_01.png) - 图集：
{category}.png(例如residential.png,npc_programmer_walk.png) - 图集 JSON：
{category}.json(例如residential.json,npc_programmer_walk.json)
- 单张精灵图：
2. 精灵图类型与详细规范
2.1 地形瓦片 (Terrain Tiles)
- 尺寸：
32x32像素。 - 内容：草地、泥土、石地、沙地、水域等基础地形元素。
- 特点：必须能够无缝拼接，支持自动瓦片 (Autotile) 变体。
- 季节化：支持多季节变体，例如
grass_spring.png,grass_winter.png。 - 锚点：通常为
(0, 0)(左上角)。
2.2 建筑精灵 (Building Sprites)
- 尺寸：
- 小型建筑 (如房屋)：
64x96像素 (宽x高) - 中型建筑 (如商店、酒馆)：
96x128像素 (宽x高) - 大型建筑 (如广场、市场)：
128x128像素 (宽x高) - 注意：这些是最终处理后的画布尺寸，AI 生成的原始图会更大，需要经过裁剪和缩放。
- 小型建筑 (如房屋)：
- 内容：各种住宅、商业、公共、工业建筑。
- 透视：2.5D 俯视角。
- 阴影：建筑底部应包含像素化的阴影，与建筑主体融合，增强立体感。
- 锚点：
(0.5, 1)(底部中心)。这意味着精灵的(x, y)坐标将对应其底部中心的像素点。在素材处理时，应确保建筑的视觉底部（例如大门底部或地基边缘）与图片的底部边缘对齐，以便锚点计算准确。 - 季节化：建筑主体不进行季节化变体，通过 PixiJS
ColorMatrixFilter进行色调调整。冬季可能需要单独的雪顶叠加层。
2.3 角色精灵 (Character Sprites)
- 尺寸：
32x48像素 (宽x高)。 - 内容：NPC 和玩家角色，包含不同职业、性别、外观等。
- 动画：每个角色应包含至少 4 个方向 (上、下、左、右) 的行走动画，每个方向至少 8 帧。
- 锚点：
(0.5, 1)(底部中心)。 - 图集结构：每个角色的每个动作方向可以打包成一个独立的 JSON 图集，例如
npc_programmer_walk.json。
2.4 装饰物精灵 (Decoration Sprites)
- 尺寸：根据实际物体大小而定，例如树木
32x48，灌木32x32，花朵16x16。 - 内容：树木、灌木、花卉、路灯、围栏、石头等。
- 透视：2.5D 俯视角。
- 阴影：应包含像素化的阴影。
- 锚点：通常为
(0.5, 1)(底部中心)，对于地面装饰物可能为(0.5, 0.5)(中心)。 - 季节化：自然类装饰物（如树木、花卉）应支持多季节变体。
2.5 UI 图标 (UI Icons)
- 尺寸：
16x16或24x24像素。 - 内容：各种界面图标，如职业图标、状态图标、操作按钮图标等。
- 背景：透明背景。
- 锚点：
(0.5, 0.5)(中心)。
3. 素材处理要求
所有 AI 生成的原始图像在导入前端之前，必须经过 scripts/process_assets.py 脚本的严格处理，以确保符合上述规范：
- 背景透明化：使用图像处理库（如 Pillow, OpenCV）进行背景移除，确保 Alpha 通道干净。
- 内容裁剪：自动检测图像中的非透明区域，裁剪掉多余的透明边距。
- 等比缩放：将裁剪后的图像等比缩放到目标尺寸。如果原始图像宽高比与目标尺寸不符，应在保持比例的前提下进行缩放，并填充透明区域或进行居中裁剪。
- 像素边缘处理：对 Alpha 通道进行二值化处理，消除半透明像素，确保像素边缘清晰。
- 输出校验：脚本应能校验处理后的精灵图是否符合尺寸、透明度等规范。
作者：Manus AI 日期：2026年7月10日