Troubleshooting

Keys and tools

A shortcut does nothing, or does Blender’s thing instead. Most Voxel Mode keys work only in Edit Mode on a voxel model, with a voxel tool active. With Blender’s own tool active, or with the mouse over another editor, the key is Blender’s. The shortcut reference says where each key works. If you rebound it, check Preferences ▸ Voxel Mode ▸ Keyboard Shortcuts for a red clash.

My number keys, L or Shift+A stopped working on normal meshes. They shouldn’t. Voxel Mode keys refuse ordinary meshes and fall through to Blender. If they don’t, you are on an old version: update.

The toolbar shows Extrude, Knife and so on while I’m editing a voxel model. It shouldn’t. On a voxel model the toolbar shows the voxel tools only. Exit and re-enter Edit Mode (Tab twice).

The header’s Add menu put real geometry into my voxel model. In Edit Mode, Shift + A opens the Voxel Library, but the Add menu in the header is still Blender’s mesh menu. Undo, and place shapes with Shift + A or the library instead.

Display

Roughness, metal, glow or glass don’t show. Solid shading shows colour only. Switch to Material Preview or Rendered. Glass and water also need raytracing in EEVEE; the Material panel has a button for it.

My water looks like a flat blue lid. Water needs something to reflect above it and something to see below it. Put a floor (sand, pebbles) under shallow water, and use the entries of the Water and Glass palette.

I can’t see individual cubes on a flat area. Turn on Display ▸ Show Voxel Grid, or Shift + Alt + S ▸ Show Voxel Grid.

I shrank my selection and it disappeared. It is inside the model. Shrinking a selection that covers a solid removes the outer layer first. The header still shows the selected count.

My model looks wrong or has holes. Grid ▸ Rebuild redraws it from its grid. The grid is always the truth.

Scaling and placement

I scaled my model and it snapped back. That’s by design. A model resizes in whole voxels and its object scale stays 1; the scale you asked for becomes a grid resize once you let go. See Models.

Two models don’t line up. They need the same voxel size. Then turn on Snap To Voxel Grid, or press Align To Voxel Grid.

Characters

“Rest pose changed near Thigh… give knees a slight forward bend.” Despite the wording, the usual cause is that a foot isn’t centred under its shin. A foot wider on one side than the leg above puts the ankle half a voxel sideways, and the knee can’t bend in a flat plane. Make thigh, shin and foot share the same X centre (for example, widen the foot equally on both sides), then Back to the foot and assign it again.

“N voxels still need a body part.” Every voxel needs a part. Show Unassigned Voxels highlights them, and Give Leftovers to Nearest Part assigns them. A common case is a skirt, kilt or robe with a centre column between the legs: a mirrored thigh can’t take a voxel on the centre line, so go Back to the waist/hips and include that column there.

“The opposite side has a different shape.” Your character isn’t symmetrical. Turn off Mirror limb selections and assign each side yourself.

The animal’s head and tail are the wrong way round. In the Face it forward step, turn the model until its head points along the arrow before continuing.

I deleted part of my character and it came back. The visible character is generated from the rig and the model. To remove it, delete the rig; the whole character’s generated parts go with it, and your voxel model and Actions are kept.

The Action Editor changed the wrong object. Click the character to select it; the click is redirected to the rig. Then pick the Action in Character ▸ Action.

Export

The model arrives lying down or tiny in my engine. Use the preset for that engine (Export File ▸ Godot / Unity / Unreal), not Blender’s generic exporter.

Colours are blurry in the engine. Set the atlas texture’s filtering to Nearest or Point.

Strict Grid won’t export to FBX. It can’t: the mesh changes every frame. Use Rigid Parts for FBX/glTF, or export Strict Grid as sprite sheets.

My corrected built-in shape was reverted after an update. Built-in shapes live inside the extension, which an update replaces. Save your corrected version into My Shapes.

Performance

The model you are editing is drawn as chunks, so a stroke only rebuilds the chunks it touched. Every other model in the scene is folded: drawn as one object, with its voxel data dropped from memory until you edit it again. A scene of a hundred large models costs Blender a couple of hundred objects, not tens of thousands, and a mouse move over it costs nothing.

• Press Tab on a folded model and it unfolds behind its own picture; a big model fills in over a second or two while you can already work on it. Leave Edit Mode and it folds again a moment later.
• Preferences ▸ Fold Idle Models switches this off if you ever need every model as chunks. Fold After is the pause before a model folds, and Keep Decoded is how much recently folded voxel data stays in memory so stepping back into a model is instant.
• Show Voxel Grid is drawn by a shader over the model you are editing. It costs the pixels it covers, however big the model.
• Hollow big solid models (Reshape ▸ Hollow, thickness 1). Nothing inside is visible anyway.
• Model at the voxel size you need. A 1024³ grid is possible, but a 256³ model with the same look is far lighter to draw.
• For large generated scenes in Rendered view, keep EEVEE volumes modest (tile size 8, 64 samples, no volumetric shadows).
• Undo inside Edit Mode reaches the strokes of the current editing session. Once a model has folded, its earlier strokes are undone from Object Mode with Blender’s own undo, which still holds every step.

Benchmark (Grid panel) prints the timings of the edit loop on the active model, which is useful when reporting a problem.