ResourcePatch扩展深潜(下):Mesh与MorphTarget二进制补丁技巧

原创2026-11-01 13:42:301,362 阅读
文章标签:游戏开发插件系统

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 属性时,扩展会执行一套"克隆 + 打标签"流程:

  1. 克隆:为补丁中的每个 appearance 创建副本,携带 name 与 chunkMaterials(区块材质列表)
  2. 打三个标签:ResourcePatch 固定标签、扩展名标签(expansionTag)、以及源标签(sourceTag)
  3. 注册源:调用 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)做了三道防线:

  1. 补丁源不存在 → 打印 LogError 并跳过,不阻断游戏
  2. 补丁资源又成为另一个补丁的目标 → 判为非法并移除,杜绝链式补丁
  3. 同目标多补丁 → 按 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 中绝大多数的外观与形变类资源。

登录后查看全文
cp2077-archive-xl