玩家时装

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

上面描述的是分部位时装。玩家穿戴具备标准十部位名称的整身人形时装时，会自动使用通用人形动作：以角色根位置渲染，隐藏原版玩家主体，手持物跟随自定义前臂，无需保存映射。已有自定义动作绑定优先生效；不符合标准骨架且没有自定义绑定的时装仍遵循本页挂点规则。

完整配置

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

yaml

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]                       # 默认朝向修正后的角度微调

字段说明

model、texture 和 animation 均支持本地相对路径或 HTTP/HTTPS 直链，可以混用。完整网络配置、下载缓存与失败重试见网络资源。

字段	必填	默认值	说明
`model`	是	无	时装模型相对路径或 HTTP/HTTPS 地址
`animation`	否	空	时装动画相对路径或 HTTP/HTTPS 地址
`texture`	条件必填	无	PNG 相对路径或 HTTP/HTTPS 地址；BBModel 使用工程自身纹理时可留空
`part`	否	`body`	跟随的玩家身体部位
`scale`	否	`1.0`	在内置挂点变换之后应用的缩放
`position`	否	`[0, 0, 0]`	在内置挂点上的 X、Y、Z 微调
`rotation`	否	`[0, 0, 0]`	在内置朝向修正后的 X、Y、Z 角度微调

part 支持值

标准值	别名	跟随部位
`body`	`chest`、`torso`、`back`	身体；潜行时随身体前倾
`head`	`helmet`	头部；随视角转动
`left_arm`	`leftarm`、`arm_left`	左臂
`right_arm`	`rightarm`、`arm_right`	右臂
`left_leg`	`leftleg`、`leg_left`	左腿
`right_leg`	`rightleg`、`leg_right`	右腿

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

运行规则

挂点与变换

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

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

持续与临时时装

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

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

辅助命令

text

/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。

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

玩家时装 ​

完整配置 ​

字段说明 ​

part 支持值 ​

运行规则 ​

挂点与变换 ​

持续与临时时装 ​

辅助命令 ​

玩家生命周期同步 ​

ChaUI 预览 ​

常见问题 ​

相关文档 ​