plugins.bwmp.dev

Troubleshooting Bestiary

Bestiary's diagnostic commands are designed to answer different layers of the same problem:

/bestiary info <mob|skill>
/bestiary cast <skill> [target]
/bestiary debug <mob>
/bestiary platform

info shows the compiled definition, cast traces an isolated execution, debug attaches the trace to a live mob, and platform records the detected compatibility tier and loaded content.

A definition does not load

Read the grouped load report after startup or /bestiary reload. Errors are isolated per definition, so one bad mob does not remove unrelated working content. Verify:

  • the id namespace follows the file location;
  • every referenced skill, mob, drop table or Sigil item exists;
  • shorthand braces, targeters, conditions and triggers are balanced;
  • durations and numeric ranges use a supported form;
  • an integration-backed mechanic is available on this server.

Fix the first error for that definition, reload, then inspect it with /bestiary info.

A skill loads but does nothing

Run /bestiary cast <skill> and follow the trace node by node. Look for a targeter resolving zero targets, a condition returning false, an expression resolving an unexpected value, or a mechanic returning failure. Use /bestiary debug <mob> when the problem depends on live threat, phase or trigger state.

A custom mob looks vanilla

Confirm the mob definition loaded and inspect its options, equipment, attributes, bossbar and ModelEngine settings. If custom AI is expected, check /bestiary platform: unsupported NMS AI features must report a version gate, while portable Bukkit AI continues to work.

A mob does not spawn

For a manual test, use /bestiary spawn <mob>. If that succeeds, inspect the spawning source:

  • placed spawner: list it, confirm world/location, radius and player requirements;
  • random rule: check biome/world/light/height conditions and the per-world budget;
  • structure anchor: list anchors, confirm the stored mob id, activation range and cooldown;
  • external system: confirm the hook is installed and enabled.

/bestiary anchor reset clears an intended respawn cooldown for testing.

A guard aborts a skill

The warning names the skill, limit and offending node path. Do not immediately raise the limit. Check for recursive skill calls, nested repeats, an overly broad targeter or a large particle shape. The wall-clock budget normally suspends and resumes; depth, mechanic and target ceilings abort loudly because silently truncating a boss action would be harder to diagnose.

Players see lag or too many particles

Use the timing mode in /bestiary debug, reduce target fan-out, increase timer periods and narrow particle view distance before reducing visual fidelity globally. Polled triggers create no task unless a definition uses them, so identify the specific live mob and skill first.

Storage fails at startup

SQLite needs a writable Bestiary data folder. MySQL needs a reachable host, valid database and credentials, and the schema permissions required for migrations. Bestiary does not silently switch backends after a connection failure because that would split persistent state.

Capture a reproducible baseline

Before changing limits or definitions, save the startup load report, /bestiary platform, /bestiary info <mob> and one /bestiary cast <skill> trace. For live-only failures, attach /bestiary debug <mob>. Together they separate parsing, capability selection, compiled content and runtime context.