BetterMob

BetterMob

Custom mobs in YAML, with 3D models, skills and boss fights.
A lightweight, multi-platform mob engine for Paper, Folia, and Fabric (singleplayer & dedicated server) with BetterModel support.

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

[!WARNING]
Fabric Beta / Early Access Notice
Fabric support is currently in active development. We recommend using the Fabric mod primarily in Singleplayer or on testing/development servers before deploying it to a live production environment.

---

🎯 Goals & Milestones

---

✨ 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 and Paper as a plugin, and on Fabric 1.21+ as a mod (supporting both client singleplayer and dedicated server environments).

🌐 Platform Feature Matrix

Feature	Paper / Folia	Fabric
YAML Mob Definitions	✅ plugins/BetterMob/mobs/*.yml	✅ config/bettermob/mobs/*.yml
3D Models	✅ BetterModel & ModelEngine	✅ BetterModel-Fabric
Skill Engine (Triggers, Conditions, Targeters)	✅ Full	✅ Core (@self, @caster, @target, @trigger, @eir, @pir, @p)
Core Mechanics (model, damage, heal, msg, sound, velocity, potion, ignite, lightning)	✅ Full	✅ Full
Boss Fights & Health Phases	✅ Full	✅ Full
Custom Drops & Experience	✅ Full	✅ Full
Spawners	✅ plugins/BetterMob/spawners.yml	✅ config/bettermob/spawners.yml
Commands (/bettermob spawn, /bettermob reload)	✅ Full	✅ Full
WorldGuard / PlaceholderAPI	✅ Supported	❌ Bukkit-only

🚀 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

3. 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.

Wild spawns

Add a Spawn block to a mob file (including a mob inside packs/<pack>/Mobs/).
REPLACE is the default and converts natural spawns of the mob's vanilla Type.
ADD makes independent land spawn attempts every 20 seconds around players in
Survival or Adventure mode. It only uses already loaded chunks, at a distance
of 24–48 blocks from the player.

# In nm_raccoon.yml, below Type: PIG
Spawn:
  Action: ADD
  Worlds: [world]
  Biomes: [TAIGA, OLD_GROWTH_PINE_TAIGA]
  Time: ANY
  Chance: 0.05
  Cooldown: 60
  MaxNearby: 3

Chance is a probability from 0 to 1 per attempt, not a number of mobs
per day. Cooldown is in seconds per player and mob after a successful spawn;
MaxNearby limits that mob to the given count within 48 blocks of the spawn
point. Worlds must use the server's exact world name. Reload with
/bettermob reload after changing the file.

To diagnose ADD attempts, use /bettermob debug chat. This also works when
global Debug is off and immediately lists the active ADD rules. Players
with the bettermob.debug permission see their own attempt results in chat,
including the location and reason a spawn was skipped. /bettermob debug info
also enables the global debug log. Use
/bettermob debug filter nm_raccoon to limit output to one mob.

🔌 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. Releases and the newest dev state (dev-SNAPSHOT) are on JitPack.

🧱 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, pack compatibility reports and pull requests are welcome. Start with CONTRIBUTING.md and please follow the Code of Conduct.

📊 Servers that use BetterMob

📄 License

MIT