How to Make a Modular Item

A modular item is built from parts, one in each of its slots, and each part is made from a material. The item remembers the material in every slot, so one item config covers every combination: three slots and 20 materials is 8,000 different items from one file. This page covers making parts and a modular item from scratch.

Quick start

1. Make the materials you'll use, e.g. cobalt, wood and iron.

2. In /plugins/EcoItems/items/, create one item per part shape, e.g. pickaxe_head.yml, with a part: section. items/_example_part.yml lists every option.

3. Create the modular item, e.g. modular_pickaxe.yml, with a modular: section naming its slots. items/_example_modular.yml lists every option.

4. Draw one greyscale texture per part shape and put it in pack/assets/<namespace>/textures/.

5. Run /ecoitems reload.

6. Give one with /ecoitems give <player> modular_pickaxe 1 head:cobalt handle:wood binding:iron, or make the parts at an anvil and put them together at a crafting table.

Naming and IDs

Parts and modular items are normal EcoItems, so their ID is the file name without .yml. Slot IDs and part shapes are your own names.

The structure of a part

# === Recipe: made at an anvil or a smithing table ===
item:
  item: flint
  recipes:
    type: anvil
    base: ecoitems:pickaxe_head_pattern # The left slot.
    material: material # The right slot: any material.
    repair-cost: 1 # The level cost.

part:
  # === Shape: which slots it fits ===
  shape: pickaxe_head
  cost: 2 # How many of the material's items it takes.

  # === Display: name and texture ===
  name: "%material% Pickaxe Head"
  texture: ecoitems:item/part/pickaxe_head # Greyscale, recoloured per material.

Recipe

material accepts any material: the part is made from whichever material's item is used. It works as an anvil's material and a smithing table's addition. At an anvil, cost of the material is used up.

Texture

Draw the texture with only these 8 greys, darkest to lightest: 34, 62, 92, 122, 152, 186, 220 and 250. The resource pack makes a copy for each material by swapping each grey for that material's palette colour, the way vanilla colours armor trims. Draw each part where it sits on the finished item, since the item stacks the part textures on top of each other.

3D model

A part can be drawn in 3D in a modular item, such as a strap behind a shield. Set model to a model whose elements use the texture #layer0:

part:
  texture: ecoitems:item/part/shield_strap # The part's own icon, and the texture the model's faces use.
  model: ecoitems:item/part/shield_strap_3d # Read from pack/assets/ecoitems/models/item/part/shield_strap_3d.json

The model is written again for each material with the recoloured texture as #layer0, and is held the same way as the rest of the item. The part's own icon stays flat. A model with no elements is skipped with a warning, and the part is drawn flat.

The structure of a modular item

# === Recipe: parts of any material fit ===
item:
  item: iron_pickaxe
  recipes:
    type: crafting_table
    recipe:
      - ""
      - ecoitems:pickaxe_head
      - ""
      - ""
      - ecoitems:binding
      - ""
      - ""
      - ecoitems:tool_rod
      - ""

modular:
  # === Slots: slot ID to the part shape it takes ===
  slots:
    head: pickaxe_head
    handle: tool_rod
    binding: binding
  layers: # The texture order, bottom to top.
    - handle
    - head
    - binding
  overlays: # Drawn on top, never recoloured.
    - ecoitems:item/part/pickaxe_shine

  # === Display: name and lore ===
  name: "%material_head% Pickaxe"
  lore:
    - "&7Head: %material_head%"

  # === Swapping: replace a part at an anvil ===
  swappable: true
  swap-cost: 1 # The level cost.
  swap-returns-part: false # Give the replaced part back.

  # === Mining: optional ===
  mining:
    blocks: "#minecraft:mineable/pickaxe"
    from: head # The slot whose material gives the speed and tier.

slot: mainhand

Layers and overlays

The slot textures are drawn in layers order, bottom to top. Above them come any overlays the slots' materials add (see How to Make a Material), then the item's own overlays. Overlays are never recoloured, and every item from this config shows its overlays whatever its materials.

Recipe

Each part ingredient matches that part made from any material. When the item is crafted, each slot takes the first part in the grid with its shape.

Stats

The item's stats are built from its slots: attribute modifiers and durability add up, then each durability-multiplier is applied. See How to Make a Material for what a slot can give. The item's own components and effects still apply on top.

Repairing

With repair-from set to a slot ID, the item can be repaired at an anvil with any item that counts as the material in that slot, including custom items such as ecoitems:cobalt_ingot. Each item repairs a quarter of the item's durability and costs one level, like a vanilla repair.

modular:
  repair-from: head # The slot whose material repairs the item.

It works alongside the item's own repair-items, see How to Make an Item. Leave both out and the item repairs only the vanilla way, for example through a repairable component.

Slot textures

A part is drawn with its own texture by default. When one part sits in a different place on different items, for example a handle that is longer on a hammer than on an axe, give the item its own texture for that slot. It is recoloured per material the same way, and drawn in that slot's place in layers:

modular:
  textures:
    handle: ecoitems:item/hammer/handle # Greyscale, recoloured per material.

A slot with no entry here uses its part's texture. Animated items use the part's states while pulled.

Animation

Bows and crossbows change their look while pulled. Set animation: bow or animation: crossbow on the modular item, and give each part a texture per state under states:

# In the part:
part:
  texture: ecoitems:item/part/bow_limb
  states:
    pulling_0: ecoitems:item/part/bow_limb_pulling_0
    pulling_1: ecoitems:item/part/bow_limb_pulling_1
    pulling_2: ecoitems:item/part/bow_limb_pulling_2

# In the modular item:
modular:
  animation: bow
  state-overlays: # Drawn on top in one state only, never recoloured.
    pulling_2:
      - ecoitems:item/arrow_nocked

A bow has the states pulling_0, pulling_1 and pulling_2. A crossbow also has arrow and rocket, for when it is loaded. A part with no texture for a state uses its texture. The thresholds match vanilla, and the item's base should be a bow or crossbow so it can be drawn.

Shields and tridents work the same way with animation: shield and animation: trident. A shield has the state blocking and a trident has throwing, both optional. Vanilla draws these two as 3D models, so EcoItems holds the flat item its own way: a shield at your side and up in front of you while blocking, and a trident over your shoulder while throwing. The shield's back faces you, so a 3D part such as a strap goes on the back, at z 8.5 and up. Use a shield or trident base so it can block or be thrown. A thrown trident looks like the vanilla one.

Swapping

With swappable: true, put the item in the left slot of an anvil and a part in the right. The part replaces the one in the first slot of its shape that has a different material, for swap-cost levels. The replaced part is used up, unless swap-returns-part: true, in which case it is given back once the new item is taken. If more than one part item has that shape, the one whose ID is the shape name is given back.

Internal placeholders

Lookups and /ecoitems give take materials as arguments: material:<id> for a part, and <slot>:<id> for each slot of a modular item.

Where to go next

• Materials: How to Make a Material for what each slot gives.

• Recipes: Workstation Recipes for anvil and smithing table recipes.

• The base item: How to Make an Item for the item's other fields.

• Defaults: the shipped examples live here.