TESSERA

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

KeyTypeDefaultNotes
materialmaterial namePAPERAny item material. An unknown name skips this item with a warning; the rest of the file still loads.
display_nameMiniMessagethe idUsed as the item name.
lorelist of MiniMessageemptyOne entry per line.
custom_model_datainteger0Applied only when greater than zero.
modelmodel idunsetModel the item is drawn with, such as shop:item/ruby. Tessera writes the item definition for it.
item_modelnamespace:idunset1.21.4+ item model component. With model, needs no custom model data.
unbreakablebooleanfalseSets the unbreakable flag.
max_stack_sizeintegerunsetApplied 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!"
KeyTriggerNotes
chanceboth0 to 1 for the whole trigger. Default 1.
cooldownbothSeconds, per player and per trigger. The item shows the cooldown overlay.
lifestealon_hitShare of the damage dealt that heals the attacker.
bonus_damageon_hitAdded to the hit.
lightningon_hitStrikes the target.
explosionbothpower, break_blocks, fire. The player is the source, so protection plugins apply.
effectsbothPotion 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.
soundbothA sound name, or name, volume, pitch.
particlesbothA particle name, or type, count, spread.
commandsbothRun as the player; [console] in front runs them from the console. %player% is replaced.
messagebothMiniMessage 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.