Mob Leveling Overview
The Mob Leveling system dynamically assigns and updates levels for NPC mobs based on configurable rules and in-world context. This allows mobs to scale naturally with player progression, location, or instance difficulty while remaining performant and predictable.
When a mob is first encountered, it is given an initial spawn level. This level is persisted and periodically recalculated depending on the configured leveling mode.
Key characteristics:
- Mob levels are stored persistently per entity
- Levels are recalculated at a fixed interval (every ~2 seconds)
- Levels are clamped between 1 and the configured maximum mob level
- Scaling is only re-applied when the mob's level actually changes
On first creation, a mob is assigned a deterministic random level:
- Range: 1–10
- Seeded by the mob's UUID
- Ensures consistent spawn levels across restarts
This spawn level is used immediately and may later be overridden by dynamic recalculation.
Mob levels are recalculated periodically based on the configured Level Mode. If a mob is locked, recalculation is skipped.
Recalculation includes:
- Computing the new level based on the active mode
- Clamping the level to the configured maximum
- Applying stat scaling if the level changed
When a mob's level changes, its stats are scaled accordingly.
Currently applied scaling:
-
Health Scaling
- Health increases linearly per level
- Formula:
1 + (level - 1) * MobHealthMultiplier
- Applied as a max-health modifier
Additional stat scaling may be layered on top depending on configuration.
- Mob levels are saved automatically at intervals
- Recalculation is throttled to prevent excessive computation
- Scaling is idempotent and only applied when necessary
This design ensures the system remains efficient even in high-entity environments.
