BetterMob

Custom mobs in YAML, with 3D models, skills and boss fights.
A lightweight mob plugin for Paper and Folia that runs MythicMobs-style content.

Features · Quick start · MythicMobs · Developers · Addons · Wiki

---

✨ Features

🐷 Mobs in YAML	Any vanilla type as the body, with health, damage, AI goals and options. One mob per file or many per file.
🎭 3D models	Attach BetterModel or ModelEngine models, including rideable seats with real WASD control.
⚡ Skill engine	Triggers, mechanics, conditions and targeters with delay, cd and inline ?condition on every line. Variables, skill arguments, inline skills.
👹 Boss fights	Health phases, boss bars, patrol and guard behaviour, groups that call for help, leaders and followers, threat tables.
🎴 Items and loot	Custom items with right-click, swing and pickup skills, drop tables, vanilla loot tables, spawn eggs, kill counters and top lists.
🗺️ World	Natural spawn rules, spawners, WorldGuard regions and a spawn flag.
📦 Packs	Drop a content pack into packs/, validate it with /bettermob validate and switch it off with one line.
🧰 Tools	/bettermob test, aggro lines, a live reload report, skill profiling, JSON schemas for editors.
🔌 Developer API	Custom mechanics, conditions, targeters, placeholders and a long list of events.

BetterMob runs on Folia as well as Paper.

🚀 Quick start

1. Put BetterMob.jar into plugins/ (BetterModel or ModelEngine is optional) and start the server.
2. Create plugins/BetterMob/mobs/wumpus.yml:

Type: PIG
Display: '&9Wumpus'
Health: 12

AIGoalSelectors:
  - clear
  - randomstroll

Options:
  MovementSpeed: 0.25
  Invincible: true

Skills:
  - model{mid=wumpus} @self ~onSpawn
  - model{mid=wumpus} @self ~onLoad
  - sound{s=entity.pig.hurt;p=1.5} @self ~onDamaged
  - skill{s=wumpus_wave} ~onInteract

1. Run /bettermob reload, then /bettermob spawn wumpus.

The wiki walks through installation, mobs, skills and packs.

🧩 MythicMobs compatibility

BetterMob is not a full MythicMobs replacement. It implements the parts that model-based content packs rely on: custom mob registration, triggers, YAML packs and the MythicMobs-style skill system. If you know that file format, you already know this one. Check a pack before you use it:

/bettermob validate <pack>

It lists every line BetterMob does not understand. The pack compatibility page explains what is supported and what is not.

🔌 For developers

BetterMob registers a service with BetterMobAPI, custom mechanics, conditions, targeters and placeholders, and fires events for spawns, damage, targets, phases, drops, skills, mechanics, spawners and reloads. See the Developer API and the API events, or start from the example plugin in examples/api-example.

🧱 Addons

Addons are separate plugins that build on the Developer API and need BetterMob installed.

• BetterMobCrucible: extra item triggers, item data and lore mechanics for content made for MythicCrucible-style plugins. Latest release.

Made an addon? Open an issue or a pull request to get it listed here.

🏗️ Supported environment

🤝 Contributing

Bug reports and pull requests are welcome. wiki/Development.md explains how to build, test and run the Folia smoke test. The people behind BetterMob are listed in CONTRIBUTORS.md.

📊 Servers that use BetterMob

📄 License

MIT