How to Make an Item

An EcoItem is a custom item defined in its own config file: you set its display, its components, its recipe, and the effects it runs while held or worn. This page takes you from an empty file to a working item you can give yourself in-game.

Quick start

1. Open the /plugins/EcoItems/items/ folder.

2. Copy _example.yml and rename it to your item's ID, e.g. mithril_sword.yml.

3. Edit the item: section to set the base item, display name, and lore.

4. Set the slot: and any effects: you want.

5. Run /ecoitems reload.

6. Give yourself the item with /ecoitems give <you> mithril_sword and confirm it appears with your display name and lore.

Naming and IDs

The file name without .yml is the item's ID. That ID is what you use in commands and in the Item Lookup System, so mithril_sword.yml has the ID mithril_sword.

The structure of an item

# === Item: what the player gets ===
item:
  item: iron_sword hide_attributes # The base item: https://hub.auxilor.io/wiki/eco/the-item-lookup-system-the-item-lookup-system
  name: "<g:#f953c6>Mithril Sword</g:#b91d73>" # The item name (the item_name component)
  lore: # The item lore, one entry per line
    - "&7Damage: &c12❤"
    - "&7Attack Speed: &c1.5"
    - ""
    - "<g:#f953c6>MITHRIL BONUS</g:#b91d73>"
    - "&8» &#f953c6Deal 50% more damage in the nether"
  components: # Optional; vanilla item components: https://minecraft.wiki/w/Data_component_format
    "minecraft:attribute_modifiers":
      - type: "minecraft:attack_damage"
        id: "ecoitems:damage"
        amount: 11
        operation: "add_value"
        slot: "mainhand"
  recipes: # How the item is made
    type: crafting_table # Optional; where it's made, defaults to crafting_table
    permission: ecoitems.craft.custom_item # Optional; permission required to craft the item
    shapeless: false # Optional; whether the recipe is shapeless, defaults to false
    give-amount: 1 # Optional; how many items the recipe gives, defaults to 1
    recipe: # The recipe: https://hub.auxilor.io/wiki/eco/the-item-lookup-system-the-item-lookup-system/recipes
      - ""
      - ecoitems:mithril 2
      - ""
      - ""
      - ecoitems:mithril 2
      - ""
      - ""
      - stick
      - ""

# === Behaviour: where it works ===
slot: mainhand # The slot the item must be in to activate; defaults to mainhand
rarity: rare # Optional; the item rarity from the rarities folder

# === Effects: what it does ===
effects:
  - id: damage_multiplier # The effect to run
    args:
      multiplier: 1.5
    triggers:
      - melee_attack # When the effect fires
conditions:
  - id: in_world # A condition that must hold for the effects to run
    args:
      world: world_the_nether

Item

The item: section defines the base item players receive and how it's crafted. The base item is an Item Lookup string, so modifiers like hide_attributes, glint, unbreakable, and max_damage:4096 all work inline.

Components

item.components lets you set any vanilla item component on the item, using the same structure as vanilla commands - see the Data component format for every component and its fields. This is how you set combat stats, food behaviour, tool rules, cooldowns, equippability, and anything else the game itself supports:

item:
  components:
    max_stack_size: 1
    use_cooldown:
      seconds: 2.5
    attribute_modifiers:
      - type: "minecraft:attack_damage"
        id: "ecoitems:damage"
        amount: 11 # On top of the player's base 1 damage, so 12 total
        operation: "add_value"
        slot: "mainhand"

Component keys without a namespace are treated as minecraft: components, so no quoting is needed; write "somemod:component" in quotes for anything namespaced. Invalid components are skipped with a warning in the console telling you what's wrong.

Texture (paid version)

Give the item a custom texture with item.texture, pointing at a .png under plugins/EcoItems/pack/assets/ecoitems/textures/item/ - the path is relative to textures/, without the extension. The resource pack is generated and delivered automatically - see Resource Packs.

item:
  texture: item/mithril_sword # pack/assets/ecoitems/textures/item/mithril_sword.png

Slot and rarity

slot accepts mainhand, offhand, hands, helmet, chestplate, leggings, boots, armor, any, a number from 0-40 for an exact slot, or a list like "9, 10, 11, mainhand". rarity is optional and references a rarity from the rarities/ folder.

Templates

Items that share most of their config can extend a template instead of repeating it. Any _-prefixed file under items/ is a template - it never loads as an item, and other items reference it by its file name without the underscore:

# items/_sword_base.yml
item:
  item: netherite_sword unbreaking:3 hide_enchants
  lore:
    - "&8A blade from the armory"
slot: mainhand
rarity: rare

# items/reaper.yml
template: sword_base
item:
  name: "&cReaper"
  texture: item/reaper

The item's own keys always win over the template's; nested sections merge key-by-key and lists are replaced whole. template: also accepts a list (later templates override earlier ones), and templates can themselves extend other templates.

Hiding items

exclude-from-gui: true hides an item from the /ecoitems gui browser, and exclude-from-commands: true hides it from tab-completion (giving it by exact id still works). Useful for internal items like quest rewards or crafting intermediates.

Furnace fuel

Items based on a vanilla fuel can override how long they burn:

fuel:
  burn-ticks: 3200   # 0 stops the item from being usable as fuel at all

Furnaces only consume items vanilla recognizes as fuel, so base the item on one (coal, blaze_rod, ...) and tune from there.

Effects

The effects: and conditions: sections are where the item gets its functionality: effects run on a trigger, and conditions gate when they're allowed to run.

effects:
  - id: damage_multiplier # The effect to run
    args:
      multiplier: 1.5
    triggers:
      - melee_attack # When the effect fires
conditions:
  - id: in_world # A condition that must hold for the effects to run
    args:
      world: world_the_nether

Where to go next

• Foods and tools: Custom Foods and Custom Tools add eating and mining behaviour to an item.

• Workstations: Workstation Recipes to craft the item at a furnace, anvil, stonecutter, and more.

• Rarities: Item Rarity for the rarity tags used by rarity:.

• Textures: Resource Packs for custom item textures and models (paid).

• Default configs: the shipped items live here, and you can find community items on lrcdb.