Skip to content

entity template.yml

Jump to bottom
Valor edited this page Nov 9, 2025 · 1 revision

Entity Template

This document explains every top-level section in src/main/resources/entities/template.yml. Each section from the template file is split out and described with syntax notes and copy‑paste examples so you can create or edit rare entity definitions safely.

Click here to view the full template.yml file.

Overview

  • Purpose: Define a RareEntity (a configurable "rare" mob) — spawn weight, conditions, appearance, abilities, drops, and behavior.
  • Required: Only type is strictly required; other keys are optional.

Spawn weight & group

  • Controls how often this entity is chosen when the plugin decides to spawn a rare.
  • Keys:
    • weight: numeric weight used to choose between rares (relative probability).
    • spawn-group: the spawn-group name defined in config.yml (fallback is "default"). Example:
weight: 10
spawn-group: group1

Conditions

  • Set when and where the entity may spawn.
  • Keys:
    • select-new: boolean — if false, RareSpawns may try other rares when conditions fail.
    • biomes: list of biome ids (namespace:biomeId) allowed to spawn.
    • biome-blacklist: boolean — if true, treat biomes as a blacklist instead.
    • weather: CLEAR, RAIN, THUNDER
    • time: SUNRISE, DAY, SUNSET, NIGHT or custom numeric range '0-24000' Example:
conditions:
 select-new: true
 biomes:
  - 'minecraft:forest'
  - 'terralith:highlands'
 biome-blacklist: false
 weather: CLEAR
 time: DAY

Identity: name, name-visible, nameplate

  • name: logical name for the rare (informational).
  • name-visible: boolean — show the entity's vanilla name tag (not recommended with custom nameplate).
  • nameplate: rich display settings (text array, shadow, line width, billboard, scale, background, view-distance, offset). Example:
name: 'Dragon Slayer'
name-visible: false
nameplate:
 text:
  - 'Dragon Slayer'
  - 'line 2'
 text-shadow: true
 line-width: 0
 billboard: CENTER
 scale: 1.0
 background: false
 background-color: BLUE
 see-through: false
 view-distance: 60
 offset: 0, 1.5, 0

Type & Stats

  • type: REQUIRED — living entity type (e.g., ZOMBIE, SKELETON).
  • health: total max health (numeric).
  • effects: potion effects list (EFFECT:level). Example:
type: ZOMBIE
health: 2000
effects:
 - SPEED:1
 - FIRE_RESISTANCE:1

Items / Equipment

  • Provide equipment (can include custom items referenced by template names or nexo: / itemadder: / oraxen: prefixes if integrations are used).
  • Keys: items with slots: main-hand, off-hand, helmet, chestplate, leggings, boots Example:
items:
 main-hand: template
 off-hand: ''
 helmet: CARVED_PUMPKIN
 chestplate: IRON_CHESTPLATE
 leggings: ''
 boots: ''

Behavior flags (despawn, stuck, AI)

  • can-despawn: boolean, whether this rare can naturally despawn.
  • anti-stuck: boolean, auto-teleports to the target if stuck.
  • ai: enable vanilla AI.
  • hostile: treat passive creatures as hostile. Example:
can-despawn: false
anti-stuck: true
ai: true
hostile: true

Attributes & iframes

  • attributes: list of attribute changes (Bukkit Attribute enum).
  • iframes: number of ticks for invulnerability frames (damage cooldown). Example:
attributes:
 - SCALE:2
 - MOVEMENT_SPEED:0.05
iframes: 20

Spawn & death messages

  • spawn-message and death-message allow broadcasting a multi-line message with optional radius and sound.
  • message: array of text lines (supports color codes).
  • radius: broadcast radius (blocks).
  • sound: SOUND_KEY:volume:pitch. Example:
spawn-message:
  message:
    - '&8==========================================='
    - '&6The Dragon Slayer has risen!'
    - 'Slay him quickly for unfathomable treasure!'
    - '&8==========================================='
  radius: 100
  sound: ITEM_GOAT_HORN_SOUND_5:1.0:0.75

death-message:
 message:
  - '&8==========================================='
  - '&6The Dragon Slayer has fallen!'
  - 'The lands remain safe once more.'
 radius: 100
 sound: ITEM_GOAT_HORN_SOUND_0:1.0:0.9

Drop table

  • drop-table defines what the rare drops when killed.
  • real: boolean — whether to use the entity's real drop-table (true) or RareSpawns should drop items.
  • items: list of entries, supporting:
    • MATERIAL:amount
    • MATERIAL:amount:chance
    • MATERIAL:min-max:chance
    • template:1 or nexo:id:amount, itemadder:id:amount, oraxen:id:amount (if integrated) Example:
drop-table:
 real: true
 items:
  - template:1
  - DIAMOND:1:20
  - EMERALD:1-4:20

Abilities

  • abilities: list of ability names (optionally abilityName:cooldown seconds). If no cooldown is given, ability defaults apply. Example:
abilities:
 - template
 - fireBreath:30

Bossbar

  • Display a boss bar for the rare:
  • name, color (BarColor), style (BarStyle), distance (visibility distance). Example:
bossbar:
 name: '&6Dragon Slayer'
 color: BLUE
 style: SEGMENTED_20
 distance: 50

Misc / Common flags

  • A large set of common entity options. Key list and brief meaning:
    • aggro-range: detection radius
    • arrows-in-body, arrows-despawn-ticks
    • baby: boolean for baby variants
    • pick-up-items: whether entity can pick up items
    • collidable, gliding, invisible, leadable
    • underwater_breath: ticks of air underwater (20 ticks = 1s)
    • remove-when-far-away: boolean to despawn when far
    • swimming, riptiding, passenger (entity carried), fall-distance, fire-ticks, on-fire
    • glowing, gravity, use-portals, silent, visible-by-default
    • Slime-specific: slime-size, slime-split
    • Wolf / cat specifics: wolf-angry, wolf-type, cat-type Example:
ai: true
aggro-range: 20
arrows-in-body: 10
baby: false
pick-up-items: false
underwater_breath: 200
remove-when-far-away: false
on-fire: true
glowing: false

Species-specific keys

  • Several entity types have extra nested settings. Use them only where applicable.

Horse:

horse:
 color: WHITE
 style: BLACK_DOTS
 armor: DIAMOND_HORSE_ARMOR

Parrot:

parrot-type: RED

Rabbit:

rabbit-type: GOLD

Axolotl:

axolotl-type: CYAN

Tropical fish:

tropical-fish:
 color: GREEN
 pattern: DASHER
 pattern-color: BLACK

Panda:

panda:
 main-gene: LAZY
 hidden-gene: AGGRESSIVE

Slime:

slime-size: 2
slime-split: false

Wolf / Cat:

wolf-angry: true
wolf-type: BLACK
cat-type: JELLIE

Tameable

  • Configure how players can tame this entity (if naturally tameable).
  • Keys:
    • vanilla-tameable: boolean fallback
    • tameable.item: item required (material or custom)
    • tameable.chance: percent chance (integer)
    • tameable.fail-sound, fail-particle, tame-sound, tame-particle and amounts Example:
vanilla-tameable: false
tameable:
 item: NETHER_STAR
 chance: 10
 fail-sound: ENTITY_WOLF_GROWL:0.5:1.0
 fail-particle: SMOKE
 fail-particle-amount: 10
 tame-sound: ENTITY_WOLF_HOWL:0.5:1.0
 tame-particle: HEART
 tame-particle-amount: 10

Spellcaster

  • For Evoker / Illusioner-like entities.
  • spellcaster.spells is a list of spell enums (e.g., FANGS, BLINDNESS). Example:
spellcaster:
 spells:
  - FANGS
  - BLINDNESS

Immunities

  • immune-to — list of DamageCause enum values that the entity ignores. Example:
immune-to:
 - LAVA
 - DROWNING
 - FREEZE
 - HOT_FLOOR

Minimal example

weight: 10
spawn-group: group1

conditions:
 biomes:
  - 'minecraft:forest'
 time: DAY

name: 'Forest Warden'
type: ZOMBIE
health: 500
items:
 main-hand: IRON_SWORD
 helmet: IRON_HELMET
can-despawn: false
abilities:
 - template
drop-table:
 real: true
 items:
  - DIAMOND:1:10

Full example (combines many sections)

weight: 10
spawn-group: group1
conditions:
 select-new: true
 biomes:
  - 'minecraft:forest'
 weather: CLEAR
 time: DAY

name: 'Dragon Slayer'
type: ZOMBIE
health: 2000
effects:
 - SPEED:1
items:
 main-hand: template
 helmet: CARVED_PUMPKIN
can-despawn: false
anti-stuck: true
attributes:
 - SCALE:2
 - MOVEMENT_SPEED:0.05
iframes: 20

spawn-message:
  message:
    - '&6The Dragon Slayer has risen!'
  radius: 100
  sound: ITEM_GOAT_HORN_SOUND_5:1.0:0.75

drop-table:
 real: true
 items:
  - template:1
  - DIAMOND:1:20
  - EMERALD:1-4:20

abilities:
 - template

bossbar:
 name: '&6Dragon Slayer'
 color: BLUE
 style: SEGMENTED_20
 distance: 50

Testing & troubleshooting (non-dev)

  1. Save the entity file and restart or reload the plugin.
  2. Use RareSpawns commands or spawn the entity via in-game command (if the plugin exposes one).
  3. Check the server console for parsing, validation, or integration messages.
  4. If the entity misbehaves:
    • Verify the type is a valid living entity.
    • Check for typos in enum values (case-sensitive).
    • Reduce features (e.g., remove custom attributes) to isolate the problem.

Best practices

  • Keep entity files focused and documented with comments.
  • Use can-despawn: false for bosses to avoid accidental disappearance.
  • Test in a staging environment before enabling complex mechanics (attributes, huge health, spawn messages, or custom drops).
  • When referencing custom items (Nexo, ItemsAdder, Oraxen), use the proper prefix (e.g., nexo:, itemadder:, oraxen:) in equipment or drop tables and ensure those plugins are installed.
  • Back up your entity files before making major edits.

–]===========>

___⎛⎝ ≽ > ⩊ < ≼ ⎠⎞___"It's dangerous to go alone, take this."_____

🐲 RareSpawns Wiki

✅ Getting Started

⚙️ Configuration

🍳 Resources

🔌⚡ Supported Plugins (And why 🤔💭)

👑 Premium Features

</> For Developers

🔎 Tips

  • Use the search box above to quickly jump to a page.

Clone this wiki locally