Avoyd Voxel Editor 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).

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:

• Add and customise a new Material Type; or
• Import an image (palette) as a Material Type.

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

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

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

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

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

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.

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:

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.

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.

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.

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

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.

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.

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