Getting Started
This is a small getting started guide to get you up and running with AniVoxel.
Changelog:
- 29.08.2023 - Update for release version 1.0.1
- 20.08.2023 - Update for release version 1.0
- 11.05.2023 - Add info about deleting timeline control points
- 09.05.2023 - Initial Version
Prerequisites
Windows instructions
AniVoxel may trigger the Windows SmartScreen filter as an "unrecognized app". If this happens, please right-click the "AniVoxel.exe" file and open the file properties. Then, under "General" at the bottom tick the "Unblock" checkbox.
Linux instructions
Under linux the AniVoxel file may need to be set as an executable program. For this, please right-click the "AniVoxel" file and open the file properties. Then, under "Permissions" at the bottom tick the "Allow executing file as program" checkbox.
Notes
If anything goes wrong along the way, there is always the option to undo/redo changes using the buttons in the top left corner of the viewport or the shortcuts Ctrl+Z for undo and Ctrl+Y for redo.
If the app should crash at some point, please consult or provide to the developer the log.txt file in the same folder as AniVoxel.
Startup
When opening AniVoxel for the first time the below image is what you will see. The window is divided into three sections:
- The meshes, armature bone hierachy as well as the bone and animation settings are on the left side.
- On the top right is the main viewport with the model to be animated.
- On the bottom right are the animation timeline, playback controls, and mesh graphs.
Viewport Navigation
The mouse is used to navigate inside the viewport:
- The right mouse button (RMB) is used to rotate the view
- The middle mouse button (MMB) is used to drag the current view target
- The mouse wheel is used to zoom in and out
Display Settings
The display settings can be found via the button in the viewport. Here you can change the viewport background color, recenter the camera, and toggle the visibility of the bones and model's bounding box grid lines.
Starting from Scratch
For the sake of this guide, we start from scratch with the same model you already saw in the viewport. Of course you may also load your own.
First, we need to import the model. For this in the menu click "File > Import > MagicaVoxel Model (.vox)" and navigate into the "assets" folder of AniVoxel where you will find the file "tentacle2.vox". Select the file and click "Ok". The file should now be loaded and the window should look something like below.
Creating the Armature
By default only a root bone is created when importing a new file. To keep things simple, we will create three more bones: one for the head, one for the left arm, and one for the right arm.
To do this, we click on the three dots button of the root bone and click "Add Child Bone". This will create a new bone with the root bone as it's parent. This is also visible in the viewport as the new bone starts at the tip of the root bone.
We may now rename the new child bone to something more fitting such as "head" and the length of the bone should already be fine in our case. By default the same length as the parent bone is set for the new child bone.
Next we will create the bone for the left arm. For this, we again click on the three dots button of the root bone and click "Add Child Bone". The new bone will be on the same level as our previously created head bone and overlap with it in the viewport. First we rename the new bone to "left arm". Now we need to rotate the bone by 90 degrees to be aligned with left arm. To know which axis needs to be rotated, we may consult the viewport where the axis is visualized for the selected bone, in this case the Z axis. The bone is a bit too long, so we will change the length to 8.
In the same way, we now create the right arm bone but with a Z axis rotation of -90 degrees.
We should now have something like below.
Voxel Bone Assignment
We successfully created our armature, but the tool does not yet know which voxels are assigned to which bone. By default, all voxels are assigned to the root bone.
On the left of the viewport the tool modes are available. Currently, we are in the cursor tool mode which can be used to select bones. As we want to assign voxels, we need to switch to the voxel assignment tool by clicking the button which will open a menu. Here we have multiple sub-tools available. For learning purposes let's click the first button . Now we should see that all voxels are of the same color, the "voxel assignment color" of the root bone.
When a bone is selected and we hover with the mouse over a voxel, we should now see an outline of this voxel. If we left click on this voxel, it will be assigned to this bone, or unassigned if it was previously assigned to this bone.
The same applies for the second voxel assignment tool , which is an area assignment. With this tool a rectangle can be dragged across the screen while holding the left mouse button and when we release the mouse button, all selected voxels will be assigned.
Of course, not all voxels may be directly visible as they are inside the model and hidden by other voxels. For this, there is a layer slider left of the tool buttons in the viewport. When we change this slider, we hide all voxel layers above the selected layer. This way we can see and select these hidden voxels.
Finally, there are two auto assignment modes available , one using a simple distance metric from the voxels to their nearest bone, and another one using a heat distribution method. For simplicity we will auto assign the voxels by distance. The result should look something like below. If the assignment colors may not be easily distinguishable, you may always change the assignment colors in the settings for each bone.
Our First Animation
Now with the setup of our armature done, we can move on to creating our first animation. To create a new animation we click the plus button right of the "Animations" header under the bone hierarchy. We change the name to something like "Dance", the frames per second to 4, and the total number of frames to 16. You probably already noticed the animation timeline changing while modifying these values. The active bars of the timeline are shown in alternating grey colors with their frame number above. Light grey lines show the second marks defined by the frames per second property of the animation. The currently active frame is highlighed in red.
Timeline Navigation
To move around in the timeline and maybe see something a bit easier, several navigation methods are available in the timeline. If nothing happens, please select a bone first.
- Normal mouse wheel zooms the Y axis of the timeline.
- Holding the right mouse button (RMB) and moving the mouse around moves the timeline in the X and Y axis.
- Holding Ctrl and the right mouse buttom (RMB) and moving the mouse around zooms the timeline in the X and Y axis.
Moving the Head
Now we are finally ready to bring our model to life. First, make sure the Dance animation is selected and select the head bone. We want the head to swing from left to right over the course of the timeline. We check the required axis in the viewport, as done during bone creation, and click on the timeline. With left mouse click we can now create control points in the graph and move them around by clicking and dragging them. A middle mouse button click on a control point will delete the point.
Let's create a single control point for now. If nothing in the viewport changed, this is likely because the voxel assignment mode is still active, in that case switch to the cursor tool. Let's click on the play button above the timeline for now. The red highlight bar in the timeline should now move from frame to frame and the head should have tilted depending on the angle where the control point was placed. By clicking the control point and dragging it along, we can change it's position on the graph.
To have a continous motion of the head from left to right and back and to loop properly, we move our control point to (0, 0) and create three more control points at (5, 15), (9, 0), (13, -15). For easier control point creation at specific locations there are also two value inputs left of the plus button above the timeline. It's not required to create another control point at (17, 0) as the animation automatically interpolates back to the first control point for seamless looping. While playing the animation, the head should now move from left to right in an endless loop. Great!
Finishing the Animation
For a proper dance, the head is not enough and we should also move the arms. This works just like we did with head. We select the respective arm bone go to the "Rz" timeline and start building our graph however you like.
To see a specific frame, it's possible to pause the animation playback and then click one of the frame numbers or move the current frame with the buttons next to the playback buttons to navigate to the correct frame.
Finally, we can save our project using Ctrl+S or via the menu "File > Save As..".
To use the animation in other tools or game engines, we can export them using the menu under "File > Export" currently to MagicaVoxel animation format, per-frame obj or ply models or 2D tilesets.
The saved ".voxa" files can also be used directly in Unity or UnrealEngine. However, this requires a plugin for the respective game engine which are not yet published and in a prototype state.