Bestiary

A custom-mob and skill engine for Minecraft servers.

Minecraft

1.19.4-26.x

Servers

Spigot, Paper, Paper forks, Folia

Java

17+

Needs

Nothing else

Licence

LGPL-3.0

Choose your path

Bestiary has two content types. A mob is what a creature is, and a skill is what something does. Both are composed from the same four primitives:

140 mechanics, 39 targeters, 52 conditions and 25 triggers ship built in.

A skill is a tree, not a list

skill is itself a mechanic, so skills nest to whatever depth you write. An inline skills: block inside a flow mechanic becomes a real skill under a synthetic id rather than living inside its parent's config, which means every call takes the same executor path whether it is nested or not.

That is what lets the guards see the whole tree, and it is why /bestiary info can show a nested block like any other skill.

Two ways to write the same thing

example_shockwave:
  cooldown: 8s
  skills:
    - type: damage
      amount: 9
      ignore_armor: true
      targeter: { type: players_in_radius, radius: 7 }
      conditions:
        - { type: on_ground }

example_shockwave:
  cooldown: 8s
  skills:
    - damage{amount=9;ignoreArmor=true} @playersInRadius{r=7} ?onGround

Both parse to the identical tree, through the same parser. There is one validator and one set of error messages, and mixing the two forms in one file is fine. Structured YAML is the canonical form, which is what makes the in-game editor possible without round-tripping strings.

What makes it different

A runaway skill cannot take the server with it

Four guards, because skills call skills: recursion depth, mechanics per execution, targets per targeter, and wall clock per tick. Exceeding any one aborts that execution and logs the skill id and the node path.

Nothing is silently truncated, because a boss that half-fires is a bug report nobody can reproduce.

Trees suspend rather than abort

Skills are walked over an explicit frame stack, not by recursion. A Java call stack cannot be paused and resumed next tick; an explicit one can, so exceeding the tick budget means "stop looping and reschedule" rather than "give up". delay and the sync/async hops fall out of the same mechanism for free.

Nothing is polled unless it is asked for

A mob only runs a task if its definition declares a polled trigger, and that task's period is the GCD of the declared intervals. One ~onTimer:160 costs one task every 160 ticks, not a per-tick task that checks a counter.

Bosses spawn where structures are

A world generator places a marker where a boss belongs. Bestiary adopts it on chunk load, records the position, deletes the entity, and from then on spawns the boss on player proximity with a persisted respawn cooldown.

Position and existence are stored separately, so any removal Bestiary did not intend heals itself on the next visit, whether that was peaceful difficulty, a fall into the void, or another plugin's remove().

Custom AI costs zero NMS

Paper ships a supported goal-selector API, so custom goals work across the entire supported band, including stripping a Ravager's vanilla goals entirely and replacing them. Only navigation, move and look control need a Mojang-mapped runtime.

Parse failures are per definition

One broken skill does not take out the other forty beside it. Each failure names the file, the YAML path, the offending value and what was expected.

Where to go next

• Getting started: install it and spawn your first boss.
• Mobs: every key a mob file can contain.
• Skills: mechanics, targeters, conditions and triggers.
• Expressions: placeholders and arithmetic in any parameter.
• Spawning: anchors, spawners, regions and random spawns.
• Custom AI: goals, navigation and what needs which server.
• Server configuration: limits, storage, anchors, hooks and performance defaults.
• Troubleshooting: trace load, skill, spawn and storage problems.