Docs / User guide

Modeling

Build and paint voxel models, use the palette and mirrors, and animate models with frames or parts.

Every object in your game, from a grass tile to the player, is a voxel model. You build them in the Model tab (F2). To edit a model you've placed, double-click it in the world. Press Esc or F1 to go back to the level.

#Moving around

• Hold the right mouse button and drag to orbit.
• WASD moves around, Q / E go down and up, and Shift goes faster.
• Middle-drag pans, and the mouse wheel zooms.
• F frames the whole model.

The corner at the top right shows the X (red), Y (green) and Z (blue) axes. Z points to the model's front. Click a ball on it to jump to that view.

#Model size

The size button on the Model toolbar sets the model's box, up to 64 × 64 × 64 voxels. 16 voxels make one tile in the world. If you shrink the box, it warns you how many voxels would be cut.

#The tools

The tool rail down the left side of the view has every tool that changes the model. The options bar under the toolbar shows the picked tool's options.

#Brush options

For Add, Remove, Paint and Line, the options bar has:

• Brush size 1–8. Press [ for smaller and ] for bigger.
• Tip: Cube, Ball, or flat Square or Disc on the face you click.
• Vary 0–4, which picks nearby palette colors at random so walls and grass don't look flat.
• Voxel / Face / Box modes. Voxel draws as you drag, Face works on the whole flat face you click, and Box fills, clears or recolors a rectangle you drag on a face.

Paint's Color mode recolors every voxel of the color you click. Add's Stamp mode stamps what you copied (Ctrl+C) onto the faces you click.

#Shapes

With Shape (O), drag a footprint and pick a box, sphere, cylinder, cone or pyramid. Tick Hollow for just the shell. Drag the arrows to size it, then press Enter to place it in the current color.

#Selections

• With Select, drag over empty space around the model to select everything inside a rectangle. Hold Shift to add and Ctrl to take away. Turn on Lasso to draw a free shape instead.
• Alt+click a voxel to select by its color.
• Ctrl+A selects all; Ctrl+Shift+A selects none; Esc clears the selection.

A selection works like a stencil: while voxels are selected, Add, Remove, Paint and Fill only change those voxels. Drag inside the selection's box to move the voxels, or use the arrow keys to nudge them.

Tools ▸ Selection has Invert, Grow, Shrink and Delete. Tools ▸ Flip / Scale flips the selection or scales it 2×, 3× or ½.

#Mirrors

The X and Z buttons on the Model toolbar copy every edit across the model's middle. Mirror X (M) copies left and right; Mirror Z (Shift+M) copies front and back. With both on, one click goes to all four corners, so you can draw one table leg and get four. Tools ▸ Mirror Y adds top and bottom.

Tools ▸ Mirror Around the Selection moves the mirrors to the middle of the selected voxels, which helps when a shape isn't centered in its box.

#Useful modifiers

Tools ▸ Modify has quick ways to add detail:

• Outline darkens where two colors meet.
• Cover Top paints the top layer, for snow, grass or moss.
• Color Noise makes stone, bark and grass look less flat.
• Erode nibbles the surface away at random.
• Smooth rounds blocky shapes.
• Gradient… blends from one color to another.
• Hollow, Fill Holes and Crop to Fit.
• Adjust Colors… changes hue, brightness and saturation.

#Seeing inside

• Front / Side / Top views are on the toolbar's View ▾, or numpad 1, 3 and 7.
• Slice (U) cuts the model open so you can draw on an inside layer. Move the slice with PageUp / PageDown.
• Isolate (H) shows only the picked part.
• Ref ▾ puts a see-through reference picture behind the model.

#The palette

Your project has one shared palette, shown in the Palette tab on the right. Every color has a Glow slider: glowing voxels shine in the dark, which is good for lamps, lava and crystals.

• Presets ▾ switches to a ready-made palette such as PICO-8, Sweetie 16 or Endesga 32.
• Import… brings in a palette from lospec.com by name or link, or from a palette file. You can add the colors to unused slots, or replace the palette and let every model move to its nearest new color.
• Under the palette are Gradient…, Merge duplicates and Export….

#Importing and exporting models

You can import MagicaVoxel .vox files. Only the first model in the file comes in, and its colors are matched to your palette. MagicaVoxel glowing materials come in as glowing colors.

Other ways to make models:

• File ▸ Import Picture as Voxels turns a PNG, JPG or WebP into a model, standing up or lying down as a height map.
• Create ▸ 3D Text… makes blocky letters as a new model.

File ▸ Export Model saves the model as .vox, .obj or .glb, or as a .png picture.

#Tags

Under the palette in the Model tab you can give a model tags such as ground, water, wall or npc. Type one and press Enter. Tags matter in the game: for example, models tagged water get gentle waves, and enemies path around wall and obstacle.

#Animation

Models can animate in two ways. Both live in the Timeline strip under the model.

#Frames

A flip-book of frames, like the village's water and torches. N adds a frame (a copy of the current one), , and . step through frames, and Shift+Space previews the loop. Set the speed (fps) in Properties.

#Parts

Characters are animated by parts: Body, Head, arms, legs and so on.

• Skeleton… fits a ready-made skeleton to your model, such as Simple biped, Full humanoid, Four legs, Bird / winged, Snake / worm or Blob. Leave Make its game animations on to get idle, walk, run, jump, attack, hurt and die.
• Or select voxels and press + Part.
• + From library… adds ready-made animations, such as walks, sword slashes, spells, emotes and deaths.
• With the Pose tool (0), click a part and drag its handles. A keyframe is set automatically. Press Space to play or stop.

Animations named idle, walk, run, jump, attack and hurt play in the game on their own. For more on posing and the Timeline, use Help ▸ Modeling & Animation Guide in the app.

#Attachments

Attach… in the Timeline strip adds attachment points where other models are held or worn: a sword in the right hand, a hat on the head. Auto: hands, head, back adds the usual four. A character's Right hand holds the player's weapon or tool.

Next: Building levels.