For Mod Authors

资源替换 Mod 命名规则说明

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

通用结论

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

命名原则

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

热刷新说明

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

1. 通用规则

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

最好不要在不同 Mod 文件夹里放同名资源。即使暂时看起来能工作，冲突时实际生效顺序也不稳定。

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`
`UIResource + HomeBackgroundPlayer`	Home 主题按钮 / Home 背景左右图 / Home 背景前景 `player` 层 PNG	`tm_rhodes_day_btn_battle.png`
`NameCardStyle`	名片样式背景 PNG，当前支持 `largeBg / shortBg / longBg / shareBg`	`namecardstyle_nc_as2025_bloomsoftime_largebg.png`
`StoryAVG`	剧情 AVG 背景 / 人物 PNG，文件名统一使用 `avg_` 前缀	`avg_bg_wild_a.png`

3. 静态立绘

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

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_...。
部分皮肤名中包含 # 或 @ 时，系统也会尝试把它们替换成下划线后的变体。

虽然存在兼容候选，但作者仍然应该优先使用游戏原始静态图常见写法，即 illust_...。

4. 编队头像与半身像

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

当前常见前缀

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

当前实现实际使用的是 charportraits_skins_ 复数形式，不是 charportraits_skin_ 单数形式。

常见命名示例

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 贴图

当前实现也会把“无扩展名但内容看起来像 JSON 的骨骼文件”按 JSON 处理，但发布时仍建议明确写成 .json 或 .skel。

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

对于复杂动态立绘，如果贴图页较多，建议直接参考现有成功 Mod 的整套文件命名，不要只替换其中一页后期待系统自动猜中其它页。

6. 主题 Home 背景 / 前景 / 按钮

这部分主要由 UIResource 和 HomeBackgroundPlayer 处理。 UIResource 负责主页主题按钮、主题图片、Home 背景左右图等 Sprite 资源； HomeBackgroundPlayer 负责 Home 背景里的前景 player 层。对作者来说，通常都只需要准备 .png，不需要自己打 AB。

6.1 主题按钮

日志中可以看到这部分挂在 HomeThemeBigButton._ApplyImage 和 HomeThemeImage.OnUIApply 上。运行时 sprite path 会被整理成 dyn/arts/ui/hometheme/...，然后再用扁平文件名去匹配。

最推荐直接写成 主题ID_资源名.png。
如果主题目录名带 [uc]，文件名里可以省略这个前缀。
只写最后一级名字例如 btn_battle.png 也可能命中，但非常容易和别的主题撞名，不推荐。

tm_rhodes_day_btn_battle.png
tm_rhodes_day_btn_friend.png

例如主题 ID 是 tm_rhodes_day 时，按钮资源 btn_battle 推荐写成 tm_rhodes_day_btn_battle.png，这样比只写 btn_battle.png 更稳。

6.2 Home 背景

主页背景左右图挂在 HomeBackgroundMultiFormImageHandler._SetSprites 上。代码会按 dyn/arts/ui/<backgroundId>/<formId>/left.png / .../right.png 这种路径生成 key，再把路径扁平化后去匹配文件名。

如果当前背景没有额外 formId，推荐命名为 <backgroundId>_left.png / <backgroundId>_right.png。
如果该背景有多形态 / 多表单，则推荐命名为 <backgroundId>_<formId>_left.png / ..._right.png。
日志里的 [to_left]、[from_right] 只是刷新阶段标签，不是文件名的一部分。
某些直接落在 dyn/arts/ui/ 根下的单张背景相关图片，也可以直接用扁平 key，例如 bg_rhodes_night.png。

bg_rhodes_night_left.png
bg_rhodes_night_right.png
bg_rhodes_night.png

当前示例目录里的 bg_rhodes_night_left.png 就是这一类写法。如果后续日志里出现了具体 formId，再把 formId 插到中间即可。

6.3 Home 背景前景（player 层）

Home 背景里的前景不是走上面的 left/right 图，而是单独挂在 HomeBackgroundPlayer.HomeDisplayController._CreateEffectView 上。当前实现会把这层资源整理成 dyn/arts/ui/homebackground/player/<spriteName>.png 来匹配。

优先按运行时实际 sprite 名命名。
如果运行时拿不到 sprite 名，代码会回退到 <backgroundId>_player.png。
实战里最推荐直接使用 <backgroundId>_player.png 这一套命名。

bg_rhodes_night_player.png

这里的“前景”当前指的是 Home 背景中的 player 前景图层，不是 effectBg、effectFront、effectCamera 这类背景 AB 特效对象本体。

7. 名片样式

名片替换由 NameCardStyle 模块处理。当前正式链路挂在 CharacterUtil.LoadNameCardV2SkinStyleAndApplyTmpl 和 UIStyleProvider.Reset 上，所以不仅首次加载会替换，热刷新后当前仍然存活的名片样式也会重新绑定。

7.1 当前支持的槽位

largeBg：大图背景
shortBg：短版背景
longBg：长版背景
shareBg：分享背景

当前探针里虽然也能读到 mainEffect，但正式替换逻辑还没有接入这个槽位。也就是说，现在名片 Mod 只替换上面这四类背景，不替换 mainEffect。

7.2 推荐命名

名片文件名必须以 namecardstyle_ 开头，并且只扫描 .png。最推荐的基础写法是：

namecardstyle_<skinId>_largebg.png
namecardstyle_<skinId>_shortbg.png
namecardstyle_<skinId>_longbg.png
namecardstyle_<skinId>_sharebg.png

例如当前示例目录里的可用写法就是：

namecardstyle_nc_as2025_bloomsoftime_largebg.png

7.3 `tmpl` 变体

名片样式还支持按模板号区分。若日志里出现了具体的 tmpl，可以写成：

namecardstyle_<skinId>_tmpl_0_largebg.png
namecardstyle_<skinId>_tmpl_1_largebg.png

匹配顺序会先尝试带 _tmpl_<n> 的文件。
如果没找到对应模板文件，会回退到不带 tmpl 的通用文件。
所以如果你不想区分模板，直接放不带 tmpl 的文件就可以。

7.4 槽位后缀写法

当前实现同时兼容紧凑写法和带下划线写法：

largebg 或 large_bg
shortbg 或 short_bg
longbg 或 long_bg
sharebg 或 share_bg

文档仍然推荐优先使用紧凑写法，例如 largebg、shortbg。这样和当前日志、示例文件、代码里的主命名分支最一致。

7.5 skinId 说明

文件名中的 skinId 对应游戏里的名片样式 ID，例如 nc_as2025_bloomsoftime。
如果运行时 skinId 带有 [uc] 前缀，匹配时会自动去掉，所以文件名里通常不用手动写 [uc]。
你可以只替换某一个槽位，例如只放 namecardstyle_nc_as2025_bloomsoftime_largebg.png，其它槽位会继续使用游戏原图。

8. 剧情 AVG 背景 / 人物

剧情背景和剧情人物由 StoryAVG 模块处理。这一类资源现在不再直接使用原始 key 作为 Mod 文件名，而是统一要求在原始 key 前面加上 avg_ 前缀，避免和其它模块或普通素材发生重名冲突。

8.1 命名规则

运行时原始 key 不变，Mod 文件名只是在前面补一个 avg_。
例如原始匹配 key 是 bg_wild_a，现在文件名应写成 avg_bg_wild_a.png。
人物也是同样规则，例如原始匹配 key 是 char_106_franka_1，现在文件名应写成 avg_char_106_franka_1.png。
旧写法 bg_wild_a.png 不再参与 StoryAVG 索引。
背景和人物都走同一条规则，也就是统一使用 avg_<原始key>.png。

avg_bg_wild_a.png
avg_char_106_franka_1.png

8.2 alpha 配套图

如果对应的剧情背景或人物资源使用了分离 alpha，alpha 文件也需要跟着主文件一起保留 avg_ 前缀。

avg_bg_wild_a.png
avg_bg_wild_a[alpha].png

avg_char_106_franka_1.png
avg_char_106_franka_1[alpha].png

当前兼容的 alpha 后缀包括：

[alpha]
_alpha
[alphe]

这里的 avg_ 只是 Mod 文件命名前缀，不会改动游戏运行时真正加载的剧情 key。内部仍然是按原始 key 匹配，只是索引时要求文件名带这个前缀。

8.3 实用建议

最稳妥的做法是先从日志或探针里确认原始 key，再手动改写成 avg_<key>.png。
如果只记得旧文件名，基本可以直接在前面补一个 avg_。
若同一资源有主图和 alpha 图，两者的主 stem 必须完全一致，只差 alpha 后缀。

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

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

静态立绘：通常只需要 .png，必要时加 alpha 图。
头像 / 半身像：只需要 .png。
Spine 资源：最稳妥的是同时提供 .skel/.json + .atlas + .png。
名片样式：只需要 .png，而且可以只替换某一个背景槽位。
剧情 AVG 背景 / 人物：只需要 .png，必要时加同 stem 的 alpha 图。

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

10. 实用建议

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

11. 推荐速查表

用途	推荐命名
静态立绘	`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`
主题按钮	`tm_xxx_btn_xxx.png`
Home 背景左 / 右图	`bg_xxx_left.png` / `bg_xxx_right.png`
Home 背景前景（player 层）	`bg_xxx_player.png`
名片大图背景	`namecardstyle_nc_xxx_largebg.png`
名片模板背景	`namecardstyle_nc_xxx_tmpl_0_largebg.png`
剧情 AVG 背景 / 人物	`avg_原始key.png`
剧情 AVG 人物 alpha	`avg_char_xxx_xxx[alpha].png`

资源替换 Mod 命名规则说明

通用结论

命名原则

热刷新说明

1. 通用规则

2. 模块总览

3. 静态立绘

推荐命名

alpha 配套图

兼容命名

4. 编队头像与半身像

当前常见前缀

常见命名示例

说明

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

支持的文件类型

5.1 动态立绘

5.2 入场 / 进场动画

5.3 战斗小人正反面

5.4 基建小人

5.5 多页贴图 / 贴图页变体

6. 主题 Home 背景 / 前景 / 按钮

6.1 主题按钮

6.2 Home 背景

6.3 Home 背景前景（player 层）

7. 名片样式

7.1 当前支持的槽位

7.2 推荐命名

7.3 tmpl 变体

7.4 槽位后缀写法

7.5 skinId 说明

8. 剧情 AVG 背景 / 人物

8.1 命名规则

8.2 alpha 配套图

8.3 实用建议

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

10. 实用建议

11. 推荐速查表

7.3 `tmpl` 变体