ChaUI 时装模型预览

ChaUI 可以在自己的实体模型组件中选择性调用 ChaEngineMod 的通用预览桥，为某个查看者显示一组临时时装。预览不修改目标实体的真实穿戴，也不广播给其他玩家。

本页只说明 ChaEngine 提供的模型能力边界。页面、组件与交互逻辑由 ChaUI 文档负责。

ChaUI 3D 场景物品模型

ChaUI 的 scene_model 支持选择 ChaEngine 物品模型目录：来源与目录均选择 item，模型 ID 使用已有物品配置 ID。目录只显示配置了三维模型资源的物品，纯平面贴图物品不会列入。每个场景节点独立控制模型变换与动画，不需要生成世界物品实体。

此能力需要同时更新 ChaUIMod 与 ChaEngineMod，并让客户端完成 ChaEngine 资源同步。进入模型属性时会自动读取目录；新增资源后也可手动刷新。完整字段与页面示例见 3D 场景组件。

安装组合

客户端组合	结果
ChaUI + ChaEngineMod	可使用实体模型与时装预览
只有 ChaUI	页面仍可工作，但应隐藏或降级模型预览能力
只有 ChaEngineMod	模型系统正常，不能单独提供 ChaUI 页面

服务端需要安装 ChaEngine 和 ChaUI 对应的服务端组件。调用前使用 ChaEngineEntityAPI.supportsUiEquipPreview(viewer)，只有返回 true 才发送预览快照。

预览上下文

一条预览由四部分共同标识：

查看者 Player：只有该玩家看见预览；
页面 ID pageId；
组件 ID elementId；
被预览实体 UUID entityUuid。

同一上下文后发快照覆盖先发快照。页面 ID、组件 ID 和每个时装 ID 会去除首尾空白，长度必须为 1..128；时装最多 64 件，按输入顺序去重，并逐个验证是否存在。

设置与清理

java

import com.github.ginirohikocha.engine.api.entity.ChaEngineEntityAPI;
import com.github.ginirohikocha.engine.manager.entity.UiEquipPreviewManager;

if (ChaEngineEntityAPI.supportsUiEquipPreview(viewer)) {
    UiEquipPreviewManager.PreviewResult result =
            ChaEngineEntityAPI.setUiPreviewCarrierEquips(
                    viewer,
                    "wardrobe",
                    "player_preview",
                    target.getUniqueId(),
                    selectedEquipIds);
}

setUiPreviewCarrierEquips 要发送完整时装 ID 快照，不是增量。空集合等同于清除此上下文的预览：组件会显示不含预览时装的模型，而不是回退到实体真实穿戴。

页面或组件关闭时，调用：

java

ChaEngineEntityAPI.clearUiPreviewCarrierEquips(
        viewer, pageId, elementId, target.getUniqueId());

玩家离开整个页面、业务取消或插件停用时，调用：

java

ChaEngineEntityAPI.clearAllUiPreviewCarrierEquips(viewer);

玩家断开连接时 ChaEngine 自动移除该查看者的全部就绪状态与快照。页面关闭不会由 ChaEngine 自动感知，ChaUI 接入方必须主动清理，避免同一连接中遗留不可见上下文。

返回值

结果	含义与处理
`SUCCESS`	快照已发送
`INVALID_PLAYER`	查看者为空或不在线；停止本次流程
`NOT_READY`	客户端尚未声明支持；最新快照已暂存，就绪后自动补发
`INVALID_SCOPE`	页面 ID 或组件 ID 无效
`INVALID_ENTITY_UUID`	实体 UUID 为空
`INVALID_EQUIP_ID`	集合为空引用，或至少一个时装 ID 无效
`TOO_MANY_EQUIPS`	输入或去重结果超过 64 件
`SEND_FAILED`	数据提交失败；检查玩家连接和服务端日志

supportsUiEquipPreview 是当前连接的能力判断，不应按 Minecraft 版本硬编码。客户端尚未安装 ChaEngineMod、能力未就绪或协议不兼容时都会返回 false。

ChaUI 时装模型预览 ​

ChaUI 3D 场景物品模型 ​

安装组合 ​

预览上下文 ​

设置与清理 ​

返回值 ​

推荐生命周期 ​

相关文档 ​

ChaUI 时装模型预览

ChaUI 3D 场景物品模型

安装组合

预览上下文

设置与清理

返回值

推荐生命周期

相关文档