Installation

Multi-part ZIPs (.001, .002, ...)

Info

Only applies if you downloaded .001, .002, ... files. You can skip this section if you downloaded a .zip file directly.

Some of our addons take a lot of space because they are packed with high-quality resources. To make downloads manageable we split these addon ZIPs into multiple files. This is doubly necessary because both BlenderMarket and Gumroad limit the size of files we can upload.

These split ZIP files (also called part files) have to be put next to each other and then extracted to get the big ZIP file for installation in Blender.

WindowsmacOS 10Linux

Unfortunately, the archive tool included in your operating system might not be up to the task. We recommend using 7-zip to extract the part files. You can use other ZIP extraction tools but in the rest of this guide we will use 7-zip.

Head over to the 7-zip download page, download the installer and run it. Now go to the folder where you put all the .001, .002, ... files and right click on the .001 file. Hover over 7-Zip and select Extract here.

Wait until the dialog finishes. A new ZIP file will appear next to the .001, .002, ... files. Delete the .001, .002, ... files and proceed with the extracted big ZIP file.

Unfortunately, the archive tool included in your operating system might not be up to the task. We recommend using The Unarchiver to extract the part files. You can use other ZIP extraction tools but in the rest of this guide we will use The Unarchiver.

Install The Unarchiver from the App Store.

Set up The Unarchiver to open .001 files by right clicking on the them, selecting Open With and clicking on The Unarchiver. After this step the tool will begin extracting.

Wait until extracting finishes. A new ZIP file will appear next to the .001, .002, ... files. Delete the .001, .002, ... files and proceed with the extracted big ZIP file.

If you are using Linux you know what to do .

# if using apt-get (Ubuntu, Debian)
apt-get install p7zip-full

# if using dnf (Fedora, newer CentOS, RHEL)
dnf install p7zip

# if using yum (older CentOS, RHEL)
yum install p7zip

cd folder_where_part_files_are
7za x *.zip.001

---

For one Blender Version (easy)

Materialiq addon python code and assets are included in one big ZIP file. This entire file has to be installed for the addon to work. First download the ZIP file from BlenderMarket or Gumroad.

macOS 10 auto extracting ZIPs

Safari might auto extract the ZIP file when downloading. This is undesirable and will prevent the addon from working.

To stop macOS 10 automatically unzipping your files:

1. Go into Safari Preferences,
2. Locate page titled General,
3. Scroll down to the bottom,
4. Deselect the box with the text 'Open safe files after downloading',
5. materialiq will now be downloaded as a .zip file and can be installed on macOS 10.

At this stage you should have an unextracted ZIP file ready on your hard-drive.

Open the specific Blender version you want to use with materialiq. Each Blender version has its own directory for scripts and addons, this directory is not shared between them. In our example we will use Blender 3.0.1.

One addon installation for multiple blenders

See custom addon path if you want to use materialiq in multiple Blender versions without duplicating data.

Open Preferences by navigating to Edit → Preferences:

Click Add-ons and then the Install... button:

Navigate to the addon ZIP file you downloaded earlier, select it and click install.

Screen will freeze for a bit

It is normal for Blender to freeze for a little bit while the addon is installing. Blender is extracting all the meshes, textures and other data. Please be patient. It might take up to 10 minutes, depending on your hard-drive performance.

Interrupted installations have to be retried

If you stop the Blender process at this point your materialiq installation will be corrupted, you will have to remove it and start over.

Not having enough disk space results in a corrupted installation

If you attempt to install materialiq and do not have enough disk space Blender will still attempt to unpack it and fail. This results in corrupted installations, you will have to free up disk space, remove the corrupted installation and try again.

After the screen unfreezes, check the materialiq addon to enable it. The addon preferences should show up and after this point you are ready to use materialiq and make some epic scenes!

Restart Blender after installing materialiq

Restarting Blender cleans its Python module cache and prevents issues with old functions being used by accident.

Save Blender preferences

Before you go enjoy materialiq, click the "hamburger" menu in the bottom left of Blender preferences and select Save preferences. This will enable materialiq on startup. If you omit this step and do not have auto-save preferences enabled, materialiq would still be installed after starting Blender but would not be enabled!

To a Custom Addon Path (advanced)

There are cases where you don't want to install the materialiq ZIP into Blender's default script path: - you want to use materialiq in multiple Blender versions, - you want materialiq on a drive different from the Blender installation, - you want materialiq in a specific path so that .blends shared with colleagues work out of the box.

If any of those apply to you, you may want to go the more advanced route and set the addon installation path to a path of your choice.

As a first step, make sure no version of materialiq is installed. You don't want to run into problems having multiple versions of materialiq in addon path.

Choose an addon path of your convenience. Make sure this is on a hard-drive with enough free disk space. In our example we will use C:/blender_addons.

Choose a simple path

We recommend not choosing a path with unicode characters or a path that is too long. Some Operating Systems have path length limits and if you run into those the addon won't be able to find some or all files! Choose something simple, ideally as short a path as possible...

Go to Edit -> Preferences and select File Paths in the left menu. Look for the "Scripts" path and set it to the C:/blender_addons path.

You might need to reinstall addons

If you have addons already installed in the default path you have to reinstall them in the custom path. By changing the script path you are telling Blender to look for user addons elsewhere. The addons included with Blender will still be available but addons you installed yourself need to be reinstalled in the new path.

Now go to the Add-ons tab on the left menu and select the Install... button. Choose the materialiq addon ZIP you downloaded earlier. On the Target Path dropdown menu select Preferences and click Install Add-on. This will unzip the addon into the path selected in "Scripts".

After the screen unfreezes, materialiq should appear.

Enable it via the checkbox:

And voila! You have installed materialiq to a custom path. If you set up the same Scripts filepath in other Blender versions you may share materialiq or even other addons across different Blender versions.

Alternative: Install by extracting the files yourself

Instead of using the Install... button in Blender, you can extract the ZIP to the custom path using your preferred utility. For example, if we use C:/blender_addons as our desired path, we create another directory inside it called addons. We set the "Scripts" path as explained above and extract the ZIP in such a way that the folder inside the ZIP ends up inside C:/blender_addons/addons/.

In our experience extracting with 7zip or a similar tool is faster, especially for large addons. This procedure may require hitting the Refresh button or restarting Blender for the addon to appear.

Choose the correct path

The folder at the chosen path must contain another folder called addons. Do not set it to C:/blender_addons/addons, that would not work! It needs to be just C:/blender_addons.

Megaddon (dependency)

materialiq requires one more addon to be installed. This addon is called megaddon and it is the central polygoniq addon that contains most of the addon features. It needs to be enabled for materialiq to work correctly.

materialiq installs megaddon automatically

megaddon is automatically installed when materialiq is enabled in the addon preferences after installation. If this doesn't happen for you, check troubleshooting for more detailed information.

Don't disable megaddon

If you disable megaddon materialiq features will not work correctly.

Restart Blender after installation

If you had an older version of materialiq or megaddon installed it is necessary to restart Blender to cleanup cached Python modules after enabling the addon. It is recommended to restart Blender after each installation so everything can bootstrap fresh.

Troubleshooting

If there is an issue with megaddon dependency and materialiq is installed correctly according to installation then there might be an issue with the megaddon version present in Blender.

Check megaddon dependency state

State of megaddon dependency installation can be checked in the materialiq preferences. Any relevant errors will be displayed here.

Older polygoniq addons

Having older versions of any polygoniq addons can cause issues. Make sure that all other polygoniq addons are up to date, so they don't override updated megaddon or other module code!

Disable and Enable materialiq to re-install megaddon

If there is any issue with the dependency, correct version of megaddon is shipped with each zip file and is automatically installed when the addon is enabled in preferences.

Restart Blender after enabling, because the old Python modules may be cached.