asset-pipeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Asset pipeline: from art to engine-ready files

资产管线：从美术素材到引擎就绪文件

The fal-assets skill makes pictures. This skill makes files the game accepts: the right size, frame layout, orientation, alpha, palette and format. All commands are

um sprite ...

and

um render3d ...

; each has

--help

with examples.

fal-assets skill 用于生成图片。这个 skill 用于生成游戏引擎可接受的文件：尺寸、帧布局、朝向、Alpha、调色板和格式都要正确。所有命令均为

um sprite ...

和

um render3d ...

；每个命令的

--help

中都提供了示例。

1. Learn the target format from the game itself

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

Before converting anything, open two or three of the game's own assets and write down in MODLOG.md:

Dimensions: frame size, frames per sheet, and the layout (vertical strip / grid / one file per frame).
Orientation: which way the art faces (Terraria: items point right, NPCs face left, the engine flips them), and where the pivot or hotspot sits (AoE2: the unit's ground point at the canvas centre).
Alpha: hard 1-bit edges (BC1 punch-through, pixel art) or soft.
Style: palette size and outline (dark 1-2 px outline in most pixel-art games).
Format: PNG, DDS BC1/BC3/BC7, XNB, SLD, atlas + JSON...

The draw code is the final authority. In Terraria, NPC frame height = texture height /

Main.npcFrameCount

, so any consistent frame size works.

转换任何素材之前，先打开游戏自身的两到三个素材，并在 MODLOG.md 中记录：

尺寸： 帧尺寸、每个 Sprite Sheet 中的帧数，以及布局（纵向序列条/网格/每帧一个文件）。
朝向： 美术素材面朝哪个方向（Terraria：物品朝右，NPC 朝左，引擎会翻转它们），以及 pivot 或 hotspot 的位置（AoE2：单位的地面锚点位于画布中心）。
Alpha： 硬 1-bit 边缘（BC1 punch-through、像素艺术），还是柔和 Alpha。
风格： 调色板颜色数量与描边（大多数像素艺术游戏使用深色 1–2 px 描边）。
格式： PNG、DDS BC1/BC3/BC7、XNB、SLD、图集 + JSON……

绘制代码是最终判定标准。在 Terraria 中，NPC 帧高 = 纹理高度 /

Main.npcFrameCount

，因此只要每帧尺寸一致即可。

2. 2D pipeline

2. 2D 管线

bash

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

Pixel art: scale once, with nearest neighbour, to the final size. Never scale pixel art twice.
Painted / HD art: use
```
fit --smooth
```
.
Real frames: for animation frames beyond bob/squash, generate each frame with the fal edit endpoint using the base sprite as reference ("same drone, rotors tilted, frame 2 of 4"), then cut out and fit each frame the same way. Or go 3D (below).

bash

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
```
。
完整动画帧： 对于 bob/squash 之外的动画帧，使用基础 Sprite 作为参考，通过 fal edit 端点逐帧生成（“同一架无人机，旋翼倾斜，第 2 帧，共 4 帧”），然后以相同方式对每一帧进行抠图和适配。也可以改用 3D（见下文）。

3. 3D → sprites (consistent angles and animations)

3. 3D → Sprite（保持一致的角度和动画）

bash

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

Presets:

Preset	Projection	Camera	Facings
`aoe2`	ortho	30°	16 clockwise from east
`iso8`	ortho	30°	8
`trueiso`	ortho	35.264°	8
`topdown`	ortho	—	8
`side`	ortho	—	2 (right, left)
`turntable`	persp	—	24 (promo/icon spins)

```
--length
```
sets the model's longest horizontal side in pixels at 1x, so match stock units.
```
--forward-yaw
```
turns the model so its nose faces +X; check the first frame.
```
--shadows
```
adds a shadow-only pass (
```
*_s.png
```
) for engines that keep shadows in their own layer.
Motions: bob, walk, lunge, die, wreck, spin.
Then pack with
```
um sprite sheet
```
, or with an engine writer (e.g.
```
examples/aoe2-de-civ/sld.py
```
).
Needs Blender (
```
blender
```
on PATH or
```
BLENDER=...
```
). Cycles uses the GPU when available.
Dark generated textures: raise
```
--sun
```
/
```
--ambient
```
, or brighten in post.
For game-ready 3D (not sprites), remesh with
```
um fal run tripo3d/tripo/remesh mesh_url=@unit.glb face_limit:=8000
```
, then convert in Blender (GLB → FBX/OBJ) with the engine's scale and axis convention: Unity Y-up metres, Unreal Z-up centimetres, Bethesda NIF via PyNifly.

bash

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
```
），供将阴影保存在独立图层的引擎使用。
动作：bob、walk、lunge、die、wreck、spin。
然后使用
```
um sprite sheet
```
打包，或使用引擎写入器（例如
```
examples/aoe2-de-civ/sld.py
```
）。
需要 Blender（PATH 中有
```
blender
```
，或设置
```
BLENDER=...
```
）。Cycles 在可用时会使用 GPU。
生成的纹理较暗时：提高
```
--sun
```
/
```
--ambient
```
，或在后处理中提亮。
对于游戏就绪的 3D 素材（而非 Sprite），先通过
```
um fal run tripo3d/tripo/remesh mesh_url=@unit.glb face_limit:=8000
```
执行 remesh，然后按引擎的缩放和轴向约定在 Blender 中转换（GLB → FBX/OBJ）：Unity 使用 Y-up 米制，Unreal 使用 Z-up 厘米制，Bethesda NIF 则通过 PyNifly 处理。

4. Textures and materials

4. 纹理与材质

Tiling:
```
um fal texture
```
generates it tiled. Check with
```
um sprite tile-preview t.png t3.png
```
. Fix seams on other images with
```
um sprite seamless
```
.
PBR sets:
```
um fal pbr
```
. Convert to the engine's packing: Unreal ORM (occlusion/roughness/metal in RGB), Unity metallic-smoothness (smoothness = 1 - roughness in alpha).
DDS: texconv (DirectXTex) or
```
magick
```
with DXT settings. BC7 for quality, BC1 for cutout sprites, BC3 when alpha is soft.

平铺：
```
um fal texture
```
会生成平铺纹理。使用
```
um sprite tile-preview t.png t3.png
```
检查。其他图片的接缝问题可使用
```
um sprite seamless
```
修复。
PBR 贴图组：
```
um fal pbr
```
。转换为引擎的打包方式：Unreal ORM（occlusion/roughness/metal 打包到 RGB 中），Unity metallic-smoothness（smoothness = 1 - roughness 位于 Alpha 通道中）。
DDS： texconv (DirectXTex) 或使用带 DXT 设置的
```
magick
```
。追求质量时使用 BC7，抠图 Sprite 使用 BC1，Alpha 柔和时使用 BC3。

5. Verify in the game

5. 在游戏中验证

Put one converted asset into the game and screenshot it next to stock art (

um win shot

). Check the scale, facing, pivot, outline and palette. Fix the recipe, then batch-convert the rest with the same commands (a small script or Makefile, so the pipeline is reproducible from

assets/gen/

将一个转换后的素材放入游戏，并与现有美术素材并排截图（

um win shot

）。检查缩放比例、朝向、pivot、描边和调色板。修正转换方案后，使用相同命令批量转换其余素材（可使用小型脚本或 Makefile，使管线能够从

assets/gen/

重复执行）。