Voxcom is a tool for compositing multiple MagicaVoxel models into a combined scene.
You can specify in a .yaml
file the location and orientation of each .vox
model.
The output is a .vox
file with the composited scene.
If the models have different palettes, Voxcom intelligently merges them into a single, unified palette in the final output.
It greatly reduces the manual work of combining reusable models into scenes.
We wrote it to speed up our modeling for our mobile game Road Trip.
Here are three Magica models:
This .yaml
file specifies how the scene should be composited:
output: "road_scene.vox"
ignoreMaterials: no
models:
- name: "vox/road.vox"
- name: "vox/tree.vox"
posX: 10
posY: 20.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 270
- name: "vox/tree.vox"
posX: 9
posY: 60.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 180
- name: "vox/tree.vox"
posX: 10
posY: 100.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 90
- name: "vox/tree.vox"
posX: 111
posY: 20.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 90
- name: "vox/tree.vox"
posX: 112
posY: 60.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 180
- name: "vox/tree.vox"
posX: 111
posY: 100.5
posZ: 2
centerX: yes
centerY: yes
rotateZ: 90
- name: "vox/car_blue.vox"
posX: 40.5
posY: 75
posZ: 1
centerX: yes
centerY: yes
rotateZ: 0
- name: "vox/car_blue.vox"
posX: 67.5
posY: 50
posZ: 1
centerX: yes
centerY: yes
rotateZ: 180
And here is the composited result from Voxcom:
To use Voxcom, you must have Java installed. In a terminal window, change into the voxcom directory and run:
java -jar voxcom.jar <scene.yaml>
You can use road.yaml
that is provided in the distribution to test it out.
When you are ready to make your own scene, here is the format of the .yaml
file:
output: filename.vox
. If omitted, the default is scene.vox
.
viewer: yes
and remove the filename extension from output: filename
. The model will be split up into chunks and a text file generated for use in MagicaVoxel Viewer. See below for more details. ignoreMaterials: yes
. The default if omitted is no
. This is discussed in more detail later.models:
line.
name
field is the path to the .vox
file.scale: N
. As expected N
defaults to 1.posX
, posY
, and posZ
. They default to 0
if missing.(0, 0, 0)
is placed at (posX, posY, posZ)
.
If you would like to center the model along any of the axes instead, then specify centerX: yes
, centerY: yes
, and/or centerZ: yes
.
Note that if you wish to center a model along an axis with an even number of voxels, you can specify the position at the half way point between two voxels to make it clear where you would like it to be centered.
This is done in the example above.flipX: yes
, flipY: yes
, and flipZ: yes
.90
, 180
or 270
degrees with rotateX: N
, rotateY: N
, and rotateZ: N
.
The rotations are processed first for the X axis, then the Y, then finally the Z, and these are all processed after the flips above.MagicaVoxel only supports 255 palette entries. Each entry has a color, as well as various material settings (glass, emission, metal).
If models are merged naively, this information can be lost.
Voxcom keeps track of which palette entries are actually being used by the model, and preserves those.
As new models are composited, it will reuse existing palette entries if they exactly match the incoming entries.
For those that don't match, an unused palette entry is overwriten with the new entry.
If this process results in more than 255 unique palette entries, then undefined behavior will result.
if there is demand for it, an algorithm to produce the best compromise palette could be attempted.
If the ignoreMaterials
flag is switched on, then all material settings are disregarded and only the color is used to merge palettes.
The MagicaVoxel editor only supports models up to 126 x 126 x 126 voxels.
For scenes larger than this, the MagicaVoxel Viewer is used instead.
It doesn't have support for materials, or some of the other latest rendering features, so only use this if your scene is too large.
A grid of .vox files are generated and placed in a folder (specified by the output
parameter).
A text file is generated that specifies to the Viewer how the models should be laid out.
Simply drag this file into the Viewer and it will be rendered.