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

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.

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