Synergy

Coordinated server-side performance and fluidity optimizations for Vintage Story. Reduces TPS overhead, bandwidth, and GC pressure while improving multiplayer smoothness.

Works as server-only or with both client+server installed. Clients are not required - but installing on both enables delta position encoding (~70% bandwidth reduction). Compatible with Tungsten and OptiTime.

All 15 optimizations are individually toggleable. Runtime circuit breaker with auto-fallback to vanilla on any error.

Optimizations

Server-Side Performance (9)

• Entity Activation Range - Skip ticking entities beyond 48 blocks of any player (whitelisted behaviors still tick)
• Collision Fast-Path - Skip collision resolution for stationary entities with zero motion
• Network Flush Consolidation - Batch small TCP packets into fewer SendAsync calls per tick
• Block Tick Pooling - Pool 512 BlockPos objects per thread in random tick loop
• Inventory Dirty Scan - Skip full inventory iteration when nothing has been modified
• Pathfinding Node Pooling - Pool 4096 PathNode objects per thread (transpiler, zero heap allocs)
• Pathfinding Distance Throttle - Reduce pathfinding frequency based on distance to player
• Repulse Agents Throttle - Throttle O(N²) repulsion checks for distant entities
• AI Brain Tick Throttle - Distance-based AI evaluation LOD (DEAR formula)

Server-Client Fluidity (6)

• Entity Tracking Hysteresis - Speed-proportional buffer zone prevents entity pop-in flickering
• Distance-Based Send Frequency - 15Hz for distant entities, stationary suppression
• Attribute Sync No-Op Skip - Skip unnecessary full tree resyncs on no-op RemoveAttribute calls
• Entity Spawn Priority Ordering - Nearest entities appear first after teleport/login
• Entity Load Budgeting - Eliminate login/teleport frame spikes (5 entities/tick budget)
• Delta Position Encoding - Varint/zigzag delta encoding (~70% bandwidth reduction with Synergy client)

Built-in Diagnostics

Per-optimization measurement framework. See exactly how much each optimization saves:

• /synergy diag all on - enable counters (auto-dumps every 5 min to server log)
• /synergy diag all dump - print stats immediately
• /synergy stats - live metrics (entities, AI throttle %, bandwidth saved)

Real measurements from a dedicated server session (~2 min, 1 player, ~234 entities):

Optimization	Metric	Result
Entity Activation Range	Entities sleeping	68% of ticks saved
AI Brain Throttle	StartNewTasks skipped	62% CPU saved
Network Flush	Packets consolidated	80% (1263 buffered, 302 passthrough)
Delta Encoding	Bandwidth reduction	70% (~56 KB/s saved)
Repulse Throttle	O(N²) checks skipped	69% at distance
Send Frequency	Position packets saved	29% bandwidth
Tracking Hysteresis	Flicker prevented	96% of boundary entities kept
Pathfinding Pool	Heap allocations	100% reuse (3352 nodes pooled)
Inventory Scan	Scans skipped	100% while idle
Block Tick Pool	Heap allocations	100% reuse

Combined: ~68% entity tick reduction, ~70% position bandwidth reduction, 80% TCP syscall reduction, 100% pathfinding GC elimination.

Safety

• Circuit breaker: each optimization auto-disables after 5 errors, falls back to vanilla
• Conflict detection: checks Harmony.GetPatchInfo() before patching - skips if another mod is there
• Graceful degradation: all prefixes return true (run vanilla) on any unexpected exception
• No client-side requirement: works with vanilla clients (delta encoding is optional enhancement)

Commands

• /synergy - show optimization status + circuit breaker health
• /synergy stats - live metrics (entities, AI throttle, bandwidth)
• /synergy all on|off - toggle all optimizations (restart required)
• /synergy <opt> on|off - toggle individual optimization
• /synergy reload - reload config from disk
• /synergy diag [all|<module>] [on|off|dump|reset] - per-optimization diagnostics

Compatibility

Compatible with most mods. Harmony conflicts are auto-detected - Synergy skips its patch when another mod already patches the same method. Verified compatible with Tungsten, OptiTime, and 200+ content mods.

License

Copyright (c) 2026 Zaldaryon - All Rights Reserved

Synergy - Coordinated optimizations so your server runs smoother.