> For the complete documentation index, see [llms.txt](https://docs.colormass.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.colormass.com/building-blocks/materials/blender-addon.md). # Blender Addon The colormass Blender addon allows downloading materials from the platform to Blender and also creating materials within Blender and uploading them to the platform. ## Install The addon ships as one universal zip covering Windows, Linux and macOS. It can be downloaded directly from the platform by clicking on the question mark icon:

In Blender, open Edit ▸ Preferences ▸ Get Extensions, click the ▾ at the top right and choose Install from Disk…, then pick the downloaded Zip file. It appears in the list as *colormass Platform Interface.*

Turn on Preferences ▸ System ▸ Network ▸ Allow Online Access. The addon declares the network permission and can reach the platform only with this enabled. ## User Interface Open a Shader Editor, press `N` and go to the colormass tab. Under `Settings`, enter your email and password and press `Log in`. The panel then shows your name with an `✕` to log out. Press `Select cache folder` and choose where downloaded textures should live. Everything the addon fetches is written there and reused.

{% hint style="info" %} **Updating later.** When the platform holds a newer build, the colormass panel shows *“colormass 3.x.x is available”* with an Install update button. {% endhint %} ## Download a material Select the object in Blender whose material you want to replace, so the Shader Editor shows its node tree.\ Type the platform’s id into `Material ID` — the digits from its ID, e.g. `12345`. These can be copied from the material dialog of the platform.

After having entered the `Material ID` in the addon UI and pressed enter click the revision list (it reads the revisions as v1, v2, ...) and choose the one you like to download, most often it will be the latest one. Press `Download selected material revision`. Two progress bars appear — the whole job and the current file — with `Cancel` beside them. All downloaded Textures land in your cache folder. The downloaded material graph replaces the active material, when everything was downloaded. You can then use this material as any arbitrary Blender material in your workflow.

## Create and upload a new material You can also create your own material just as any other Blender material and upload it to the platform to make it available there. To upload, you can create a new material using the `Create new material` in the `Material` panel. During the creation you can choose a name for the material on the platform and link it to a particular organization. Once created, you can upload it by clicking the `Upload new material` revision button.

**A few things to know first** Your material is rendered on the platform, not on your machine, so the platform needs its own copy of everything it uses. Anything that only exists on your computer — an image on your drive, for instance — has to be uploaded first. **Images need to be either `Texture from Set` or `Texture Set`** A normal Blender native `Image Texture` node only points at a file on your drive, so every image has to go into one of the two colormass nodes instead: * **Texture Set** — one node holding a full set of PBR maps: color, normal, roughness, ... Add it from *`Add Colormass node` ▸ `Colormass Texture Set`* to use a set that is already on the platform, or *`Colormass Texture Set From Images`* to use your own files.

* **Texture from Set** — one node holding a single map. Add it from *Add Colormass node ▸ Colormass Texture From Set*, either taking one map out of a set or picking one image from your drive.

**When to pick which?** If the maps belong together and describe the same surface, use a `Texture Set`, e.g. a stack of PBR maps. Use a `Texture from Set` when you only need one map on its own — e.g. as a mask or as bump. Either way you can build the material first and upload later; the nodes do not need the material to exist on the platform yet. Two rules apply to both: all the maps in a set have to be the same resolution, and you have to say how big the texture is in the real world, in centimeters. **Converting the textures of an existing material** If you already have an ordinary Blender material, you do not have to rebuild it. Press **`Replace image textures`** in the Material panel and the addon swaps its image textures for colormass **`Texture from Set`** nodes, leaving the rest of the graph as it is.

For that to work, each image texture needs a **`Mapping`** node feeding it, set to *`Texture`* mode. The addon reads the real-world size straight off that node's Scale. If an image has no Mapping node, or one is in the wrong mode, the addon tells you exactly which node to fix. The images are sent with your next upload, so once everything is converted, press *`Upload new material revision`*. **Use the colormass Principled BSDF** Blender's own `Principled BSDF` is not what the platform renders, so use ours. Add it from *`Add Colormass node` ▸ `Colormass BSDF Principled`*, or press **`Replace BSDF`** to swap the one already in your material — your settings come across with it.