> 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/integrations-and-plugins/blender-addon/materials.md).

# Materials

All material tools are in the **Shader Editor**: open the sidebar with **N** and choose the **colormass** tab. The **Material** panel works on the active material of the selected object.

## Download a material

Every material on the platform has a number, its Material ID. You find it in the material's dialog on the platform:

![The Material ID in the platform's material dialog](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/OPlNBwQQNe24pUiyo4Kg/images/material-id-on-platform.png)

{% stepper %}
{% step %}

## Select the object

In Blender, select the object that should get the material.
{% endstep %}

{% step %}

## Enter the Material ID

In the **Material** panel, enter the **Material ID** and press Enter. The panel shows the material's name and organization.
{% endstep %}

{% step %}

## Pick a revision

Pick a revision from the list (v1, v2, …). The newest one is selected.
{% endstep %}

{% step %}

## Download the material

Click **Download selected material revision**.
{% endstep %}
{% endstepper %}

![A downloaded material in the Shader Editor](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/nkms0rpo4tUxxwyVRUc1/images/material-panel.png)

Blender shows the download's progress in the status bar: how many textures are done, and the current file. The ✕ button cancels it.

![A running download in the status bar](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/bgv7pppxEGjccwWmPcR2/images/download-progress.png)

Once everything has arrived, the material replaces the object's active material. If the object has no material yet, the addon creates one. From then on it works like any other Blender material. The textures are stored in your cache folder and reused, so a material you download again is ready at once.

A downloaded material remembers where it came from: the panel shows its **Material Revision ID**. 

## Create and upload a material

### A few things to know first

Your material is rendered on the platform, not on your computer, so the platform needs its own copy of everything the material uses. Anything that only exists on your computer, such as an image on your drive, has to be uploaded along with the material. The colormass nodes take care of that. Add them from the **Add Colormass node** menu:

![The Add Colormass node menu](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/lEnhQpP4jN97HKDAGvLW/images/add-node-menu.png)

* **Colormass BSDF Principled:** the shader the platform renders. Use it in place of Blender's Principled BSDF.
* **Colormass Scanned Transmission:** for scanned materials that let light through.
* **Colormass Texture Set** and **Colormass Texture Set From Images:** a full set of maps in one node.
* **Colormass Texture From Set:** a single map in one node.

### Images go into Texture Set or Texture From Set nodes

Blender's **Image Texture** node only points at a file on your drive, so the platform can't use it. Every image goes into one of the two colormass texture nodes instead.

In this fabric material, one **Texture Set** holds the complete set of scanned maps: colour, metalness, specular, roughness, anisotropy and normal. Each output feeds the matching input of the Colormass BSDF Principled. A separate **Texture From Set** holds a dirt mask. It isn't part of the fabric's set, and it only decides where a darker colour is mixed over the fabric's colour:

![A Texture Set and a Texture From Set node in a material](https://1229207575-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv3R7xjvJcsIFNxg1zMmq%2Fuploads%2FAnbomnHNNEsMOWMkmkJf%2Ftexture-nodes.png?alt=media\&token=fb35934c-9fcb-4e84-9de4-e2f6c8cb0c4a)

#### Texture Set

A Texture Set is one node holding a full set of PBR maps, such as color, normal and roughness.

* **Colormass Texture Set** adds a set that is already on the platform. Leave **Texture set ID** empty to choose from the sets of this material, or enter another texture set's ID to use its maps.

  ![Adding a texture set from the platform](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/6cl4TZyJEnwzkQH3OFSl/images/texture-set-dialog.png)
* **Colormass Texture Set From Images** makes a new set from your own files. Choose the maps in the file browser. The addon guesses from each file name which map it is, and how its colours are to be read. Check the guesses, then enter how large the texture is in the real world.

  ![Adding a texture set from your own images](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/HzIYJnKgGmqWwMOdao5U/images/texture-set-from-images.png)

#### Texture From Set

A Texture From Set is one node holding a single map. **Colormass Texture From Set** takes either one map out of a texture set on the platform (**Texture set**) or one image from your drive (**Image file**). For an image, say which map it is, how its colours are read, and its real-world size.

![Adding a single map from an image file](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/WbZaFJrpev8xSx4N6had/images/texture-from-set-dialog.png)

#### When to pick which?

If the maps belong together and describe the same surface, like a stack of PBR maps, use a Texture Set. Use a Texture From Set when you need one map on its own, for example as a mask or for bump.

Either way:

* **All maps of a set need to have the same resolution.** The dialog tells you if they don't.
* **Every texture needs its real-world size** in centimetres. This is the size it gets on the platform. Enter the width, and the height follows from the image's proportions.
* **You can build first and upload later.** The nodes don't need the material to exist on the platform yet. Your images are uploaded with the material's next revision.

### Convert a material you built with Blender's nodes

You don't have to rebuild an ordinary Blender material. If it uses Blender's Principled BSDF or image textures, the panel offers **Prepare material for the platform**:

![A material built with Blender's nodes](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/YyfEVYALNEVpMbmtBnAs/images/material-local.png)

Before it changes anything, the addon lists what it will do, including settings the colormass BSDF handles differently:

![The Prepare dialog](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/5BN4CwpqFQYIfkZfkg9v/images/prepare-dialog.png)

* Blender's **Principled BSDF** becomes the **Colormass BSDF Principled**, and your settings come across with it.
* Every **Image Texture** becomes a **Texture From Set** node. The rest of the node tree stays as it is.

![The same material, prepared for the platform](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/QMZhZ7FqWaUUAcFj8uo8/images/material-prepared.png)

Every image texture needs a **Mapping** node in front of it. The addon reads the texture's real-world size from that node's Scale. Mapping nodes of type Point become type Texture, so the texture stays where it was. If an image texture has no Mapping node, the addon tells you which node to fix, and changes nothing until every node can be converted.

To prepare all materials of an object at once, use the same button in **Properties ▸ Object ▸ colormass**.

### Upload

{% stepper %}
{% step %}

## Create a new material

For a new material, click **Create new material**. Give it a name and choose the organization it belongs to. This creates the material on the platform, still without a revision.

![Creating a new material](https://content.gitbook.com/content/v3R7xjvJcsIFNxg1zMmq/blobs/es1roB6iJIL1qD37OE60/images/create-material.png)
{% endstep %}

{% step %}

## Upload a new revision

Click **Upload new material revision**. The addon uploads the material as a new revision, together with any of your own images it uses.
{% endstep %}
{% endstepper %}

To update a material that is already on the platform, download it, change it, and click **Upload new material revision** again.

When you upload meshes to the template editor, the addon can upload their changed and new materials along with them. See [*Scenes*](/building-blocks/integrations-and-plugins/blender-addon/scenes.md).