Installation

Installation

Optimum installs into your existing Vintage Story directory. It adds a few files alongside the vanilla game — nothing is modified, nothing is replaced. When you launch Optimum.exe, it applies performance patches on first run (cached for instant launches thereafter).

Requirements

• A working Vintage Story installation (any platform)
• That's it. No SDK, no build tools, no compilation.

Windows (GUI Installer)

1. Download the latest release from Releases.
2. Extract the zip anywhere.
3. Double-click install-windows.cmd.
4. The installer auto-detects your VS installation.
   • If multiple installations are found, pick from the dropdown.
   • If none are found, click Browse to locate your VS folder.
5. Check/uncheck Desktop shortcut and Start Menu options.
6. Click Install.
7. Launch via the desktop shortcut, Start Menu, or Optimum.exe in your VS folder.

The installer registers Optimum in Programs & Features — you can uninstall from the Windows control panel like any other application.

Upgrading

Re-run the installer. It detects the existing Optimum version, removes the old files (preserving your settings), and installs the new version. The patch cache is cleared and regenerated on next launch.

Legacy Standalone Install

If you have a previous Optimum version installed in a separate directory (the old model created a full game copy in C:\Games\Optimum or similar), the installer detects it and offers to remove that folder. The new model doesn't need a separate copy.

Linux

./scripts/install-linux.sh

The interactive installer:

• Auto-detects VS installations (common paths, Steam, Flatpak)
• Shows a numbered list if multiple installations are found
• Copies Optimum files to the selected VS directory
• Creates a .desktop menu entry
• Optionally creates a desktop shortcut

Run the game with run-optimum.sh in your VS directory, or from the applications menu.

Upgrading

Re-run the same script. It detects the existing version and upgrades in-place.

Legacy Standalone Install

If you have the old standalone Optimum in ~/.local/share/optimum or ~/Games/Optimum, the installer detects it and offers to remove it.

macOS

./scripts/install-macos.sh

The script detects VS in ~/Library/Application Support/vintagestory or /Applications/Vintagestory.app/Contents/MacOS/ and installs Optimum alongside it.

Uninstall

Optimum only touches its own files. Uninstalling restores vanilla completely.

Platform	Method
Windows	Programs & Features → Optimum → Uninstall
Windows	Re-run installer → click Uninstall
Linux/macOS	./scripts/uninstall.sh
Linux/macOS	./scripts/install-linux.sh --uninstall --vs-dir /path
Manual (any)	Delete: Optimum.exe, Optimum.dll, Optimum.deps.json, Optimum.runtimeconfig.json, Optimum.Patcher.dll, VintagestoryLib.Donor.dll, Mono.Cecil*.dll, and the .optimum/ folder

How It Works

You launch Optimum.exe instead of Vintagestory.exe
  → First launch: patches applied via Cecil (~2 seconds), cached to .optimum/cache/
  → Every other launch: cache validated (<10ms), game starts instantly
  → VS updates: cache auto-invalidates, re-patches next launch
  → Failure: launches vanilla Vintagestory.exe with a warning

Data Path

Optimum uses your standard Vintage Story data path. Your worlds, servers, settings, and mods carry over with zero migration. To use a separate data path, pass --dataPath "/path/to/data" to Optimum.exe.

This is Not a Mod

Optimum is not a .dll you drop into the Mods folder. It's a launcher that applies engine-level optimizations before the game starts. It's fully compatible with all mods — they load normally on top of the optimized engine.

Files Installed

File	Purpose
Optimum.exe	Launcher (what you run)
Optimum.dll	Launcher logic (cache, assembly loading)
Optimum.Patcher.dll	Cecil patcher (applies patches)
VintagestoryLib.Donor.dll	Optimized method bodies (source of patches)
Mono.Cecil*.dll	Cecil library (IL manipulation)
.optimum/cache/	Cached patched DLL (auto-generated)
.optimum/optimum.json	Your Optimum settings
.optimum/version	Installed version marker

Total: ~15MB added to your VS directory. Vanilla files remain untouched.