UE Mutable 换装系统（一）：需求拆解与整体架构设计

总览

这一系列不再把 Mutable 当成“点按钮换一件衣服”的演示，而是把它放进一个真实项目会遇到的上下文里：角色有背包和商城，装备有职业、体型、性别和资源版本限制，UI 要能预览和取消，存档要能迁移，联网要由服务端裁决，打包后还要能追踪软引用和失败回退。

本篇先定系统规划。Mutable 负责根据 CustomizableObject 和参数生成标准 UE 资源；换装系统负责把业务里的 ItemID、Slot、预览状态、保存快照、网络复制和错误处理组织起来。两者边界清楚，后面的蓝图实现才不会越写越乱。

本篇目标

1. 明确生产级换装系统的目标、非目标和模块边界。
2. 定义系统核心状态：正式穿搭、预览穿搭、待应用请求、上一次稳定状态。
3. 规划 BP_OutfitComponent、数据资产、UI、存档、网络和 Mutable Runtime Wrapper 的职责。
4. 给出第一版可落地的数据结构、蓝图函数、事件委托和主流程。
5. 从第一篇开始建立失败路径和验收标准，而不是到上线前才补救。

非目标

1. 本篇不展开 Mutable 图内部节点制作，资源和参数规划放到第二篇。
2. 本篇不写完整衣柜 UI，预览和交互细节放到第五篇。
3. 本篇不实现存档、异步队列和多人同步，分别放到第六、七、八篇。
4. 本篇不讨论玩家是否拥有装备。所有权属于背包、商城或账号系统，换装系统只接收“这件外观是否允许应用”的校验结果。
5. 本篇不把所有逻辑强行放进蓝图。蓝图需要清晰可读；数据校验、缓存、网络和批量构建在生产项目里更适合逐步下沉到 C++。

生产需求拆解

一个可上线的换装系统至少要覆盖这些场景：

这里的关键是：系统的核心不是 SetEnumParameterSelectedOption，而是“谁拥有状态、谁校验请求、谁触发表现、谁能回退”。

模块边界

生产级系统建议按下面的边界拆分：

第一版可以先让 BP_OutfitComponent 直接完成大部分事情，但边界要先画出来。后续性能和多人压力上来时，才有空间把队列、缓存、校验迁到 Subsystem 或 C++。

状态模型

换装系统至少需要四份状态：

不要把“正在点选的 UI 项”“Mutable 里当前参数”“服务器权威状态”混成一个变量。它们的生命周期不同，失败处理也不同。

推荐基础结构如下：

UENUM(BlueprintType)
enum class EOutfitApplyState : uint8
{
    Idle,
    ResolvingData,
    LoadingAssets,
    ApplyingMutable,
    Failed
};

USTRUCT(BlueprintType)
struct FOutfitSlotState
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName SlotId;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FName ItemId;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    bool bLocked = false;
};

USTRUCT(BlueprintType)
struct FOutfitSnapshot
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 SchemaVersion = 1;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TMap<FName, FOutfitSlotState> Slots;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TMap<FName, FLinearColor> ColorOverrides;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 Revision = 0;
};

USTRUCT(BlueprintType)
struct FOutfitApplyResult
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadOnly)
    bool bSuccess = false;

    UPROPERTY(BlueprintReadOnly)
    FName ErrorCode;

    UPROPERTY(BlueprintReadOnly)
    FText Message;

    UPROPERTY(BlueprintReadOnly)
    FOutfitSnapshot AppliedSnapshot;
};

Revision 是异步换装的安全绳。Mutable 更新、资源加载、网络 OnRep 都可能乱序返回，回调时必须先确认 Revision 或 RequestId 仍然有效。

蓝图组件规划

BP_OutfitComponent 是整个系统的运行时核心。它挂在角色 Actor 上，对外只暴露意图级接口，不暴露 Mutable 内部参数。

关键变量

对外函数

内部函数

事件委托

UI 只订阅事件，不直接读取或写入 Mutable。这样衣柜 UI、商城试穿 UI、角色选择界面可以共用同一组件接口。

主流程蓝图

生产链路建议用完整 Snapshot 驱动，而不是只改某个 Slot 参数。

UI Click Item
 -> OutfitComponent.EquipItem(ItemId, bPreview=true)
 -> Resolve Item Data
 -> Validate Character Tags and Slot Rules
 -> Build Next OutfitSnapshot
 -> Write Full Snapshot to Mutable Parameters
 -> Request Mutable Async Update
 -> On Success: update PreviewOutfit and notify UI
 -> On Fail: rollback to CurrentOutfit or LastStableOutfit

UI Confirm
 -> CommitPreview
 -> ApplyOutfitSnapshot(PreviewOutfit, bPreview=false)
 -> On Success: update CurrentOutfit and LastStableOutfit
 -> Save or submit to server

UI Cancel
 -> CancelPreview
 -> ApplyOutfitSnapshot(CurrentOutfit, bPreview=true or false)
 -> Clear PreviewOutfit

“完整 Snapshot” 很重要。比如玩家装备连体衣时，需要同时卸下裤子；取消连体衣后，下装要回到默认裤子；戴全脸头盔时发型和眼镜要被隐藏。只写一个 Slot_Upper = Suit_A 会留下很多残留参数。

请求合并策略

玩家会连续点击，UI 也可能拖动颜色滑条。第一版不要把所有请求都排队，先实现“同一角色只保留最后一次请求”：

If ApplyState == ApplyingMutable:
    PendingRequest = NewRequest
    bHasPendingRequest = true
    return RequestId

When active request finishes:
    If bHasPendingRequest:
        StartRequest(PendingRequest)

颜色滑条可以更进一步：拖动中只改材质预览参数，松手后再触发 Mutable 生成。否则一个 Slider 就能把角色生成队列打满。

失败路径和回退

生产级系统必须从第一天就定义失败路径：

回退顺序建议：

Requested Item
 -> ItemData.FallbackItemId
 -> SlotConfig.DefaultItemsBySlot[Slot]
 -> LastStableOutfit
 -> Global Default Outfit
 -> Base Body Mesh

线上最忌讳的是半成功：UI 显示穿上了，存档也保存了，但 Mutable 实际失败。正式状态只能在生成成功后提交。

最小可用版本

第一阶段不要追求一次做完所有功能。建议先实现：

这版足够验证核心闭环：数据能查到，状态能生成，Mutable 能应用，失败能回退，UI 能感知结果。等闭环稳定，再加多体型、Groom、布料、DLC、远端玩家降级和服务端权威。

验收标准

1. UI 无法直接修改 Mutable 参数，所有换装请求都进入 BP_OutfitComponent。
2. CurrentOutfit、PreviewOutfit、LastStableOutfit 生命周期清楚。
3. 任意装备请求都会先解析数据、校验规则，再写 Mutable。
4. 正式状态只在 Mutable 更新成功后提交。
5. 连续快速点击装备时，最终只应用最后一次有效请求。
6. 失败时不会留下半套参数，能回到默认装备或上一次稳定外观。
7. 初始化、预览、确认、取消、读档和未来网络 OnRep 都复用 ApplyOutfitSnapshot。
8. 每个失败都有 ErrorCode、RequestId、ItemID 和 fallback 结果日志。
9. 第一版能在打包环境中完成一次完整 Smoke Test：进入衣柜、预览、确认、保存、重启恢复。

本篇结论

Mutable 是表现生成器，不是完整换装系统。生产级方案要先把系统边界、状态模型、蓝图接口、失败回退和验收标准定住，再去接资源和 UI。下一篇进入资源规划：角色基准模型、Mutable 子对象、参数命名、身体裁剪和材质通道应该怎么设计。

参考资料

• Mutable Quickstart Guide
• Mutable FAQ
• Mutable Resource Usage at Runtime
• Mutable Plugin API Index
• UCustomizableObject::CreateInstance
• UCustomizableObjectInstance::GetComponentNames