modtools/doc/blockbench_to_luanti.md

blockbench_to_luanti.sed Usage Instructions

This file is a script for the sed unix command-line utility that takes Blockbench-generated WaveFront OBJ model files (with correct configuration, see below) and modifies them such that Luanti's texture mapping will work correctly for them.

Setting up the Blockbench Project

If your model only uses one texture (one entry in the tiles array), the only thing this script will do is remove comments, empty lines, and commands that Luanti does not use (such as material specifications).

Otherwise, if you need to use more than one texture, this script will allow you to specify textures per-"cube" (in blockbench terms) by renaming cubes.

By default all cubes will use the first entry in the tiles array, but by naming a cube mat<n> where n is a positive whole number, you can specify that that cube and all the following cubes (those below it in the tree viewer) should use the texture n+1; for example, naming a cube mat1 will use the second tile from that point on until a cube named mat2 is encountered, which will use the third tile and so on.

Be aware that the textures must be specified in increasing numerical order, and mat0 will result in an invalid file as 0 is not a valid group ID (all vertices are by default part of the 0th vertex group).

Using the Script

To apply the script to a file, run sed -r -f blockbench_to_luanti.sed model.obj > new_model.obj to create a new model from the existing one, or sed -i -r -f blockbench_to_luanti.sed model.obj to replace the model with the new Luanti-compatible version.

Other Considerations

• Blockbench's "ground plane" is at 0, which is correct for Minecraft models but will result in models offset upward by half a node if used as-is in Luanti. Select all cubes and move down by 8 Blockbench units to correct for this.

• Untextured and fully obscured faces are left in by Blockbench's OBJ exporter, which may reduce performance in situations with lots of meshes. Once you're finished configuring UVs for your model, select all cubes then go to Tools > Remove Blank Faces. This will delete all faces without a set texture.

• Planes (cubes of 0 width on one axis) are normal in Minecraft but will cause issues in Luanti. If one of the faces is not flipped along the texture's lines of symmetry, Z-fighting (texture flickering) will occur, and in all cases dynamic shadows will appear to be applied twice to the plane, resulting in faces that appear twice as dark as they should. To avoid these issues simply leave one face of the plane untextured (and perhaps remove it as shown above).

• Luanti doesn't use materials, so you can safely delete the filename.mtl files generated by Blockbench.

• Blockbench will usually create a duplicate of your texture files in the export directory. These should be deleted as well.