实体模型 ​

实体模型把服务端配置与客户端生物渲染关联起来。服务端同步定义、管理强制模型和特殊动画；客户端按实体当前数据匹配模型，并根据状态自动选择动画。

完整配置 ​

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

crystal_guardian:                              # 实体模型 ID
  model: "guardian/guardian.geo.json"          # 相对于客户端 model/ 的模型
  animation: "guardian/guardian.animation.json" # 动画文件
  texture: "guardian/guardian.png"             # 模型贴图
  scale: 1.0                                   # 模型缩放
  position: [0, 0, 0]                         # X、Y、Z 位置偏移
  collision: [1, 1, 1]                        # X、Y、Z 碰撞尺寸；会参与真实碰撞和命中
  match:                                          # 可选；只通过模型 ID 显式绑定时可以省略
    - "name#start#水晶,type#equal#minecraft:zombie"
    - "name#equal#水晶守卫"

字段说明 ​

匹配字段 ​

name、type、uuid 支持以下操作符：

规则列表的多行之间是 或；同一行用英文逗号分开的条件之间是 且。空规则、未知字段、未知操作符和格式不完整的条件都不会匹配。

运行规则 ​

自动匹配与 MythicMobs ​

客户端按照同步配置的顺序检查 match。对 MythicMobs 生物，最容易复现的做法是先按最终显示名匹配：

match:
  - "name#equal#水晶守卫"

如果名称带等级、颜色或前后缀，可以在确认实际纯文本名称后改用 start 或 contains。需要用 NBT 时先确认目标值确实是顶层键；当前写法不遍历任意嵌套路径。

直接绑定 MythicMobs 生物 ​

如果模型只服务于某一种 MythicMobs 生物，可以在 MythicMobs 生物配置中直接填写 ChaEngine.model，不必为它编写名称或 NBT 的 match 规则：

CrystalGuardian:
  Type: ZOMBIE
  Display: "水晶守卫"
  ChaEngine:
    model: crystal_guardian  # 来自 plugins/ChaEngine/entity/*.yml 的模型 ID，不是文件路径

ChaEngine 会在每次新生成该 MythicMobs 生物时使用这个实体模型 ID，写入永久模型并应用对应的 collision。该配置只影响之后新生成的生物；已经存在的实体不会被批量迁移。模型 ID 必须能在实体模型目录中找到，大小写也要一致。ChaEngine 段缺失、值为空白或 ID 未知时，生物仍会按 MythicMobs 原配置生成，不会取消事件；服务端会针对同一 MythicMobs 类型和 ID 限制警告次数。生成后仍可使用本页的命令或 Java API 覆盖模型。

强制模型优先级 ​

实体还可以由命令或 Java API 强制指定模型。客户端选择顺序固定为：

1. 临时强制模型；
2. 已同步的永久强制模型；
3. 实体自身保存的永久模型 NBT；
4. match 规则。

临时指定只影响当前运行状态。永久指定会把模型 ID 保存到实体的 ChaEngine 自定义数据，并在实体重新加载后恢复。清除强制模型后才重新使用 match。

若较高优先级保存了一个不存在的模型 ID，客户端会失败关闭该强制结果，不继续回退到 match，以免无意显示错误模型。

真实碰撞与命中 ​

实体模型生效时，collision 不只是渲染参考，而会参与服务端真实碰撞、攻击命中和客户端选取。Y 表示高度；X、Z 中较大的值作为水平宽度。三个值都必须是大于或等于 0 的有限数。

临时或永久强制模型、自动 match 模型都会使用对应配置的碰撞尺寸。清除模型、实体卸载、配置失效或插件停用时会恢复原实体尺寸。

Citizens NPC 与普通生物采用各自兼容入口。若当前服务端核心或实体实现不允许修改真实尺寸，ChaEngine 会保留原碰撞并在服务端日志记录警告；此时不要把客户端看到的模型大小当作服务端命中范围。

发光描边 ​

实体获得原版发光效果时，替换后的实体主体也会显示描边。除此之外，管理员或业务插件可以为实体设置严格的 #RRGGBB 自定义颜色，例如 #33CCFF。这项能力仅接受 Bukkit LivingEntity，不会作用于掉落物、弹射物等非生物实体。

自定义颜色优先于原版队伍颜色；清除自定义颜色后，实体重新遵循原版规则，包括发光状态与队伍颜色。Forge 1.20.1 与 NeoForge 1.21.1、1.21.4、1.21.8、1.21.11 中，原版实体和 ChaEngine 替换模型的实体主体都适用，额外挂载的时装、装备、方块模型和模型预览不适用。

Forge 1.16.5 当前不提供世界实体替换显示，因此该版本只对原版 LivingEntity 绘制自定义描边。

这是客户端轮廓描边，不是 Buff，也不是表面自发光或材质发光。它不会让模型在黑暗中自行发亮，也不会绕过客户端的原版实体轮廓开关、可见性判断、剔除或渲染距离。

同一实体的自定义颜色对所有玩家一致，重复设置会覆盖旧颜色。状态只保存在当前运行期；实体卸载、切换维度、插件重载或服务器重启时都会清理，不写入实体自身数据。

辅助命令 ​

/chaengine entity model set <entity> <id>
/chaengine entity model set <entity> <id> <temporary|permanent>
/chaengine entity model clear <entity>
/chaengine entity glow set <entity> <#RRGGBB>
/chaengine entity glow clear <entity>
/chaengine entity animation play <entity> <animation>
/chaengine entity animation stop <entity>

管理员玩家可以把 <entity> 写成 @aim 或 @nearest；控制台应使用实体 UUID 或当前运行期数字 ID。省略模式时按 temporary 处理。排查自动匹配时可以先执行 /chaengine entity model set @aim crystal_guardian temporary，验证结束后执行 /chaengine entity model clear @aim 恢复 match。

动画与同步时序 ​

客户端根据实体状态寻找空闲、移动、奔跑、攻击、受伤、死亡、跳跃、游泳、潜行和使用等动画名称；找不到时回退到可用的 idle。服务端触发特殊动画后，它会临时覆盖自动状态动画，停止后恢复自动选择。业务插件还可播放一层覆盖动画，让受击、技能等动作叠加在基础移动动画上。

玩家加入时服务端立即同步模型配置，并在 20 tick、60 tick 后补发。客户端注册相关能力后，永久强制状态还会在 1 tick、20 tick 后补发，用于处理登录阶段先后顺序。资源文件始终由客户端本地读取。

常见问题 ​

名称规则不匹配：先只保留一条 name#equal#实际名称，去掉颜色与插件前缀后验证，再逐项增加条件。

NBT 规则不匹配：确认键在实体保存数据顶层，且字符串表示与规则值完全一致；nbt 不使用通用比较操作符。

被强制模型后无法回到自动匹配：执行 /chaengine entity model clear <entity>；仅停止动画不会清除模型覆盖。

模型出现但状态动画不切换：核对动画文件中实际 ID，并查看模型动画的名称候选规则。

模型大小正确但攻击范围不对：确认服务端日志没有真实碰撞适配警告，并检查 collision；水平宽度取 X、Z 较大值，高度取 Y。

客户端日志显示 forced model id missing：服务端保存的强制 ID 不在本次同步配置中。恢复对应配置，或清除该实体的强制模型。

MythicMobs 生物没有替换模型：确认 ChaEngine 与 model 的缩进、ID 是否来自 entity/*.yml，并执行 /chaengine reload 后重新生成生物。若仍无效，查看服务端是否记录了未知 ID 的一次性警告，并确认客户端已收到同名模型配置。

相关文档 ​

• 第一个实体模型
• 模型动画
• 命令参考
• Java API