# Materials

> Set the surface of built-in objects, create reusable material assets, and override the materials of imported models slot by slot.

Source: https://feather-engine.com/docs/rendering/materials/

Feather Engine 2 has two ways to set how a surface looks. Built-in objects such as cubes, trees and
cottages carry their own **surface settings** in the Details panel. **Material assets** are reusable,
project-wide materials with textures; you assign them to any object, either to the whole object or
to one named material slot of an imported model. Editing a material asset updates every object
that uses it, live.

## Set the surface of a built-in object

1. Select the object.
2. In the Details panel, open **Appearance**.
3. Pick a colour and a **Preset**, then adjust the sliders.

| Setting | Range | Default | Description |
| --- | --- | --- | --- |
| Base colour | sRGB | — | Labelled **Canopy colour** on trees and **Wall colour** on cottages; other parts keep their original materials |
| Unlit surface | On/off | Off | Shows the base colour without lighting |
| Roughness | 0–1 | 0.95 | Low values are glossy |
| Metallic | 0–1 | 0 | |
| Emission colour | sRGB | — | Separate from the base colour |
| Emission strength | 0–100 | 0 | Brightens the surface. It does not add a light |

| Preset | Sets |
| --- | --- |
| Matte | The defaults. **Reset material** applies it too |
| Polished | Roughness 0.18 |
| Metal | Roughness 0.2, metallic 1 |
| Emission | Emission in the base colour at strength 2 |
| Unlit | Keeps the current settings and turns on **Unlit surface** |

Groups have no surface of their own; their children keep their own materials. Imported models
keep their embedded materials; change them with material assets instead.

## Create a material asset

1. Open **Window → Materials & textures** and select the **Materials** tab.
2. Click **+ New material**. **Duplicate** copies the selected material; **Delete** removes it and
   clears every slot that used it.
3. Edit the fields. The preview sphere follows your changes while you drag.
4. Select an object in the viewport and click **Assign to *object name*** to apply the material to
   all of its meshes.

The panel shows how many objects use the material.

| Field | Range | Default | Description |
| --- | --- | --- | --- |
| Base colour | sRGB 0–1 | White | Multiplied with the base texture |
| Base texture | Project texture | None | |
| Normal map | Project texture | None | |
| Roughness | 0–1 | 0.8 | |
| Metallic | 0–1 | 0 | |
| Emission | sRGB 0–1 | White | Emission colour |
| Strength | 0–50 in the panel, 0–100 by command | 0 | Emission strength |
| Emission texture | Project texture | None | |
| Opaque / Cutout / Transparent | — | Opaque | Alpha mode |
| Cutoff | 0–1 | 0.5 | Cutout only: pixels below it are discarded, for leaves and fences |
| Opacity | 0–1 | 1 | Transparent only |
| Double sided | On/off | Off | |
| Unlit | On/off | Off | |
| Shading | Project / Standard / Toon | Project | See below |
| UV tiling | 0.01–100 per axis in the panel | 1 × 1 | Texture repeats across the mesh UVs |

### Shading

**Standard** is physically based. **Toon** is cel shading. **Project** follows the project default,
set in the **Project shading** tab of the same window. A toon material can use the project's toon
look or turn on **Own toon look** to keep its own. See
[Post-processing](/docs/rendering/post-processing/) for the toon look settings.

A material can also carry a node graph. Build it in the **Material Graph** tab; see
[Material graphs](/docs/rendering/material-graphs/).

## Override a model's materials

Imported models list each embedded glTF material in **Details → Materials**.

1. Select the model.
2. In **Details → Materials**, each slot shows **Embedded** or the material asset that replaces it.
   Pick a material asset from the list to override that slot.
3. To edit an embedded material, click **Edit** next to the slot. The editor copies it into a new
   material asset — colour, roughness, metallic, emission, alpha, double-sided and textures — assigns
   it to the slot, and opens it in the material editor.
4. **+ Whole-model override** applies one material to every mesh. On built-in objects the button
   is **+ Override material**.

Remove an override with **×**. An object can hold up to 32 material overrides.

## Textures

Materials, terrain layers and skies use **project textures**.

1. Open **Window → Materials & textures** and select the **Textures** tab.
2. Click **Import PNG texture…**.

Textures must be PNG images. Identical images share one stored file, and you can rename or remove a
texture from its menu. To use the stylized texture library instead, import a library texture with
`texture.library_import`; it copies the colour map and the OpenGL normal map into the project.

## Limits

- Up to 1,000 material assets per project.
- Up to 32 material overrides per object.
- Colours, roughness, metallic, cutoff and opacity are 0–1. Emission strength is 0–100. UV scale is
  0.001–1,000 by command.
- Textures are PNG only. A `.cube` colour LUT is converted on import for post-processing.

## Automate it

Agents create and assign materials through the same commands the editor uses. This imports a
texture, creates a tiled material from it, and assigns it to object 12:

```bash
feather-cli --connect .feather-session.json command texture.import \
  --json '{"path":"textures/stone.png"}'

feather-cli --connect .feather-session.json command material.create \
  --json '{"name":"Stone wall","base_texture":3,"roughness":0.9,"uv_scale":[4,4]}'

feather-cli --connect .feather-session.json command scene.update \
  --json '{"id":12,"patch":{"material_slots":[{"slot":null,"material_id":1}]}}'
```

| Command | Purpose |
| --- | --- |
| `material.get` | Reads project shading and material summaries; with `id`, one material in full |
| `material.create` | Creates a material asset and returns its ID |
| `material.update` | Patches a material asset; every user updates live |
| `material.remove` | Deletes a material and clears the slots that used it |
| `material.from_model` | Makes an editable material from a model's embedded glTF material |
| `material.set` | Patches the project shading defaults |
| `scene.update` | Sets `material_slots`, or the built-in `material` fields, on an object |
| `texture.import` | Imports a PNG as a project texture |

Use the IDs the commands return in place of the example IDs. See
[Agents & automation](/docs/agents/overview/) for connecting a live session.