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

20 Servers Reached 40 Servers Goal 100 Servers Goal 500 Servers Goal 1k Servers Goal

100 Downloads Reached 200 Downloads Goal 500 Downloads Goal 1k Downloads Goal

--- ## ✨ 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](https://modrinth.com/plugin/bettermodel) or [ModelEngine](https://mythiccraft.io/index.php?resources/model-engine%E2%80%94ultimate-entity-model-manager-1-19-4-26-2.1213/product-download) 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](https://enginehub.org/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](https://modrinth.com/plugin/bettermodel) & [ModelEngine](https://www.spigotmc.org/resources/model-engine-4.108821/) | ✅ [BetterModel-Fabric](https://modrinth.com/mod/bettermodel) | | **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`: ```yaml 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](https://github.com/HyperGaming99/bettermob/wiki/Installation), [mobs](https://github.com/HyperGaming99/bettermob/wiki/Mobs), [skills](https://github.com/HyperGaming99/bettermob/wiki/Skills) and [packs](https://github.com/HyperGaming99/bettermob/wiki/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 ``` It lists every line BetterMob does not understand. The [pack compatibility](https://github.com/HyperGaming99/bettermob/wiki/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//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. ```yaml # 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](https://github.com/HyperGaming99/bettermob/wiki/Developer-API) and the [API events](https://github.com/HyperGaming99/bettermob/wiki/API-Events), or start from the example plugin in [`examples/api-example`](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](https://github.com/HyperGaming99/BetterMobCrucible)**: extra item triggers, item data and lore mechanics for content made for MythicCrucible-style plugins. [Latest release](https://github.com/HyperGaming99/BetterMobCrucible/releases/latest). 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](CONTRIBUTING.md) and please follow the [Code of Conduct](CODE_OF_CONDUCT.md). ## Star History # Please give a Star on Github

## 📊 Servers that use BetterMob ![bStats](https://bstats.org/signatures/bukkit/BetterMob.svg) ## 📄 License [MIT](LICENSE)

HyperGaming99

Organizations