# 烽沙 ModelSwapFramework 模型换装框架（玩家端）
**版本：1.0.0**
## 简介
ModelSwapFramework 是烽沙（MOProject）的模型替换运行框架。它让模型作者制作的角色 / 服装模型 Mod 能够在游戏中原生加载和正确渲染——包括骨骼映射、蒙皮权重与 LOD 链的完整适配。
**这是一个纯 Mod 包（ModOnly），不包含 Mod 基础环境。** 使用前请先安装【MOProject 专用 UE4SS + ContainerLoader v0.4】作为前置。
框架本身不包含任何模型内容，需要搭配模型作者发布的模型 Mod 一起使用。
## 功能特性
- 在游戏资产加载前完成作者 Pak 和 `_Ins` 伴随包的签名兼容与挂载，模型在游戏中原生加载。
- 游戏运行期间不会解包、重打包或生成模型缓存，性能开销极小。
- 保留 UE4SS 原本的 LogicMods 加载方式，与其他 Pak / LogicMods 兼容共存。
- 游戏更新后采用按资产粒度的兼容策略：
- 没有变化且仍能识别的资产继续使用；
- 只有结构或 BoneMap 变化的对应模型需要作者重新运行工具；
- **不会因为单个资产变化而统一禁用所有 Mod。**
## 前置要求
- 已安装【MOProject 专用 UE4SS + ContainerLoader v0.4】（本框架基于该验证过的 UE4SS 环境运行）。
## 安装方法
### 1. 安装框架
1. 退出游戏。
2. 把发布包中的文件合并到：
```text
Steam\steamapps\common\mo\MOProject\Binaries\Win64\
```
（即把包内的 `ue4ss\Mods\ModelSwapFramework` 合并进已有的 `ue4ss\Mods` 目录。）
3. 保留原有 `LogicMods/` 内容；框架不会改变 UE4SS 原本的 LogicMods 加载方式。
### 2. 安装模型 Mod
把模型作者交付的所有文件放到：
```text
MOProject\Content\Paks\~mods\
```
作者通常会提供两组三件套：
```text
YourModel_P.pak
YourModel_P.utoc
YourModel_P.ucas
zzzz_YourModel_AutoIns_P.pak
zzzz_YourModel_AutoIns_P.utoc
zzzz_YourModel_AutoIns_P.ucas
```
**两组都必须安装。** 不要重命名其中单个文件，也不要删除 `zzzz_` 前缀。
如果作者自己提供了经过工具验证的合格 `_Ins`，可能只交付一组三件套，以作者说明为准。
### 3. 启动游戏
仍然从 Steam 正常启动烽沙，不需要运行额外启动器。
## 禁用或卸载模型
退出游戏，把该作者的原三件套和对应 `zzzz_*_AutoIns_P` 三件套****一起****移出 `~mods`。
**不要只移除其中一组**：只留下作者 SK 而没有正确的 `_Ins`，可能在读档或生成大量角色时闪退。
## 游戏更新后
- 没有变化且仍能识别的资产继续使用；
- 只有结构或 BoneMap 变化的对应模型需要作者重新运行工具；
- 不会因为单个资产变化而统一禁用所有 Mod。
如果发生闪退，先确认原 Pak 与其 `zzzz_` 伴随包来自同一次作者发布。
