> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Armour

> Custom worn textures for armour, elytra and mob armour, plus effects and full-set bonuses.

An item's `texture` is its icon. What it looks like **when worn** goes under `armor:`.

```yaml items/armor/ruby_armor.yml theme={null}
ruby_helmet:
  material: iron_helmet
  name: "<red>Ruby Helmet"
  texture: ruby_helmet.png
  armor:
    set: ruby
    body: ruby_layer_1.png

ruby_chestplate:
  material: iron_chestplate
  name: "<red>Ruby Chestplate"
  texture: ruby_chestplate.png
  armor:
    set: ruby

ruby_leggings:
  material: iron_leggings
  name: "<red>Ruby Leggings"
  texture: ruby_leggings.png
  armor:
    set: ruby
    legs: ruby_layer_2.png

ruby_boots:
  material: iron_boots
  name: "<red>Ruby Boots"
  texture: ruby_boots.png
  armor:
    set: ruby
```

## Sets

Pieces with the same `set` share one worn look. Each texture only has to be given **once** in the set, on any piece; the other pieces pick it up. Giving two different textures for the same layer in one set is an error. Without `set`, the item is a set of its own named after its id.

The two humanoid textures follow vanilla's armour texture layout:

| Key | Used by |
| - | - |
| `body` | Helmet, chestplate and boots (vanilla's `layer_1`). |
| `legs` | Leggings (vanilla's `layer_2`). |

## Other things you can wear

| Key | Looks |
| - | - |
| `wings` | Elytra (use `material: elytra`). |
| `wolf` | Wolf armour. |
| `horse` | Horse armour. |
| `llama` | Llama carpets. |
| `happy-ghast` or `harness` | Happy ghast harness. |
| `pig-saddle`, `horse-saddle`, `camel-saddle`, `strider-saddle`, `donkey-saddle`, `mule-saddle`, `skeleton-horse-saddle`, `zombie-horse-saddle` | Saddles. |

Any other vanilla equipment layer can be given by its own name under `layers:`:

```yaml theme={null}
armor:
  layers:
    nautilus_body: nautilus_armor.png
```

## Options

**armor.set** `id`

Pieces with the same set share their look and count together for `full-set`. Defaults to the item's id.

**armor.dyeable** `boolean` (default: false)

Tints the worn textures with the item's dye colour, like leather armour. Draw them in greyscale.

**armor.slot** `text`

Where it's worn: `head`, `chest`, `legs`, `feet`, `body`, `saddle`. Needed only when the `material` isn't wearable already, or to change where it goes.

**armor.entities** `list`

Which mobs may wear it, when that should differ from the base item. For example `[llama, trader_llama]`.

**armor.effects** `list`

Potion effects while it's worn, written as `name [level]`: `["night_vision", "speed 2"]`.

**armor.full-set** `boolean` (default: false)

Effects only apply while all four armour slots hold pieces of this set.

```yaml theme={null}
ruby_chestplate:
  material: iron_chestplate
  texture: ruby_chestplate.png
  armor:
    set: ruby
    effects: ["fire_resistance", "strength 1"]
    full-set: true
```

Effects are topped up every second, so night vision never flickers. They are only removed if they still came from the armour, so a potion the player drank is left alone.

A set where no piece gives a worn texture keeps the base item's look, so `iron_chestplate` with only `effects` still looks like iron when worn.

## 3D armour

Give a set a Blockbench model, and players see it worn in full 3D: horns, shoulder pads, capes, anything you can build out of cubes. It moves with the arms and legs and works on players, armour stands and grown-up mobs (baby mobs wear it flat).

```yaml items/armor/lodestone/lodestone.yml theme={null}
lodestone_helmet:
  material: netherite_helmet
  name: "<gray>Lodestone Helm"
  texture: lodestone_helmet.png          # the item icon
  armor:
    set: lodestone
    model: lodestone_armor.bbmodel       # the 3D look, for the whole set
    body: lodestone_layer_1.png          # flat look: helmet, chestplate, boots
    legs: lodestone_layer_2.png          # flat look: leggings

lodestone_chestplate:
  material: netherite_chestplate
  name: "<gray>Lodestone Cuirass"
  texture: lodestone_chestplate.png
  armor: { set: lodestone }
```

This is the Lodestone set that LodeItems installs on first start, in `items/armor/lodestone/`. Open its `lodestone_armor.bbmodel` in Blockbench to see how a 3D set is built.

Each piece still has its own item icon (`texture:`), a normal 16×16 item texture.

### Building the model

Build it in Blockbench around a player, with each body part's cubes in a bone (group) named after it:

| Piece | Bone names |
| - | - |
| Helmet | `head`, `helmet` |
| Chestplate | `torso` (or `chest`, `body`), `right_arm`, `left_arm` |
| Leggings | `hips` (or `waist`, `belt`), `right_leg`, `left_leg` |
| Boots | `right_boot`, `left_boot` (or `right_foot`, `left_foot`) |

* Cubes can be rotated and inflated, and nested bones work too. Only cubes are supported, not meshes.
* Keep the player in the default pose (standing, arms down). The bones follow vanilla's joints: neck, shoulders and hips.
* Save the textures inside the model (Blockbench does this by default), or keep them next to it.

### Shader packs (Iris)

Shader packs replace the game's own shaders, so LodeItems also writes the model as a **custom entity model** for the [EMF](https://modrinth.com/mod/entity-model-features) and [ETF](https://modrinth.com/mod/entitytexturefeatures) mods. Players with **Iris, EMF and ETF** see it in 3D, shader pack and all.

Iris players without EMF and ETF see the flat look.

> [!NOTE]
>
> EMF's model format can't turn a face's texture a quarter turn, so faces rotated 90° or 270° show unturned for these players. The console warns when a model has any.
>
> Armour no 3D set picks keeps its normal look for EMF players, and other EMF armour packs keep working.

### The flat look

Not every player can see 3D armour, so each set also needs a flat look. It is used:

* by players with Iris but without EMF and ETF,
* on Macs and other graphics drivers without subgroup support,
* for armour further away than `armor.3d-distance` blocks (default 48) in [config.yml](https://items.lodemc.net/configuration.md).

Give it as usual with `body:` and `legs:`, or add two textures named `…layer_1` and `…layer_2` to the Blockbench model, and LodeItems uses those. A piece with nothing modelled is always worn flat.

> [!WARNING]
>
> 3D armour can't be `dyeable`: the layer colours are what tell the game which part of the model to draw. Armour trims and the enchantment glint still draw on the plain armour shape.

> [!NOTE]
>
> 3D armour comes with a replacement for the game's entity shader, so resource packs that also replace it (ModelEngine's shader, for example) can't be used at the same time. LodeItems' version wins and the console says so.

## Hats

A head item with its own `model` and no worn textures wears its model on the head. Use this for 3D hats:

```yaml theme={null}
top_hat:
  material: leather_helmet
  model: top_hat.json
  armor: {}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.