Skip to content

Performance

Jump to bottom
Tsu edited this page Jun 9, 2026 · 4 revisions

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. When AdaptiveUnderOverload is enabled, the caps scale down once recent average tick time exceeds OverloadTickMs.

It also controls fair per-player scheduling:

  • FairSchedulingEnabled: sorts players by recent chunks sent so busy joins and mass travel do not always favor whoever happens to be first in the client list.
  • FairWindowMilliseconds: window used for recent per-player send counts.
  • NearRingRadiusChunks: split point for near/far chunk send metrics.

Outbound pressure controls can reduce a single player's chunk send budget when that client's TCP sends are already backed up:

  • OutboundPressureEnabled
  • OutboundPressurePendingSendsSoftLimit
  • OutboundPressurePendingSendsHardLimit
  • OutboundPressurePendingBytesSoftLimit
  • OutboundPressurePendingBytesHardLimit
  • OutboundPressureScale
  • OutboundPressureMinimumClientBudget

Chunk Generation

ChunkGeneration caps chunk-column request throughput. It has the same adaptive overload controls as chunk sending, with lower default floors.

Join Pressure

Join adds two safe controls for heavy login periods:

  • CacheStartupPackets: caches startup packet payloads (world metadata and server identification) so repeated joins do not rebuild the same bytes every time.
  • MaxQueueAdmissionsPerPass: limits how many queued clients are admitted into the expensive join path per pass.

Cache use is skipped when server config is dirty so stale packets are not reused. Identification cache keys include mod whitelist/blacklist data and Stratum client mod policy values.

Chunk Request Management

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

Stratum tracks which clients still want each pending chunk column before cancelling stale work. A chunk request can be kept if another player still needs it, even if the first player moved away. The performance report shows tracked wanted columns, wanted-by links, shared requests, and worker-owned tracked requests.

Pathfinding

This controls async pathfinding workers, maximum queued path requests, and stale task pruning via MaxTaskAgeMs.

Queue pressure options now let Stratum prioritize near-player path work and drop far, stale, ownerless, or finished work before useful work:

  • PriorityEnabled
  • PriorityQueueThreshold
  • FarTaskDistanceBlocks
  • DropFarTasksUnderPressure
  • FailureCooldownAfterFailures
  • FailureCooldownMs

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. The old periodic PhysicsManager tickables=... debug notification has been removed; use timings and /stratum performance instead.

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
  • sources/VintagestoryLib/Vintagestory.Server/StratumConfig.cs
  • patches/VintagestoryLib/Vintagestory.Server/ServerSystemSendChunks.cs.patch
  • patches/VintagestoryLib/Vintagestory.Server.Network/TcpNetConnection.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/VSEssentials/Entity/Pathfinding/PathfindingAsync.cs.patch
  • patches/VSEssentials/Entity/Pathfinding/Astar/WaypointsTraverser.cs.patch
  • patches/VintagestoryApi/Server/PathfinderTask.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

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

Clone this wiki locally