七、美术 art.ini 与 PNG 素材

art.ini 是美术资源注册表。它的作用：给某个 artKey（对应单位/建筑的 art= 字段）指定使用外部 PNG 精灵，替代默认的 Canvas2D 程序化绘制。格式与游戏本体 data/art_ini.js 一致。

7.1 完整示例

MOD 内推荐写法——file 可省略（由 mod.ini 的 res= 自动按 ROOT:/res/文件名 注册）：

# art.ini（MOD 内）
[cz_flameTank]
use_png=true
se=1.5
facing=rotate

[cz_fort]
use_png=true
icon_file=cz_fort_icon
icon_w=56
icon_h=46

等效的显式写法（file 用 ROOT 前缀指向包内）：

[cz_flameTank]
use_png=true
file=ROOT:/res/cz_flameTank.png
se=1.5
facing=rotate

7.2 字段速查

[artKey]>use_png= (boolean) — 启用外部 PNG。

设为 true 才使用 PNG；省略或 false 使用程序化绘制。

[artKey]>file= (file，可选) — PNG 文件路径。

路径规则见下节。MOD 场景下可省略（res= 已自动注册 file），或写 ROOT:/res/文件名.png 显式指向包内。官方数据中写 ROOT:/foo.png → data/foo.png。

[artKey]>se= (number) — 缩放倍率。

PNG 精灵相对默认尺寸的缩放，如 1.5。

[artKey]>facing= (enum: none|flip|rotate) — 朝向处理。

none 不处理（默认）；flip 水平翻转（载具）；rotate 按方向旋转（步兵）。

[artKey]>icon_file= (file) — 图标 PNG（可选）。

建造栏图标。默认图标尺寸 56×46，可用 icon_w/icon_h 指定原始尺寸。

[artKey]>ox= / oy= (int) — 像素偏移。

可选，微调精灵在格子内的位置。

7.3 PNG 路径规则

引擎解析 file= / icon_file= 时遵循（与 art.js._resolvePNGPath 一致）：

ROOT:/foo.png     →  数据源根目录 + foo.png
                   官方数据：data/foo.png
                   MOD 数据：data/uploads_mods/{用户}/{modId}/foo.png
ROOT:/res/foo.png →  数据源根目录 + res/foo.png（MOD 内即「包内 res/」）
foo.png           →  data/png/foo.png        （默认补 data/png/ 前缀）
省略扩展名         →  自动补 .png

ROOT 的含义：ROOT:/ 永远指向当前数据源的根目录——官方数据就是 data/，MOD 内就是模组包根目录（解压后的 data/uploads_mods/{用户}/{modId}/）。因此 MOD 内所有路径都以模组根为基准，写 ROOT:/res/xxx.png 即可指向自己包内的素材。

res/ 素材免写路径：只要在 mod.ini 的 res= 字段列出文件名，引擎就会自动以 ROOT:/res/文件名 注册，你无需手写完整路径。art.ini 里只需要配置 se/facing/icon_file 等附加属性。

7.4 使用流程

把你的 PNG 放入包内 res/（文件名即素材名，如 cz_flameTank.png）；
在 mod.ini 的 res= 字段列出它：res=cz_flameTank.png；
可选：在 art.ini 中为它配置 use_png=true + se/facing/icon_file 等；
单位的 art=cz_flameTank 即自动使用该 PNG。

渲染优先级：.r 素材 → PNG（use_png）→ 程序化绘制。即 MOD 提供的 .r 素材拥有最高优先级，可覆盖官方贴图。

7.5 透明与尺寸建议

PNG 建议使用透明背景（RGBA），尺寸对齐 TILE（建筑：占地格数 × 24px，如 2x2 建筑 = 48×48）；
载具 PNG 建议包含 16 个方向或至少朝右主视角（配合 facing）；
图标 PNG 建议 56×46 或指定 icon_w/icon_h。

← 国家代码 .r 素材格式详解 →