开始使用模型
模型加载与配置指南
模型概述
ArcartX 支持两种模型格式:
- bbmodel 格式:BlockBench 的原生格式,可读取 Java 模型、基岩模型、通用模型。推荐使用。
- geo 格式:基岩模型的导出格式(
.geo.json+.animation.json+.png)。
模型格式
- ArcartX 的模型格式是 ArcartX 的特化格式,我们支持通用模型的大部分能力,比如网格、多贴图以及基础的 Cube 几何能力。
- 此外,我们支持序列帧、相机动画、显示调整等原通用模型未提供的能力。
- 该格式可使用我们的插件注册到你的 BlockBench:点我下载
模型渲染
AX 提供 CPU 与 GPU 渲染路径,并支持模型附加特效。默认自动选择当前模型和渲染环境可以使用的路径;模型、材质、光影、预览或第一人称叠加等条件都可能使某次绘制使用 CPU。
需要排查渲染问题或做固定条件对比时,可在客户端启动参数中添加 -Darcartx.model.renderPath=cpu 禁用 GPU 模型路径。该参数在类初始化时读取,修改后需要重启客户端。默认值 auto 允许自动选择,不强制模型使用 GPU。
bbmodel 中一些复杂的运动方式(如 lk 等)在直接读取时无法解析,需要先在 BlockBench 中导出为 geo 格式,再导入回 bbmodel。
模型加载
模型文件放入客户端 ArcartX/resource/model 文件夹下。
bbmodel 格式
将 .bbmodel 文件放入 ArcartX/resource/model 文件夹。

重载客户端资源(或重启客户端),查看客户端日志确认模型是否加载成功。日志中输出的名称就是后续使用的模型 ID。

如果需要发光贴图,在模型的贴图列表中添加一个名为 [主贴图名]_glow 的贴图即可。

geo 格式
准备好模型文件,按以下命名规则放入 ArcartX/resource/model 文件夹:
xxx.geo.json— 模型文件xxx.animation.json— 动画文件(可选)xxx.png— 贴图文件xxx.glow.png— 发光贴图(可选)

重载客户端资源,查看客户端日志确认加载结果。

axmeta 扩展数据文件
axmeta 文件用于为模型配置额外参数。文件名格式为 模型名.axmeta.json,放在模型文件的同级目录下。
各字段说明:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| glow_level | int | 0 | 发光等级,取值 0~15 |
| double_sided | boolean | false | 是否使用同一套 UV 渲染模型的正反两面 |
| player_skin | boolean | false | 是否将贴图替换为玩家皮肤(仅对玩家实体有效) |
| item_scale | double | 1.0 | 物品类型模型的缩放比例,影响物品、方块、特效、掉落物附加模型的尺寸 |
| distance | double | 16 | 方块模型的靠近动画触发距离(格),玩家进入此距离时播放靠近动画 |
| hand_offset | float[3] | [0,0,0] | 第一人称手部模型的偏移量 [x, y, z] |
| player_host | object | 无 | 自定义玩家宿主的骨骼归属、附件定位器与时装槽位配置 |
如果希望从模型背面也能看到相同贴图,将 double_sided 设为 true。它对主模型和多贴图部件已有的面生效,背面沿用原面的 UV,不会补出模型中不存在的面。此选项不会让模型发光;正常的发光贴图渲染也会遵循双面设置。修改后重载客户端资源即可生效。
如果所有字段都使用默认值,不需要创建 axmeta 文件。
自定义玩家宿主
当外部模型使用 DEFAULT_BBMODEL 变体时,可以在 axmeta 中增加 player_host,声明这个模型的身体部位、手持物品与鞘翅定位器,以及自定义时装槽位。配置方法见玩家动作/时装篇中的「自定义玩家宿主」。
该配置不作用于内置玩家宿主或 CUSTOM_BBMODEL。未添加配置的旧模型保持原有行为。配置错误只会关闭新宿主附件,不会让模型本体加载失败。
玩家皮肤贴图
player_skin 设为 true 时,会将模型的所有贴图替换为玩家皮肤。如果你使用的是多贴图模型,只想让部分贴图使用玩家皮肤,可以将对应贴图命名为 player_skin.png,这样只有这张贴图会被替换。
