Skip to content

Usage Guide

Zaldaryon edited this page Apr 24, 2026 · 13 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:

[ot] Shader optimizations enabled
[ot] Dynamic light optimization enabled
[ot] Entity animation optimization 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. The game runs fine either way.

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.4.7 - Status:
  ambientsound: ON    bgfps: ON         chunktess: ON
  dynlights: ON       entityanim: ON    flysound: ON
  framepace: ON       guimgr: ON        handbook: ON
  occlusion: ON       particles: ON     recipe: ON
  shaders: 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

Available optimization names

Name What it controls
ambientsound Ambient sound position updates
bgfps Background FPS limiter
chunktess Chunk tesselation throttle/boost
dynlights Dynamic light culling
entityanim Entity animation LOD
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
shaders Shader replacements
shadowveg Shadow far vegetation cull
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 is not required — it's just a convenience.

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. Set to false for vanilla or other shader mods
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

All changes require a game restart.

Troubleshooting

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.
  • If you use Ancestral Bliss Shaders or Volumetric Shading Refreshed, OptiTime auto-disables its shaders. 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
Combat Overhaul / Overhaullib Entity animation optimization auto-disables
Electrical Progressive (Industry) Handbook optimization auto-disables

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