Mob reference

A mob is a vanilla base type with overrides. Bestiary does not register new entity types: that is a registry-level NMS commitment which breaks on every Minecraft release, and buys almost nothing the Goal API and display entities cannot fake.

Under mobs/, the first directory is the namespace, so mobs/aether/valkyrie_champion.yml defines aether:valkyrie_champion. One file may hold any number of mobs, keyed by id.

example_boss:
  type: ravager
  display: "<gradient:#e8d9a0:#c9a227>Example Champion</gradient>"
  health: 200
  damage: 10
  armor: 8
  knockback_resistance: 1.0
  movement_speed: 0.28
  follow_range: 40

type is the only required key. Every attribute left out keeps the vanilla value for that entity type rather than being forced to a default.

Identity and attributes

typeentity typerequired: The vanilla base, e.g. ravager, stray, wither_skeleton. Resolved through the registry rather than an enum constant, so types that moved between versions still work.
displayMiniMessage: The name shown. Gradients, colours and any other MiniMessage tag survive, and a bracketed token in a namespace Bestiary does not own is left exactly as written.
healthnumber: Maximum health. Also sets current health on spawn.
damagenumber: Melee attack damage.
armornumber: Armour points.
armor_toughnessnumber: Armour toughness.
knockback_resistancenumber: 0.0 to 1.0. 1.0 is immovable.
movement_speednumber: Base movement speed. Vanilla values are small, and a zombie is 0.23.
follow_rangenumber: How far the mob will track a target.
scalenumber: Entity scale. Needs a server new enough to have the attribute; gated and reported otherwise.
levelnumberdefault 1: The level a mob spawns at when none is given. Readable in expressions as <caster.level>.
level_modifierstring: How attributes scale with level.
factionstring: Mobs sharing a faction do not target each other.
modelstring: A ModelEngine model id. A no-op with one report line when ModelEngine is absent, since Bestiary does not do models itself.
dropsdrop table id: The table rolled on death. drop_table is accepted as an alias.
suppress_external_xpbooleandefault false: Suppresses mcMMO and Jobs XP for this mob. A 400 HP boss otherwise distorts both economies. The server-wide defaults in config.yml are on.

`options`

Per-mob switches that are not attributes.

despawnbooleandefault false: Maps to PersistenceRequired. The default is the right one: a custom mob that vanishes because a player walked 40 blocks away is never what was wanted.
prevent_other_dropsbooleandefault true: Suppresses the vanilla drops of the base type, so a custom ravager does not also drop saddles.
prevent_mob_kill_dropsbooleandefault false: Drops nothing when killed by something other than a player.
prevent_random_equipmentbooleandefault true: Stops vanilla handing the mob random armour on spawn.
prevent_sunburnbooleandefault true: Undead do not burn in daylight.
dig_out_of_groundbooleandefault true: Lifts a mob spawned inside terrain to the surface instead of leaving it suffocating.
silentbooleandefault false: Suppresses the entity's own sounds. Sounds a skill plays still fire.
collidablebooleandefault true: Whether players and mobs push it.
always_show_namebooleandefault false: Shows display without needing to look at the mob.
glowingbooleandefault false: The outline seen through walls.
invulnerablebooleandefault false: Immune to everything. Use damage_modifiers for anything finer.
gravitybooleandefault true: false for something that should hover without a flying navigation.
aibooleandefault true: false disables vanilla AI entirely. Scripted movement mechanics still work.

`equipment`

Slots accept an item id directly, or a map with a drop chance.

equipment:
  head: diamond_helmet
  mainhand: { item: netherite_axe, drop_chance: 0.05 }
  offhand: shield

Slot names accept both spellings: head/helmet, chest/chestplate, legs/leggings, feet/boots, mainhand/hand/weapon, and offhand. drop_chance defaults to 0.

`threat`

An explicit threat table, off unless the section is present.

threat: { enabled: true, decay: 0.05 }

enabledbooleandefault true: When the section exists at all.
decaynumberdefault 0: Threat lost per second.
damage_factornumberdefault 1.0: Threat per point of damage dealt.
healing_factornumberdefault 0.5: Threat per point healed, so healers are targetable without being top of the list immediately.
switch_thresholdnumberdefault 1.5: How far ahead a new contender must be before the mob switches. Without it a boss flickers between two players of near-equal threat.

`phases`

An ordered list. A mob advances when the current phase's until conditions pass, and never goes back.

phases:
  - name: ground
    until: { health_percent: "<= 60" }
  - name: enraged
    on_enter: example_enrage

namestringrequired: Matched by ?phase{(is = ground)} and by the ~onPhase trigger.
untilmap or condition list: What advances past this phase. The map form is shorthand: each key becomes a condition and its value is offered as both amount and is, so numeric and string conditions both find it.
on_enterskill id: Cast once on entering.
on_exitskill id: Cast once on leaving.
bossbar_titleMiniMessage: Replaces the bossbar title while in this phase.

`skills`

The mob's own skill lines. These are the only place triggers are read: a skill file defines what happens, a mob file decides when.

skills:
  - skill{s=example_shockwave} ~onTimer:160 ?phase{is=ground}
  - skill{s=example_scaled_bolt} ~onTimer:100 ?phase{is=enraged}
  - skill{s=example_enrage} ~onHealthThreshold:25

Both definition forms work here too; see Skills for the full grammar and the trigger list.

`bossbar`

bossbar:
  title: "<gold>Example Champion <gray>- <white><caster.hp.percent>%"
  color: yellow
  style: segmented_10
  range: 48

enabledbooleandefault true: Set false to keep the settings but hide the bar.
titleMiniMessage: Expressions are resolved live, so <caster.hp.percent> tracks.
colorstringdefault white: colour is accepted too.
stylestringdefault solid: solid, or a segmented style such as segmented_10.
rangenumberdefault 48: Who sees it.
show_healthbooleandefault true: Drives the bar's progress from the mob's health.

`damage_modifiers`

Per-cause multipliers, for resistances and weaknesses.

damage_modifiers:
  melee: 0.5
  projectile: 2.0
  magic: 0.25
  causes:
    fall: 0

melee, projectile and magic are the grouped forms; causes takes individual vanilla damage causes for anything finer. 0 is immunity.

A complete mob

example_boss:
  type: ravager
  display: "<gradient:#e8d9a0:#c9a227>Example Champion</gradient>"
  health: 200
  damage: 10
  armor: 8
  knockback_resistance: 1.0
  movement_speed: 0.28
  follow_range: 40

  options:
    despawn: false
    prevent_other_drops: true
    always_show_name: false

  faction: example
  threat: { enabled: true, decay: 0.05 }

  ai:
    goals:
      - clear: [MOVE, TARGET]
      - bestiary:melee_attack{speed=1.0}
      - bestiary:look_at_target
      - bestiary:return_to_anchor{distance=24}
      - bestiary:avoid_void

  phases:
    - name: ground
      until: { health_percent: "<= 60" }
    - name: enraged
      on_enter: example_enrage

  skills:
    - skill{s=example_shockwave} ~onTimer:160 ?phase{is=ground}
    - skill{s=example_scaled_bolt} ~onTimer:100 ?phase{is=enraged}
    - skill{s=example_enrage} ~onHealthThreshold:25

  bossbar:
    title: "<gold>Example Champion <gray>- <white><caster.hp.percent>%"
    color: yellow
    style: segmented_10
    range: 48

  drops: example_boss_drops

This ships as mobs/bestiary/example.yml, and has no Java behind it.

Verify a mob

After reload, /bestiary info <mob> is authoritative for the resolved entity type, scaled attributes, options, phases, triggers and drop table. Spawn a disposable copy at an explicit level when testing scaling, for example /bestiary spawn <mob> 5. Live mobs are rebound on reload, but their current phase and fight state can still affect what you observe.