Server Performance Optimizer — Documentation & Wiki

Welcome to the technical documentation for Server Performance Optimizer. This guide covers configuration, module details, and the developer API.

0. Installation & Compatibility

Minecraft Version Support: 1.21.x (Any version starting with 1.21) Fabric Loader: 0.16.9 or newer Java: 21

⚠️ Important Requirement: You must install the Fabric API version that matches your Minecraft version.

• If using Minecraft 1.21.1 -> Install Fabric API for 1.21.1
• If using Minecraft 1.21.x -> Install Fabric API for 1.21.x

⚙️ Configuration Guide

The main configuration file is located at config/performance_optimizer_config.json. It is automatically generated on first launch. You can edit this file while the server is running; the mod supports hot-reloading (use /reload or the dedicated command if available).

Full Configuration Structure

{
  "enabled": true,
  "debugMode": false,
  
  "scheduler": {
    "tickBudgetMs": 40,
    "maxAsyncWorkers": 4,
    "adaptiveLoadShedding": true,
    "maxTpsDrop": 5.0,
    "crashWatchdog": true,
    "watchdogThresholdMs": 50000
  },
  
  "world": {
    "chunkResidencyTimeMs": 10000,
    "predictivePrefetch": true,
    "prefetchDistance": 2,
    "snapshotCacheDurationMs": 50,
    "entityBudget": 50
  },
  
  "networking": {
    "packetOptimizationEnabled": true,
    "packetBatchMaxSize": 50,
    "packetBatchIntervalMs": 20,
    "reserveExternalNetworkOptimizerSpace": true
  },
  
  "datapack": {
    "governorEnabled": true,
    "maxFunctionsPerTick": 1000
  }
}

Parameter Explanations

scheduler

• tickBudgetMs: Max time (in milliseconds) the mod allows for its own tasks per tick. Standard tick is 50ms; setting this to 40ms leaves 10ms for vanilla logic.
• adaptiveLoadShedding: If true, non-critical tasks are dropped when TPS falls below threshold.
• maxTpsDrop: The TPS drop amount (e.g., 5.0 means 15 TPS) that triggers load shedding.
• crashWatchdog: Enables the emergency intervention system.

world

• chunkResidencyTimeMs: How long a chunk stays loaded in "shadow memory" after being flagged for unload, preventing thrashing.
• predictivePrefetch: Uses player velocity to load chunks ahead of time.
• snapshotCacheDurationMs: How long to trust a cached world state (e.g., block collision).

networking

• packetBatching: Groups small packets to save CPU/Bandwidth.
• reserveExternalNetworkOptimizerSpace: If true, reserves budget for a companion network mod.

📚 Module Deep Dive

1. Scheduler & Stability

The Scheduler is the heart of the mod. It wraps standard Fabric events to execute tasks.

• Load Shedding: When the server is lagging (TPS < 15), low-priority tasks (like prefetching or deep diagnostics) are simply discarded or deferred.
• Crash Watchdog: A separate thread that monitors the main server thread. If the main thread hangs for longer than watchdogThresholdMs, it attempts to interrupt the specific stuck task or dump a stack trace before the vanilla watchdog kills the server.

2. World Optimization

• Chunk Residency: Prevents the "load/unload loop" caused by players moving back and forth across chunk boundaries. It keeps chunks "technically loaded" but inactive for a grace period.
• Entity Budgeter: Assigns a "cost" to entity AI. If the total cost exceeds the budget, distant entities are ticked less frequently (e.g., every 5 ticks instead of every tick).

3. Networking & I/O

• Optimizer Bus: A dedicated event bus for high-priority network events.
• Packet Batching: Instead of sending 50 individual "particle spawn" packets, the mod batches them into a single bundle, reducing the overhead of packet headers and system calls.

4. Datapack Governor

• Prevents datapacks from running infinite loops or excessive commands.
• It counts the number of functions executed per tick by a datapack namespace. If it exceeds maxFunctionsPerTick, execution for that datapack is paused until the next tick.

👩‍💻 Developer API

Network Budget API

External mods can coordinate with the optimizer using the NetworkBudget class.

import orvyn19.optimizer.api.NetworkBudget;

// Check available bandwidth budget for a player
long budget = NetworkBudget.getRemainingBudget(playerUuid);

// Reserve budget for a heavy operation
if (NetworkBudget.tryReserve(playerUuid, 5000)) {
    // Send 5KB packet
}

Telemetry API

Access real-time performance metrics without reflection.

import orvyn19.optimizer.telemetry.Telemetry;

// Get current load metrics
double load = Telemetry.getServerLoad(); // 0.0 to 1.0
int queueSize = Telemetry.getTaskQueueSize();