Stress Testing

Nimbus includes a built-in stress testing system that simulates player load across your backend servers without requiring real Minecraft clients. This lets you validate scaling rules, find performance bottlenecks, and determine optimal players_per_instance values before going live.

How it works

The stress test manager simulates player load on backend servers. Simulated players:

• Count toward each service's player total (triggering the scaling engine naturally)
• Are reflected in proxy player counts and MOTD
• Respect each service's max_players cap

Console commands

Start a test

# Simulate 100 players across all backend groups
nimbus> stress start 100

# Target a specific group
nimbus> stress start 200 BedWars

# Ramp up gradually over 60 seconds
nimbus> stress start 500 --ramp 60

Check status

nimbus> stress status

Shows active test details: total simulated players, capacity, and per-service breakdown.

Adjust mid-test

# Ramp to a new target without stopping
nimbus> stress ramp 300

# Ramp over 30 seconds
nimbus> stress ramp 300 --duration 30

Stop

nimbus> stress stop

All simulated players are removed and services return to normal.

In-game commands

The bridge plugin exposes stress testing via /cloud stress:

/cloud stress start 100 Lobby 30
/cloud stress stop
/cloud stress ramp 200 60
/cloud stress status

Requires the nimbus.cloud.stress permission.

REST API

All endpoints require bearer token authentication.

Start via API

curl -X POST http://127.0.0.1:8080/api/stress/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"players": 100, "group": "Lobby", "rampSeconds": 30}'

Check status via API

curl http://127.0.0.1:8080/api/stress \
  -H "Authorization: Bearer <token>"

{
  "active": true,
  "totalPlayers": 100,
  "targetPlayers": 100,
  "capacity": 400,
  "services": {
    "Lobby-1": 40,
    "Lobby-2": 40,
    "Lobby-3": 20
  }
}

Ramp via API

curl -X POST http://127.0.0.1:8080/api/stress/ramp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"players": 200, "durationSeconds": 60}'

Scaling interaction

During a stress test, simulated players still:

• Count toward each service's reported player total (visible in status, MOTD, tab list, proxy counts)
• Respect each service's max_players cap (per-service distribution is capped, extra players overflow to the next instance)

When the test stops, StressBot-* entries are cleared and the scaling engine resumes its normal evaluation loop on the next tick.

Best practices

Finding the right players_per_instance

Run progressively larger tests and watch server performance:

nimbus> stress start 50 BedWars --ramp 30
# Monitor TPS via screen command
nimbus> screen BedWars-1
# Check if TPS stays above 19.5

nimbus> stress ramp 100 --duration 30
# If TPS drops, your players_per_instance is too high

Testing scale-up and scale-down

Because the engine is paused during a stress test, exercise scaling by varying the real instance count around a fixed simulated load, not the other way round:

# 1. Pre-start enough instances for your target load
nimbus> start Lobby 4

# 2. Apply load and confirm per-instance distribution + TPS
nimbus> stress start 200 Lobby --ramp 60
nimbus> stress status

# 3. Stop the test and let the engine reclaim idle instances
nimbus> stress stop
nimbus> status   # wait for idle_timeout, verify instances stopped

Monitoring during tests

Use screen to attach to a service console and watch TPS, memory, and tick times:

nimbus> screen Lobby-1
# Press Ctrl+C to detach

The status command shows per-instance player counts during the test. The REST API at /api/metrics provides historical data for post-test analysis.

Limitations

• Proxy groups are excluded -- only backend groups receive simulated players
• max_players is respected -- each service is capped at its configured max_players
• max_instances is respected -- the scaling engine will not exceed the group's max_instances
• Console spam suppressed -- StressBot-* events are filtered from the console output
• No real gameplay -- simulated players do not move, interact, or generate chunk load. CPU load is lower than real players.

Next steps

• Auto-Scaling -- Configure scaling rules that stress tests exercise
• Commands Reference -- Full command syntax
• API Reference -- REST API for automation