AzLagControl

Professional lag control suite for Minecraft servers — by AztrixDigitalStudio

AzLagControl is a modular performance toolkit for Paper/Spigot servers. Its philosophy is Prevention First, Cleanup Second: instead of only deleting entities after the damage is done, it actively throttles the systems that cause lag (redstone, hoppers, explosions, mob overpopulation) while still providing smart scheduled cleanup, live performance monitoring, and an automatic emergency mode that kicks in when your TPS collapses.

Every module is fully independent — enable only what you need. Everything hot-reloads with /azlag reload.

Features

| Module | What it does |
|--------|--------------|
| Smart Cleaner | Scheduled + manual cleanup of dropped items, arrows, projectiles, and optionally mobs/vehicles. Countdown warnings, world filtering, and rich protection rules (named, tamed, leashed, passengers, bosses, recent player drops). |
| Smart Mob Control | Caps mobs per chunk by category (animals, monsters, villagers, water, ambient). Periodic overflow purge for chunks over the limit. Whitelist for bosses. |
| Smart Item Control | Per-chunk ground-item limits, nearby item merging, configurable despawn lifetime, and periodic item cleanup. |
| Redstone Control | Throttles excessive redstone state changes per chunk and detects redstone clocks. Actions: LOG, THROTTLE, or ALERT admins. |
| Hopper Control | Reduces hopper tick overhead via a configurable transfer tick-rate, optional per-chunk hopper caps, and auto-disable below a TPS threshold. |
| Explosion Control | Caps explosions per tick, TNT entities per chunk, and creepers per chunk. Optional reduced block damage for large TNT farms. |
| Chunk Control | Periodically analyzes chunk health, tracks the worst N chunks, and alerts admins when a chunk exceeds an entity threshold. |
| Performance Monitor | Live sampling of TPS, MSPT, and memory with a rolling history and configurable warning/critical alerts. |
| Emergency Mode | Auto-activates on severe TPS drops. Reduces view distance, halts mob spawning, aggressively purges entities, removes TNT, and optionally disables hoppers — then auto-deactivates once TPS recovers. |
| Analytics | Keeps a rolling history of performance samples and can log snapshots to file. |

Requirements

• Server: Paper 1.20+ (Spigot-compatible API used throughout; api-version 1.20)
• Java: 17 or newer
• Optional integrations: PlaceholderAPI, spark

The plugin runs fully without any optional dependency.

Installation

1. Download AzLagControl-x.y.z.jar from Modrinth, SpigotMC, or the Releases page.
2. Drop the jar into your server's plugins/ folder.
3. Restart (or reload) the server.
4. Edit plugins/AzLagControl/config.yml to taste, then run /azlag reload.

Commands

Base command: /azlagcontrol, aliases /azlag and /alc.

| Command | Description |
|---------|-------------|
| /azlag stats | Full server stats |
| /azlag tps | Show TPS (1m / 5m / 15m) |
| /azlag mspt | Show milliseconds per tick |
| /azlag memory | Show JVM memory usage |
| /azlag entities | Entity counts per world |
| /azlag chunks [analyze] | Show chunk stats |
| /azlag cleanup | Trigger manual cleanup now |
| /azlag reload | Reload configuration |
| /azlag emergency <on\|off\|status> | Manage emergency mode |
| /azlag diagnose | Full system diagnostic |
| /azlag profiler [last N] | Show performance history |
| /azlag help | List available commands |

Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| azlagcontrol.admin | Full administrative access (grants all below) | op |
| azlagcontrol.use | Basic command access (stats, tps) | op |
| azlagcontrol.reload | Reload plugin configuration | op |
| azlagcontrol.stats | View server performance statistics | op |
| azlagcontrol.cleanup | Trigger manual entity/item cleanup | op |
| azlagcontrol.emergency | Activate/deactivate emergency mode | op |
| azlagcontrol.diagnose | Run server diagnostics | op |
| azlagcontrol.profiler | Access the performance profiler | op |

PlaceholderAPI

When PlaceholderAPI is installed, the azlagcontrol expansion is registered automatically.

| Placeholder | Output |
|-------------|--------|
| %azlagcontrol_tps% | Current TPS |
| %azlagcontrol_tps_1m% | TPS — 1 minute average |
| %azlagcontrol_tps_5m% | TPS — 5 minute average |
| %azlagcontrol_tps_15m% | TPS — 15 minute average |
| %azlagcontrol_tps_colored% | TPS, color-coded by health |
| %azlagcontrol_mspt% | Milliseconds per tick |
| %azlagcontrol_memory_used% | Used JVM memory |
| %azlagcontrol_memory_max% | Max JVM memory |
| %azlagcontrol_memory_pct% | Memory usage percentage |
| %azlagcontrol_entities% | Total entity count |
| %azlagcontrol_items% | Ground item count |
| %azlagcontrol_chunks% | Loaded chunk count |
| %azlagcontrol_emergency% | Emergency mode state |

Developer API

AzLagControl fires Bukkit events other plugins can listen to:

• AzCleanupEvent — fired around cleanup runs.
• AzEmergencyModeChangeEvent — fired when emergency mode toggles.

@EventHandler
public void onEmergency(AzEmergencyModeChangeEvent event) {
    // react to emergency mode changes
}

Configuration

The full, heavily-commented config.yml is generated on first run. Highlights:

• core — debug toggle, message prefix, update checks.
• cleaner — interval, warn-times, what to remove, protection rules, per-world scope.
• mob-control — per-chunk category caps, overflow purge, whitelist.
• item-control — per-chunk limit, merge radius, despawn lifetime.
• redstone — update caps, clock detection + action.
• hopper — tick-rate, per-chunk cap, TPS auto-disable.
• explosion — per-tick cap, TNT/creeper caps, block-damage reduction.
• chunk-control — analysis interval, top-N tracking, alert threshold.
• monitor — sampling, history size, TPS alert thresholds.
• emergency — auto-activate/deactivate TPS, actions, messages.
• analytics — history window, file logging.
• integrations — PlaceholderAPI, spark toggles.

All sections support worlds: [] (empty = all worlds) where applicable, and every module has its own enabled flag.

Building from source

git clone https://github.com/Light0mxph/AzLagControl.git
cd AzLagControl
./gradlew build

The shaded, ready-to-use jar lands in build/libs/AzLagControl-<version>.jar.

License

Licensed under the GNU General Public License v3.0. See LICENSE.

Credits

Developed and maintained by AztrixDigitalStudio.