ResourcePatch扩展深潜(下):Mesh与MorphTarget二进制补丁技巧
ResourcePatch扩展深潜(下):Mesh与MorphTarget二进制补丁技巧
本文延续《ResourcePatch 扩展深潜》系列,带你深入 cp2077-archive-xl(ArchiveXL)这个 Cyberpunk 2077 资源扩展 Mod 中最硬核的部分:ResourcePatch 扩展的 Mesh 网格补丁与 MorphTarget 形变目标补丁。无需覆盖原始游戏文件,你就能给现有网格叠加新外观、深拷贝替换渲染二进制数据、合并表情形变目标——这正是 ArchiveXL "多 Mod 无冲突扩展同一资源"的核心能力。
ResourcePatch 配置速览:source、props 与 order
上篇讲过的机制这里 30 秒回顾。在 Mod 配置中用 resource.patch 声明"补丁源 → 目标"映射:
resource:
patch:
mymod\\meshes\\hair_patch.mesh:
targets:
- characters\\common\\hair\\h1_base.mesh
props:
- appearances
order: 10
- props 为空 = 允许修改目标的全部属性;非空则仅列出属性生效
- order 决定多个补丁作用于同一目标时的先后顺序(升序)
- 补丁资源会在目标资源首次被请求时才通过
LoadAsync异步加载,不增加启动开销
完整解析逻辑见 Config.cpp,结构定义见 Config.hpp。
Mesh 补丁技巧 1:用 appearances 属性叠加新外观
钩子位于 OnMeshResourceLoad,在每个 CMesh 资源 PostLoad 前介入。当补丁网格声明了 appearances 属性时,扩展会执行一套"克隆 + 打标签"流程:
- 克隆:为补丁中的每个 appearance 创建副本,携带
name与chunkMaterials(区块材质列表) - 打三个标签:
ResourcePatch固定标签、扩展名标签(expansionTag)、以及源标签(sourceTag) - 注册源:调用
RegisterMeshPatch在目标网格的materialEntries中插入一个 dummy 材质条目,把源网格"注册"进来——后续动态材质扩展就靠它
同名 appearance 的合并规则很克制:只有当目标为空、或补丁带有 chunkMaterials 时才替换,否则追加为新外观。补丁全部完成后还会把 forceLoadAllAppearances 置回 false,避免整表预加载浪费内存。
仓库内置的真实案例值得一看:h1_base_color_patch.mesh.json 为一个发型网格追加了 35 种发色外观(blonde_golden、cyberpunk_yellow、goblin_green……),其 chunkMaterials 全部留空、renderResourceBlob 为 null——纯外观声明,具体材质由 Mesh 扩展在运行时按 @ 模板标记动态展开(见 ProcessAppearance 中对补丁标签的清理逻辑)。
Mesh 补丁技巧 2:深拷贝 renderResourceBlob 二进制数据
想彻底替换网格几何(骨骼、包围盒、LOD、阴影标记等),就要动 renderResourceBlob 属性。关键实现在 CopyRenderBlob:
- 不是简单引用赋值,而是新建 blob 并深拷贝
renderBuffer,防止目标与补丁共享同一份渲染数据被互相污染 - 替换 blob 的同时,会一并同步
boneNames、boneRigMatrices、lodLevelInfo、boundingBox、surfaceAreaPerAxis、objectType及各类阴影缓存标记——漏一个字段就可能出现阴影异常或 LOD 闪烁
⚠️ 覆盖语义是新手最常踩的坑:Modifies(prop, overwrite)(Extension.cpp)的语义是"目标已有数据时,仅当 props 中显式列出该属性才允许覆盖"。所以只想叠加外观、不想动几何的补丁,props 只写 appearances 即可;想强换几何,则必须显式写 renderResourceBlob。
MorphTarget 补丁:逐字段合并 baseMesh、blob 与 targets
MorphTarget(形变目标)补丁处理表情、口型、面部微调等资源,钩子是完整的 PostLoad 替换(OnMorphTargetResourceLoad):先按属性列表逐字段打补丁,最后再手动调用原版 PostLoad,保证引擎初始化不缺席。
可单独控制的字段一览:
| 属性 | 行为 |
|---|---|
baseMesh |
替换所依附的基础网格引用 |
baseMeshAppearance / baseTexture / baseTextureParamName |
替换基础外观与贴图(补丁侧非空才生效) |
blob |
深拷贝 rendRenderMorphTargetMeshBlob:baseBlob 头部 + diffsBuffer + mappingBuffer + textureDiffsBuffer 四段全拷 |
boundingBox |
仅当补丁侧包围盒有效(Max ≠ Min)时才替换 |
targets |
按 name 合并:同名形变目标被替换,不同名的追加 |
两个细节值得注意:
- 防递归:若当前正在加载的资源本身就是补丁源(
IsPatchResource),直接跳过,避免 A 补 B、B 又补 A 的死循环 - 项目内置的女性头部形变补丁 heb_000_pwa__basehead_01.morphtarget.json 展示了标准写法:只声明
baseMesh指向新网格、baseTexture指向法线贴图,blob与targets留空——由目标原有数据补齐
相关类型定义可查 MorphTarget.hpp。
补丁冲突处理:order 排序、防链式与动态注册
Configure 阶段(Extension.cpp)做了三道防线:
- 补丁源不存在 → 打印
LogError并跳过,不阻断游戏 - 补丁资源又成为另一个补丁的目标 → 判为非法并移除,杜绝链式补丁
- 同目标多补丁 → 按
order升序排队
除 YAML 静态配置外,扩展还暴露了动态注册 API RegisterPatch。WorldStreaming 扩展就靠它在运行时把自定义流式区块合并进主世界:WorldStreaming/Extension.cpp。这也是其他扩展复用 ResourcePatch 机制的标准姿势。
另外提醒:补丁加载有 2 × 250ms 超时(GetToken),若日志出现 failed to loaded due to timeout,优先检查补丁资源路径与体积。
新手上手清单:写出第一个 Mesh / MorphTarget 补丁
✅ 复制原资源 → 改名放入 Mod 目录(建议 WolvenKit 导出的 JSON 工作流)
✅ 只保留想改的字段,其余置空/留空数组(外观列表可参考 null.morphtarget.json 这种"空壳"模板)
✅ 配置 resource.patch,props 精确到属性名,按需设 order
✅ 开 logging.debug 验证日志:Appearance "xxx" from "yyy" added to "zzz" 即合并成功
✅ 想换几何就显式声明 renderResourceBlob / blob,想叠外观就留空 blob
关键文件索引
| 文件 | 作用 |
|---|---|
| src/App/Extensions/ResourcePatch/Extension.cpp | 补丁钩子与合并逻辑主体 |
| src/App/Extensions/ResourcePatch/Config.cpp | resource.patch YAML 解析 |
| src/App/Extensions/Mesh/Extension.cpp | RegisterMeshPatch 源网格注册 |
| bundle/source/raw/archive_xl/ | 内置 Mesh / MorphTarget 补丁示例资源 |
| README.md | 项目概览与安装说明 |
掌握 Mesh 与 MorphTarget 的二进制补丁技巧后,你已经可以安全地"无冲突扩展"2077 中绝大多数的外观与形变类资源。