玩家时装 ​

玩家时装在原版玩家模型之外追加渲染一个模型，并把它绑定到指定身体部位。它不替换玩家皮肤；时装是否穿戴由命令或 Java API 管理，不使用实体 match 自动匹配。

完整配置 ​

文件位置：plugins/ChaEngine/equip/*.yml

traveler_backpack:                           # 时装 ID
  model: "backpack/backpack.geo.json"       # 相对于客户端 model/ 的模型，也可使用 .bbmodel
  animation: "backpack/backpack.animation.json" # 可选动画文件
  texture: "backpack/backpack.png"          # 模型贴图
  part: "body"                              # 跟随身体
  scale: 1.0                                 # 模型缩放
  position: [0, 0, 0]                       # 挂点基础上的位置微调
  rotation: [0, 0, 0]                       # 默认朝向修正后的角度微调

字段说明 ​

part 支持值 ​

连字符会按下划线处理；空值和未知值回退为 body。

运行规则 ​

挂点与变换 ​

客户端先应用该身体部位的内置挂点和方向修正，再叠加 position、rotation、scale。因此配置中的数值应作为最终微调，不要把玩家模型的完整姿态重复计算进来。

同一玩家的每个规范化 part 只能有一个当前时装。向同一部位添加新时装会替换该部位的活动时装；不同部位可以同时存在。

持续与临时时装 ​

• 普通添加操作建立当前服务端运行期的持续状态，并在新观察者加入或客户端重新同步时补发。
• 临时添加操作替换该部位的当前显示，但保留其下方记录的持续状态快照。
• 删除指定时装会按其配置部位清除该部位的活动状态和持续状态。
• 清空操作会移除该玩家全部部位的两类状态。

这里的“持续”表示 ChaEngine 当前服务端进程内会重同步，不代表自动写入数据库或跨完整重启保存。需要长期保存时，业务插件应持久化玩家选择，并在玩家上线后重新调用 API。

辅助命令 ​

/chaengine equip add <player> <id>
/chaengine equip remove <player> <id>
/chaengine equip clear <player>

这些标准命令需要管理员或控制台执行，目标必须是在线玩家。add 建立上文所述的普通运行期穿戴状态；临时时装和 ChaUI 预览覆盖属于 Java API 或预览桥能力。旧 /chaengine entity equip ... 入口仅为兼容保留，详见命令参考。

玩家生命周期同步 ​

玩家加入、模型配置补发或相关客户端能力重新就绪时，服务端会向该观察者补发当前在线玩家的时装。玩家离线时不会再向其发送内容；服务端重启后，调用方需要从自己的持久化数据恢复穿戴。

ChaUI 预览 ​

ChaUI 可以通过可选桥为某个查看者临时覆盖指定预览目标的时装列表。预览状态与正式穿戴状态分离，关闭预览或查看者断开连接时会清理。集成方式见ChaUI 模型预览。

常见问题 ​

时装跟随了错误部位：检查 part 是否拼写正确。未知值不会报成自定义挂点，而是按 body 处理。

同一部位只能看到最后一件：这是单部位单活动时装的设计；把可组合部件拆到不同 part，或合并为一个模型。

重新连接后没有恢复：确认业务插件是否重新应用长期保存的玩家选择；不要把运行期持续状态当作数据库。

模型位置整体偏移：先把三项变换恢复默认，确认 part，再逐轴调整 position 和 rotation。

只有预览里不显示：先确认正常穿戴能显示，再检查客户端是否支持预览桥，以及查看者、页面和预览目标身份是否一致。

相关文档 ​

时装模型可以直接使用 .bbmodel；骨骼层级、数值动画和内嵌纹理规则见Blockbench .bbmodel 模型。

• ChaUI 模型预览
• 模型动画
• 资源目录
• 命令参考
• Java API