How to use the Avoyd Voxel Editor: tutorial and documentation for cameras, edit tool, materials, lighting, render, import and export.
Last updated 09 May 2022
Step by step tutorial for making basic voxel shapes with the edit tools Set, Paint and Delete.
To begin with, download Avoyd from our website www.enkisoftware.com and install it on your machine.
Let's create a yellow cube made of 3x3x3 voxels.
Edit Tool Set configuration and use (click to enlarge)
BEFORE: Edit Tool option 'Set' selected, Cube size 3 in yellow material; Edit Cursor on, Anchor off, Sticky off
AFTER: Created a yellow cube using Set (the edit cursor with its green wireframe is above)
Painting voxels blue. It's not just colour we're changing, but the material the voxels are made of.
Edit Tool Paint configuration and use (click to enlarge)
BEFORE: Edit Tool option 'Paint' selected, Cube size 2 in blue material
AFTER: Painted the 2x2x1 intersection of the edit cursor and the yellow cube blue (the edit cursor is above)
Edit Tool Delete configuration and use (click to enlarge)
BEFORE: Edit Tool option 'Delete' selected, Cube size 2 (material doesn't apply); red Edit Cursor with red wireframe overlaps with the yellow and blue cube
AFTER: Deleted the 2x2x1 intersection of the edit cursor and the cube (the red delete cursor is above)
Settings > Graphics...
The graphics quality settings are: Very Low, Low, Medium (default), High, Very High and Custom. For a low end PC you may want to use 'Very Low', whereas for a powerful machine you can select 'Very High'. Avoyd is designed to take full advantage of powerful machines, whilst still being able to run on the lowest minimum specification possible.
When tweaking the graphics settings, try to ensure the framerate stays above 30 FPS (frames per second). To display the framerate, tick 'Show Performance'. If you're still under 30 FPS at the lowest quality setting, you'll have to your keep voxel world size small, typically under 128 voxels a side (menu View > World Properties... > Dimensions).
The most visible difference between low and high quality settings rests with the LOD (level of detail) system. On low settings it groups voxels together to render them easier, starting at a given distance. The lower the settings, the closer to the camera position the LOD starts simplifying scene. To see more details, increase the 'LOD Change Distance'. (Note that there is also an 'LOD Far Change Distance' which is a second level of LOD simplification, even further away).
Graphics very low and very high quality comparison, showing the user interface, graphics settings values, and on the voxel model the improved shadows and increased details (due to increased LOD changed distance) in high quality. Voxel model by Niklas Mäckle knosvoxel. (click to enlarge)
Increasing the quality usually increases the energy consumption. To save power without compromising your experience, we recommend you:
Tools > Camera...
How to switch from interacting with the menus to 3D movement, and how to use the camera in 3D.
By default you are in 'Menu' mode. It lets you access the user interface controls: opening tools and windows. To move around in 3D you need to be in 'Movement' mode:
When in 'Movement' mode, you can use one of two types of camera: 'First Person' or 'Arcball'.
To choose the camera type, toggle to 'Menu' mode and open Tools > Camera... or use the context menu (right-mouse click).
In the 'Arcball Camera and Orthographic Projection' section, tick 'Orthographic' then choose a Pitch and Yaw, or use the preset Isometric angles.
'Align to Axes' automatically aligns the camera to the nearest axis, or aligns to an axis of your choosing.
When Align to Axes is on, use the roll controls to toggle the camera view up or down, or in quarters if Auto Align is on.
Cameras can be saved as Camera Template to be reused in other worlds: File > Save/Load Template > Cameras...
Menu Tools > Edit Tool > Shapes...
When the Edit Tool window is open, the Edit Cursor is displayed. It is composed of three 3D elements: the Brush Preview, the Wireframe, and the Anchor guizmo. They are designed to help you place the shapes you're editing the 3D world with.
Menu Tools > Edit Tool > Shapes... > Edit Cursor
The Anchor affects the movement of the Edit Cursor. It is set in the Edit Tool window or from the context menu (right-mouse click).
Tip: Use the Camera functions Focus or Centre on Anchor (Tools > Camera... or from the context menu).
When editing, each voxel added, painted etc. has a Material assigned. Materials are grouped in Material Types. You can choose any material from the Material Types list in the Materials window, the Edit Tool's Palettes, or using the Pick tool to choose from the world. Materials can be swapped using the Replace tool. You can create custom Palettes of materials for easy access.
Menu Tools > Materials...
Each voxel in Avoyd is made of one Material. Materials have several properties:
To modify a Material, select it then modify its properties: Colour RGB (red, green, blue) or HSV (hue, saturation, value), Metallic, Smooth, Emissivity, Transparency etc. in the Properties section.
Transparency is currently only visible in the CPU (central processing unit) path traced renderer available through the Render menu item. See the 'Glass', 'Water and Ice' or 'Cloud Smoke Fire' materials for example parameter settings to use. To make a material transparent first set the surface transparency to a non zero number. This controls how much light passes through the surface of a material. The following parameters then control how the light behaves:
To add a new Material, you can:
Material Types can be saved as Material Template to be reused in other worlds: File > Save/Load Template > Materials...
Menu Tools > Edit Tool > Palette...
Palettes are part of the Edit Tool and are there to make it easy to use a subset of materials when editing.
Menu Tools > Pick Material...
The Pick tool is used to get information from and select specific voxels in the 3D world. When open and active, the cursor size is reduced to 1 voxel so you can select one voxel at a time.
Note the Amount is independent from the material (it is not part of the material). Each voxel has an amount which affects the shape of the voxel. It is set using the Edit Tool.
Menu Tools > Replace Material...
This tools work the same way as a 'Replace All' in a text editor, but with materials. In other words, when replacing, every voxel in the world with the first material assigned is assigned the new material.
To replace: open the Replace Material window. Click on the first material line and it will automatically update to the current material. (To change the current material, select a voxel in the world with the pick tool, or click on a material swatch in a material type or in a palette). Do this for the material to replace and the material to replace it with, then click the Replace button to update the world.
Menu Tools > Light and Atmosphere...
The light and atmosphere settings are physics based.
When the Render window is open, the 'Do Raytrace Scene' button will render the scene with CPU path tracing using the Image Parameters and Quality Settings.
Renders can take time to generate. Use 'Preview' for a quick render to see how the final image will look like and adjust parameters.
You can denoise the preview to quickly improve it. It's especially effective if it's a scene containing emissives to quickly see how the Emissive voxels (light sources) affect a scene:
The Accumulate function improves the quality of the image by running a render and adding the result to the current render / previous renders: it accumulates the results.
The image can be denoised using the OIDN (Intel open image denoiser). Denoising smoothes the image but can introduce artefacts. Increasing the number of accumulations usually gives better results than denoising, but takes a lot longer.
Hovering over the rendered image with the mouse opens a zoomed in view of the area of the image under the cursor.
To render an image with DOF (depth of field) blurring of the foreground and background:
Exposure can be used to make the rendered image more or less bright.
Tip: the exposure can be set after rendering.
Menu File > Import >...
Menu File > Import > Minecraft Map (*.mca)...
Make sure you have a Minecraft map available:
Menu File > Import > MagicaVoxel (*.vox)...
Both single and multiple models can be imported into Avoyd:
Menu File > Import > Image (.jpg, .png, .tga) as Heightmap...
You can import image formats .jpeg, .png and .tga and turn them into a heightmap based on their RGB information or the alpha channel.
Menu File > Import > Image (.jpg, .png, .tga) as Material Type...
Images and colour palettes of type .JPG, .PNG and .TGA can be imported to create Material Types and Palettes in Avoyd.
For discrete colour palettes import we recomment to use the PNG or TGA format and set the 'Maximum Number of Colours' to the maximum value allowed. Discrete palettes can be downloaded from sites such as Lospec.
Importing a colour palette (PNG image of discreet colours) from Lospec as a material type in Avoyd and creating a Palette from the Material Type. The Palette is used in the Edit Tool to select materials (colours) to create voxel art with. (click to enlarge)
You can palettise any image (JPG, PNG, TGA) by following the same steps as above and choosing the 'Maximum Number of Colours' during import. (1*)
1* To ensure that the imported colour values are identical to those in the original image, set the 'Maximum Number of Colours' to a number greater or equal to the number of colours in the original. Explanation: when the image contains less than the 'Maximum Number of Colours' requested, the exact colours are imported. If the image contains more colours than the 'Maximum Number of Colours', the colours are interpolated during import and therefore modified.
Menu File > Import > Raw 3D Binary Array...
Avoyd can import raw 3D binary arrays of 8bit voxels. The data should be a continuous 3D array of bytes. Each byte should represent a voxel material with 0 being an empty voxel. All other values (1-255) will be mapped to a unique material instance which can then be modified after import. The amount of material will be set to 255. The 3D array is treated as a set of voxels in the order x + y * size_x + z * size_x * size_y.
Menu File > Export > Polygon Mesh (*.obj)...
Avoyd supports exporting to a polygon mesh in the Wavefront .obj file format for use in tools such as Blender 3D and game engines which support directly importing the format.
To export a model, open it then select File > Export > Polygon Mesh (*.obj)... then choose your filename, after which you will be presented with the export options (see below for details). The resulting export will create several files filename.obj, filename.mtl and potentially several texture files filename_*.png.
Default export options for .obj polygon mesh export in Avoyd
Reduces vertex and triangle count. The current optimization process works on 32x32x32 size volumes to reduce memory consumption for large models, so does not do a full optimization. An option for further optimization is on the roadmap for a future iteration.
Translates the output model so that cente of the bounding volume is at the origin (0,0,0).
Export normals adds a face normal per vertex. This increaases file size and is often not required as the prgoram used to import the obj will usually calculate normals on import.
With this option on a single material is used for the entire model, with the material parameters embedded in textures. Limitations of the obj format mean that only the albedo colour channel will be imported correctly by other tools, however the other textures can then be used assigned to control the metallic, smoothness/roughness and emissive channels. This approach is usually more efficient for real time rendering, but the import process requires extra work (unless just diffuse colour is required) and changing parameters once imported is harder.
When the option is off materials are exported separatly, giving the ability to setup and change materials once imported making this more suitable for further modelling and offline rendering in 3D tool such as Blender.
Enabling this will thus emit the following textures (unless 'Unity style material properties in texture' is on):
Only available if 'Export single material with parameters in texture' is off.
The materials output are in a non-standard format which Blender uses to represent metallic material parameters - use this if you are exporting to use in Blender for further modelling.
Only available if 'Export single material with parameters in texture' is on.
Unity requires the metallic and smootheness parameters to be in the Red and Alpha channels of a texture, and emissive in another RGB texture.
Enabling this will thus emit the following textures:
See the Export to Unity Guide below.
Only available if 'Export single material with parameters in texture' is on and 'Unity style material properties in texture' is off.
Exports roughness as 1-smoothness in the Green channel of the FILENAME_metal_smooth_emissive.png texture.
Example camper voxel model which will be exported to Unity, open in Avoyd. The model includes several materials including metallic, emissive and transparent.
Credit: original model by Rebecca Michalak
Avoyd isometric render of the camper. The render shows the metallic materials reflecting the ground and sky, emissive headlights, and transparent windows, light lenses and exhaust fumes. Credit: original model by Rebecca Michalak
To export the model, open it then select File > Export > Polygon Mesh (*.obj)... then choose your filename, after which you will be presented with the export options (see below for details).
The 'Export single material with parameters in texture' options should be selected, along with the 'Unity style material properties in texture'. The 'Optimize Mesh' and 'Centre on Origin' can be selected or not depending on your needs but for most cases leave on.
Polygon mesh export options window with settings for exporting to Unity.
After exporting several files will be created (usually in the Documents/Avoyd/Exports directory):
Open up or create a Unity 3D project - for this example the standard Unity 3D project will be used. Once open drag and drop these into the Assets window in Unity. Once Unity has finished processing, drag the FILENAME.obj model from the assets window into the 3D Scene window to create an instance of the model.
Select the FILENAME_col.png texture in the Unity Asset window, which should open the texture Inspector.
The following default texture import settings need to be changed:
Once these are changed the colours of diffuse (non metallic) materials should now look more like they are in Avoyd as below:
For the Unity standard 3D pipeline the shadow parameters will need to be adjusted, as Normal Bias does not work well for non-smooth polygons, as it results in gaps in the shadows. Lowering 'Normal Bias' to a very low value (0.001) and increasing 'Bias' to 0.15 works reasonably well for default scaled scenes, but these may need to be adjusted to the scale you use for your Unity project.
In order to setup the materials, they need to be edited. However Unity doesn't allow imported model materials to be modified. The simplest way around this is to select the .obj asset in the Assets window and click 'Extract Materials...' in the Inspector window, then select the folder you want the materials extracted to.
The new materials can now be modified. The 'avoyd_transparent' material should first be set to use the 'Transparent' Rendering Mode in the material Inspector.
To add metallic and smoothness properties to the materials click on the circle before the 'Metallic' property which opens up a texture selection and select the FILENAME_metal_1_1_smooth.png texture. If the model has emissive materials these can be added by modifying the material. Select the 'Emission' checkbox and then click the circle to the left of the 'Color' property to open the texture selector and choose the FILENAME_emissive.png texture. This should be done for both the transparent and opaque materials.
The default import settings for the FILENAME_metal_1_1_smooth.png texture are again not correct, so we modify them as the FILENAME_col.png texture above. The FILENAME_emissive.png texture also needs its import settings changed to be the same except the 'Format' should be RGB 24bit.
The Unity HDRP (high-definition render pipeline) import settings are the same as the above, except the emissive properties are handled slightly differently. Click the circle to the left of the 'Emissive Color' property to select the FILENAME_emissive.png texture, ensure the 'Use Emission Intensity' is off and select the HDR colour picker and set the colour to full white with a large Intensity - depending on your scene lighting you might need 10 or more.
Avoyd requires a mouse and keyboard. Controls and shortcuts are currently hardcoded.
Camera controls are enabled in Movement mode (input trapped). In other words Movement mode gives you control of the camera: you can move around in 3D using the mouse and keyboard. To engage Movement mode click and hold the right-mouse button. Alternatively, press Tab to toggle between the Menu mode and the Movement mode. The camera controls in the voxel editor are similar to a first person shooter FPS game in zero gravity without collision nor inertia.
|Engage Movement Mode||Mouse right click and hold, or Tab (toggles between the Menu and Movement modes)|
|Escape Movement Mode||Mouse right button release, Esc, or Tab|
|Camera Aim||Mouse (Invert mouse Y and sensitivity in Settings > Controls...)|
|Roll Left (counterclockwise)||Q|
|Roll Right (clockwise)||E|
|Move Down||Left Ctrl|
|Speed Increase||Left Shift|
|First Person Camera / Arcball Camera toggle||C|
|Saved Camera: Add||Alt + ↓|
|Saved Camera: Previous||Alt + ←|
|Saved Camera: Next||Alt + →|
These controls are available when the Edit Tool window is open and active. Menu Tools > Edit Tool > Shapes...
|Open Edit Tool window||Menu Tools > Edit Tool > Shapes..., or Alt+E (Shapes tab) or Alt+G (Procedural Generation tab)|
|Menu to Movement Mode||Mouse right click and hold, or Tab to toggle between the Menu and Movement modes|
|Movement to Menu Mode||Mouse right button release, or Tab to toggle between the Menu and Movement modes, or Esc|
|Show Edit Cursor||Edit Cursor section in the Edit Tool window: select Show Brush Preview and Show Wireframe|
|Move Edit Cursor||Mouse (in Menu Mode and with Anchor Off)|
|Move Edit Cursor closer/further||Mouse wheel (with Anchor unlocked; wheel sensitivity in Settings > Controls...)|
|Anchor toggle On / Off||Alt + A|
|Shape (and edit cursor) size change by 1 voxel in all directions||↑ ↓ or Shift + Mouse wheel|
|Perform edit action||F or Mouse left click over the 3D World or [ Do... ] button|
|Cut from the 3D World||Ctrl + X|
|Copy from the 3D World||Ctrl + C|
|Paste into the 3D World||Ctrl + V|
|Undo the last change in the 3D World||Ctrl + Z|
|Redo - Reverse the last Undo in the 3D World||Ctrl + Y|
|Select custom Preset edit tool||0..9 or select from the Presets dropdown|
|Open Context Menu||Mouse right click over the 3D World|
|Show / Hide all user interface elements||Ctrl + M|
|Take a Screenshot||F10 (screenshots are saved in ..\Users\username\Documents\Avoyd\Screenshots)|
Keyboard shortcuts listed alphabetically.
Note: keyboard shortcuts using the Ctrl modifier are disabled in Movement Mode so they don't interfere with the camera's Ctrl key (Move Down).
|0..9||Select custom Preset in the Edit Tool (Edit Tool active)|
|C||First Person Camera / Arcball Camera toggle|
|E||Roll Right (clockwise)|
|F||Perform edit action in the 3D World (Edit Tool active, Shapes tab)|
|Q||Roll Left (counterclockwise)|
|Alt + Enter||Toggle between fullscreen and windowed modes|
|Alt + ↓||Saved Camera: Add|
|Alt + ←||Saved Camera: Previous|
|Alt + →||Saved Camera: Next|
|Alt + A||Anchor toggle On / Off|
|Alt + C||Camera window Open / Focus on / Close|
|Alt + E||Edit Tool window Shapes tab Open / Focus on / Close|
|Alt + G||Edit Tool window Procedural Generation tab Open / Focus on / Close|
|Alt + L||Light and Atmosphere window Open / Focus on / Close|
|Alt + M||Materials|
|Alt + P||Pick and Inspect Material window Open / Focus on / Close|
|Alt + R||Replace Material window Open / Focus on / Close|
|Alt + X||Close all windows|
|Ctrl (left)||Move Down|
|Ctrl + C||Copy from the 3D World (Edit Tool active, Shapes tab)|
|Ctrl + M||Show / Hide all user interface elements|
|Ctrl + N||Create a new empty World|
|Ctrl + O||Open an existing World file *.avwr|
|Ctrl + S||Save current World to file|
|Ctrl + V||Paste into the 3D World (Edit Tool active, Shapes tab)|
|Ctrl + X||Cut from the 3D World (Edit Tool active, Shapes tab)|
|Ctrl + Y||Redo - Reverse the last Undo in the 3D World|
|Ctrl + Z||Undo the last change in the 3D World|
|Esc||Escape from Movement mode onto Menu mode, then onto Main menu|
|F1||Help window / In-game: toggle between first and third person view|
|F10||Take a Screenshot (saved in ..\Users\username\Documents\Avoyd\Screenshots)|
|Shift + Mouse wheel in / out||Shape (and edit cursor) size decrease / increase by 1 voxel increments, in all directions (Edit Tool active)|
|Shift (left)||Speed Increase (camera)|
|Tab||Toggles between the Menu and Movement modes|
|↑||Shape (and edit cursor) size Increase by 1 voxel in all directions (Edit Tool active)|
|↓||Shape (and edit cursor) size Decrease by 1 voxel in all directions (Edit Tool active)|
|Mouse (Menu Mode)||Move the mouse pointer when over the user interface
Move the edit cursor when over the 3D world (if the Edit, Pick or Replace Tool is active and the Anchor is off)
|Mouse (Movement Mode)||Camera aim|
|Left click over the 3D world / voxels||Perform edit action (if the Edit Tool is active)
Pick a voxel and make its Material current (if the Pick or the Replace Tool is active)
|Wheel in / out||Move Edit Cursor closer / further (if the Edit Tool is active and the Anchor is off or unlocked)|
|Shift + Wheel in / out||Shape (and edit cursor) size decrease / increase by 1 voxel increments, in all directions (if the Edit Tool is active)|
|Right click over the 3D world||Open the Context menu|
|Right click and hold / release||Movement mode (input trapped) engage / escape|
Avoyd is a voxel editor and game developped and published by enkisoftware • ©enkisoftware 2001-2022