Create custom items

Dungeon items are YAML. IDs must be unique across loaded files.

Import YAML, edit, then export. The library stays in this browser; keep a file backup.

Private browser workspace

Item Workbench

Import definitions, tune their numbers, and take valid YAML back out.

New itemImport YAMLExport library

Search local items

0 itemsSaved on this device

No local items yet.

Start a definition or drop a YAML file anywhere in the workbench.

✦

Build against the shipped item roster

Your definitions stay in this browser. Import an existing file or start with a valid template.

Create an itemChoose YAML files

A minimal item

custom_ember_blade:
  name: "Ember Blade"
  rarity: rare
  level: 18
  class: sword
  model: minecraft:blaze_rod
  source: "Custom"
  durability: 900
  stats:
    attack_speed: {base: -2.5, rolls: false, label: "attack speed"}
    damage: 16

class sets behaviour and stat scope. model sets appearance.

The fields

Field	What to set
name	Display name. Plain text inherits the rarity colour; MiniMessage formatting also works.
rarity	uncommon, rare, epic, legendary, set, or the off-ladder cosmetic rarity.
level	Whole-number player level required to use the item. Gear must set it explicitly; zero is valid.
class	One of the parser classes listed below. There is no safe default.
model	An item-model resource key such as minecraft:iron_helmet.
material	Optional base Minecraft material; otherwise inferred from the class or model.
source	Boss, set, shop, or other origin printed on the tooltip.
durability	Legacy maximum-damage metadata. Dungeon gear is unbreakable; damageable definitions stack to one.
stack	Stack limit from 1 to 99 when the item has no durability or rolling stats.
major_id	A Major ID already implemented by the plugin. YAML cannot create new behaviour.
flavour	A string or list of lore lines.
glint / sheen	Vanilla glint and the optional Dungeon sheen treatment.
stats	Stat ids and their authored bases. See below.
class_share	Ranged weapon pricing share, above 0 and at most 2; bows, shortbows, crossbows, and tridents only.
crossbow.reload_seconds	Crossbow reload timing; requires class_share.

The supported classes are sword, dagger, axe, mace, trident, spear, scythe, bow, shortbow, crossbow, staff, wand, shield, torch, helmet, chestplate, leggings, boots, ring, necklace, currency, and consumable. trinket is not a class; locker accessories are rings and necklaces.

Armour supports trim, dye, and equip. Shields use blocks; consumables use consumable, potion, and either healing or utility. Spears require spear.preset, with optional jab-cooldown, charge-delay, and lunge. Tridents can set trident.damage as a multiple of a melee hit. Shortbows can set shortbow.shots_per_second.

See the plugin’s items/_example.yml for the full format.

Levels are direct

Write the exact requirement the tooltip and use check should enforce:

level: 42

There is no derived requirement ladder. Gear needs an explicit level; cosmetics normally use 0. Omitted levels mean no requirement.

Stats and rolls

The short form is a number:

stats:
  damage: 16

The long form controls the exceptional cases:

stats:
  damage:
    base: 16
    rolls: true
    label: damage

Key	Meaning
base	The one authored number. It cannot be zero.
rolls	Uncommon stats default to fixed; uncommon weapons are always fixed. Other rarities default to rolling. false fixes a line.
label	Tooltip wording. Defaults to the stat id with underscores opened into spaces.
attribute	Attribute override. none means the plugin reads the stored number itself.
op	add by default; multiply for a fractional multiplier such as damage_percent.
slot	Override where the modifier applies. Normally inferred from the class.
decimals	Stored and displayed precision. Normally inferred from the stat.
harmful	Override whether a larger value is worse. Negative bases normally count as harmful; spell-cost increases are harmful and discounts are beneficial.
stars	Allow or prevent star scaling. Benefits default to scaling; costs do not.
role	Optional mechanic or flavour classification for authoring checks.

Roll bands define variance. Uncommon weapons are fixed; other uncommon items can opt into rolls. Damage, health, defense, skill points, and other whole stats are snapped to integers with decimals: 0. Use whole authored bases for those stats.

Stars scale eligible benefits; use stars: false to opt out. Harmful stats do not grow by default.

Ranged weapon settings

Match shipped definitions at nearby levels. Current authored class_share values are bow 0.75, shortbow 0.65, crossbow 0.65, and trident 0.9.

class_share: 0.65
crossbow:
  reload_seconds: 1.25

Crossbow reloads use 0.25-second steps below 1.25 seconds; shorter timings add hidden Quick Charge. Without authored timing, the legacy reload is 0.75 seconds. Missing pricing shares fall back to bow/crossbow 0.65, shortbow 0.55, and trident 0.9.

The parser raises authored draw_damage by 25% for bows, shortbows, and crossbows, then rounds to the stat’s precision. Spell and Major ID budgets divide that increase back out.

Balance armour

Compare the same slot, rarity, and level. Consider health, defense, agility, and utility together.

Before loading

• Export a file backup.
• Resolve errors and review warnings.
• Keep rolling items unstacked.
• Use dungeon stats, not vanilla enchantments.
• Run /da roll lint against the loaded definitions and run the plugin item tests before publishing.