Skip to content

Installation

Jump to bottom
Zaldaryon edited this page Aug 3, 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.

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.
    • If multiple installations are found, pick from the dropdown.
    • If none are found, click Browse to locate your VS folder.
  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 where to install (default ~/.local/share/optimum), and creates a .desktop menu entry, optionally with a desktop shortcut.

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: logs the reason, restores built-in vanilla mods, and exits before the game starts

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