猹件开发组

Appearance

On this page

方块模型 ​

方块模型使用可放置的载体物品。载体物品与放置后的方块实体都保存模型 ID，客户端从它们自己的 NBT 恢复渲染，不维护“方块坐标到模型 ID”的映射。

完整配置 ​

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

yaml
blue_crystal:                               # 配置节点名；未另写 id 时就是模型 ID
  display: "蓝色水晶"                      # 获取和破坏掉落时的物品名
  model: "crystal/crystal.geo.json"        # 相对于客户端 model/ 的模型路径
  animation: "crystal/crystal.animation.json" # 可选动画文件
  texture: "crystal/crystal.png"           # 模型贴图
  item-texture: "crystal/crystal_item.png" # 可选的载体物品贴图
  default-animation: "idle"                # 可选默认动画 ID
  scale: 1.0                                # 统一缩放
  position: [0, 0, 0]                      # X、Y、Z 偏移
  rotation: [0, 0, 0]                      # X、Y、Z 旋转角度
  collision: [1, 1, 1]                     # X、Y、Z 碰撞体积
  brightness: 15                          # 可选固定亮度；0-15，省略时跟随世界光照

客户端文件位于：

text
resourcepacks/ChaEngine/model/crystal/crystal.geo.json
resourcepacks/ChaEngine/model/crystal/crystal.animation.json
resourcepacks/ChaEngine/model/crystal/crystal.png
resourcepacks/ChaEngine/model/crystal/crystal_item.png

字段说明 ​

字段必填默认值说明
display建议空载体物品的显示名
model是无.geo.json、受支持的 .obj 或其他已支持模型格式的相对路径
animation否空动画文件相对路径；静态模型可省略
texture是无模型贴图相对路径
item-texture否空方块作为物品渲染时使用的替代贴图；省略时使用 texture
default-animation否空放置模型与物品模型的默认动画 ID
scale否1.0整体缩放倍数
position否[0, 0, 0]模型偏移，同时参与碰撞箱定位
rotation否[0, 0, 0]模型的 X、Y、Z 旋转微调
collision否[1, 1, 1]以方块为单位的碰撞箱宽、高、深；任一轴不大于零时得到空碰撞
brightness否跟随世界光照自定义方块模型的固定亮度，取值 0 到 15；0 最暗，15 为满亮度

配置节点名默认作为 ID。ID 必须在方块配置中唯一；操作中使用的是 ID，不是 display。

运行规则 ​

载体物品与放置 ​

ChaEngine 生成的方块载体物品保存模型 ID。玩家放置后，服务端把该 ID 写入载体方块自身可保存的数据。区块重新载入时，服务端和客户端都从方块数据恢复模型。

普通玩家头颅没有这份模型数据，不会因为放在某个坐标就自动变成模型。管理员可以用下方 block set 命令修改已经存在的合法载体方块，但目标必须确实是受支持的载体方块。

辅助命令 ​

text
/chaengine block get <id>
/chaengine block give <id> <player>
/chaengine block set <id> <location>
/chaengine block debug settarget <id>
/chaengine block animation play <location> <animation>
/chaengine block animation stop <location>

<location> 推荐写成 世界名,X,Y,Z，例如 world,120,64,-35。block set 把模型 ID 写入目标载体方块自身数据；block debug settarget 只能由游戏内玩家执行，用于检查八格内准星指向的玩家头颅，不应成为正式业务流程。两者都不会建立坐标映射。

破坏与掉落 ​

合法模型方块被破坏时，服务端按配置生成带有同一模型 ID 和 display 的载体掉落物。再次放置该物品即可恢复模型。其他插件若在事件链中替换方块或掉落物，可能改变这一结果，应先在无冲突环境验证。

碰撞与旋转 ​

客户端根据 collision、position 和方块朝向生成碰撞形状。水平旋转会同步旋转碰撞箱的宽深范围；配置 ID 已知但定义暂不可用时使用整方块碰撞。碰撞配置影响客户端交互形状，不会把模型身份写入坐标表。

亮度 ​

brightness 只影响自定义方块模型的方块渲染。省略该字段、填写 -1，或填写超出 0 到 15 的值时，模型跟随所在位置的世界光照；填写 0 到 15 时使用对应的固定方块与天空光照级别。它不改变物品渲染、碰撞或实体模型。

动画操作 ​

default-animation 在该方块没有显式动画状态时使用。block animation play 会替换同一方块的旧特殊动画，block animation stop 会进入无动画状态，而不是自动恢复默认动画。资源状态清理或重新建立后，才重新从配置默认值开始。

资源失败 ​

  • model、texture 或必需资源缺失：该模型不渲染，并记录资源错误。
  • 动画文件或动画 ID 缺失：静态模型仍可显示，但对应动画不可用。
  • 路径非法：客户端拒绝读取资源根以外的文件。
  • ChaAssets 返回未授权或包损坏：失败关闭，不用同路径明文文件回退。

常见问题 ​

只显示载体外观：检查物品或方块是否由 ChaEngine 生成，再检查客户端是否收到 blue_crystal 配置。

模型能显示但碰撞不对：从 [1, 1, 1] 开始小幅调整 collision 与 position，并在不同朝向分别测试。

放置后正常，重启后丢失：排查是否有其他插件清理或重写载体方块 NBT；不要添加坐标映射作为补偿。

破坏不掉落模型物品：检查保护、掉落和方块替换类插件是否取消或改写了破坏流程。

相关文档 ​