LogoArcartX Doc
模型篇

开始使用模型

模型加载与配置指南

模型概述

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 文件夹。

bbmodel 文件放置位置

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

客户端日志中的模型加载信息

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

发光贴图命名示例

geo 格式

准备好模型文件,按以下命名规则放入 ArcartX/resource/model 文件夹:

  • xxx.geo.json — 模型文件
  • xxx.animation.json — 动画文件(可选)
  • xxx.png — 贴图文件
  • xxx.glow.png — 发光贴图(可选)
geo 格式文件命名示例

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

geo 格式加载日志

axmeta 扩展数据文件

axmeta 文件用于为模型配置额外参数。文件名格式为 模型名.axmeta.json,放在模型文件的同级目录下。

axmeta 文件放置位置
{
    "glow_level": 0,
    "double_sided": false,
    "player_skin": false,
    "item_scale": 1.0,
    "distance": 16,
    "hand_offset": [0, 0, 0]
}

各字段说明:

字段类型默认值说明
glow_levelint0发光等级,取值 0~15
double_sidedbooleanfalse是否使用同一套 UV 渲染模型的正反两面
player_skinbooleanfalse是否将贴图替换为玩家皮肤(仅对玩家实体有效)
item_scaledouble1.0物品类型模型的缩放比例,影响物品、方块、特效、掉落物附加模型的尺寸
distancedouble16方块模型的靠近动画触发距离(格),玩家进入此距离时播放靠近动画
hand_offsetfloat[3][0,0,0]第一人称手部模型的偏移量 [x, y, z]
player_hostobject无自定义玩家宿主的骨骼归属、附件定位器与时装槽位配置

如果希望从模型背面也能看到相同贴图,将 double_sided 设为 true。它对主模型和多贴图部件已有的面生效,背面沿用原面的 UV,不会补出模型中不存在的面。此选项不会让模型发光;正常的发光贴图渲染也会遵循双面设置。修改后重载客户端资源即可生效。

如果所有字段都使用默认值,不需要创建 axmeta 文件。

自定义玩家宿主

当外部模型使用 DEFAULT_BBMODEL 变体时,可以在 axmeta 中增加 player_host,声明这个模型的身体部位、手持物品与鞘翅定位器,以及自定义时装槽位。配置方法见玩家动作/时装篇中的「自定义玩家宿主」。

该配置不作用于内置玩家宿主或 CUSTOM_BBMODEL。未添加配置的旧模型保持原有行为。配置错误只会关闭新宿主附件,不会让模型本体加载失败。

玩家皮肤贴图

player_skin 设为 true 时,会将模型的所有贴图替换为玩家皮肤。如果你使用的是多贴图模型,只想让部分贴图使用玩家皮肤,可以将对应贴图命名为 player_skin.png,这样只有这张贴图会被替换。

On this page