Skip to content

Metadata

Jump to bottom
OfficialRell edited this page Jun 20, 2026 · 8 revisions

Spawner Metadata

Metadata can be configured in metadata.yml file.

Spawner metadata is configured under two sections:

  • Item-spawners.values: metadata that can be applied to items only
  • Entity-spawners.values: metadata that can be applied to living entities

Item-spawners.default-value selects which item metadata is used when no item metadata is specified.

Item metadata

Item metadata entries are created under:

Item-spawners:
  default-value: <item metadata key>
  values:
    <item metadata key>:
      ...

Each key under Item-spawners.values is the item metadata ID.

Item metadata format

Item-spawners:
  default-value: <item metadata key>
  values:
    <item metadata key>:
      display:
        name: '<#ffff00>Custom Spawner'
        inside: <global item key>
      list:
        <global item key>:
          weight: 1
          amount: 1

Every option that uses <global item key> you must use an existing global item key (e.g. golden_nugget).

Item spawner default value

Item-spawners:
  default-value: <item metadata key>

This must match an existing key under Item-spawners.values.

If the configured value is invalid, the plugin falls back to its internal default metadata.

Item spawner configuration

Item-spawners:
  values:
    <item metadata key>:
      ...

<item metadata key> is the item metadata name used by the plugin.

Display name

display:
  name: '<#ffff00>Custom Spawner'

Optional

Sets the display name of the spawner.

You can use %type% placeholder to include the formatted spawner type.

If omitted or empty, default display name is used.

This can be used for both item and entity metadata.

Spawner inside display

display:
  inside: <global item key/spawner type>

Optional

Sets what is shown rotating inside the spawner.

There are 2 options:

  • a global item: shows an item
  • a valid spawner type: shows an entity

If omitted or invalid, no custom inside display is applied.

This can be used for both item and entity metadata.

Item metadata weighted item list

list:
  <global item key>:
    weight: 1
    amount: 1

Defines the drop pool for the item spawner.

Each key inside list must match an existing key from Global-items.

The list cannot be empty.

Item weight

weight: 1

Defines the weighted chance of this item being selected relative to the other entries in the same list.

This is read as an integer.

Item amount

amount: 1

or

amount: 1-3

Defines how many of that item are dropped when this entry is selected.

Accepted formats:

  • single number
  • numeric range

An amount of 0 is not allowed.

Global items

Item metadata uses entries from Global-items.

Global item format

Global-items:
  <global item key>:
    material: DIAMOND
    name: "<#00ffff>Custom Item"
    lore:
    - "<#808080>Line 1"
    - "<#808080>Line 2"
    enchantments:
      sharpness: 5
      unbreaking: 3
    model: 0

Global item configuration

Global-items:
  <global item key>:
    ...

Defines one reusable item entry.

Material

material: DIAMOND

Must be a valid Bukkit material name.

If invalid, the global item fails to load.

Name

name: "<#00ffff>Custom Item"

Optional

Sets the custom item name.

If omitted or empty, the item has no custom name.

Lore

lore:
- "<#808080>Line 1"
- "<#808080>Line 2"

Optional

Sets the item lore.

If omitted, the item has no lore.

Enchantments

enchantments:
  sharpness: 5
  unbreaking: 3

Optional

Adds enchantments to the item.

Rules:

  • the enchantment key must be valid
  • the level must be between 1 and 127

If an enchantment name or level is invalid, the global item fails to load.

Model data

model: 0

Optional

Sets the custom model data value.

If omitted, it defaults to the file’s numeric default.

Entity metadata

Entity metadata entries are created under:

Entity-spawners:
  values:
    <entity metadata key>:
      ...

Each key under Entity-spawners.values is a metadata ID.

Entity metadata format

Entity-spawners:
  values:
    <entity metadata key>:
      display:
        name: "<#ff0000>Custom %type%"
        inside: ZOMBIE
      applicable:
        list:
        - ZOMBIE
        - HUSK
        exclude: false
      traits:
      - trait: silent
        value: true

Entity spawner value configuration

Entity-spawners:
  values:
    <entity metadata key>:
      ...

Defines one entity metadata entry.

Applicable type list

applicable:
  list:
  - ZOMBIE
  - HUSK
  exclude: false

Optional

Defines to which spawner types this metadata can be applied.

Options:

  • list: List of spawner types used by the applicability filter
  • exclude:
    • false or omitted: only the listed types are allowed
    • true: the listed types are blocked, all others are allowed

If omitted, empty, or fully invalid, the metadata is treated as applicable to any type.

Entity traits

traits:
- trait: silent
  value: true
- trait: named
  ...

Defines trait operations that are applied to spawned entities.

Must be a list of trait entries.

Trait configuration

- trait: silent

The trait type.

Built-in values:

  • attribute
  • baby
  • invulnerable
  • named
  • silent
  • transform

Chance

chance: 25

Optional - Default: 100

Chance for the trait to attempt applying to each entity.

This is read as an integer percentage value.

Limit

limit: 2

Optional - Default: unlimited

Maximum number of successful applications for that trait during one execution.

Limit options:

  • 0: unlimited
  • positive n: applies the trait until it reaches n (limit: 5)
  • negative n: applies the trait until there are n entities left (limit: -3)

The limit is checked against successful applications, not just attempts.

Chained traits

then:
  trigger: success
  traits:
    - trait: silent
      value: true

Optional

Defines chained traits that run after the parent trait.

The child traits only run on entities selected by the trigger.

Chained trait trigger

then:
  trigger: success

Optional - Default: always

Controls which entities from the parent trait are passed into the chained traits.

Trigger values:

  • always: every processed entity
  • success: only entities where the parent trait succeeded
  • fail: only entities where the parent trait failed
  • index:<n>: only the entity at that exact index
  • after:<n>: only entities after that index
  • before:<n>: only entities before that index
  • every:<n>: every second entity by index rule used by the plugin

<n> starts at 0

Chained trait list

then:
  traits:
  - trait: silent
    value: true

List of child traits to run when the trigger matches.

If this list is empty or invalid, the chain is ignored.

List of all traits and their configuration

Trait - attribute

traits:
- trait: attribute
  attribute: scale
  value: '*0.5'

Changes one attribute on the spawned entity.

Options

attribute: scale

The attribute to modify.

List of all attributes:

  • armor
  • armor_toughness
  • damage or attack_damage
  • attack_knockback
  • attack_speed
  • block_break_speed
  • block_interaction_range
  • burning_time
  • camera_distance
  • entity_interaction_range
  • explosion_knockback_resistance
  • fall_damage_multiplier
  • flying_speed
  • follow_range
  • gravity
  • jump_strength
  • knockback_resistance
  • luck
  • absorption or max_absorption
  • health or max_health
  • mining_efficiency
  • movement_efficiency
  • movement_speed
  • oxygen_bonus
  • safe_fall_distance
  • scale
  • sneaking_speed
  • spawn_reinforcements
  • step_height
  • submerged_mining_speed
  • sweeping_damage_ratio
  • tempt_range
  • water_movement_efficiency
  • waypoint_receive_range
  • waypoint_transmit_range

If the attribute is invalid, the trait fails to load.

value: '*0.5'

The shift operation applied to the current attribute value.

All shift values:

  • n: sets n as the base value
  • +n: adds n to the base value
  • -n: subtracts n from the base value
  • *n: multiplies the base value by n
  • /n: divides the base value by n

If invalid, the trait fails to load.

Notes

  • This only succeeds on entities that support the selected attribute.
  • When changing health, the plugin also updates the entity’s current health to match the new base value, with a minimum of 0.01.

Trait - baby

traits:
- trait: baby
  value: true

Makes an entity baby or adult.

Optional - Default: false

Options

value: true
  • true: set as baby
  • false: set as adult

Notes

  • This only succeeds on ageable entities.
  • On unsupported entities, the trait runs but does not succeed.

Trait - effect

traits:
- trait: effect
  potion: speed
  duration: 200
  amplifier: 2
  ambient: false
  particles: true
  icon: false

Applies a potion effect to the spawned entity.

Options

potion: speed

Potion effect to apply.

List of all potion effects:

  • speed
  • slowness
  • haste
  • mining_fatigue
  • strength
  • instant_health
  • instant_damage
  • jump_boost
  • nausea
  • regeneration
  • resistance
  • fire_resistance
  • water_breathing
  • invisibility
  • blindness
  • night_vision
  • hunger
  • weakness
  • poison
  • wither
  • health_boost
  • absorption
  • saturation
  • glowing
  • levitation
  • luck
  • unluck
  • slow_falling
  • conduit_power
  • dolphins_grace
  • bad_omen
  • hero_of_the_village
  • darkness
  • trial_omen
  • raid_omen
  • wind_charged
  • weaving
  • oozing
  • infested
  • breath_of_the_nautilus
duration: 200

Effect duration in ticks.

Optional - Default: 100

amplifier: 2

Strength of the effect. Starts at 1.

Optional - Default: 1

ambient: false

Whether the effect is ambient.

Optional - Default: false

particles: true

Whether the effect omits particles.

Optional - Default: true

icon: false

Whether the effect shows an icon.

Optional - Default: true

Trait - invulnerable

traits:
- trait: invulnerable
  value: true

Sets whether the entity is invulnerable.

Options

value: true
  • true: invulnerable
  • false: vulnerable

Optional - Default: false

Trait - named

traits:
- trait: named
  name: "<#ff0000>Elite %type%"
  visible: true

Sets the entity custom name.

Options

name: "<ff0000>Elite %type%"

The name applied to the entity.

You can use %type% placeholder to include the formatted spawner type.

visible: true

Controls whether the custom name is visible.

  • true: always visible
  • false: hidden unless the player is looking at it

Optional - Default: false

Trait - silent

traits:
- trait: silent
  value: true

Sets whether the entity is silent.

Options

value: true
  • true: silent
  • false: not silent

Optional - Default: false

Trait - transform

traits:
- trait: transform
  to: WITHER_SKELETON

Replaces the spawned entity with a new entity of another spawner type.

Options

to: WITHER_SKELETON

The spawner type to transform into.

If invalid, the trait fails to load.

Example trait configuration

traits:
- trait: transform
  to: WITHER_SKELETON
  chance: 25
  limit: 2
  then:
    trigger: success
    traits:
    - trait: attribute
      attribute: scale
      value: '*0.5'
    - trait: silent
      value: true

Explanation: When an entity spawns it has a 25% chance to be transformed into a Wither Skeleton and scaled half its size and set silent.

Clone this wiki locally