Logo 3.5Cats_AndHalfAFish

3.5Cats_AndHalfAFish

From MagicaVoxel to Godot.

March 17, 2019 Bethee, MagicaVoxel, Blender, Godot
Getting started with MagicaVoxel, Blender, and Godot (part 2).

Disclaimer : I don't claim to know what I'm doing ; I'm discovering things as I go.

I'm using MagicaVoxel 0.99.3, Blender 2.76, and Godot 3.0.6.

Godot is a free and open-source, no strings attached game engine. It can be used for 2d and 3d games. Everything is based on Nodes in a SceneTree, and scripts. The documentation is good, and the community is friendly.
I've been using Godot for a short time only, while working on a 2d hidden object game (wip). The node system takes a bit of getting used to ; it is not quite the same node system as in eg. the ActionScript display list. In fact, it is much more powerful ! I was also surprised by how little code one has to write to get things going ... Amazing.

Blender is a free and open source 3d creation package. It is a very powerful tool and quite complicated to get started with. But I will only use it for cleaning up MagicaVoxel meshes and creating .dae or .obj export files (to be imported in Godot).


As I indicated in the previous blog post, there are several ways to get your model from MagicaVoxel into Godot. You can :

  • install the Godot addon 'MagicaVoxel Importer' by Scayze. This allows you to use the .vox files without first exporting them.
  • export your model to .obj (wavefront) and import it into Godot. You will also need your saved palette (.png file).
  • export your model to .obj or .ply (Stanford) and import into Blender. Clean up, or do whatever. Export as .dae (Collada) or .obj, and import into Godot.

Using the Godot addon.

Installing the MagicaVoxel addon (1/3).
Installing the MagicaVoxel addon in Godot (1/3).

The addon is installed on a per-project basis. In other words : you can only install it in an existing project !
Go to the AssetLib tab (1), and search for 'MagicaVoxel' (2). Click the 'MagicaVoxel Importer' by Scayze, and press 'install'. I'm using version 1.3 of the addon.

Installing the MagicaVoxel addon (2/3).
Installing the MagicaVoxel addon in Godot (2/3).

You see a 'success' message (1) when the addon has finished downloading. Click the 'install' button to install the addon in your project 'res' folder (2).

Installing the MagicaVoxel addon (3/3).
Installing the MagicaVoxel addon in Godot (3/3).

Finally, go to Project Settings (1) 'Plugins' tab, and activate the plugin (2).

MagicaVoxel addon and .vox files.
MagicaVoxel addon and .vox files.

(1) The project res folder now contains the activated addon.
(2) I also copied a MagicaVoxel .vox file into the res folder.

MagicaVoxel addon and .vox file.
Using MagicaVoxel .vox files in Godot.

If you double click the .vox file, you'll see that the MagicaVoxel model has been imported as an ArrayMesh (1) with material (2). I'm not really sure what an ArrayMesh is, but I'm assuming it's an array of mesh vertices (location, color, ... info). If you click the material slot in the inspector (2), you'll see that it is actually a SpatialMaterial (3) that uses vertex colors as albedo (4) (not a texture).

Displaying the MagicaVoxel model in Godot
Displaying the MagicaVoxel model in Godot.

To actually use the MagicaVoxel file in a scene, you can either drag the .vox file onto the viewport, or, create a MeshInstance node and drag the .vox file onto the Mesh property in the inspector.
Notice the size of the cube : 4x4x4 large squares on the editor grid (= 40x40x40 voxels in MagicaVoxel). The origin of the cube has the same (x,y,z) position as the mesh had in the world view in MagicaVoxel.

Note : It seems that the size of the .vox meshes is 10 times larger in Godot than it should be (?). You can either scale all meshes manually, find a way to modify the addon script (?), or not care. =)

Using an .obj file exported from MagicaVoxel.

Obj export from MagicaVoxel.
.Obj export from MagicaVoxel.

(1) Simply press the obj export btn ... You're done.
The exporter has created 3 files : an .obj file, a .mtl file, and a .png file.

Importing the MagicaVoxel .obj file into Godot.
Importing the MagicaVoxel .obj file into Godot.

If you copy the 3 files into the res folder of your project, Godot will create an ArrayMesh with a material for you. The SpatialMaterial however is not using vertex colors now ; it is using an albedo texture (.png). The .png file is 256x1 px ; it contains the custom palette. Sometimes Godot automatically sets the texture, other times you need to drag the .png file onto the texture slot of the Albedo property. Not sure why that sometimes happens.

Using the .obj MagicaVoxel export file in Godot.
Using the .obj MagicaVoxel export file in Godot.

To add the model to the viewport, I created a Spatial root node with a MeshInstance child, and dragged the .obj file into the Mesh slot.
Notice the size of the cube : 4x4x4 small squares (which makes the model 10x smaller in every direction, as compared to using the .vox files directly !) The origin of the mesh is the same was it was in the MagicaVoxel world view.

Importing an .obj file from MagicaVoxel into Blender and exporting it as a .dae or .obj file.

.Obj import into Blender.
.Obj import into Blender (default settings).
Model with material and texture.
Mesh with material and texture.

(1) If you switch to the material shading tab in the viewport, you'll see that the .obj file generated a cube mesh with a (2) material (called 'palette' by default), and a texture (3) with the color information coming from flag.png (4), the color palette that we used in MagicaVoxel.
Notice the position of the cube on the Blender grid. This is what happens if you don't position the MagicaVoxel mesh over (0,0,0) in the world view (I did this on purpose). If necesarry, this can be corrected in Blender.

Removing double vertices from the mesh.
Removing double vertices from the mesh (in Blender).

(1) If we go into edit mode by selecting the cube and pressing 'tab', we see what the mesh really looks like. It's a cube shape with triangular faces and 40 vertices (quite a lot for a simple cube with 3 colors). We can improve this be selecting all vertices and selecting 'remove doubles' from the left menu.
We are now left with a funky looking cube with only 16 vertices (2). The strange look of the cube (a bit hard to see in this image) is due to shading ; change it from 'smooth' to 'flat' in object mode ... and all is well again.

Setting the correct origin for the cube.
Setting the correct origin for the cube.

And while we're in Blender, we might as well set the preferred mesh origin. That will save us some trouble later on in Godot.
(1) In edit mode, select all verts, and choose 'snap cursor to selected' to set the 3d cursor to the center of the mesh. If it is more convenient, you can also select another origin : the center of the bottom face, the bottom left vertex, ...
Back in object mode (2), choose 'transform' - 'origin to 3d cursor'. Done (3).

We are now ready to export our model to either .dae or .obj. You do this in Blender by going to the file menu and selecting the 'export' option.
Edit : It seems that Godot 3.1 can no longer work with the .mtl file produced by the Blender obj exporter : "Couldn't open MTL file ; it may not exist or not be readable" ... See Animations in 3d for my preferred workflow in Godot 3.1.

I created a test scene in Blender to illustrate the difference between a .dae export and an .obj export.
The scene contains a camera and light source, a plane, and 2 cubes. I selected everything in the scene for export.

A Blender export test scene.
A Blender export test scene.

These are the options I picked in the export menus :

Exporting a Blender test scene.
Exporting a Blender test scene.

I'm actually not very sure about most of the options in the export menus, but these seem to work fine. I think it's a good idea to use 'selected only', and with the .obj export you have to make sure the up and forward axes are correct for Godot (Blender uses Z up, Godot uses Y up !).

The .dae exporter produces a single file. If you open it in a text editor, you can see that litterally every setting from the Blender scene is present : camera settings, light and shadow settings, material settings, and mesh info.
Copying the .dae file to the Godot res folder creates several files : one .dae file, and one .mtl file for each material used in Blender. Double clicking the .dae file triggers this popup :

Importing the .dae file into Godot (1/2).
Importing the .dae file into Godot (1/2).

If we select 'open anyway', we can see what was imported into Godot : our entire scene ! We can hit the F6 button right away to test it out.

Importing the .dae file into Godot (2/2).
Importing the .dae file into Godot (2/2).

To actually use the imported scene in your game, you need to 'Instance the scene' (rather than adding it as a child node) :

Using the .dae file in Godot.
Using the .dae file in Godot.

Notice that the origin of the imported scene is the same as the one we set in Blender. The size of the cubes is also the same as in Blender.
If we want to change something in our imported scene (cube location, material, ...) , we need to pick the 'New Inherited' option in the popup menu and save the modified scene.

Now, let's take a lookt at what the Blender .obj exporter produced : an .obj file and a .mtl file. If you open them in a text editor, you'll see that the files are a lot simpler than the .dae file. The .obj file contains mesh info, and the .mtl file has simple material info.
Copying the 2 files to the Godot res folder results in only one file : the .obj file. Double clicking the file and looking at the information in the properties tab, shows us the ArrayMesh and the 3 materials :

Importing the .obj file into Godot.
Importing the .obj file into Godot.

To actually use the file, we need to create a MeshInstance node, just like before. If we want to test the scene, we'll need to add a camera and a light source as well.
If we want to modify something in the imported scene, we actually have to reimport the .obj file. Select the .obj file, go to the 'import' tab and select 'import as scene'. Press the 'reimport' button. You can now follow the same workflow as earlier, with the .dae file import.

Modifying the imported .obj scene in Godot.
Modifying the imported .obj scene in Godot.

In summary.

Well, not really 'in summary'. I just wanted to have a quick look at file sizes and run metrics with a simple test scene.

Godot Monitor : MagicaVoxel addon + .vox file.
Godot Monitor : MagicaVoxel addon + .vox file.
Godot Monitor : MagicaVoxel .obj + .png files.
Godot Monitor : MagicaVoxel .obj + .png files.
Godot Monitor : Blender .obj + MagicaVoxel .png files.
Godot Monitor : Blender .obj + MagicaVoxel .png files.

Two conclusions :

  • Using the .vox files in Godot should only be used for quickly testing things out. The vertex count (and vertext video memory) are significantly higher. There's also the problem of the mesh scaling.
  • Surprisingly, the debugger monitor tab shows no difference between the Blender optimized .obj and the .obj straight from MagicaVoxel. Godot must be doing the double vertex removal behind the scenes !
    The file size however seems to be different, but maybe I made a mistake somewhere. Blender will only need to be a necessary step if you want to change the mesh origin.

Note : it would be interesting to also compare the optimized .exe files for the 3 test projects.