Avoyd Voxel Editor Documentation

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

Avoyd Voxel Editor screenshot - A scene opened for editing in the voxel editor showing a landscape generated by importing a Mandelbrot fractal image as a heightmap. Procedural boxes were added using the Edit Tool's procedural generation tool. The user interface shows the windows: Edit Tool, Materials, Light and Atmosphere settings, Replace Material, Pick and Inspect Material, Cameras and Render tools.



Definitions



Voxel
Representation of data on a 3D (three dimensional) grid. Since voxels are data, they can be represented many different ways: cubes, spheres, lego bricks, textured shapes that are deformed according to their neighbours (for smooth shapes) etc. Voxels are used in video games, in medical imagery (for instance to store MRI (magnetic resonance imaging) scans 3D data and visualise it in 3D or slices), to make art. Voxels can be monochromatic or have a texture applied.

Voxel Art
3D art made of voxels. Each voxel is typically represented as a single colour cube, although there can be stylistic variations such as visible edges or rounded corners. Voxel editors are commonly used to create voxel models and render them as voxel art.

Voxel Editor
3D art tool used produce models made of voxels and render them for voxel art, to produce assets for video games, animation, etc. Examples of voxel art software are our application Avoyd, open sourced Goxel, popular MagicaVoxel, Qubicle aimed at games developers, and many more.


Introductory Tutorial: how to edit voxels in Avoyd



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.

1. Create a simple voxel shape with 'Set'

Let's create a yellow cube made of 3x3x3 voxels.

  1. Open the Voxel Editor: start Avoyd and click on "Voxel Editor" in the main menu.
  2. Open the Edit Tool window: in the top menu bar, select Tools > Edit Tool > Shapes...
  3. Before you start, check that:
    • the Edit Cursor is visible: open 'Edit Cursor' and ensure 'Show Wireframe' and 'Show Brush Preview' are ticked.
    • the Anchor is off (unticked)
    • Sticky mode is off (unticked)
  4. Select Set from the list of tools in the left-hand column.
  5. Select the 'Cube' from the 'Shape' drop-down in the column on the right.
  6. Adjust the cube's parameters:
    • set Size to '3' voxels
    • Set Amount to '255'
    Tip: To edit a value, double click in the field and type the value then Enter, or drag the cursor horizontally across the field.
  7. Choose a material: open the 'Palette' and click on a yellow colour swatch to select it.
    Tip: If you can't see a yellow swatch (square), click on Reset. (Note you'll lose your current palette).
  8. Move the mouse pointer outside the 'Edit Tool' window and over the world: the Edit Cursor, a yellow 3x3x3 cube preview with a green wireframe, follows the movements of the mouse pointer.
    Tip: Use the middle mouse button wheel to move the cursor closer to you or further away.
  9. Click the left mouse button: a 3x3x3 solid yellow cube is created.
    Tip: Every time you click in the world, a new shape is created.

Voxel Edit Tool Set configuration and use in Avoyd: before and after edit
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)

2. Change materials with 'Paint'

Painting voxels blue. It's not just colour we're changing, but the material the voxels are made of.

  1. In the Edit Tool tab Shapes, select Paint.
  2. Select the Cube shape and set its size to 2 voxels.
  3. Select a blue material from the Palette.
  4. Move the mouse pointer over the world: the Edit Cursor, a blue 2x2x2 cube preview with a green wireframe, follows the movements of the mouse.
  5. Move the wireframe until it touches and intersects with a solid shape, for instance the yellow cube we created before.
    Tip: Use the middle mouse button wheel to move the wireframe closer to you or further away.
  6. Click the left mouse button to paint: a piece of the solid shape is painted blue. The original material has been replaced by the blue material.

Voxel Edit Tool Paint configuration and use in Avoyd: before and after edit
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)

3. Erase voxels with 'Delete'

  1. In the Edit Tool, select Delete.
  2. Set the Cube shape size to 2 voxels.
  3. Move the mouse pointer over the world: a red 2x2x2 'delete' wireframe and cube preview follows the movements of the mouse.
  4. Move the wireframe until it intersects with a solid shape and click the left mouse button: a piece of the solid shape is deleted.

Voxel Edit Tool Delete configuration and use in Avoyd: before and after edit
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)

4. Going further



Documentation



Graphics Settings and Performance

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).

Level Of Detail

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).

Avoyd voxel editor graphics very low and very high quality setting 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
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)

Power Saving

Increasing the quality usually increases the energy consumption. To save power without compromising your experience, we recommend you:

  • Keep the 'Power Save Mode' ON (default). It stops redrawing the screen when no computing nor user interaction happens (e.g. when the mouse doesn't move). This doesn't affect the graphics quality in any way.
  • Turn 'VSync' (vertical synchronisation) ON. If this causes motion sickness, turn it back off.

Cameras: Moving around in the 3D World

Tools > Camera...


How to switch from interacting with the menus to 3D movement, and how to use the camera in 3D.

Menu and Movement Modes

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:

  1. To activate Movement Mode, press the 'Tab' key or hold the right-mouse button down.
  2. Move around in 3D using the mouse and keyboard.
  3. Go back to 'Menu' mode: press 'Tab' again, press 'Esc', or release the right-mouse button.
    Tip: The status bar indicates which mode you are in (bottom-right corner).

First Person and Arcball Cameras

When in 'Movement' mode, you can use one of two types of camera: 'First Person' or 'Arcball'.

  • The First Person Camera lets you move around in 3D using the same controls as in a first person game.
  • The Arcball Camera lets you circle around a centre point. Use the controls to move around and closer / away from the centre.

To choose the camera type, toggle to 'Menu' mode and open Tools > Camera... or use the context menu (right-mouse click).

Orthographic and Isometric Projections

In the 'Arcball Camera and Orthographic Projection' section, tick 'Orthographic' then choose a Pitch and Yaw, or use the preset Isometric angles.

Align Camera to Axes

'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... or drag & drop the template file into Avoyd.


Edit Tool: the Edit Cursor and using Anchor

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.

Edit Cursor Brush Preview and Wireframe

Menu Tools > Edit Tool > Shapes... > Edit Cursor


  • The Brush Preview is an approximation of the 3D shape you use to edit.
  • The Wireframe is a box displayed as a grid that contains the 3D shape. The gridlines are the voxel edges. It is sometimes referred to as the AABB (axis-aligned bounding box).
  • You can choose to hide them, both or individually, in the Edit Tool > Shapes... > Edit Cursor section. You can also change their appearance from Settings > Display... > Spacial Interface

Cursor Movement and Anchor

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).

  • When Anchor is off, the Edit Cursor follows the movements of the mouse.
  • When Anchor is on, the Edit Cursor is fixed (anchored) in the 3D world.
    • The Anchor is represented in the 3D World by a guizmo showing the axis X (red), Y (green) and Z (blue). You can move the Edit Cursor around and resize it using the guizmo:
      • Click and drag the white square in the centre to move anywhere.
      • Click and drag on the coloured squares to move in a single plane: orthogonal to X (red square), Y (green square) or Z (blue square).
      • Click and drag the chosen axis to move along a line: along the axis X (red line), Y (green line) or Z (blue line). Each axis has a single colour in the positive direction and black stripes in the negative direction.
      • Click and drag the grey spheres to resize. Note this will cause the Edit Cursor to move.
      • If you Lock the Anchor position, the guizmo will only let you resize it, not move it. Its centre will remain fixed.
    • Whether the Anchor is locked or not, you can change the position of the centre in the Edit Tool or from the context menu.

Tip: Use the Camera functions Focus or Centre on Anchor (Tools > Camera... or from the context menu).


Materials

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.

Materials and Material Types

Menu Tools > Materials...


Each voxel in Avoyd is made of one Material. Materials have several properties:

  • Colour
  • Metallic and Smooth
  • Emissive intensity
  • Transparency parameters
  • Strength which affects how easily the material is damaged during gameplay
  • A Unique Id (number). Example: ID 240 corresponds to a unique desaturated red material.
  • A Type (name of a group of materials e.g. Iron, Clay, or an imported palette.) and an identifying number within the Type. Example: the red material 240 is also the 160th member of the 'Clay' type, '240 - Clay 160'.

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:

  • Absorption Length - after passing this distance in the material white light will take on the colour set for the material. Set shorter for more absorption, longer for less.
  • Scatter Length - distance at which it becomes likely the light will scatter. Set shorter for more scattering, longer for less.
  • IOR (index of refraction) - controls the refraction (bending) and reflection of light. Glass is 1.5, water 1.3, air 1.0.
  • Phase - controls the phase of scattering; positive phase scatters more light forwards (in nature forward scattering gives water clouds their silver lining), negative for more backwards scattering.

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... or drag & drop the template file into Avoyd.

Palettes

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.

  • You can add (and remove) individual Materials or entire Material Types to a palette.
  • You can use the 'Default' palette or create and edit as many different palettes as you need.
  • Palettes are saved together with the World.
  • Palettes can be saved as Material Template: File > Save Template > Materials...

Notes:

  • When editing you don't have to use only the materials that are in the palette: you can also select them in the Materials Types or in the world using Pick.
  • Creating and filling a Palette is probably easiest from the Materials window. The Pick tool is also useful to retrieve a material from a voxel in the world.
  • Palettes are mostly used with the Edit Tool but also with functionality that enable a choice of Material, for example Import Image (File > Import > Image as Heightmap...)

Pick and Inspect

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.

  • Hovering over a voxel shows its summarised info in the Inspect section
  • Clicking on the voxel selects it. You can then use it to edit with in the Edit Tool, add it to or remove it from the Palette and the Material window will show its type and potentially modify it.
  • Note the currently selected material is displayed in the status bar at the bottom-right of the screen.

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.

Replace

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.


Lighting and Atmosphere

Menu Tools > Light and Atmosphere...


The light and atmosphere settings are physics based.

  • To change the position of the light source, modify the parameter 'Light Direction'. (Note the UI is evolving: we will make it easier to use in future releases).
  • To add a fog effect, in the Atmosphere section decrease the 'Half Length' (how far before half the geometry is hidden by the atmosphere) and/or increase the 'Amount' (how dense the atmosphere is).
  • Presets help to quickly change how bright or foggy the scene is: dawn, sunny, sunset, clear atmosphere, haze or fog. You can then adjust the parameters manually using the light and atmosphere settings.
  • The 'Neutral' global preset renders the original voxel colours unaffected by e.g. the light colour or atmospheric scattering.
  • For other visual modes such as ambient occlusion, shadows, pure colours etc. use Settings > Voxel Style > Display Mode
  • Light and Atmosphere settings can be saved as template and reused in other worlds: File > Save/Load Template > Light and Atmosphere... or drag & drop the template file into Avoyd.

Render: Raytracing Scenes

Menu Render


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.

How to do a Render

  • Open menu 'Render'.
  • Click 'Preview' for a quick render.
  • Adjust the image size, depth of field and other parameters.
  • When you're happy with the scene, click 'Do Raytrace Scene'.
  • Click 'Accumulate' to run the raytracing again and increase the quality of the render. Note that after several accumulations the result will stop improving.
  • When you're satisfied with the result you can denoise the render to remove artefacts (small dots).
  • Finally, save the image.

Preview

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:

  1. in the Render window, pick a small image size (so the raytracing is faster)
  2. set 'Emissive Material Intensity' to a large number (e.g. 1000)
  3. press Preview
  4. press Denoise

Accumulate

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.

  • Continuous Accumulate will accumulate renders up to the Max Continuous Accumulate setting, improving image quality.
  • You can add accumulations whilst the renderer is working by increasing the Max number.
  • To pause the continuous accumulation press "Stop" or un-tick "Continuous".

Denoise

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.

  • Click the information button for instructions on how to download and install the denoiser.
  • You can denoise both previews or raytraced scenes.
  • Tick HQ (high quality) Denoise to denoise the colour and albedo output channels prior to merging them together. This gives better results for transparency but is slower to run.

Image Inspector

Hovering over the rendered image with the mouse opens a zoomed in view of the area of the image under the cursor.

Mode, Auto-Save and Output Channels

  • The Mode drop-down allows you to view different outputs from the renderer.
  • If Auto Save is on, the Colour and Denoised Colour channels will save automatically every time the render is changed.
  • The Save Current Image button can be used to save any of the output channels.

Depth of Field

To render an image with DOF (depth of field) blurring of the foreground and background:

  • Use the Pick tool to select a focus point.
  • Check the Use Picked Position checkbox to use the focus point for the Focus Distance.
  • set the Aperture to a non-zero value (this is in Voxel units, and a value of 0.5 is a decent starting point to use).
  • Raytrace the scene.

Exposure

Exposure can be used to make the rendered image more or less bright.
Tip: the exposure can be set after rendering.

Tips and Settings

  • The 'Samples Per Pixel' setting can be used to change the rendering quality / speed, but using Accumulate gives better feedback for convergence.
  • The 'Emissive Material Intensity' setting can be used to modify the light emission from all materials.
  • Enable the 'Full Voxels' setting for faster renders, but be aware all voxels will represented as cubes.
  • The saved Image Format (JPEG, PNG...) and Quality are set in Settings > System > Saved Images Properties, Render Image Format and Render JPEG Quality.

Import

Menu File > Import >... or drag & drop

Minecraft Maps

Menu File > Import > Minecraft Map or Structure (*.mca, *.nbt)...


Make sure you have a Minecraft map available:

  • Avoyd can load your own Minecraft maps generated when you play (stored in %appdata%.minecraft\saves\ )
  • or you can download a map from PlanetMinecraft for example, and save it to disk, extracting it if it is a zip file.
How to Import a Minecraft Map or Structure into Avoyd
  • Open the menu File > Import > Minecraft Map or Structure (*.mca, *.nbt)...
    • Map: select the region file directory (containing .mca files) and 'Open' to import it. If you have 'The Nether' or 'The End' dimensions as well as the normal 'The Overworld', a pop-up will enable you to choose which dimension to import.
    • Structure: select the .nbt file and 'Open'.
  • Press Import and wait. For large maps this operation make take a while.
  • Once imported, save the map as an Avoyd world file.
How to Explore the Map
  • First you need to lock the camera to the horizontal plane:
    • select menu Tools > Camera... > Align To Axes
    • select 'y'
    • set the Axis Preference to '0.80' or above
  • To explore the world, hold the mouse right button or press Tab on the keyboard, then use the keyboard to move and the mouse to look around.
  • The keyboard controls are listed uner menu Help > Controls > Camera Controls - Movement Mode.
How Minecraft Blocks are Represented in Avoyd, and How to Modify Them
  • Avoyd does not use textures, but the materials used in Avoyd match the Minecraft default materials as closely as possible: their colour is based on Minecraft textures averages and they have specular reflection, transparency and emissive properties where relevant (water, glass, metal, lava...).
  • Note that emissive voxels representing torches, lava etc only emit light when rendered. The same applies to transparent materials: they are only see-through when rendered.
  • Each block and most of their variations are mapped to a material in Avoyd. We've mapped the vast majority of Minecraft Java Edition blocks to the appropriate materials settings in Avoyd
  • For Minecraft versions prior to 1.13 (the flattening) we now use both both block Id and data value to assign the correct namespace Id to a an imported block. For versions post 1.13 we directly use the namespace Id provided. The namespace Id of every Minecraft block is part of the material name in Avoyd.
  • To edit the Minecraft materials individually in Avoyd, open menu Tools > Materials... and choose 'Minecraft' from the Material Type drop-down. Click on a colour swatch to edit the material properties. You can also access the materials from the Palette in Tools > Edit Tool
  • You can make specific block types (for example barrier) invisible in renders by making the material entirely transparent. In Tools > Materials, select the material and set its parameters as follows:
    • Colour = White (R=255 G=255 B=255)
    • Metallic = 0
    • Smooth = 0
    • Emissive = 0
    • Surface Transmission = 1
    • Absorption Length = 1,048,576
    • Scatter Length = 1,048,576
    • Phase = 0
  • If you want to reuse your material alterations in other maps, save them as a template in File > Save/Load Templates > Materials. After you've imported a new Minecraft map, load your materials template and it will overwrite the defaults.
Tips
  • Tune the Graphics properties under Settings > Graphics. Increasing the 'Graphics Quality' improves detail but can reduce performance.
  • Once a map is saved as an Avoyd world file, you can open it faster and use it as a paste brush.
  • If you imported Minecraft worlds into a version of Avoyd older than 0.8.10, you should install the latest version of Avoyd and import again to ensure the latest transparent materials are used.
Limitations
  • It is not possible to re-export any edits made in Avoyd back to Minecraft
  • Avoyd only supports Minecraft Java Edition maps. It does not support Bedrock.
  • Avoyd does not currently support schematics import
  • Avoyd does not use textures nor block models so all the Minecraft decorations, half-blocks, steps, objects such as torches etc. appear as full voxel blocks made of a single material in Avoyd.
  • It is currently not possible to hide block types in Avoyd: you have to delete them manually using the Edit Tool, or make the block type invisible (see tips section) before you render the scene. We intend to add block hiding in the future.

MagicaVoxel Models Vox files

Menu File > Import > MagicaVoxel (*.vox)...


Both single and multiple models can be imported into Avoyd:

  • Open the menu File > Import > MagicaVoxel (*.vox)...
  • Select a *.vox file and 'Open' to import
Tips
  • Once imported, save the model as an Avoyd world file. This will enable you to open it faster and use it as a paste brush.
  • The import creates a Material Type named after the vox file. You can edit the materials individually from menu Tools > Materials... or from the Palette in Tools > Edit Tool...
  • To match the MagicaVoxel Palette display order (lowest index bottom left) in Avoyd: use Menu Materials > Material Type > invert vertical grid toggle button, or Menu Settings > Display > Layout > Invert Materials Grid Display.
Limitations
  • When importing multiple models, they are merged into a single Avoyd world. They are imported in the same order as in MagicaVoxel.
  • It is not currently possible to re-export any edits back to vox files. Avoyd can handle larger models than the .vox format, and the material amount value is not supported by .vox so it would not be a 1:1 conversion

Images as Heightmap and Palettisation

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.

  • Open the menu File > Import > Image (.jpg, .png, .tga) as Heightmap...
  • Select an image file and 'Open'
  • Set the parameters and 'Import'
Tips
  • To import a flat image (1 voxel thick), set the Scale (maximum height) to 1, Amount = 255 and turn off Smooth Surface
  • Enable 'Palettise Image Colours' to import the image colours. The principles are the same as for Import Image as Material Type (see the 'Importing Colour Palettes' section below)
  • Setting the Amount to 255 and enabling 'Smooth Surface' results in full columns of voxels, except for the top one which amount is proportional to the remain and therefore morphs and creates a smooth surface effect
  • Use Invert to get the elevation that would be produced by the negative image, but keep the colours
  • Add a floor to avoid leaving holes if the value is 0 or max (depending on invert)
  • When on, the 'Surface Layer Only' option results in only the top voxels of the heightmap to be saved, like a cloth. You can adjust the thickness. This can be useful for creating complex curved structures.

Colour Palettes

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.

How to Import a Discrete Colour Palette

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.

  • Download your palette in .PNG or .TGA format and save it to your computer
  • Open the Avoyd Voxel Editor and select File > Import > Image (.jpg, .png, .tga) as Material Type...
  • Find the palette file you downloaded and click Open
  • Set the 'Maximum Number of Colours' to the maximum allowed. This ensures the discreet colours are kept as they are. (1*)
  • Click Import and open menu Tools > Materials

Steps for importing a colour palette - PNG image of discreet colours - from Lospec as a material type in Avoyd, creating a Palette from the Material Type. The Palette is used in the Edit Tool to select materials (colours) to create voxel art with. Step 1: Download a .PNG from e.g. lospec.com. Step 2: In Avoyd Voxel Editor: open menu File > Import > Image (*.jpg, *.png, *.tga) as Material Type. Select the PNG file and import with the highest maximum colours. Step 3: A new Material Type is created. Use Auto + to create a new palette. Step 3: in the Tolls > Edit Tool, select the newly created palette and click on a coloured material swatch to use it to edit the 3D voxel model.
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)

Image Palettisation

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*)

Tips
  • Importing an Image creates a Material Type with the same name as the image.
  • the 'Maximum Number of Colours' setting defines the maximum number of Materials in the Material Type.
  • Only colours are imported. Material properties such as Metallic, Smooth, Emissivity, Transparency etc. have to be set manually.
  • You can quickly create a Palette directly from the Material Type using the Auto + Palette
    • Open menu Tools > Materials
    • In the Material Types section, choose a Material Type from the drop-down
    • In the Palettes area, press Auto + to create a new Palette with the same name and Materials selection as the selected Material Type.
  • You can add any number of Material Types or individual Materials to any palette

Notes:
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.

Raw 3D Binary Array

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.

  • Open File > Import > Raw 3D Binary Array... and select the binary file to import.
  • The Raw 3D Binary Array import dialogue opens with settings for x and y size. The importer automatically calculates the z size using size_z = file_size / ( size_x * size_y ) and warns if the provided sizes do match the file size.

Export to Polygon Mesh

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.

Options

Default export options for .obj polygon mesh export in Avoyd: Optimise Mesh, Centre on Origin and Blender Compatible Metallic Materials are ticked.
Default export options for .obj polygon mesh export in Avoyd

Optimize Mesh

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.

Centre on Origin

Translates the output model so that cente of the bounding volume is at the origin (0,0,0).

Export Normals

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.

Export single material with parameters in texture

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):

  • FILENAME_col.png RGBA texture with albedo colour and transmission in alpha.
  • FILENAME_metal_smooth_emissive.png RGB texture with Metallic in Red, Smoothness in Green and Emissive intensity in Blue.
Blender Compatible Metallic Materials

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.

Unity style material properties in texture

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:

  • FILENAME_col.png RGBA texture with albedo colour and transmission in alpha.
  • FILENAME_metal_1_1_smooth.png RGBA texture with Metallic in Red, Smoothness in Alpha and 1 in Blue/Green.
  • FILENAME_emissive.png RGB texture with emissive colour (emissive intensity * albedo).

See the Export to Unity Guide below.

Export roughness instead of smoothness

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.

Export and Import into Unity

Example voxel model open in Avoyd which will be exported to Unity. The model is an orange camper made of several materials including metallic, emissive and transparent. Credit: original model by Rebecca Michalak
Example camper voxel model which will be exported to Unity, open in Avoyd. The model includes several materials including metallic, emissive and transparent.
Download permissively licensed voxel model Camper.avwr

Isometric render of example model in Avoyd. The render shows the metallic materials reflecting the ground and sky, emissive headlights, and transparent windows, light lenses and exhaust fumes.
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: Optimise Mesh, Centre on Origin, Export single material with parameters in texture and Unity style material properties in texture are ticked.
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):

  • FILENAME.obj
  • FILENAME.mtl
  • FILENAME_col.png
  • FILENAME_metal_1_1_smooth.png
  • FILENAME_emissive.png

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.

Initial view of the Unity 3D project with an exported Avoyd model. The colour and materials setup is not yet complete.
Initial view of the Unity 3D project with an exported Avoyd model. The colour and materials setup is not yet complete.

Select the FILENAME_col.png texture in the Unity Asset window, which should open the texture Inspector.

Unity Inspector window open with the Default texture import settings.
Unity Inspector window open with the Default texture import settings.

The following default texture import settings need to be changed:

  • Advanced:
    • Non-Power of 2: None
    • Generate Mip Maps: Off
  • Wrap Mode: Clamp
  • Filter Mode: Point (no filter)
  • Max Size: 256
  • Resize Algorithm: Bilinear
  • Format: RGBA 32 bit

Once these are changed the colours of diffuse (non metallic) materials should now look more like they are in Avoyd as below:

Unity Inspector open with the fixed texture import settings.
Inspector open with the fixed texture import settings.

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.

Unity - Adjusted Bias and Normal Bias to remove light leakage and shadow acne.
Adjusted Bias and Normal Bias to remove light leakage and shadow acne.

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.

Unity - Scene with materials extracted.
Scene with materials extracted.

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.

Unity - Scene with transparent material set to use the Transparent Rendering Mode.
Scene with transparent material set to use the Transparent Rendering Mode.

Unity - Scene with transparency applied viewed from front.
Scene with transparency applied viewed from front.

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.

Unity - Scene with metallic and smoothness along with emission textures applied to material.
Scene with metallic and smoothness along with emission textures applied to material.

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.



Controls and Shortcuts



Avoyd requires a mouse and keyboard. Controls and shortcuts are currently hardcoded.

Camera Controls in Movement Mode

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.

Function Control
Engage Movement Mode Mouse right click and hold, or
Tab (toggles between the Menu and Movement modes)
Escape Movement Mode Mouse right button release, or
Esc, or
Tab
Camera Aim Mouse (Invert mouse Y and sensitivity in Settings > Controls...)
Move Forwards W
Move Backwards S
Strafe Left A
Strafe Right D
Roll Left (counterclockwise) Q
Roll Right (clockwise) E
Move Up Space
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 + →


Edit Tool Controls

These controls are available when the Edit Tool window is open and active. Menu Tools > Edit Tool > Shapes...

Function Control
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)
Open worlds, load templates, or import Mouse click on file then drag and drop into Avoyd, or
Menus File > Open; File > Load Template; File > Import


Keyboard Shortcuts

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).

Shortcut Function
0..9 Select custom Preset in the Edit Tool (Edit Tool active)
A Strafe Left
C First Person Camera / Arcball Camera toggle
D Strafe Righ
E Roll Right (clockwise)
F Perform edit action in the 3D World (Edit Tool active, Shapes tab)
P Pause game
Q Roll Left (counterclockwise)
S Move Backwards
W Move Forwards
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)
Space Move Up
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 Controls

Control Function
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
Drag and drop a file into Avoyd Open worlds, load templates, or import


Avoyd is a voxel editor and game developped and published by enkisoftware  •  ©enkisoftware 2001-2022