-
Notifications
You must be signed in to change notification settings - Fork 0
Usage Guide
- Download the latest zip from GitHub Releases or Mod DB.
- Drop it into your
VintagestoryData/Mods/folder. Don't unzip it. - Start (or restart) the server.
That's it. All 15 optimizations are enabled by default and there's nothing to configure unless you want to.
Synergy works as server-only, client-only, or with both sides installed. Clients don't need it — but installing on both sides enables delta position encoding (~50-60% bandwidth reduction).
After starting the server, check the log for:
[Synergy] Server-side loaded (14 optimizations active)
If you see 14 optimizations active, everything is working. If the number is lower, some optimizations couldn't be applied — the log will tell you which ones and why. The server runs fine either way.
You might also see:
[Synergy] Skipping patch on TickEntities — transpiler conflict with: com.zaldaryon.tungsten
This is normal if you're running Tungsten alongside Synergy. It means Synergy detected that Tungsten already patches that method and gracefully skipped its own patch.
All commands require controlserver privilege. Run from server console or in-game chat.
Shows the status of all optimizations with their current state (ON/OFF).
Toggle a specific optimization:
/synergy activationrange off
→ activationrange: OFF.
⚠️ Server restart required.
Available names: activationrange, repulsethrottle, collisionfastpath, networkflush, inventoryscan, pathfindingpool, pathfindingthrottle, hysteresis, sendfrequency, attributedelta, spawnpriority, aithrottle, deltaencoding, entityloadbudget, blocktickpool
Toggle every optimization at once. Useful for A/B testing.
Reloads Synergy.json from disk. Useful if you edited the file by hand.
Shows live metrics: entity counts (active/sleeping), AI throttle percentage, delta encoding clients, bandwidth savings, last save times.
Config file: VintagestoryData/ModConfig/Synergy.json
Created automatically on first startup. Default config:
{
"BlockTickPoolingEnabled": true,
"NetworkFlushConsolidationEnabled": false,
"InventoryDirtyScanEnabled": true,
"EntityActivationRangeEnabled": true,
"EntityActivationRangeBlocks": 48.0,
"ActivationRangeExcludedEntities": ["smoke"],
"CollisionFastPathEnabled": true,
"PathfindingOptimizationsEnabled": true,
"PathfindingThrottleEnabled": true,
"RepulseAgentsThrottleEnabled": true,
"AiBrainThrottleEnabled": true,
"EntityTrackingHysteresisEnabled": true,
"DistanceBasedSendFrequencyEnabled": true,
"AttributeSyncResyncPreventionEnabled": true,
"EntitySpawnPriorityOrderingEnabled": true,
"DeltaEncodingEnabled": true,
"EntityLoadBudgetingEnabled": true,
"GcDiagnosticsEnabled": true
}All changes require a server restart.
| Setting | Default | What it controls |
|---|---|---|
EntityActivationRangeEnabled |
true | Skip ticking distant entities |
EntityActivationRangeBlocks |
48.0 | Distance threshold in blocks |
ActivationRangeExcludedEntities |
["smoke"] | Entity codes that always get full tick |
CollisionFastPathEnabled |
true | Skip collision for stationary entities |
NetworkFlushConsolidationEnabled |
false | Batch small TCP packets |
BlockTickPoolingEnabled |
true | Pool BlockPos in tick loop |
InventoryDirtyScanEnabled |
true | Skip inventory scan when nothing dirty |
PathfindingOptimizationsEnabled |
true | Pool A* PathNode objects |
PathfindingThrottleEnabled |
true | Throttle distant entity pathfinding |
RepulseAgentsThrottleEnabled |
true | Throttle distant entity repulsion |
AiBrainThrottleEnabled |
true | Distance-based AI evaluation LOD |
EntityTrackingHysteresisEnabled |
true | Buffer zone on tracking range |
DistanceBasedSendFrequencyEnabled |
true | 15Hz for distant entities |
AttributeSyncResyncPreventionEnabled |
true | No-op RemoveAttribute skip |
EntitySpawnPriorityOrderingEnabled |
true | Nearest entities spawn first |
DeltaEncodingEnabled |
true | Delta-encoded positions (needs client) |
EntityLoadBudgetingEnabled |
true | Budgeted entity loading on login |
GcDiagnosticsEnabled |
true | Log GC info at startup |
The EntityActivationRangeBlocks setting controls how far from any player an entity must be before it enters "sleep" mode. The default of 48 blocks is a good balance.
- 32 — Aggressive. Good for very busy servers (30+ players).
- 48 — Default. Good balance for most servers.
- 64 — Conservative. Entities stay active further out.
Sleeping entities still run whitelisted behaviors (breathe, health, despawn, grow, multiply, harvestable), so animals still grow, breed, and despawn correctly. Entities in lava, on fire, or in water always get full ticks regardless of distance.
Entity types listed in ActivationRangeExcludedEntities always get full ticks regardless of distance. The default ["smoke"] ensures compatibility with the Real Smoke mod (smoke entities need continuous ticking for dissipation). Add other entity codes if a mod's entities accumulate when far from players.
When Synergy is installed on both client and server:
- Server sends a handshake to the client on connect
- Client responds with its capabilities
- Server sends delta-encoded positions via a mod UDP channel
- Client reconstructs absolute positions from baselines + deltas
This reduces entity position bandwidth by ~50-60%. Vanilla clients connected to a Synergy server receive unchanged packets — no compatibility issues.
Synergy works with almost all mods. Tested against 200+ popular mods from the VS Mod DB.
- Combat Overhaul, XSkills, Primitive Survival, Carry On, Pet AI
- Hydrate or Diedrate, Toolsmith, Rivers, Smithing Plus, Dana Tweaks
- Tungsten (different targets, auto-detected), OptiTime (client-only)
- All content mods and client-side mods
If any mod patches the same method as Synergy, Synergy detects it via Harmony.GetPatchInfo() and skips its own patch with a logged warning. No crashes, no conflicts.
Per-optimization measurement system. Proves each optimization is working and quantifies its impact in your specific world.
/synergy diag all on
Counters start collecting. Auto-dumps to server log every 5 minutes. To see results immediately:
/synergy diag all dump
| Command | What it does |
|---|---|
/synergy diag |
List all 16 modules and their state |
/synergy diag all on |
Enable all counters (starts auto-dump timer) |
/synergy diag all off |
Disable all (zero overhead) |
/synergy diag all dump |
Print all enabled counters |
/synergy diag all reset |
Zero all counters |
/synergy diag <module> on |
Enable a specific module |
/synergy diag <module> dump |
Dump a specific module |
/synergy diag <module> reset |
Reset a specific module |
activationrange, collisionfastpath, networkflush, blocktickpool, inventoryscan, pathfindingpool, pathfindingthrottle, repulsethrottle, aithrottle, hysteresis, sendfrequency, attributesync, spawnpriority, entityloadbudget, deltaencoding, gc
=== [Synergy] Diagnostic: activationrange ===
[Synergy/diag] activationrange: fullTick=79957 sleeping=170310 (68%) whitelistedBehaviorTicks=681240 elapsed=51.2s
=== end diag ===
- fullTick/sleeping: entities getting full vs sleeping treatment
- percentage: how much work is being saved
- elapsed: time since counters were enabled/reset
| Module | Key Metric | Expected |
|---|---|---|
| activationrange | sleeping % | 55-70% |
| aithrottle | saved % | 55-65% |
| networkflush | consolidated % | 70-85% |
| deltaencoding | saved % | 60-70% (with Synergy client) |
| repulsethrottle | throttled % | 55-70% |
| sendfrequency | bandwidth saved % | 20-30% |
| pathfindingpool | reuse rate | 100% |
| inventoryscan | skipped % | 95-100% |
| collisionfastpath | fast-pathed % | 0% (normal — gravity) |
| networkflush | in singleplayer | 0 (expected — DummyConnection) |
The /synergy status command shows circuit breaker health:
CircuitBreaker: all healthy (0 degraded)
If an optimization hits 5 errors, it auto-disables:
CircuitBreaker: 1 degraded: NetworkFlush
NetworkFlush: DISABLED (errors: 5)
Server won't start after installing Synergy
- Make sure you're running Vintage Story 1.22.0 or newer
- Check that the zip is in the Mods folder, not unzipped
- Check server logs for
[Synergy]error messages
I want to isolate a problem to a specific optimization
- Set all options to
falseinSynergy.json - Restart the server
- Enable one optimization at a time, restarting each time
How do I know it's working?
- Check the startup log for
[Synergy] Server-side loaded (N optimizations active) - Use
/synergy statsfor live metrics - Each optimization logs its activation at startup
Animals drowning in ponds?
- Fixed in v1.1.6. Entities in water now get full tick so they can swim out.
- Remove the Synergy zip from your Mods folder.
- Restart the server.
That's it. Synergy makes no persistent changes to world data, configs, or save files.