content 01
Items
Every .yml file in items/ is loaded, including files in subfolders. Each top-level key is one
item id. A file can hold as many items as you like.
Keys
| Key | Type | Default | Notes |
|---|---|---|---|
material | material name | PAPER | Any item material. An unknown name skips this item with a warning; the rest of the file still loads. |
display_name | MiniMessage | the id | Used as the item name. |
lore | list of MiniMessage | empty | One entry per line. |
custom_model_data | integer | 0 | Applied only when greater than zero. |
model | model id | unset | Model the item is drawn with, such as shop:item/ruby. Tessera writes the item definition for it. |
item_model | namespace:id | unset | 1.21.4+ item model component. With model, needs no custom model data. |
unbreakable | boolean | false | Sets the unbreakable flag. |
max_stack_size | integer | unset | Applied only when greater than zero. |
There are no other item keys. See Not implemented below before copying examples out of the config comments.
Example
# plugins/Tessera/items/ruby.yml
ruby:
material: EMERALD
display_name: "<gradient:#ff416c:#ff4b2b><bold>Ruby</bold></gradient>"
lore:
- "<gray>A precious crimson gemstone"
- "<dark_gray>Common Material"
custom_model_data: 10001
max_stack_size: 64
ruby_sword:
material: DIAMOND_SWORD
display_name: "<gradient:#ff416c:#ff4b2b><bold>Ruby Sword</bold></gradient>"
lore:
- "<gray>Forged from crystallized ruby"
- "<red>+10 Attack Damage"
custom_model_data: 10002
unbreakable: true
That file ships with the plugin.
Ids
The id is the key, ruby above. It is what you type in commands, what a recipe refers to as
tessera:ruby, and what a block drop table refers to. Ids are stored in the item's
PersistentDataContainer when the stack is built, so the plugin can recognise the item later even
after it has been moved between inventories.
/tessera get ruby 16
/tessera give Steve ruby_sword
/tessera inspect # shows the stored id of the held item
Text formatting
display_name and lore are MiniMessage. Glyphs are substituted before parsing, so :ruby: and
<glyph:ruby> both work inside item text. See Glyphs and HUD.
Models
Since 1.21.4 the client picks an item's model from an item definition,
assets/<namespace>/items/<name>.json, and ignores overrides in item models. Tessera writes those
definitions for you. There are two ways to give an item a model:
# 1. item_model: one definition per item, no numbers to keep track of
ruby_wand:
material: STICK
item_model: shop:ruby_wand # writes assets/shop/items/ruby_wand.json
model: shop:item/ruby_wand # assets/shop/models/item/ruby_wand.json
# 2. custom_model_data: needed for items that already exist with a number
ruby:
material: EMERALD
custom_model_data: 10001
model: shop:item/ruby
With custom_model_data, every item of one material shares one definition: Tessera writes
assets/minecraft/items/<material>.json as a range_dispatch on custom model data, with the
material's previous definition as the fallback. When the items go, the previous definition is put
back.
model without a namespace means minecraft:. Put the model and its textures into
plugins/Tessera/pack/assets/. If they are missing, the pack check on the next reload says so; see
Resource pack. An item_model in the minecraft namespace that
names a vanilla item is refused, because it would replace that item for everyone.
Mechanics
An item does things when it hits or is right-clicked:
thunder_blade:
material: DIAMOND_SWORD
mechanics:
on_hit:
chance: 0.3
cooldown: 2
lifesteal: 0.15
bonus_damage: 4
lightning: true
explosion: { power: 1.5, break_blocks: false, fire: false }
effects:
- { type: SLOWNESS, duration: 3, amplifier: 1, chance: 0.5 }
sound: { name: entity.warden.sonic_boom, volume: 1, pitch: 1 }
particles: { type: ELECTRIC_SPARK, count: 20, spread: 0.4 }
on_click:
cooldown: 10
effects: [ { type: SPEED, duration: 10, amplifier: 1 } ]
commands: [ "say %player% used the blade", "[console] give %player% diamond 1" ]
message: "<aqua>Woosh!"
| Key | Trigger | Notes |
|---|---|---|
chance | both | 0 to 1 for the whole trigger. Default 1. |
cooldown | both | Seconds, per player and per trigger. The item shows the cooldown overlay. |
lifesteal | on_hit | Share of the damage dealt that heals the attacker. |
bonus_damage | on_hit | Added to the hit. |
lightning | on_hit | Strikes the target. |
explosion | both | power, break_blocks, fire. The player is the source, so protection plugins apply. |
effects | both | Potion effects: type, duration in seconds, amplifier, chance, target (target or self). on_hit effects go to the target by default, on_click effects to the player. |
sound | both | A sound name, or name, volume, pitch. |
particles | both | A particle name, or type, count, spread. |
commands | both | Run as the player; [console] in front runs them from the console. %player% is replaced. |
message | both | MiniMessage sent to the player. |
A right-click that runs a mechanic does not also eat, place or use the item. The list form
- type: lifesteal with heal_percent (and poison, thunder, explosive) is read as on_hit.
Not implemented
max_durability, food, stat modifiers such as attack speed or armour toughness, rarity and mana
appear in config comments only. The parser ignores them.