DynamicMobLimiter

Automatic, TPS-aware mob spawn throttling for Paper servers.

DynamicMobLimiter watches your server's performance in real time and dynamically scales down natural mob spawning when TPS starts to drop — then automatically restores normal spawn rates once performance recovers. No manual intervention, no permanent spawn caps, no wasted potential.

✨ Features

• Live TPS monitoring — uses Paper's built-in 1-minute TPS average, checked on a configurable interval.
• Stepped throttling — define multiple TPS thresholds, each with its own spawn-allow percentage (e.g. 75%, 50%, 20%, 0%).
• Automatic recovery — as soon as TPS climbs back above your threshold, spawn rates return to 100% on their own.
• Selective spawn reasons — choose exactly which spawn reasons are affected (NATURAL, CHUNK_GEN, BREEDING, EGG, etc.).
• Mob whitelist — exempt specific entities (e.g. WITHER, ENDER_DRAGON) so boss fights and important spawns are never blocked.
• Built for performance — the spawn handler runs in O(1): two set lookups, one volatile read, and at most one random roll. No Bukkit API calls, no allocations, no async hops in the hot path.
• Admin command — /dml status shows live TPS and current spawn rate; /dml reload reloads the config without a restart.

⚙️ How It Works

1. Every check-interval-seconds, the plugin reads the server's 1-minute TPS average.
2. If TPS is above min-tps-threshold, spawning runs at 100% — the plugin does nothing.
3. If TPS drops below the threshold, the plugin looks up your configured throttling steps and applies the matching spawn percentage.
4. Each CreatureSpawnEvent with a configured spawn reason then has a chance (equal to that percentage) to proceed — otherwise it's cancelled before the mob ever spawns.

🛠️ Configuration

settings:
  check-interval-seconds: 5
  min-tps-threshold: 18.0

tps-throttling-steps:
  19.0: 1.0   # 100% spawns (normal)
  18.0: 0.75  # 75% allowed
  17.0: 0.50  # 50% allowed
  16.0: 0.20  # 20% allowed
  15.0: 0.00  # spawning stopped

affected-spawn-reasons:
  - NATURAL
  - CHUNK_GEN
  - BREEDING
  - EGG

whitelist-mobs:
  - WITHER
  - ENDER_DRAGON

💬 Commands & Permissions

Command	Permission	Description
/dml status	dynamicmoblimiter.status	Shows current TPS, active spawn rate, and configured steps
/dml reload	dynamicmoblimiter.reload	Reloads config.yml without restarting

Default for both: op

📋 Requirements

• Paper (or Paper-fork) 1.20+
• Java 21+

🐞 Issues & Suggestions

Found a bug or have an idea for a feature? Open an issue on the GitHub repository.