An extensive guide for Minecraft's obj loader (Forge/Neoforge)

obj-loader-guide.md

1) Preparing our .obj model!

If you are reading this, you probably have a .obj file already, and also a .mtl file if you want to textures on it.

Common issue: your .obj has Quads! Minecraft mod loaders do not accept Quads, you MUST Triangulate your model.

How to triangulate your model (Blender):

• Open your Obj file with the .mtl (Also called Wavefront format)
• Select "Edit Mode", you can either use the Tab key (⇥) or click manually in "Object Mode" to change the mode to "Edit".
• Click "A", so that you select all faces of the model. You should see them in a more orange color.
• Click "Control + T" to triangulate the faces.
• Done! You can now go to File > Export > Wavefront (.obj), it will also create the .mtl alongside the .obj

Another common issue is a unconfigured .mtl, where you aren't referencing the textures you want right.

Simplest .mtl:

newmtl m_cd691c73-cb2a-3c69-3087-31ec41884691
map_Kd minecraft:block/dirt

These are the 2 only important and needed values. newmtl (id) is the id of the texture used in the .obj file. It references a texture id so that inside the .obj file can be referenced with usemtl (id). In the other hand, map_Kd (texture) is the important statement, which you will have to manually change so that you can use your texture. You can use #texture0 instead of minecraft:block/dirt so you can add the texture on the jsons (cleaner!), will be explained further down the guide.

In the first line of an .obj file:

mtllib your_model.mtl

This is the line that tells the .obj which .mtl to use, so if you renamed your .mtl, you have to change this line accordingly.

Note: both the .obj and the .mtl must be inside the models/ folder, and in the same folder.

2) Prepare the jsons!

This is an example_block.json, it's the model's json. It's loaded by the blockstate's json as with any other block in modding.

{
  "loader": "neoforge:obj",
  "model": "examplemod:models/block/your_model.obj",
  "textures": {
    "texture0": "minecraft:block/dirt"
  }
}

• loader loads the correct loader for the obj format, if you are on forge use forge:obj.
• model is the folder where your .obj and .mtl are.
• texture0 is the reference used in the map_Kd inside the .mtl

Other fields for the model json of the block (Click to reveal)

{
  "loader": "neoforge:obj",
  "model": "examplemod:models/block/your_model.obj",
  "textures": {
    "texture0": "minecraft:block/dirt"
  }
  "shade_quads": false,
  "flip_v": true,
  "emissive_ambient": false
}

• flip_v flips texture V coordinates (vertical). Use true if textures appear upside down.
• shade_quads when the texture isn't properly applied in the model, it will show certain parts black, this makes them invisible so the mistakes while modeling are harder to notice.
• emissive_ambient adds a shadow at the bottom of the model, like MC entities have.

By now the model and texture should render properly! there shouldn't be issues with them if the model is done right.

3) Positioning X and Z axis

This guide covers Blender, but can be done with any editor in a similar way.

Example of the issue: As you can see above, the model is in a corner of the block, instead of being horizontally centered. This section aims to solve this.

• Open Blender, select with "A" the default dube, press "Delete" key.
• Open your folder with your_model.obj and your_model.mtl and drop them in Blender.

It shows in the center, but renders at a corner in minecraft. We need to offset it 0.5 to each horizontal axis.

• Make sure the whole object is selected (Click "A")
• Press "G", then "X"(the axis), then "0.5", then "Enter" key.
• Repeat the same with the Y axis but for "-0.5" instead of "0.5".
• Export the model as Wavefront (.obj) and fix your .mtl and .obj manually if needed

BEFORE:

AFTER: