Ue4 Pak Mod

UE4.27 模型 Mod

两条路线怎么选

默认选编辑器烘焙——它才是「自由做 mod」的正解。二进制替换适合「拿游戏里已有的另一张网格 顶上」这种不需要编辑的快速换皮：不用开编辑器、不用 cook、秒出结果，而且完全保留游戏原始包结构。 （没有编辑器免开的开源方案能写出烘焙态的包：FModel / CUE4Parse / umodel 全是只读， UEFormat 的反向也要 UE 插件。详见 references/editor-cook-pipeline.md 开头。）

Overview（二进制替换路线）

把游戏里某个资产换成另一个资产（最典型：把角色 A 的网格换成角色 B 的网格），做成一个 .pak 放进游戏的 ~mods 目录生效。

这件事不能靠「把文件改名复制过去」完成。 有两条铁律，任何一条错了表现都是 「角色直接隐身 / 部件消失」，而且游戏日志里通常看不到明确报错：

1. 导出对象名必须等于文件名。 UE 解析 Eve_Body_SM.Eve_Body_SM 这类引用是 「按文件路径加载包 → 再按名字在导出表里查对象」。你把 Npc_Aida_SM.uasset 改名成 Eve_Body_SM.uasset 放到目标路径后，包里导出的对象名还是 Npc_Aida_SM， 按名查找落空 → 引用解析成 null → 那个网格组件什么都不画。 必须用 modtool build 把导出名也改掉。
2. pak 挂载点必须是 ../../../ 前缀的标准形式。 UE 的 FPakFile::NormalizeFilename 先用 FPaths::MakeStandardFilename 把绝对路径变成 ../../../EM/Content/...， 再用挂载点做前缀比对去截取包内路径。挂载点写错（比如少一层 ..）不会报错， 只是这个 pak 里的文件永远匹配不上。 本技能默认用 -m ../../../ + 包内放 EM/Content/... 全路径（repak 默认，见 references/pak-and-asset-format.md）。

打包之外还有一步同样关键的前置判断：源网格和目标网格必须共用同一套骨架（USkeleton）， 否则动画/骨骼对不上，模型会扭曲或无法受力。判断方法见下面第 2 步。

When to use

• 「把 X 的模型替换成 Y 的模型」「做一个换模型 mod」「生成 mod pak」。
• 「把模型导出到 Blender 改完再导回游戏」——走编辑器烘焙路线。
• 需要改写已烘焙 .uasset 的内容（改名、换引用、替换载荷）。
• 排查「替换后角色隐身 / 部件不见了 / 拿到空网格」「装上去毫无变化」「模型变默认灰」。
• 确定某个 UE4.27 游戏该用哪个 pak 版本、挂载点、压缩、加密。
• 已经解包过资产，想直接把改好的资产重新打回 pak。

Prerequisites

二进制替换只需要：

1. repak.exe、UAssetCLI.exe、以及可用的 dotnet SDK 10（modtool 需要）。
2. 游戏已解包（解包树同时是「源资产」和「目标资产原样」的来源）。
3. 首次构建 modtool 需要联网（从 NuGet 还原 UAssetAPI 1.1.0）。

编辑器烘焙额外需要：

4. UE4.27 编辑器，且版本要和游戏一致（大版本必须相同，否则烘焙产物的序列化版本对不上）。 本机在 D:\soft\UE_4.27（已由 launcher 注册，.uproject 里 EngineAssociation: "4.27" 可用）。
5. Blender（本机 5.2 LTS）——glb ⇄ FBX 互转，可无头跑。
6. 引擎源码（D:\soft\UE_4.27\Engine\Source）——排查序列化/烘焙行为时的权威依据，有它就不用猜。

路线无关：清楚目标游戏 pak 的版本。UE4.27 用 V11；不确定就看游戏自带的 pak 或 本机已有的现成 mod（repak info）。

Workflow（二进制替换路线）

1. 找到源资产与目标路径

在解包树里定位。网格源通常是 .../Asset/Char/<阵营>/<角色>/Mesh/*.uasset，目标就是你要覆盖的那个包路径。

一个网格资产是 .uasset + .uexp 成对出现的，两个都要处理（modtool 会自动输出 .uexp）。

2. 判断能不能换：比对骨架 ★最容易忽略的一步

用名字表里的字符串就能判断，不用解析二进制：

cd <解包树>/Asset/Char/Player/Char035_Eve/Mesh
for f in *_SM.uasset; do
    printf "%-28s %s\n" "$f" "$(grep -a -o -E "[A-Za-z0-9_]*_Skeleton" "$f" | sort -u | tr '\n' ',')"
done

只换骨架与被替换目标同款的网格。 骨架不同意味着骨骼层级/命名不一致， 换上之后要么不受动画驱动（停在绑定姿势），要么直接错位。

同时注意：一个角色往往不是一个网格，而是 Body + Face + Hair 等好几个组件拼的 （见第 3 步）。如果目标角色的网格是一张「整合了全身」的网格，那就要把 Body/Face/Hair 都指向它 —— 只要它们共用骨架、且挂载点在同一个节点上（RelativeLocation 为 0）， 这几份几何体就是完全重合的，合成结果仍是单个角色，不会穿帮。

3. 确认角色的组件是怎么拼起来的

角色的装配不在 Asset/Char/... 里，而在 AssetDesign：

AssetDesign/Char/Player/<角色>/BP_<角色>.uasset        # 玩家角色
AssetDesign/Char/Npc/CharacterNpc/<角色>/BP_NPC_*.uasset # NPC
AssetDesign/Char/Monster/<怪物>/BP_Mon_*.uasset

想知道「谁引用了这个网格」，直接对解包树做字符串搜索最快（.uasset 的名字表是明文）：

cd <解包树>
grep -rl -a --exclude-dir=Animation --exclude-dir=Cinematics "Eve_Body_SM" .

拿到 BP 的 JSON 导出（UAssetCLI export）后重点看三件事：

• SkeletalMesh：哪个组件用了哪个网格。
• RelativeLocation / AttachParent：组件挂在根节点还是某个 socket 上。 挂在 socket 上的组件不能塞全身网格进去（会把整张身体画在那个骨骼位置）。
• OverrideMaterials：是否逐组件覆盖了材质。值全是 0 表示是空槽（用网格自带材质）， 这种情况才可以把多个组件指向同一张网格而不串色。

4. 写映射表

制表符分隔，# 开头为注释，三列：

<源 uasset 绝对路径>	<游戏内相对路径，不含扩展名>	<新导出名>

第三列必须等于第二列的文件名，否则违反铁律 1。

可直接复制 examples/eve-to-aida.tsv 改。

5. 一键构建

.agents/skills/ue4-pak-mod/scripts/build-mod.sh <mapping.tsv> <out.pak>

脚本会依次：编译 modtool → 按映射表生成改名后的包到 <workDir>/pakroot → 自校验（导出名是否等于目标名、.uexp 是否与源文件逐字节一致） → repak pack → 打印 pak 元数据。

workDir 默认是 <skill>/.tmp（已被 .gitignore 忽略），用 WORK_DIR=... 覆盖。

任何一步不过就直接失败，不会产出一个「看起来成功但装上去没用」的 pak。

6. 校验并安装

# 第二个参数是 build-mod.sh 的中间目录，默认 <skill>/.tmp/pakroot
.agents/skills/ue4-pak-mod/scripts/verify-mod.sh <out.pak> \
    .agents/skills/ue4-pak-mod/.tmp/pakroot

会打印元数据、包内路径列表，并把 pak 解包后与构建产物逐字节比对。

安装（放到游戏 paks 目录下的 ~mods，UE 会递归扫描该目录下的 *.pak）：

cp <out.pak> "<游戏>/<项目名>/Content/Paks/~mods/"

装完重启游戏。UE 在启动时挂载 pak，不会热加载。

编辑器烘焙路线（自由编辑模型）

需要真正改模型（改形状、加删顶点、重拓扑、重做 UV/权重）时走这条。完整原理与踩坑记录见 references/editor-cook-pipeline.md，这里只给操作顺序：

# 1) 建工程（只需一次；build 时也会自动建）
.agents/skills/ue4-pak-mod/scripts/editor/setup-project.sh          # 默认建在 D:\dev\ue-modkit

# 2) 拿游戏模型给 Blender 改
#    解包树里已有 FModel 导出的 .glb（带 skin/权重/UV），Blender 直接打开即可

# 3) 改完一键构建
.agents/skills/ue4-pak-mod/scripts/editor/build-mod-editor.sh \
    <改完的.glb> \
    EM/Content/Asset/Char/Player/<角色>/Mesh/<网格名> \
    <输出.pak>

四个阶段：Blender 转 FBX → UE 导入为骨骼网格（骨架/材质占位到游戏真实路径）→ cook -Unversioned → 只挑网格包 repak。

三个必须记住的点（细节见 reference）：

• 工程名必须是 EM：UE 按工程名生成烘焙输出目录，叫 EM 才落在 EM/Content/...。
• cook 必须带 -Unversioned：游戏资产是 IsUnversioned: true，不带这个开关形态就对不上。
• 骨架和材质是「占位」：在游戏的真实路径上建同名资产，让烘焙产物的引用正确； 它们不能进 pak（游戏自己有），所以打包时只挑网格包。

改完先用自检包验证管线：把游戏原本的网格原样走一遍烘焙，装上去外观应当毫无变化。 这一路线唯一无法离线证明的就是「游戏能不能加载烘出来的包」，必须进游戏看。

Guidelines

• .uasset 头变了，SerialOffset 必须跟着变。 加一个新名字会让 .uasset 变大 20 字节，导出数据在 .uexp 里的起始偏移必须同步更新，否则 UE 读 .uexp 会错位。 UAssetAPI 的 Write() 会自动处理；自己动手改二进制时这是头号坑。 modtool check / verify-mod.sh 就是在守这条线。
• 改名前先做往返测试。 modtool roundtrip <in> <out> 读一遍写一遍，然后 cmp 原文件。 逐字节相同才说明这个库能安全改写这批资产；不一致就说明该游戏的资产有库不认识的字段， 此时不要继续，改用 UAssetGUI 或换库版本。本机这批 DNA 资产已验证往返逐字节一致。
• 不要为了「彻底」去换非同骨架的网格。 少换一个配件，最坏是残留一件原角色的饰件； 换错了骨架/挂载点，最坏是整张身体画在错位置。前者可接受，后者不可接受。
• pak 要覆盖游戏自带的包，靠的是挂载顺序。 放在 ~mods 子目录（名字 ~ 排序靠后） 或用一个更大的 chunk 号（pakchunk999-*）都能让它后挂载、优先生效。
• 别把大 pak 提交进仓库。 本仓库的 husky pre-commit 钩子会执行 git add .， 一个 20 MB 的 pak 会被一起暂存。产出物放 .tmp/，或先加 .gitignore 规则。
• modtool 假设每个包只有 1 个导出（网格包的常态）。遇到多导出包它会直接报错， 这是故意的 —— 那种情况必须先人工确认该改哪个导出，不能瞎猜。
• 构建中间产物默认写在 <skill>/.tmp/（已被 .gitignore 忽略），可用 WORK_DIR 覆盖。