1 Introduction

Voxility Pro: Voxel File Format Exchange is a comprehensive Blender addon designed to revolutionize your voxel-based workflows. With its intuitive features and seamless integration, it empowers artists and designers to unleash their creativity and explore new dimensions of voxel modeling within the familiar Blender environment.

Voxility Pro supports seamless import and export of various popular textured voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl and a plethora of many more voxel file formats, ensuring compatibility with a wide range of voxel editors and game engines. Additionally, this addon introduces an integrated voxelization feature for textured meshes, allowing for streamlined voxelization directly within Blender.

1.1 Overview

Voxility Pro offers a robust set of tools and functionalities tailored specifically for voxel modeling enthusiasts. From integrated Mesh Voxelization to Import and Export capabilities, this addon provides a complete solution for incorporating voxel-based techniques into your projects.

1.2 Purpose

The primary goal of Voxility Pro is to simplify the process of working with voxel data in Blender while preserving the fidelity of your original models. One of its standout features is the ability to convert meshes with textures into voxel-type meshes. These voxel meshes can be exported to various formats such as MagicaVoxel.vox Qubicle.qb Voxlap.vxl and many more voxel file formats. Importantly, this addon preserves color information during the conversion process, enabling seamless transitions between traditional mesh modeling and voxel-based workflows.

1.3 Functionality

Voxility Pro boasts a range of powerful functionalities.

1.3.1 Functionalities

Feature	Description
Mesh Voxelization	Transform polygonal meshes into voxel-based representations with ease.
Texture Preservation	Retain color information from textures during mesh-to-voxel conversion.
Bake Texture	Bake any voxelized object with complex shaders into one Diffuse texture for easy export.
Import / Export	Seamlessly import and export voxel file formats for compatibility with various voxel editors and game engines.
Efficient Workflow	Intuitive tools and customizable settings streamline your voxel modeling workflow, enabling you to focus on your creative vision.

1.3.2 Limitations

Most file formats don't support exporting complex textures, let alone full-blown material definitions or other application-specific features. For more detailed information on this limitation, please refer to this link. Hence, we only support simple material definitions, either through the Image Texture node or basic color Diffuse definitions via the Principled BSDF node's Base Color socket.

No need to worry. Our integrated Bake Feature still enables you to use complex shaders to create model Diffuse colors. Just click Bake to consolidate shaders into a single Image Texture for easy export. Keep in mind, this process flattens your object by applying all modifiers, including the voxelization modifier, so ensure you back up your object beforehand. Baked images are not automatically saved, so remember to save them manually before closing to avoid losing them.

1.4 Compatibility

Voxility Pro is compatible with Blender versions 3.3 to 4.1 and above, running on Microsoft Windows, Mac OS, or Linux Platforms, ensuring broad accessibility for Blender users. You can easily identify the version of Blender you're using by accessing menu Help⇒Manual

However, if users choose to install it on lower versions up to 2.93, an older version with limited functionality will be available, although with reduced support.

1.4.1 Supported Voxel File Formats

Voxility Pro supports a wide range of formats, and we are continually adding more support. Currently, the following types are supported, indicated by a checkmark for their corresponding import or export format.

Voxel File Format Name	File Extension	Import	Export
MagicaVoxel	.vox	✓	✓
Qubicle Binary Exchange	.qb	✓	✓
Qubicle Binary Tree Exchange	.qbt	✓	✓
Qubicle Exchange Format ASCII	.qef	✓	✓
Qubicle Project	.qbcl	✓	✓
Binvox command line voxelizer	.binvox	✓	✓
CubeWorld CubeMap	.cub	✓	✓
Minecraft Schematic	.schematic	✓
Minecraft level dat	.dat	✓
Minecraft Anvil Region	.mca	✓	✓
Minetest Template	.mts	✓
Sandbox VoxEdit Collection	.vxc	✓
Sandbox VoxEdit Hierarchy	.vxr	✓	✓
Sandbox VoxEdit Tilemap	.vxt	✓
Sandbox VoxEdit Model	.vxm	✓	✓
MagicaVoxel XRAW	.xraw	✓	✓
Tiberian Sun	.vxl	✓	✓
Voxlap Voxel Engine	.kv6	✓	✓
Voxlap Voxel model format	.kvx	✓	✓
Animatoon 3D Scene	.scn	✓
Sproxel csv	.csv	✓	✓
StarMade Blueprint	.sment	✓
Goxel	.gox	✓	✓
Voxel Max	.vmax	✓
Voxel Builder	.vbx	✓
Voxel3D	.v3a	✓	✓
Vengi	.vengi	✓	✓
Nicks Voxel Model	.nvm	✓
Particubes	.pcubes	✓	✓
CuBic Mesh	.csm	✓
Cubzh	.3zh	✓	✓
Cubzh World	.b64	✓

2 Installation

We will guide you through each step of the installation process in a systematic manner.

2.1 Addon Requirements

It is crucial to ensure that your system meets all the necessary requirements for running this addon effectively. Please verify the following requirements:

Requirement	Description
Blender Version	Voxility Pro is fully compatible with Blender versions 3.3 through 4.1, and onwards. However, if users choose to install it on lower versions up to 2.93, an older version with limited functionality will be available, although with reduced support.
Operating System	Supported on Windows, Mac OS, and Linux platforms.
Hardware Requirements	Your system should meet the minimum hardware specifications recommended for running Blender smoothly.

2.2 Addon Download

• Locate the Voxility Pro addon product page.
• Click on the Purchase or Download button to obtain the addon.
• Complete the payment process if required.
• Once the download is complete, you will receive a .zip file containing the addon.

2.3 Addon Installation

After downloading the Voxility Pro addon and launching Blender on your system, you can install it by following these instructions:

• Go to menu Edit⇒Preferences...⇒Add-ons
• At the top right of the window, click on the Install... button.
• Navigate to where you downloaded the .zip file and select it.
• Click the Install Add-on button to install the addon.
• Enable the addon by checking the checkbox as shown below.

2.4 Addon Activation

To activate the Voxility Pro addon and unlock its full range of features, please follow the instructions provided below based on your respective Operating System, and review the following information. Take note of the voxconvert version, which is an executable binary file used within this addon, because this information may be needed after addon installation depending on your Operating System. Open Edit⇒Preferences...⇒Add-ons

Also please take note of the Blender version used. You can get the version by navigating to menu Help⇒Manual which opens a browser.

2.4.1 Microsoft Windows Activation

If you are running Blender on Microsoft Windows then you are all set. Please feel free to proceed to the Getting Started section.

2.4.2 Apple Mac OS Activation

If you are running Blender on a Mac computer then you are all set. Please feel free to proceed to the Getting Started section.

2.4.3 Linux Platform Activation

After installing the addon on Blender running on Linux, open the Linux Console or Terminal and copy-paste the following command text into any text editor. Then modify the text to adjust to your Blender version (e.g.4.0) and the voxconvert version (e.g.0.0.29). Then copy-paste the new modified text into your Linux Console and press Enter

Make sure the path is correct and there are no errors. Then copy the following commands line by line and paste each line into terminal and press Enter. Read the terminal outputs, because you may need to type in y for yes and press Enter to confirm command.

Read the output for each line you execute and make sure there are no errors. Finally test if you have successfully installed vengi-voxconvert by typing in the following command:

This should print out the voxconvert version. If successful, close Blender, reopen it, and the command should become available for Blender.

3 Getting Started

We'll walk you through the initial steps to familiarize yourself with our addon and its basic functionalities. Whether you're a newcomer or a seasoned user, this guide will help you navigate through the essential features and get you up to speed quickly.

3.1 Configuration Options

Enhance the addon by navigating to menu Edit⇒Preferences...⇒Add-ons and searching for VOXILITY. Then, click the small arrow located to the left of the addon name and checkbox. This action will unveil a plethora of configuration options, allowing you to personalize your experience and tailor the application to meet your unique requirements.

Select the checkboxes corresponding to the voxel file formats you'll use. This streamlines the voxel formats list by hiding irrelevant choices during object import/export, preventing clutter and ensuring a smoother workflow. Observe that the import list and export list (supported export formats only) now exclusively presents the options you've configured.

3.2 User Interface Overview

In this section, we'll provide an overview of the user interface to familiarize you with the main components and features.

3.2.1 Voxility Pro Panel

You can convert your textured mesh objects into voxel representation directly within Blender. Simply position your mouse in the 3D Viewport and press the N key. This will prompt the Sidebar, commonly known as the N-Panel to appear. From there, you can easily locate and click on the Voxility tab button to open the Voxility Pro addon panel. You can then click the Voxelize button to convert your object to voxel mesh representation.

If your intention is to export the resulting voxel mesh, you have the option to choose a Target export voxel format from the dropdown menu situated within the expandable Export tab. Hover your cursor over each option to unveil a tooltip providing an explanation for each property, allowing for a comprehensive understanding of their respective functionalities.

Below are the distinct functionalities provided by the addon panel:

Function	Description
Voxelize Button	Adds a voxelization Geometry Nodes modifier to the selected objects. Avoid directly modifying the modifier, as the addon automatically handles any necessary adjustments.
Voxel Size	Change the size or dimension of the voxels usually in meters between 0.01 to 100. If you need more detail, scale the entire model and Apply scale.
UV Map	Active Object's UV Map if any. Only one UV map is supported per object. See Limitations section
Vertex Colors	Active Object's Color Attribute if any. Only one Color Attribute is supported per object. See Limitations section
Export Target	Specify the desired voxel file format for export.
Check Problems	Click to validate your voxel mesh prior to export.
Bake Button	Optionally bake your object and colors or shaders into a single Image Texture for exporting complex shaders not directly supported. Baking will flatten your object or apply all modifiers, so be sure to back up your object beforehand. Baked images aren't automatically saved, so remember to save them manually before closing to avoid losing them.
Export Button	Click to export your voxel mesh to the specified Export Target

3.2.2 Voxility File Conversion Panel

Voxility File Conversion panel can be accessed by clicking anywhere within the 3D Viewport, ensuring that no object is selected. Browse for an Input File, choose a Target format, and then click the Convert button to select a location for saving the result.

3.2.3 Export Voxel Format File

You have the flexibility to export your models to a diverse range of widely recognized and popular voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl and many more voxel file formats by accessing the export options through menu File⇒Export⇒Voxility Voxel Formats⇒.* and selecting a voxel format of your choice. You can streamline this export list by filtering out only the relevant options through the Configuration Options.

Simply select all mesh objects and click Voxelize button and then export. You will be presented with the Export Dialog where you can select a location and input a file name. Press the Export button to start the conversion process and save it to your chosen destination. This may take some time, so please be patient.

In the previous example we exported a .vox file which can be opened in MagicaVoxel

MagicaVoxel is just one example of various software and game engines that are capable of processing a wide array of voxel file formats, each designed to accommodate different needs and functionalities.

3.2.4 Import Voxel Format File

You have the flexibility to import your models from a diverse range of widely recognized and popular voxel file formats, including MagicaVoxel.vox Qubicle.qb Voxlap.vxl as well as numerous other voxel file formats by accessing the import options through menu File⇒Import⇒Voxility Voxel Formats⇒.* and selecting a supported voxel file. You can streamline this import list by filtering out only the relevant options through the Configuration Options.

Once you have chosen a voxel format, you will be presented with the Import Dialog where you can select a file to import. You can also adjust the import options. Hover your cursor over each option to unveil a tooltip providing an explanation for each property, allowing for a comprehensive understanding of their respective functionalities. Press the Import button to start the import process. This may take some time, so please be patient.

3.3 Voxility Logging

It is recommended to switch to the Scripting workspace tab so you can see the processing output, and please take note of the dimension of the object. The larger the object in dimensions, the more voxel detail you can produce, but it may take longer to process. The output will be visible in the Info Editor.

4 Troubleshooting

4.1 Common Issues

At this early stage, with Voxility Pro being newly released, we're pleased to inform you that there haven't been any common issues reported thus far. However, for any questions or concerns, please feel free to reach out to us via Blender Market, the platform through which you acquired the addon, and we'll be more than happy to assist you promptly.

5 Support and Community

5.1 Contact Information

Please reach out to us via Blender Market, the platform through which you acquired the addon. We are committed to promptly addressing any concerns or issues you may encounter. We're excited to announce that we will soon be launching a Discord community. Stay tuned for updates, as we look forward to connecting with you and fostering a vibrant community of Blender enthusiasts.

6 Appendix

6.1 Glossary

Term	Description
Voxel	Volumetric pixel used in 3D modeling and computer graphics to represent volumetric data.
Voxelization	Process of converting a mesh or other 3D data into a voxel representation.
Addon	Piece of software that extends the functionality of Blender, designed to enhance and streamline various aspects of the Blender workflow.
Texture	Surface appearance of an object when it's rendered. It includes characteristics such as color, roughness, reflectivity, and bumpiness, etc.
VOX File	Simple binary format used to store voxel data. It consists of a header section followed by the voxel data, which is typically encoded using run-length encoding (RLE) or other compression techniques to reduce file size.
MagicaVoxel	Voxel modeling software that uses its own proprietary file format (.VOX) for saving voxel models.
Qubicle	Voxel modeling software that uses its own file format (.QB) for saving voxel models.
Executable	External program or script that can be run by Blender as a separate process.
Terminal or Console	Provides a command-line interface where users can type commands directly to interact with the operating system and run various programs or utilities.
ZIP File	Compressed archive that contains script and one or more assets. Users can install these addons by importing the zip file directly into Blender's addon manager, simplifying the installation process.

6.2 Additional Resources

Resource	Resource Link
Voxconvert Documentation	https://vengi-voxel.github.io/vengi/voxconvert/Index/
Voxconvert Tutorial	https://www.youtube.com/watch?v=Erstqc5uSxU

6.3 Version History

Previously known as MagicaVoxel Vox Exporter, this addon initially offered only basic export functionality for MagicaVoxel only. Renamed as Voxility Pro we have significantly expanded its capabilities to include both import and export functions for various formats. Additionally, we've introduced a dedicated panel within Blender that facilitates in-app voxelization — a feature designed to enhance your voxel modeling experience.