Skip to content

Installation

Jump to bottom
Zaldaryon edited this page Aug 5, 2026 · 20 revisions

Installation

Optimum is distributed as source, because Vintage Story is proprietary — no game binaries are stored in this repository or produced by CI. The installer builds Optimum against your own Vintage Story installation and produces a self-contained Optimum folder. Your original Vintage Story install is never modified.

When you launch Optimum.exe from that folder, it applies the performance patches to copies of the game's assemblies on first run, and caches the result for instant launches thereafter. Vanilla assemblies on disk are never written.

Requirements

  • A working Vintage Story installation (used as the decompile and packaging source)
  • .NET 10 SDK
  • Git
  • Windows: PowerShell 5.1+ · Linux/macOS: bash, python3, curl, perl

The first build downloads the official client (~570MB) and decompiles it. Subsequent builds reuse the cache.

Vintage Story Version

Optimum targets whichever Vintage Story version it finds installed. Vintage Story 1.22.5 is the default and the fully verified path. Vintage Story 1.22.6 is supported experimentally, ahead of Anego publishing matching open source updates: install Vintage Story 1.22.6 yourself first (Optimum never updates it for you), then run the Optimum installer against that install. The Windows and Linux installers detect the installed version automatically; macOS asks you to confirm it. See Compatibility for details on what "experimental" means here.

Windows (GUI Installer)

  1. Clone the repository: git clone https://github.com/Zaldaryon/Optimum.git
  2. Open the folder.
  3. Double-click install-windows.cmd.
  4. The installer shows a checklist of prerequisites (.NET 10 SDK, Git, ilspycmd, a local Vintage Story install) and offers a Download link for anything missing.
  5. The installer auto-detects your VS installation and builds against whichever supported version (1.22.5 or 1.22.6) it is.
    • If multiple installations are found, pick from the dropdown.
    • If none are found, click Browse to locate your VS folder.
    • If your install is neither 1.22.5 nor 1.22.6, the status line shows a mismatch and Install stays disabled until you point it at a supported one.
  6. Check/uncheck Desktop shortcut and Start Menu options, and choose where to install the built Optimum folder.
  7. Click Install.
  8. Launch via the desktop shortcut, Start Menu, or Optimum.exe in the folder you chose.

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.

Linux

./scripts/install-linux.sh

The interactive installer shows a ✓/✗ checklist of required tools (.NET 10 SDK, bash, python3, git, curl, perl), offers to install anything missing, auto-detects VS installations (common paths, Steam, Flatpak) and shows a numbered list if multiple are found, asks which Vintage Story version to build against (defaults to 1.22.5, offers 1.22.6 when a bridge patch set is available), asks where to install (default ~/.local/share/optimum), and creates a .desktop menu entry, optionally with a desktop shortcut. Pass --version 1.22.6 to skip the prompt.

Run the game from the menu, or with ~/.local/share/optimum/optimum-launch.sh.

Upgrading

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

macOS

git clone https://github.com/Zaldaryon/Optimum.git
cd Optimum
make build
./scripts/package-macos.sh --arch arm64        # Apple Silicon .dmg
./scripts/package-macos.sh --arch x64          # Intel .dmg

Open the .dmg and drag Optimum.app to Applications. Builds on Linux are unsigned; Gatekeeper shows a warning on first open, so right-click > Open to accept.

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 the Optimum install folder. Your original Vintage Story install and your data path (worlds, settings, mods) are untouched.

How It Works

You launch Optimum.exe instead of Vintagestory.exe
  → First launch: a splash screen appears while Cecil patches four assemblies
      VintagestoryLib.dll   (engine transplant: 4 types, 52 methods, 1 IL hook)
      VintagestoryAPI.dll   (API rules: inventory, chisel LOD, chisel shadow, logger, version label)
      Mods/VSEssentials.dll    (runtime donor manifest)
      Mods/VSSurvivalMod.dll   (runtime donor manifest)
    → results cached to .optimum/cache/
  → Every other launch: cache validated, game starts instantly
  → VS or Optimum updates: cache auto-invalidates, re-patches next launch
  → Failure: prints the failed patch, validation, or preflight check, restores built-in vanilla mods, and exits before game startup

If Optimum stops during patching, assembly validation, or JIT preflight, keep the error output and report it with your Optimum and Vintage Story versions. Do not launch through the Optimum shortcut again until the reported error is resolved. You can still start the original Vintage Story executable yourself because Optimum does not change vanilla files.

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

The install folder is a complete, self-contained copy of the game plus:

File Purpose
Optimum.exe Launcher (what you run)
Optimum.dll Launcher logic (cache, assembly loading, splash screen)
Optimum.Patcher.dll Cecil patcher (transplant, injection, IL hooks)
Optimum.Api.Contracts.dll Optimum bridge methods called from patched vanilla code
Optimum.GameContent.dll Optimum runtime mod system (status command, diagnostics)
Mono.Cecil*.dll Cecil library (IL manipulation)
runtimes/<rid>/native/ GLFW and Skia natives for the patch splash screen
.optimum/donors/ Donor assemblies: VintagestoryLib.Donor.dll, VintagestoryAPI.Contracts.dll, VSEssentials.Donor.dll, VSSurvivalMod.Donor.dll
.optimum/vanilla/Mods/ Pristine copies of VSEssentials.dll and VSSurvivalMod.dll used as patch input
.optimum/cache/ Cached patched assemblies (auto-generated)
.optimum/optimum.json Your Optimum settings
Logs/optimum-launcher.log Launcher and patcher diagnostics, rewritten each run

Optimized shaders and the Optimum language strings are overlaid into assets/game/shaders/ and assets/game/lang/ in this folder. Your original Vintage Story installation is not touched.

Clone this wiki locally