FAQ

FAQ

Is this a mod?

No. Optimum is a launcher that applies engine-level optimizations via Cecil before the game starts. It's not a .dll in your Mods folder. Your existing mods load normally on top of the optimized engine.

Do I need to install anything on the server?

No. Optimum is client-only and works with any server running the matching Vintage Story version.

Do I need to build from source?

Yes, but the installer does it for you. Vintage Story is proprietary, so Optimum cannot legally ship game binaries — releases are source-only. Clone the repository and run the installer for your platform; it checks prerequisites, downloads and decompiles the official client, applies the patches, compiles, and installs the result. You need the .NET 10 SDK, Git, and an existing Vintage Story install. See Installation.

Will I get banned for using Optimum?

Optimum does not give gameplay advantages. It renders the same world the same way, faster. Server admins cannot detect it because it does not modify network behavior. Check your server's rules if unsure; some servers have blanket "no modified clients" policies.

Can I use my existing worlds?

Yes. Optimum uses the same data folder as vanilla. Your worlds, servers, settings, and mods carry over with zero migration. You can switch between Optimum and vanilla on the same world.

How do I use a separate data folder?

Launch with --dataPath "/path/to/data" or create a datapath.cfg file in the VS directory containing the absolute path on one line.

Does Optimum modify my game files?

No. The installer builds a separate, self-contained Optimum folder and leaves your original Vintage Story installation exactly as it was. Inside that folder, the engine and built-in mod assemblies also stay vanilla on disk — Optimum patches copies of them into .optimum/cache/ at launch. Deleting the Optimum folder removes Optimum completely.

What happens when Vintage Story updates?

The cache auto-invalidates because the vanilla DLL hash changes. On the next Optimum launch, the patcher re-applies optimizations to the new DLL. If the new VS version changes internals that break the patcher, Optimum records the failure, restores built-in vanilla mods, and exits before the game starts. Check Logs/optimum-launcher.log for the reason.

Does Optimum work on ARM Linux / ARM Windows?

The build targets x64 on Linux and Windows because Vintage Story has no official ARM client for those platforms. On ARM hardware, the x64 build runs via emulation (box64 on Linux, Windows-on-ARM). macOS Apple Silicon uses the native osx-arm64 client.

The macOS build gives a Gatekeeper warning.

Expected for unsigned builds. Right-click the app, select Open, confirm the dialog. This happens once.

How do I go back to vanilla?

Launch Vintagestory.exe instead of Optimum.exe. Or uninstall Optimum (Programs & Features on Windows, ./scripts/uninstall.sh on Linux/macOS). Your worlds and account stay untouched.

How much FPS improvement should I expect?

Depends on your hardware, view distance, and scene complexity. Frame pacing improvements reduce stutter on any hardware. CPU-bound players with high entity counts benefit from the distance gates. GPU-bound players benefit from FSR and shader reductions. The .optimum status command shows per-optimization counters.

The first launch is slow. Is that normal?

Yes. On first launch (or after a VS or Optimum update), Optimum applies Cecil patches to VintagestoryLib.dll, VintagestoryAPI.dll, VSEssentials.dll and VSSurvivalMod.dll, showing a splash screen while it works. The result is cached, so every subsequent launch is instant.

I had Optimum 0.2.x. Do I need to do anything?

Yes. Optimum 0.3.3 uses the runtime launcher introduced in the 0.3.x series. Older 0.2.x installations shipped pre-patched game assemblies. Remove the old Optimum installation and run the 0.3.3 installer fresh. Your worlds, settings and mods live in the shared Vintage Story data path and carry over untouched.

The installer doesn't find my VS installation.

Click Browse and manually select the folder containing Vintagestory.exe. On Linux, pass --vs-dir /path/to/vs. Common locations: %APPDATA%\Vintagestory (Windows), ~/.local/share/vintagestory (Linux), ~/Library/Application Support/vintagestory (macOS).

Can I contribute?

Yes. The source is GPL-3.0 with the Commons Clause. Pull requests are welcome. See Building from Source and CONTRIBUTING.md.

I got a crash at startup with "Field not found" or "Method not found".

The cached DLL may be stale. Delete .optimum/cache/ in your VS directory and relaunch — Optimum will re-patch cleanly. If it persists, the Optimum version may be incompatible with your VS version. Check the Releases page for the correct version.

The Extra tab is missing and the version label says plain "v1.22.5".

That means patching failed and the launcher stopped before the game started. Check Logs/optimum-launcher.log in your data path for Launch aborted and the failure reason. Deleting .optimum/cache/ and relaunching forces a clean re-patch.