config.yml
Main configuration file controlling all plugin runtime behavior. Changes to sections other than heuristics.triggers require a full server restart.
auto-regulation
Automatic profile switching according to a daily schedule. Uses 24-hour format in the server JVM's local timezone.
auto-regulation:
enabled: false # Set true to activate scheduled switching
profile: survival # Active profile on server startup
schedule:
- time: "08:00"
profile: survival
- time: "20:00"
profile: aggressive # Anticipate peak-hour load
- time: "03:00"
profile: conservative # Overnight — minimal intervention
notify-admins: true # Notify online admins of profile changes
discord
Discord webhook notifications. Delivery failures are logged but do not affect plugin operation.
discord:
webhook-url: "" # Empty string disables notifications
alert-tps-threshold: 14.0 # Alert fires when TPS drops below this value
notify-automatic-actions: true # Post a message for each automatic action executed
notify-profile-changes: true # Post a message on profile changes
handlers — Per-Action Configuration
Default parameters for each action handler. These values are used when the orchestrator selects an action without an explicit parameter override from a policy.
handlers:
pause-mob-ai:
default-radius: 6 # Default chunk radius for AI suspension
max-radius: 12 # Maximum radius (cannot be exceeded by policies)
exclude-pets: true # Never pause AI of tamed animals
exclude-villagers: false # Set true to always protect villagers
exclude-villagers-threshold: 0
auto-renew: true # Re-apply automatically if conditions persist after revert
aggressive-item-merge:
default-chunk-radius: 6
max-chunk-radius: 12
throttle-hoppers:
default-ticks: 5 # Ticks between transfers (vanilla is 8)
min-ticks: 1
max-ticks: 1200
default-radius: 0 # 0 = global (all chunks in the world)
max-radius: 12
default-max-transfers-per-sec: 4
throttle-redstone:
enabled: true
chunk-threshold: 500 # Max redstone events per chunk per interval
block-threshold: 15 # Max redstone events per block per interval
reset-interval-ticks: 20 # 20 ticks = 1 second
removal-action: REMOVE # REMOVE (recommended) | DISABLE | DROP
set-spawn-limit:
default-limit: 50
default-category: "MONSTER" # MONSTER | ANIMAL | WATER_ANIMAL | AMBIENT
entity-tracking:
default-distance: 8
auto-revert
Controls when and how automatic optimizations are reverted once the triggering condition has resolved.
auto-revert:
enabled: true
metrics:
tps-recovery-threshold-pct: 30.0 # % TPS improvement from baseline at action time
mspt-recovery-threshold-pct: 20.0
entity-recovery-threshold-pct: 20.0
player-recovery-threshold-pct: 10.0
chunk-recovery-threshold-pct: 10.0
# false = any individual metric meeting its threshold triggers the revert
# true = all configured metrics must meet their thresholds simultaneously
require-all-metrics: false
regional:
enabled: true
action-types: # Only these types use regional revert evaluation
- pause-mob-ai
- set-view-distance
- set-simulation-distance
require-all-metrics: true
required-consecutive-confirmations: 2 # Cycles that must confirm recovery
signal:
mode: composite # composite | hotspots-only
weights:
entity-hotspots: 0.60
chunk-hotspots: 0.25
players: 0.15
min-uptime-before-revert-ms:
default: 120000 # 2 minutes minimum uptime
pause-mob-ai: 120000
set-view-distance: 180000 # 3 minutes minimum
set-simulation-distance: 180000
distance-overrides
distance-overrides:
queue:
reset-after-single-apply: true # Apply one override then clear the queue (prevents cascades)
dynamic:
enabled: true # Enable proportional degradation based on server load
target-tps: 20.0
target-mspt: 50.0
multiplier-min: 0.50 # VD cap can be reduced to 50% of the permission cap
multiplier-max: 1.00
min-delta-chunks: 1 # Minimum change to be considered significant
cooldown-ms: 15000 # Minimum 15s between dynamic adjustments
actionbar:
enabled: true
min-interval-ms: 10000
template: "" # Empty = use language-file default
engine
engine:
min-evaluation-interval-ms: 10000 # Minimum time between full orchestration cycles
history-max-records: 2000
history-max-file-size-mb: 10
history-persist-interval-ms: 5000 # Flush action history to disk every 5 seconds
heuristics — Main Activation Engine
The most critical section of config.yml. Defines every threshold that determines when the orchestrator considers an intervention necessary.
heuristics:
engine:
tps-baseline-floor: 18.0 # EMA floor — prevents baseline collapsing under sustained load
tps-critical: 14.0 # CRITICAL severity threshold (maximum response intensity)
tps-high: 17.0 # HIGH severity threshold
cooldown-min-seconds: 12
cooldown-max-seconds: 180
circuit-breaker-failures: 3 # Consecutive failures to open the circuit breaker
circuit-breaker-silence-seconds: 120
aimd:
additive-increase: 0.05 # Factor increment per successful action cycle
multiplicative-decrease: 0.5 # Factor reduction on failure
min-factor: 0.1
max-factor: 1.0
initial-factor: 0.5
triggers:
# Entities
entity-count: 80 # DEMO — production: 300-500
passive-mob-count: 40 # DEMO — production: 150-300
entity-hotspot: 35 # DEMO — production: 100-200 (per chunk)
tile-entity-count: 1000 # DEMO — production: 10000-50000
# Chunks
loaded-chunks: 450 # DEMO — production: 5000-20000
simulated-chunks: 220 # DEMO — production: 2000-10000
forced-chunks: 60 # DEMO — production: 200-500
chunk-entity-hotspot: 30 # DEMO — production: 50-100
# Redstone and mechanics
redstone-updates: 500 # DEMO — production: 5000-20000
piston-activations: 100 # DEMO — production: 1000-5000
Important: All values marked DEMO are intentionally low for test environments. For production, multiply entity and chunk thresholds by 5–10x and redstone/piston thresholds by 10–20x. Always validate with Analysis mode first.