OBJ 模型 ​

ChaEngineMod 可以根据 model 路径扩展名选择模型格式：.obj 进入静态 OBJ 解析器，.java.json 进入 Java 模型解析器，.geo.json 或其他 .json 进入 Geo 模型解析器。

完整示例 ​

服务端方块配置：

stone_statue:
  display: "石像"
  model: "statue/statue.obj"      # 扩展名决定使用 OBJ
  texture: "statue/statue.png"    # OBJ 使用这一张配置贴图
  scale: 1.0
  position: [0, 0, 0]
  rotation: [0, 0, 0]
  collision: [1, 1, 1]

客户端文件：

resourcepacks/ChaEngine/model/statue/
├─ statue.obj
├─ statue.mtl   # 可以保留用于源素材管理，但 ChaEngineMod 不读取
└─ statue.png

支持版本与模型类别 ​

在支持的模块中，OBJ 可用于方块、物品、实体、玩家时装和通用模型预览。它们共用原有模型 ID、资源读取、变换和缓存规则。NeoForge 1.21.4 当前模块没有接入共享 OBJ 解析与网格转换路径，因此不能沿用 1.21.1 的 OBJ 实现；用同一资源分别验证时，应在该版本改用等价 .geo.json，其余公开配置含义保持一致。

支持的 OBJ 内容 ​

• v：三维顶点，支持可选齐次坐标 w，但 w 不能为零。
• vt：纹理坐标；只写 u 时 v 默认为零。
• vn：法线。
• f：三角形或多边形面；多边形按扇形拆成三角形。
• o、g：记录对象或分组名称。
• 正索引和负索引。

缺少 UV 时使用稳定的默认 UV；缺少法线时从三角形计算。OBJ 的 1 个单位按 1 个方块处理，内部换算为 16 个模型单位，并修正 Z 轴、V 轴和顶点绕序以适配渲染坐标。

材质与 MTL ​

当前不读取 mtllib、usemtl 或 .mtl 内容，也不按材质拆分网格。OBJ 始终使用 YAML 的单张 texture。这些未识别指令会被忽略，不会赋予多材质能力。

需要多种视觉材质时，应把它们合并到一张纹理图集并调整 OBJ UV，或拆成多个 ChaEngine 模型配置。

运行规则 ​

OBJ 仅支持静态网格，不支持骨骼、关键帧或 animation。如果同一配置填写 animation 或 default-animation，客户端忽略动画并记录警告，模型仍可静态显示。

Forge 1.16.5 的旧渲染接口会把光照方向归一到最接近的六个方块方向；轮廓、UV、坐标和公开变换与 1.21.1 相同，斜面光照可能有轻微差异。

限制与拒绝条件 ​

以下情况会拒绝整个模型：没有任何面、面少于三个顶点、索引为零或越界、数值为 NaN/Infinity、齐次坐标 w 为零、三角形面积为零，或超过任一安全限制。失败后不会用猜测结果继续渲染。

常见问题 ​

配置后仍按 JSON 读取：确认 model 最终以 .obj 结尾；扩展名选择不依赖 .mtl。

贴图全错：ChaEngineMod 忽略 MTL，请把正确的单张 PNG 写到 YAML 的 texture，并检查 OBJ UV。

模型大小不对：导出时按“1 OBJ 单位 = 1 方块”准备，再用配置 scale 做最终微调。

只有 NeoForge 1.21.4 不显示：该模块当前未接入 OBJ 路径，改用等价 .geo.json；不要通过修改路径扩展名伪装格式。

动画不播放：OBJ 只支持静态网格。需要骨骼动画时使用 .geo.json。

相关文档 ​

• 资源目录
• 方块模型
• 物品模型
• 版本兼容