Custom Models - mchorse/blockbuster GitHub Wiki

This page describes how to load custom models into Blockbuster mod. Before reading this, you could try browsing through Blockbuster models YouTube playlist, or watching this video or this archived livestream.

All models that can be loaded by Blockbuster mod are stored in .minecraft\config\blockbuster\models\. Every folder with one of the model files (model.json, any .obj file, or any .vox file) is considered to be a model folder.

If you don't know how to find this folder, instead of finding the .minecraft folder, you can open McHorse's mods configuration screen (by pressing Ctrl + 0 in the world), select Blockbuster in the list on the left, and then click on Open models... button, and voilà!

Nested folders are supported. You can put model folders, within other folders within .minecraft\config\blockbuster\models\, and they will be displayed in a separate morph category under Blockbuster's models (which is good for organization).

You can rename the model folder by adding two underscores, i.e. __ in front of the model folder's name, and it will make Blockbuster ignore any model folder starting with __. Same works with nested folders, but all of the models within will be ignored.

Blockbuster primarily supports three model formats:

• Blockbuster's model JSON format (model.json file)
• OBJ models (.obj)
• MagicaVoxel models (.vox)

If you need to import Blockbench models, you can either export them as OBJs (following this tutorial) or using my Chameleon mod (following this and this tutorials).

OBJ is a widespread 3D format for static models, i.e. doesn't contain any animation data, and therefore can't be animated by itself. There are multiple videos that show how to import OBJ models into Blockbuster mod, like these:

• Importing static OBJ models (most recent livestream)
• Importing biped OBJ models (2020, with basic animations)
• Importing static OBJ models (2019, still works to an extent)

Installing OBJ models is in theory as simple as:

1. Creating a model folder in .minecraft\config\blockbuster\models\
2. Moving .obj and .mtl (if it exists) file(s) into the model folder
3. Moving the texture(s) to skins folder (see Texture(s) section below)

However, due to complexity of models that are usually uploaded on the internet, if you have no experience in loading OBJ models into Blockbuster mod, you'll encounter some issues at one point, therefore read a little guide/check list below.

If your model doesn't appear correctly in the game, it's recommended to check the model, by opening it in Blender, for following things:

• Scale, some models found on the internet can be quite gigantic, I found some that are bigger than 400 blocks tall. Obviously, such model won't appear at all because it will most likely clip the far plane. So what you need to do is to downscale that model.
• Orientation, some models found online can be rotated in the wrong direction, because it could be either a part of some composition, or maybe some game engines/3D software work with different coordinate system, so if the front of the model, isn't aligned with positive Y (see how it's done here).
• Mesh names, in Blender's outline, check that names of individual mesh objects use only numbers, English letters (with no accent) and spaces, hyphens or underscores. Blockbuster works poorly with Unicode (at least at the moment of writing of this) and there would be loading issues where the object will appear as a cube when having a name that contains Japanese, Chinese, Cyrillic, Latin with accents, etc. So if there are foreign characters, rename both object and data name (like shown here).
• N-gons, if you model have holes in it, you can either try to update to Blockbuster 2.3.1 or above, or when export (or re-export) the model with Triangulate Faces option in File > Export > Wavefront OBJ dialog enabled. Basically, before 2.3.1, Blockbuster didn't support non triangle or non quad faces, which use more than 4 sides to make a face, so triangulation is the easiest way to fix those holes.

Once everything is checked, you need to export the model by going File > Export > Wavefront OBJ. Enable appropriate options (if your model has only one texture, make sure to disable Write Materials) and overwrite the .obj file you initially opened. That should be it.

OBJ models can come with one or multiple textures. Sometimes they can come not only with textures, but also with material file, which can provide solid color materials, which might remove necessity for textures.

If you have only one texture and no materials (i.e. solid colors that aren't part of the texture), when setting up a model, you need to remove .mtl from model's folder, if such was generated. After that, you need to reload models (for example by executing /model reload command) and the texture should appear just fine. If it didn't, it's possible that the model was just shipped this way, nothing you can do about it.

If there were multiple diffuse* textures, if you loaded the OBJ model and it appears like purple and black, you need to setup materials. This excerpt of Blockbench OBJ video shows how to do it, but here is also a text version.

* - sometimes model come with different variants of the same textures, like weirdly colorful one, which is usually normal map; black and white, which could be roughness map; RGB looking, which could be specular, etc.

Step 1. Open the .mtl file.
Step 2. Look for lines that start with newmtl ... where ... is the name of material.
Step 3. After newmtl ... line, look for map_Kd ... line, but it must be before next newmtl ....
Step 4. For every map_Kd ... line, move the texture by the name of the image specified there to model's skins/MATERIAL_NAME/ folder, and rename the texture to default.png (exactly default.png). If the material should have a texture, BUT there is no map_Kd, then add a new line under newmtl ... that just has map_Kd texture.png or something like that.
Step 5. Once you moved all textures, go back to Minecraft, and execute /model clear command in the chat.

Once all of these steps were done, the textures should appear correctly. If they are not, then most likely you did something wrong, check that you correctly placed textures for every material, and renamed the texture to default.png.

For example, we have following .mtl file for my model named cup:

newmtl Paint_Black
Ns 62.745098
Ka 0.039216 0.039216 0.039216
Kd 0.039216 0.039216 0.039216
Ks 0.367059 0.367059 0.367059
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
map_Kd C:\Users\Admin\Downloads\model_from_the_internet\cup.png

newmtl Plastic_Black
Ns 21.568627
Ka 0.058823 0.058823 0.058823
Kd 0.153325 0.153325 0.153325
Ks 0.600000 0.600000 0.600000
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2

newmtl Plastic_Text
Ns 96.078431
Ka 1.000000 1.000000 1.000000
Kd 0.500000 0.500000 0.500000
Ks 0.350588 0.350588 0.350588
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2
map_Kd C:\Users\Admin\Downloads\model_from_the_internet\label.png
map_Kd_linear

newmtl Wh
Ns 62.745098
Ka 0.019608 0.019608 0.019608
Kd 0.019608 0.019608 0.019608
Ks 0.362353 0.362353 0.362353
Ke 0.000000 0.000000 0.000000
Ni 1.000000
d 1.000000
illum 2

In this example, there are for materials Paint_Black, Plastic_Black, Plastic_Text and Wh. Only Paint_Black and Plastic_Text have textures (because only they have map_Kd below them until the next material), while Plastic_Black and Wh are solid color materials. What I should do for this model, is take those two textures specified in both map_Kd's, and move the to model's materials, which is something like this:

• C:\Users\Admin\Downloads\model_from_the_internet\cup.png goes to .minecraft\config\blockbuster\models\cup\skins\Paint_Black\default.png
• C:\Users\Admin\Downloads\model_from_the_internet\label.png goes to .minecraft\config\blockbuster\models\cup\skins\Plastic_Text\default.png

After reloading textures with /model clear, it should work. Since Plastic_Black and Wh are solid colored materials, Blockbuster will automatically paint all of the geometry with the color specified under newmtl ... in Kd R G B instruction.

If by any chance you downloaded a model that is in a 3D software model format like .blend, .libc4d, or 3D Max or Maya formats, in some cases all, or some, textures are actually not textures but they can be procedurally generated. In such case, you'll need to somehow bake the texture (which is most likely difficult, and you'll need to do your own research to find out how it's done).

MagicaVoxel is a voxel editor. With it, it's much simpler to create dedicated voxel (cubic) models outside of Minecraft. It's a pretty intuitive tool (just like building in Minecraft) to create cubic models. Beside that, polygonal models can be turned into voxel models pretty easily.

MagicaVoxel models can be imported pretty easily into Blockbuster mod. All you have to do is to create a new folder in .minecraft\config\blockbuster\models\, and place there .vox file, and upon opening the morph picker, that model would be there. Alternatively, watch basic or character tutorial video(s).