Skip to content

Usage Guide

Jump to bottom
Zaldaryon edited this page Jul 31, 2026 · 12 revisions

Usage Guide

Installation

  1. Download the latest zip from GitHub Releases or Mod DB.
  2. Drop it into your VintagestoryData/Mods/ folder. Don't unzip it.
  3. Launch Vintage Story.

That's it. All optimizations are enabled by default and there's nothing to configure unless you want to.

OptiTime is client-side only. Servers don't need it installed.

Verifying it loaded

After joining a world, check the game log (client-main.log) for lines like:

[OptiTime] Precise frame pacing optimization loaded
[OptiTime] Dynamic light optimization loaded
[OptiTime] Entity animation optimization loaded
[OptiTime] 16 optimization(s) enabled

If you see these, everything is working. If an optimization couldn't be applied (usually due to a mod conflict), the log will say why.

Commands

All commands use the .optitime prefix and work in both singleplayer and multiplayer without admin privileges.

.optitime

Shows the status of all optimizations. Example output:

OptiTime v1.5.5 - Status:
  ambientsound: ON    bgfps: ON         chunktess: ON
  dynlights: ON       entityanim: ON    entityinterp: ON
  flysound: ON        framepace: ON     guimgr: ON
  handbook: ON        occlusion: ON     particles: ON
  recipe: ON          repulseagents: ON shaders: ON
  shadowveg: ON       tickingblocks: ON weatherwind: ON

.optitime <opt> on|off

Toggle a specific optimization.

.optitime dynlights off
→ Dynamic light optimization disabled. Restart required.

.optitime recipe on
→ Recipe lookup optimization enabled. Restart required.

The change is saved to config immediately, but takes effect after a game restart.

.optitime <opt>

Show info about a specific optimization.

.optitime entityanim
→ Entity Animation: Distance-based LOD for animation updates.
   Status: ON

.optitime profile on|off|dump|reset

Built-in profiling helpers (off by default).

.optitime profile on    # start collecting timing data
.optitime profile dump  # print collected data to chat
.optitime profile reset # clear collected data
.optitime profile off   # stop profiling

.optitime diag [module] on|off|dump|reset

Per-optimization diagnostic counters. Measures cache hit rates, cull percentages, trigger rates, and allocation savings in real-time.

.optitime diag              # list all modules
.optitime diag all on       # enable all counters
.optitime diag all dump     # print all stats to chat + log
.optitime diag all reset    # reset all counters
.optitime diag recipe dump  # print recipe cache stats

Dumping a module that was never enabled prints a hint to run .optitime diag <module> on first (instead of showing all-zero counters).

Zero runtime cost when disabled (single volatile bool check per hot-path entry).

Available optimization names

Name What it controls
ambientsound Ambient sound position updates
bgfps Background FPS limiter
blur Blur shader optimization (independent toggle)
dynlights Dynamic light culling
entityanim Entity animation LOD
entityinterp Entity interpolation smoothing (multiplayer)
flysound Fly sound volume updates
framepace Precise frame pacing
guimgr GUI manager LINQ-free iteration
handbook Handbook relationship caching
occlusion Occlusion culling gate
particles Particle view distance scaling
recipe Recipe lookup optimization
repulseagents Repulse agents distance cull
shaders Shader replacements (chunkliquid, chunkshadowmap)
shadowentity Entity shadow distance cull
shadowveg Shadow far vegetation cull
suppress Hide compatibility messages in chat on world load
tickingblocks Ticking blocks GC reduction
weatherwind Weather wind speed throttle

Configuration

ConfigLib GUI (optional)

If ConfigLib is installed, use .configlib to open a GUI for OptiTime settings. ConfigLib treats these settings as client-side, so multiplayer players can edit their local configuration without the controlserver privilege. Changes are saved immediately; settings applied during startup take effect after restarting. ConfigLib is not required.

Manual configuration (OptiTime.json)

Config file: VintagestoryData/ModConfig/OptiTime.json

Created automatically on first startup. Default config:

{
  "ShaderOptimizations": true,
  "RecipeLookupOptimizations": true,
  "ParticleViewDistanceScalingEnabled": true,
  "BackgroundFpsLimiterEnabled": true,
  "BackgroundMaxFps": 20,
  "PreciseFramePacingEnabled": true,
  "GuiManagerNoLinqEnabled": true,
  "GuiManagerInputNoLinqEnabled": false,
  "WeatherWindOptimizations": true,
  "TickingBlocksOptimizations": true
}
Setting Default Description
ShaderOptimizations true Enable shader replacements (chunkliquid, chunkshadowmap). Set to false for vanilla or other shader mods
BlurOptimizationEnabled true Independent blur shader toggle (9-tap linear-sampling)
RecipeLookupOptimizations true Crafting-grid lookup: previous-match fast path, positive cache, candidate narrowing
ParticleViewDistanceScalingEnabled true Reduce particle counts at high view distances (75% at 384+, 50% at 512+)
BackgroundFpsLimiterEnabled true Lower frame cap when window is unfocused
BackgroundMaxFps 20 Unfocused FPS cap
PreciseFramePacingEnabled true Hybrid frame pacing when VSync is off
GuiManagerNoLinqEnabled true LINQ-free GUI render iteration
GuiManagerInputNoLinqEnabled false No-LINQ input patches (enable only if no conflicting UI mods)
WeatherWindOptimizations true Throttle wind speed lookups from every frame to every 4th frame
TickingBlocksOptimizations true Reuse BlockPos in particle tick loop to reduce GC pressure
ShadowFarVegetationCullEnabled true Skip vegetation in far shadow cascade to reduce shadow cost
SuppressCompatibilityMessages false Hide mod conflict chat notifications on world load (info still logged)

All changes require a game restart.

Troubleshooting

OptiTime appears in "Involved Harmony IDs" in a crash log. Is it the cause?

  • Almost certainly no. Vintage Story's crash reporter lists ALL mods that have Harmony patches on ANY method in the crash stacktrace, even if that mod's code never ran and isn't in the stacktrace at all.
  • OptiTime patches ScreenManager.OnNewFrame (for the background FPS limiter). Since almost every crash passes through OnNewFrame in the call stack, OptiTime will appear in "Involved Harmony IDs" for crashes caused by completely unrelated mods.
  • How to tell if OptiTime actually caused the crash: Look at the stacktrace itself. If you see OptiTime or com.zaldaryon.optitime in the actual error lines (not just the "Involved Harmony IDs" header), then it might be OptiTime. If the stacktrace only mentions another mod's code, OptiTime is innocent.
  • This is a known limitation of the game's crash reporting system and affects all Harmony mods that patch common methods.

Game crashes after installing OptiTime

  • Make sure you're running Vintage Story 1.22.0 or newer.
  • Check client-main.log for the crash details.
  • Try .optitime <opt> off for each optimization to isolate the problem.

Shaders look different or broken

  • Run .optitime shaders off and restart. This disables OptiTime's shader replacements and uses vanilla shaders.
  • The blur optimization is independent: .optitime blur off to disable just the blur shader.
  • If you use Ancestral Bliss Shaders, Volumetric Shading Refreshed, or CoriaenderShaders, OptiTime auto-disables its shader replacements. No action needed.

Crafting grid is slow or laggy

  • Run .optitime recipe off and restart. Report the issue if this fixes it.

An optimization shows OFF but I didn't disable it

  • Another mod is patching the same method. OptiTime auto-disables to avoid conflicts. Check the log for details.

Commands don't work on a server

  • Make sure you're using .optitime (dot prefix), not /optitime (slash).
  • Commands work in multiplayer without admin privileges.

Compatibility

OptiTime works with most mods. Known interactions:

Mod What happens
Ancestral Bliss Shaders OptiTime auto-disables its shader assets
Volumetric Shading Refreshed OptiTime auto-disables its shader assets
CoriaenderShaders OptiTime auto-disables shader file replacements (chunkliquid, chunkshadowmap)
Combat Overhaul / Overhaullib Entity animation and entity interpolation optimizations auto-disable
Electrical Progressive (Industry) Handbook optimization auto-disables
Synergy Fully compatible. Synergy is server-side, OptiTime is client-side. No overlap.
Tungsten Fully compatible. Tungsten is server-side, OptiTime is client-side. No overlap.

For any other Harmony conflict, OptiTime auto-disables the specific optimization that overlaps and keeps everything else active. The log will tell you what was disabled and why.

Clone this wiki locally