For Mod Authors

资源替换 Mod 命名规则说明

本文档面向替换静态立绘、编队头像/半身像、动态立绘、战斗小人、基建小人的 Mod 作者。 内容基于当前项目实际实现整理，尽量区分“推荐写法”和“兼容写法”。

通用结论

• 目录支持多级子目录。
• DISABLE_ 前缀目录会被跳过，不加载其中的 Mod 文件。
• 修改后按 F10 刷新，无需重启游戏。

命名原则

• 优先沿用游戏原始资源名或资源名加兼容前缀。
• 不同 Mod 目录中不要放同名 key，避免冲突。
• 推荐直接复制现有可用示例后再改图。

热刷新说明

• F10 会刷新静态立绘、头像、语音、Spine 等索引。
• 刷新可能在战斗锁期间被跳过或延后。
• logs 和 dump 目录属于保留目录，会被忽略。

1. 通用规则

• 所有替换模块都支持递归扫描子目录，所以可以把不同角色、不同主题拆到多级目录中。
• 任意目录名前缀是 DISABLE_ 时，该目录及其子目录都会被跳过。
• 保留目录 logs 和 dump 不参与 Mod 扫描。
• 默认使用 F10 触发刷新，修改资源后一般不需要重启游戏。
• 如果不同 Mod 目录提供了相同 key，后续命中的同名项会被忽略。由于扫描顺序依赖文件系统，不建议依赖“谁先覆盖谁”。

2. 模块总览

模块	作者需要准备什么	典型命名
AssetBundleReplace + IllustReplace	静态立绘 PNG，可选 alpha 配套图	illust_char_002_amiya_1.png
PortraitReplace	头像 / 半身像 PNG	charportraits_char_002_amiya_1.png
SpineReplace	动态立绘 / 战斗小人 / 基建小人的 .skel/.json + .atlas + .png，可选 alpha	dyn_illust_char_1037_amiya3_sale#13.skel

3. 静态立绘

静态立绘的实际替换由 IllustReplace 完成，AssetBundleReplace 负责在 prefab / UI image 层面把对应图像交给它刷新。 对作者来说，通常只需要准备 PNG，不需要自己打 AB。

推荐命名

• illust_* 前缀是最推荐、最稳妥的写法。
• 常见例子：illust_char_002_amiya_1.png
• 皮肤例子：illust_char_002_amiya_winter#1.png

alpha 配套图

如果目标静态立绘使用了分离 alpha，可以额外提供同名 alpha 图：

illust_char_002_amiya_winter#1.png
illust_char_002_amiya_winter#1[alpha].png

当前兼容的 alpha 后缀包括：

• [alpha]，推荐使用
• _alpha
• [alphe]，旧兼容写法

兼容命名

静态立绘匹配时会尝试一些兼容候选：

• 如果运行时名本身就是 illust_...，也会尝试去掉前缀后的名字。
• 如果运行时名是 char_...，也会尝试补成 illust_char_...。
• 部分皮肤名中包含 # 或 @ 时，系统也会尝试把它们替换成下划线后的变体。

4. 编队头像与半身像

PortraitReplace 处理的是扁平 key，而不是目录层级 key。 它会把原始资源路径去掉开头的 dyn/ 或 arts/，再把路径分隔符 / 变成下划线 _。

当前常见前缀

• charportraits_：原皮半身像
• charportraits_skins_：皮肤半身像
• charavatars_：原皮头像
• charavatars_skins_：皮肤头像

常见命名示例

charportraits_char_002_amiya_1.png
charportraits_skins_char_391_rosmon_sale#16.png
charavatars_char_4056_titi.png
charavatars_skins_char_002_amiya_epoque#4.png
charavatars_elite_char_4056_titi_2.png

说明

• charavatars_elite_... 需要特别注意：这里的 elite 不是随便加的修饰词，而是角色精英化头像资源路径里原本就带有的层级，扁平化后就会体现在文件名中。
• 例如 charavatars_elite_char_4056_titi_2.png 可以理解为“角色精英化头像”的 key，因此命名时不要把 elite 省略掉。
• 文件只需要提供 .png。
• 热刷新时，系统也会根据 Sprite / Texture 名字尝试补全 charportraits_、charavatars_ 等前缀。

5. 动态立绘 / 战斗小人 / 基建小人

SpineReplace 负责替换这类 Spine 资源。最稳妥的做法是提供完整三件套： 骨骼 + atlas + 主贴图，必要时再补 alpha 图。

支持的文件类型

• .skel 或 .json：骨骼数据
• .atlas：图集
• .png：主贴图
• [alpha].png / _alpha.png：alpha 贴图

5.1 动态立绘

最常见前缀是 dyn_illust_。

dyn_illust_char_1037_amiya3_sale#13.skel
dyn_illust_char_1037_amiya3_sale#13.atlas
dyn_illust_char_1037_amiya3_sale#13.png

如果该资源需要分离 alpha，还可以提供：

dyn_illust_char_1037_amiya3_sale#13[alpha].png

5.2 入场 / 进场动画

对于被识别为“进场”的 SkeletonDataAsset，当前实现会优先尝试以下前缀：

• start_
• entry_
• entrance_

推荐写法示例：

entry_dyn_illust_char_003_kalts_boc#6.skel
entry_dyn_illust_char_003_kalts_boc#6.atlas
entry_dyn_illust_char_003_kalts_boc#6.png

这样可以和普通动态立绘文件区分开，避免出现“同一个 AB / 同一个 skeleton 基名，普通立绘和入场动画撞名”的问题。

5.3 战斗小人正反面

当前实现明确支持以下战斗方向前缀：

• front_
• back_
• face_front_，兼容前缀
• face_back_，兼容前缀

front_char_002_amiya.skel
front_char_002_amiya.atlas
front_char_002_amiya.png

back_char_002_amiya.skel
back_char_002_amiya.atlas
back_char_002_amiya.png

5.4 基建小人

基建小人通常直接按原始 skeleton 名匹配，常见命名是 build_*。

build_char_002_amiya.skel
build_char_002_amiya.atlas
build_char_002_amiya.png

5.5 多页贴图 / 贴图页变体

如果一个 Spine 资源有多页贴图，当前实现会按材质主贴图名在同目录中继续查找更精确的 PNG。 所以除了主 key 对应的 PNG 外，也可以放更细分的贴图页文件。

dyn_illust_char_1013_chen2_boc#6.skel
dyn_illust_char_1013_chen2_boc#6.atlas
dyn_illust_char_1013_chen2_boc#6.png
dyn_illust_char_1013_chen2_boc#6[alpha].png
dyn_illust_char_1013_chen2_boc#62.png
dyn_illust_char_1013_chen2_boc#62[alpha].png

6. 是否必须提供完整三件套

不是绝对必须，但建议如下：

• 静态立绘：通常只需要 .png，必要时加 alpha 图。
• 头像 / 半身像：只需要 .png。
• Spine 资源：最稳妥的是同时提供 .skel/.json + .atlas + .png。

当前 Spine 模块允许只替换其中一部分资源，比如只换贴图、只换 atlas、只换 skeleton， 但这类做法更依赖原资源兼容性，建议仅在你明确知道资源结构时使用。

7. 实用建议

• 最开始先复制一个已知能工作的示例文件名，再替换自己的资源内容。
• 同一角色的不同资源可以分子目录，但不要把同一个 key 分散到多个 Mod 文件夹中。
• 动态立绘如果普通版和入场版重名，优先用 entry_ 前缀区分。
• 静态立绘和头像类资源建议直接导出成 PNG，不要混用其它格式。
• 修改后按 F10 刷新；如果当前处于战斗锁，刷新可能会延后。

8. 推荐速查表

用途	推荐命名
静态立绘	illust_char_xxx_xxx_1.png
静态立绘 alpha	illust_char_xxx_xxx_1[alpha].png
原皮半身像	charportraits_char_xxx_xxx_1.png
皮肤半身像	charportraits_skins_char_xxx_xxx_skin#n.png
原皮头像	charavatars_char_xxx_xxx.png
皮肤头像	charavatars_skins_char_xxx_xxx_skin#n.png
动态立绘	dyn_illust_char_xxx_xxx_skin#n.skel/.atlas/.png
入场动画	entry_dyn_illust_char_xxx_xxx_skin#n.skel/.atlas/.png
战斗正面	front_char_xxx_xxx.skel/.atlas/.png
战斗背面	back_char_xxx_xxx.skel/.atlas/.png
基建小人	build_char_xxx_xxx.skel/.atlas/.png