asset-pipeline

资源流水线：从美术素材到可直接用于引擎的文件

fal-assets 技能负责生成图片。本技能负责生成游戏可接受的文件：尺寸、帧布局、朝向、Alpha 通道、调色板和格式都要正确。所有命令均为 um sprite ... 和 um render3d ...；每条命令都可通过 --help 查看示例。

1. 从游戏本身了解目标格式

转换前，先打开游戏自带的两三份资源，并在 MODLOG.md 中记录：

• **尺寸：**单帧尺寸、每张图包含的帧数，以及布局（垂直条带 / 网格 / 每帧一个文件）。
• **朝向：**美术素材的朝向（Terraria：物品朝右，NPC 面朝左，由引擎翻转），以及轴心点或热点的位置（AoE2：单位的落地点在画布中心）。
• **Alpha 通道：**硬边缘 1 位透明（BC1 透明裁切、像素美术）还是柔和边缘。
• **风格：**调色板大小和描边（大多数像素美术游戏使用 1-2 px 的深色描边）。
• **格式：**PNG、DDS BC1/BC3/BC7、XNB、SLD、图集 + JSON……

绘制代码是最终依据。在 Terraria 中，NPC 帧高 = 纹理高度 / Main.npcFrameCount，因此只要帧尺寸统一，什么尺寸都可以。

2. 2D 流水线

um sprite info raw.png                                    # size, alpha coverage, corner colour
um sprite cutout raw.png cut.png                          # flat bg → transparent (border flood fill keeps interior whites)
um sprite cutout raw.png cut.png --grey 150 --keep-top 0.8   # also remove a soft grey shadow / the floor under it
um sprite fit cut.png item.png --size 64x26 --hard-alpha  # trim + ONE nearest-neighbour scale into the frame
um sprite fit cut.png npc.png --size 38x34 --anchor bottom   # standing sprites sit on the frame's bottom edge
um sprite pixelate cut.png px.png --size 32x32 --colors 16 --outline   # true pixel art from painterly art
um sprite palette px.png px2.png --from stock_sprite.png  # snap to the game's own colours
um sprite frames npc.png frames/ --n 3 --kind bob          # cheap idle animation (bob/squash/wobble/flash)
um sprite sheet sheet.png frames/*.png --vertical         # Terraria-style strip (or --cols N grid)
um sprite slice sheet.png out/ --frame 32x32              # the other direction
um sprite team-mask unit.png unit_grey.png --hue blue     # player-colour mask (+ desaturated sprite)
um sprite preview item.png look.png --scale 6             # checkerboard + zoom: LOOK at it before shipping

• **像素美术：**使用最近邻算法一次性缩放到最终尺寸。切勿对像素美术进行二次缩放。
• **绘制 / HD 美术：**使用 fit --smooth。
• **真实动画帧：**对于上下浮动 / 挤压之外的动画帧，使用 fal edit endpoint，以基础精灵图为参考逐帧生成（“同一架无人机，旋翼倾斜，第 2/4 帧”），然后以相同方式抠图并调整每帧尺寸。或者使用 3D（见下文）。

3. 3D → 精灵图（保持角度和动画一致）

um fal model3d concept.png --name unit                   # textured GLB (Trellis 2 by default)
um render3d assets/gen/unit.glb frames/ --preset aoe2 --length 80 --forward-yaw -90 \
  --anims idle:10:bob,walk:12:walk,attack:16:lunge,death:20:die --shadows --samples 40
um render3d assets/gen/unit.glb side/ --preset side --canvas 128 --length 110 --engine eevee   # platformer facing R + L

预设：

预设	投影	相机	朝向数
aoe2	正交	30°	从东面起顺时针 16 个
iso8	正交	30°	8
trueiso	正交	35.264°	8
topdown	正交	—	8
side	正交	—	2（右、左）
turntable	透视	—	24（宣传图 / 图标旋转）

• --length 设置模型最长水平边在 1x 下的像素长度，因此应与游戏原有单位匹配。
• --forward-yaw 旋转模型，使其正面朝向 +X；检查第一帧。
• --shadows 添加仅阴影渲染通道（*_s.png），用于将阴影单独放置在图层中的引擎。
• 动作：上下浮动、行走、冲刺、死亡、残骸、旋转。
• 然后使用 um sprite sheet 打包，或使用引擎写入工具（例如 examples/aoe2-de-civ/sld.py）。
• 需要 Blender（blender 位于 PATH 中，或设置 BLENDER=...）。Cycles 在可用时会使用 GPU。
• 生成的纹理过暗：调高 --sun / --ambient，或在后期处理中提亮。
• 对于可直接用于游戏的 3D 模型（非精灵图），先使用 um fal run tripo3d/tripo/remesh [email protected] face_limit:=8000 重新网格化，然后在 Blender 中转换（GLB → FBX/OBJ），并遵循引擎的比例和坐标轴约定：Unity 使用 Y 向上、单位为米；Unreal 使用 Z 向上、单位为厘米；Bethesda NIF 使用 PyNifly。

4. 纹理和材质

• 平铺：um fal texture 会生成可平铺纹理。使用 um sprite tile-preview t.png t3.png 检查。对于其他图片，使用 um sprite seamless 修复接缝。
• PBR 材质集：um fal pbr。转换为引擎所需的通道打包格式：Unreal ORM（RGB 分别为环境光遮蔽 / 粗糙度 / 金属度），Unity 金属度-光滑度（Alpha 通道中的光滑度 = 1 - 粗糙度）。
• **DDS：**使用 texconv (DirectXTex) 或设置 DXT 参数的 magick。追求质量时使用 BC7，透明裁切精灵图使用 BC1，Alpha 通道较柔和时使用 BC3。

5. 在游戏中验证

将一份转换后的资源放入游戏，并使用 um win shot 截图，与游戏自带的美术素材并排比较。检查比例、朝向、轴心点、描边和调色板。修正转换方案后，使用相同命令批量转换其余资源（编写一个小脚本或 Makefile，确保可从 assets/gen/ 重现整个流水线）。

6. 转换客串游戏的 Unity 资源（混搭）

使用 UnityPy 读取用户自己的安装文件，并写入本地私有资源包。切勿将输出放入模组、其仓库或发行包中；每位用户都应在自己的副本上运行转换器。

• 内存：UnityPy.load() 会解压整个资源包（一个 865 MB 的资源包占用了 8.7 GB 内存）。 只解压序列化文件，并按块延迟读取 .resS / .resource；让每个转换器模块在独立进程中运行。
• 环境：UnityPy.Environment(path="")，并一起加载相互引用的资源包；否则 UnityPy 会在工作目录中搜索缺失的依赖项。
• **查找资源：**Addressables 资源包名称会在每次更新时哈希处理（按前缀查找）；Addressables 2.x 使用二进制 catalog.bin。通过 GUID 键将游戏对象映射到预制件，不要猜测名称。若有低画质版本，优先使用它（网格相同，纹理更小）。
• **蒙皮网格以绑定姿势存储（通常是 T 姿势）。**要呈现游戏内的外观，请自行在 t = 0 时评估 idle 动画片段（UnityPy 可以读取 AnimationClip 对象，但不会对其进行采样；Generic 动画片段通过路径的 CRC32 将 Transform 绑定），重建世界矩阵，然后进行蒙皮。
• 从容器根节点遍历层级结构，跳过未激活的 GameObject 及其子对象，并丢弃辅助网格（眼睑、地面阴影、模板/描边材质）。
• **坐标轴：**Unity 使用左手坐标系，Minecraft 使用右手坐标系：翻转一个轴上的位置和法线，并反转绕序；翻转 V 轴；限制 UV 范围。使用命名骨骼进行验证（右手应位于右侧）。
• **共享图集：**将每个部件的纹理裁剪到其 UV 边界框，并重新映射 UV。
• 音频：AudioClip.samples 需要 FMOD（fmod_toolkit）；使用 ffmpeg 编码为单声道 OGG。
• **Minecraft 端：**资源包需要 pack.mcmeta（适用于 1.20.1 的 pack_format 为 15）；ResourceLocation 只接受 [a-z0-9_./-]。对于摆姿势的网格，使用 RenderType.entityCutoutNoCull 绘制的自定义网格文件，比 forge:obj 更可靠（方块图集纹理、usemtl）。
• **校验：**重新读取写出的文件，渲染预览图，然后检查效果。