Item Configuration

Declare items — blocks, tools, weapons, armor, ammo, and more — in your mod's item catalog.

Every item in the game — blocks, tools, weapons, armor, ammo, and more — is declared as an entry in your mod’s item catalog. This is the file that gives an item its name, its stacking behavior, and its type, which determines what it actually does when used.

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

item-config: item-config.yaml

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/item-config.yaml

The file is a single list of item entries:

items:
  - name: my_item
    type: item
  - name: my_sword
    type: weapon
    weapon-info:
      type: short_sword
      damage: 10.0

Item names are automatically prefixed with your mod name unless you write one already containing a colon, so my_item becomes YourMod:my_item — this is the full name used anywhere an item is referenced (crafting recipes, loot tables, mob drops, Lua scripts).

Minimal Example

items:
  - name: wooden_stick
    type: item

type: Item (or type: Empty) declares a plain item with no special behavior — just something that exists and can be held, stacked, and crafted with.

Blocks and interactables don’t need an entry here. Declaring a block in block-config.yaml (or an interactable in interactable-config.yaml) automatically registers a matching type: block / type: interactable item. Add an entry here only to give it more than the defaults — a display-name, tooltip, material-types, or light — and your entry replaces the generated one.

Common Fields

Every item entry supports these, regardless of type:

Unknown keys at the top level of an entry (and inside tool-info) are rejected: a misspelled or misplaced field is a load-time error naming the bad key, not a silently-ignored one — so a typo can’t quietly leave your item without its tooltip. Note in particular that power-level and mining-speed belong inside tool-info; writing them at the top level is an error. The nested light and wielded-item-data blocks are validated too — an unrecognized key inside them is a load-time error, not a silently-ignored one (a bad key in wielded-item-data, like a wrong-typed block, makes it fall back to all-defaults). See Unknown Fields.

Item Types

type selects the item’s behavior. Each (aside from item/empty, block, and interactable) requires a matching *-info block with its own fields.

The value is case-insensitive, and the two-word types accept either separator — projectile-launcher and projectile_launcher are the same value, so the type can be written the same way as the *-info key beside it.

tool-info

tool-info:
  power-level: 2      # optional, default 1. Must meet or exceed a block/object's required power to break it.
  mining-speed: 1.0    # optional, default 1.0. Multiplies how fast blocks/objects take damage.

weapon-info

weapon-info:
  type: short_sword   # required. Currently the only weapon type.
  damage: 10.0               # required
  hit-cooldown-ms: 250        # optional, default 300. Minimum time between this weapon's hits landing on the same target.
  knockback: 20.0             # optional, default 0 (none). Shoves the target away from the wielder on a landed hit.

hit-cooldown-ms sets the per-target invulnerability window this weapon grants on a landed hit — a fast dagger can use a low value, a heavy hammer a high one. Keep it below the weapon’s swing animation time, or alternate swings will silently deal no damage (each swing already hits a given target at most once regardless of this setting).

knockback shoves the target away from the wielder (in the direction the wielder is facing) and lifts it a little on a hit that actually lands — a blocked, invulnerable-deflected, or invincibility-framed hit imparts no force. It is a velocity magnitude in blocks/second that briefly overrides the target’s own movement and decays over a fraction of a second, so it reads as a distinct knock: a light dagger might use a small value, a heavy hammer a large one. A struck mob is knocked clear of whatever it was doing (it stops pathing toward you and gets flung in a short arc), then resumes. 0 (the default) leaves the target where it stands.

armor-info

armor-info:
  armor-type: helmet    # required: Helmet, Chestplate, Leggings, or Boots (case-insensitive)
  flat-armor: 1.0        # optional, default 0.0. Flat damage reduction.
  percent-armor: 8.0     # optional, default 0.0. Percentage damage reduction.

armor-type is what decides the equipment slot — do not also set itemstack-slot-types on an armor item. Declaring both is a load-time error, because the two could disagree. Previously armor-type was cosmetic (it only fed the tooltip) and itemstack-slot-types did the real work, so every armor item had to write the same value twice: forgetting the second one produced a helmet equippable into every armor slot, and setting them differently produced a piece that equipped into one slot while its tooltip named another. There is now a single source of truth.

projectile-launcher-info

projectile-launcher-info:
  ammo-types:                 # a string or a list; at least one of ammo-types/ammo-names is required
    - Arrow
  fire-cooldown-ms: 1000          # optional, default 100
  launch-velocity: 100.0        # optional, default 50.0

• ammo-types matches against an ammo item’s ammo-type (see below) — use this for “anything tagged Arrow.” The plural/singular pairing is the schema’s usual one: the plural key is the set of tags accepted, the singular key is the one tag that item carries, exactly as material-types pairs with a recipe’s material-type.
• ammo-names matches specific item names instead, if you want a launcher restricted to exact ammo items.

ammo-info

ammo-info:
  ammo-type: arrow          # required. Matched against a launcher's ammo-types.
  projectile: wooden_arrow   # required. The projectile-config.yaml projectile fired when this ammo is used.
  damage: 5.0                 # optional. Overrides the projectile's own configured damage for this ammo.
  gravity-multiplier: 1.0      # optional. Overrides the projectile's own configured gravity-multiplier.

summon-info

summon-info:
  mob-to-summon: glorbo   # required. The mob-config.yaml entry to spawn.

mob-to-summon accepts a bare mob name (shown above) — the common case. It also accepts a block form when you want to override the summoned mob’s presentation:

summon-info:
  mob-to-summon:
    name: glorbo            # required. The mob-config.yaml entry to spawn.
    display-name: Glorbo    # optional. Overrides the mob's display name.
    hitbox: {width: 1.0, height: 1.0}         # optional. Overrides the mob's hitbox.
    damage-hitbox: {width: 1.0, height: 1.0}  # optional. Overrides the mob's damage hitbox.

summon-mount-info

summon-mount-info:
  mount-to-summon: my_mount   # required. The mount to spawn.

Display Name

name is an identifier. It’s the key that crafting recipes, loot tables, block drop tables, structure spawns and Lua all use to find the item, so changing it breaks every one of those references. display-name is what players actually read:

items:
  - name: wooden_stick          # the identifier — referenced everywhere, never changes
    type: item
    display-name: Sturdy Branch  # what the player sees
    tooltip: Snapped from a young oak. Good for handles.

Hovering that item shows Sturdy Branch as the tooltip’s title, (YourMod) beneath it, then the tooltip text.

Omit display-name and the tooltip falls back to the identifier with the mod prefix stripped — Creation:wooden_stick shows as wooden_stick. That’s what the UI did before this field existed, so adding it to the engine changed nothing for existing mods; you opt in per item.

A few consequences worth knowing:

• Renaming for presentation is now free. Change display-name as often as you like; recipes referencing wooden_stick keep working. Never rename name for cosmetic reasons.
• It is client-only. The server never reads it, so it doesn’t need to match between client and server, and it isn’t sent over the network.
• It doesn’t have to be unique. Two items may share a display name (a “Torch” from two mods, say) — they stay distinct because their identifiers differ.
• Long names wrap to the tooltip width rather than overflowing, so a descriptive name is fine.

Blocks don’t have their own display-name. A placeable block is registered as an item under the same Mod:name, and a block only ever shows its name while it’s in your inventory as that item — so setting display-name on the item covers the block too.

Tool Types

tool-types is the categories an item counts as, independent of its type. A pickaxe with type: Tool still needs tool-types: pickaxe to actually be recognized as a pickaxe by blocks that require one. Accepts a single value or a list, the same shape a block’s tool-break-types uses.

Tool categories are an open registry — invent your own. Any tag is a valid category, the same way a crafting station’s type or an item’s material-types works. tool-types: hammer on your item plus tool-break-types: hammer on your block is all a new tool category takes; no engine change, no fixed list. Matching is case-insensitive.

The categories the base game ships with, which you’d reuse rather than reinvent:

A typo fails closed, not open. Because the registry is open, tool-break-types: pickaxee is not a load error — it’s a category, just one no item declares, so the block becomes breakable by nothing. That is the safe direction (it used to resolve to “no tool requirement”, leaving a pickaxe-only block breakable by hand), and the server warns at load naming the object and the unmatched category, so you find it at startup rather than in game.

tool-types: pickaxe        # single category
# or
tool-types: [shears, axe]  # several

Slot Types

itemstack-slot-types restricts which equipment slot(s) an item can be placed in. Accepts a single string or a list, and the values are a closed set — an unrecognized one fails the entry at load rather than being ignored, since a dropped value would silently leave the item unable to enter any restricted slot.

itemstack-slot-types: helmet
# or
itemstack-slot-types: [helmet, chestplate]

Not for armor. An Armor-type item takes its slot from armor-info.armor-type and must not declare itemstack-slot-types — doing so is a load-time error. This field is for non-armor items you want restricted to an equipment slot.

Light

Makes dropped copies of this item — the ones lying on the ground, not the item in an inventory or in a player’s hand — emit light:

light:
  magnitude: 8.0
  intensity: 1.0
  color: { r: 1.0, g: 0.945, b: 0.4627, a: 0.5 }
  drop-off-distance: 3.0
  is-static: false

This is the shared light: block, identical here to the one on blocks, interactables and particles — see Shared Blocks → light for every field, its default, and how magnitude, intensity and drop-off-distance combine into the falloff curve.

One item-specific note: leave is-static at its false default. A dropped item can be kicked around, and a static light is baked at the position it was created, so a moving item with is-static: true leaves its light behind.

Wielded Item Data

Controls how the item is positioned and animated in a player’s hand:

wielded-item-data:
  x-offset: 2.0
  y-offset: 1.0
  hitbox:                        # optional — the swing's hit area (default 1x1)
    width: 2.0
    height: 1.0
  primary-use-animation:
    - towards-cursor: true       # this frame lunges the item toward the cursor
      position-offset: 3.0
      time-ms: 400

hitbox ({ width, height } in blocks) is the area the item sweeps for melee hit detection — an entity is hit when this box, positioned at the item during its swing, overlaps the target’s damage hitbox. Omitting it defaults to a 1×1 box. Larger or wider weapons (and big boss claws) want a larger hitbox.

Each entry in primary-use-animation is one animation frame, played in sequence, with time-ms as its duration. Two kinds of frame are supported:

• towards-cursor: true — moves the item toward wherever the player is aiming, by position-offset blocks.
• Expression-based (used when towards-cursor is absent or false) — x-expression/y-expression are math expressions (can reference animation_time_s) evaluated each frame to compute the offset, with an optional align-rotation-to-user: true to rotate the item to face the player’s aim.

primary-use-animation:
  - x-expression: -1.5 * cos(6.0 * animation_time_s + 1.570796)
    y-expression: 2.0 * sin(6.0 * animation_time_s + 1.570796)
    align-rotation-to-user: true
    time-ms: 500

Primary Use Function

Runs a Lua handler when a player primary-uses (left-clicks with) this item. Declare it under the item’s scripts: map, keyed by server-on-primary-use, with the bare path to a .lua file:

scripts:
  server-on-primary-use: /items/sword_use.lua

The path is relative to your mod’s folder, and the file must return its handler function:

-- /items/sword_use.lua
return function(entity, x, y)
    entity:animate("SWING", false)
end

Complete Example

items:
  - name: wooden_pickaxe
    type: tool
    tool-types:
      - Pickaxe
    tool-info:
      power-level: 2
    interact-range: 10
    wielded-item-data:
      x-offset: 2.0
      y-offset: 1.0

  - name: wooden_short_sword
    type: weapon
    weapon-info:
      type: short_sword
      damage: 0.5
    wielded-item-data:
      x-offset: 2.0
      y-offset: 1.0
      primary-use-animation:
        - towards-cursor: true
          position-offset: 3.0
          time-ms: 400
    scripts:
      server-on-primary-use: /items/sword_use.lua

  - name: wooden_helmet
    type: armor
    stackable: false
    armor-info:
      armor-type: helmet
      flat-armor: 1.0
      percent-armor: 8.0
    itemstack-slot-types: helmet

  - name: wooden_bow
    type: projectile_launcher
    projectile-launcher-info:
      ammo-types:
        - Arrow
      fire-cooldown-ms: 1000
      launch-velocity: 100.0

  - name: wooden_arrow
    type: ammo
    ammo-info:
      ammo-type: arrow
      projectile: wooden_arrow

  - name: glow_rock
    type: block
    light:
      magnitude: 8.0
      color: { r: 1.0, g: 0.945, b: 0.4627, a: 0.5 }
      drop-off-distance: 3.0