Performance

This page covers the config that reduces load, smooths spikes, and spreads heavy work out over time.

Source of Truth

• Config model: sources/VintagestoryLib/Vintagestory/Server/StratumConfig.cs (StratumPerformanceConfig)
• Runtime metrics/timings: sources/VintagestoryLib/Vintagestory/Server/StratumPerformanceStats.cs, sources/VintagestoryLib/Vintagestory/Server/StratumTimings.cs
• Behavior changes: performance-related files under patches/

What The Runtime Uses

StratumRuntime owns the main performance systems:

• PacketLimiter
• PacketBackPressure
• PerformanceStats
• Timings
• Pregen

ServerSystemStratum.OnBeginConfiguration also uses the performance config to wire startup behavior like block-entity staggering and timer resolution.

StratumBlockEntityInitConfig beInit = StratumRuntime.Config.Performance.BlockEntityInit;
BlockEntity.StratumDefaultInitialDelaySpreadMs = (beInit != null && beInit.Enabled) ? beInit.MaxStaggerMs : 0;

StratumTimerResolutionConfig timerCfg = StratumRuntime.Config.Performance.TimerResolution;
if (timerCfg != null && timerCfg.Enabled && stratumActiveTimerPeriodMs == 0
		&& RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
	uint period = (uint)Math.Max(1, timerCfg.PeriodMs);
	uint result = StratumTimeBeginPeriod(period);
}

Config Groups

Chunk Sending

ChunkSending caps how many chunks are sent per server tick and per client tick.

Chunk Generation

ChunkGeneration caps chunk-column request throughput.

Chunk Request Management

This keeps stale requests from sitting around forever and adds distance-aware prioritization for moving players.

Pregen

This is the pre-generation throttle. It controls how much pregeneration can run per second, how big the queues can get, and whether pregeneration pauses when players are online.

Simulation Distance

This limits random ticks and block game tick listeners by distance.

Physics

This handles activation ranges, catch-up ticks, and overloaded tick behavior.

Entity Ticking

This is where far entity ticking, moving-entity skipping, and ambient fauna throttling live.

AutoSave

This spaces out save work and lets chunk pressure delay some of it.

Block Ticks

This caps random ticks, main-thread block ticks, and overload scaling.

Timings

This is the Stratum timings system. It starts disabled unless EnabledOnStartup is set.

Event Tick

This adds slowdown thresholds and adaptive throttling for entity/block listeners.

Entity Collisions

This is the collision cap behind repulse-agents.

Block Entity Init

This spreads block-entity startup across time so a chunk load does not dump everything on the same tick.

Timer Resolution

This raises Windows timer resolution so the server can sleep accurately instead of getting stuck on the default scheduler tick.

The comment in StratumConfig says why this exists:

// Windows multimedia-timer resolution boost. Without this, Thread.Sleep() on Windows
// rounds up to the next ~15.6ms scheduler tick, capping the server's effective tickrate
// at ~25 tps regardless of how little work each tick does.

Real Code Paths

These are the main patch files that use the performance config:

• patches/VintagestoryLib/Vintagestory.Server/ServerMain.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/ServerSystemSendChunks.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/ServerSystemEntitySimulation.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/ServerSystemBlockSimulation.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/PhysicsManager.cs.patch
• patches/VintagestoryLib/Vintagestory.Common/EventManager.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/BlockAccessorWorldGen.cs.patch
• patches/VintagestoryLib/Vintagestory.Server/BlockAccessorWorldGenUpdateHeightmap.cs.patch
• patches/VSEssentials/Systems/EntityPartitioning.cs.patch
• patches/VSEssentials/Entity/Behavior/BehaviorRepulseAgents.cs.patch
• patches/VSEssentials/Entity/Behavior/BehaviorDespawn.cs.patch
• patches/VSEssentials/Entity/AI/AiTaskManager.cs.patch
• patches/VSSurvivalMod/Entity/Behavior/BehaviorBodyTemperature.cs.patch
• patches/VintagestoryApi/Common/BlockEntity.cs.patch

What To Read First

If someone wants to understand the performance config first, start with:

1. ChunkSending
2. PacketBackPressure
3. EntityTicking
4. Physics
5. BlockTicks
6. EventTick

Those are the settings that show up most clearly in the tick profile.

Deep Dive Pages

• Feature: Chunk Send and Request Management
• Feature: Packet Back-Pressure
• Feature: Entity Partition Reuse
• Feature: Physics Tracking and State Packet Batching
• Feature: Repulse-Agents Gate and Collision Cap
• Feature: Selection Raytrace Throttle
• Feature: AI Task Scan Throttle
• Feature: Body Temperature Tick Throttling
• Feature: Async Pathfinding Workers and Queue Bound
• Feature: Event Tick Adaptive Throttle
• Feature: Timed Despawn Stagger and Budget
• Feature: Block Tick Smoothing
• Feature: Incremental Autosave and Chunk IO Read Pool
• Feature: Startup Wiring and Timer Resolution

Suggested Performance Read Order

1. Feature: Chunk Send and Request Management
2. Feature: Packet Back-Pressure
3. Feature: Physics Tracking and State Packet Batching
4. Feature: Block Tick Smoothing
5. Feature: Event Tick Adaptive Throttle
6. Feature: Incremental Autosave and Chunk IO Read Pool