猹件开发组第一个实体模型
完成后的效果
完成后，任何名称精确为“水晶守卫”的实体都会显示成你准备的模型。客户端会根据实体状态尝试播放 idle、walk、attack 等已有动画，不需要为普通移动逐次发送操作。
开始前准备
- 服务端已安装 ChaCore 与 ChaEngine。
- 客户端已安装对应版本的 ChaEngineMod。
- 准备实体模型、贴图和动画文件。
- 准备一个可以改名的测试生物。建议先使用原版生物完成验证，再接入其他生物插件。
准备资源文件
在每个客户端放置：
resourcepacks/ChaEngine/model/guardian/
├─ guardian.geo.json
├─ guardian.animation.json
└─ guardian.png动画文件至少准备 idle；如果希望移动、攻击时有不同表现，再加入 walk、attack 等对应动画 ID。
编写完整配置
在服务端创建 plugins/ChaEngine/entity/guardian.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:
- "name#equal#水晶守卫" # 名称完全相等时匹配match 的组合规则为：
- 多个列表行之间是 或：任意一行成立即可匹配。
- 同一行用英文逗号分开的多个条件之间是 且：该行所有条件都成立才匹配。
例如下面的扩展示例表示“名称以水晶开头且类型是僵尸”，或者“名称精确为水晶守卫”，满足任意一行即可：
match:
- "name#start#水晶,type#equal#minecraft:zombie"
- "name#equal#水晶守卫"第一次测试先使用教程中的单行精确名称，减少变量。
加载并生成测试实体
- 保存 YAML，由管理员执行
/chaengine reload。 - 在测试位置生成一个原版生物。
- 使用命名牌或可靠的服务端方式，把它的显示名设为
水晶守卫。 - 让已准备资源的客户端靠近该实体。
- 让实体静止、移动和攻击，观察动画变化。
服务端只同步配置和操作，不发送模型资源。实体名称匹配成功但文件缺失时，客户端仍无法显示模型。
重载命令：
/chaengine reload可选：区分匹配问题与资源问题
自动匹配没有显示时，管理员玩家可以瞄准测试实体，临时强制使用刚配置的模型：
/chaengine entity model set @aim crystal_guardian temporary如果强制后能显示，优先检查 match；如果仍不显示，优先检查客户端模型、贴图和 Mod。诊断结束后清除覆盖，重新验证教程要求的自动匹配：
/chaengine entity model clear @aim这两条命令只用于隔离问题，不能代替正常的 match 配置。
如何确认成功
- 只有名称精确为“水晶守卫”的实体被替换。
- 未改名的同类型实体保持原版外观。
- 静止时能播放
idle。 - 动画文件含
walk或其他受识别状态动画时，实体状态变化会切换动画。 - 玩家重新进服后，配置仍会同步并继续匹配现有实体。
常见问题
所有实体都没有模型：先确认客户端 Mod 已加载、三个资源文件存在，再检查服务端是否成功重载 crystal_guardian。
名称看起来相同但不匹配：检查实际自定义名是否包含颜色、前后缀或额外空格。先用无格式的精确名称完成测试，之后再按需要改用前缀或包含匹配。
模型出现但总是静止：检查动画文件是否存在 idle；移动动画可使用该实体状态支持的约定名称。找不到当前状态动画时会回退到可用默认动作。
一行多条件始终失败：逐个拆成单条件确认字段值，再用英文逗号合并。不要把“且”条件误写成多个列表行。
需要查看更多证据：开启客户端调试日志，按顺序查找配置已同步、实体已匹配、模型文件缺失、贴图缺失或动画缺失等信息；无需检查内部通信数据布局。
下一步
需要直接使用 Blockbench 工程时，把模型路径改为 guardian/guardian.bbmodel，并阅读Blockbench .bbmodel 模型中的 outliner、动画和安全路径要求。