FAQ

FAQ

Is this a mod?

No. Optimum is a standalone client. It replaces the engine DLLs, not a zip in your Mods folder.

Do I need to install anything on the server?

No. Optimum works with any server running the matching Vintage Story version.

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 you are unsure; some servers have blanket "no modified clients" policies.

Can I use my existing worlds?

Yes. Optimum reads the same data folder format as vanilla. Point it at your existing data path or let it use the default. You can switch between Optimum and vanilla on the same world without migration.

How do I use a separate data folder?

Three options:

1. Check "Use a separate data folder" in the Windows or Linux installer. The installer writes a datapath.cfg file that the launcher reads on startup.
2. Create a file called datapath.cfg in the Optimum install folder containing one line: the absolute path to your data folder.
3. Launch with --dataPath "/path/to/data" on the command line (takes priority over everything else).

Do I download a prebuilt client?

No. Optimum ships as source. You download the source, run the build script, and the build downloads the official client (~570 MB) on your machine. Optimum itself ships no game files, so the source download is small.

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. Builds produced without an Apple Developer certificate are unsigned. Right-click the app, select Open, confirm the dialog. This happens once.

How do I go back to vanilla?

Run your original Vintage Story client. Your worlds and account stay untouched. Optimum writes settings under Optimum* keys in clientsettings.json; vanilla ignores them. The ModConfig/optimum.json file is also ignored by vanilla.

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 the shader pass reductions. The .optimum status command shows per-optimization hit/skip counters so you can see what helps in your specific scenario.

The installer does not detect Git / .NET / PowerShell even though I installed it.

The installer probes all known locations (Program Files, Scoop, Chocolatey, registry PATH, custom drives). If it still fails, click the "Browse" button next to the failed prerequisite and point it at the folder containing the binary. You may also need to close and reopen the installer after installing a prerequisite (the session PATH updates on restart).

Can I contribute?

The source is GPL-3.0 with the Commons Clause. Pull requests are welcome. Read Building from Source to set up the dev environment.

I got a "Client Thread Crash" on world load with 0.2.1.

Known bug in 0.2.1: the chunkculling thread died on every world load with Field not found: 'ClientWorldMap.chunksLock'. Fixed in 0.2.2. Reinstall from the 0.2.2 release; the broken DLL lives in your install folder, so updating requires a rebuild.

The game crashed at startup with a shader error (e.g. blur.vsh ... unexpected $end).

A partially extracted or corrupted game download poisoned the build cache. Since 0.2.2 the installer detects truncated files, discards the bad extraction, and asks you to re-run. On older versions, delete the .vanilla folder next to the installer (or the Optimum install) and reinstall.

The installer picks the wrong Vintage Story version (I have multiple installs).

Fixed in 0.2.3. The installer now scans all registry entries and common filesystem paths, then picks the install matching the required version. If you have 1.21.x and 1.22.3 side by side, it selects 1.22.3 automatically. If auto-detection still fails (non-standard install path), use the Browse button or pass -VsPath "C:\path\to\your\1.22.3" on the command line.

Build fails with "OptimumConfig does not exist" / "OptimumDiagnostics does not exist".

The GameVersion.cs.patch failed to apply, which blocked the sources overlay step. This happened to users who downloaded the 0.2.2 zip from ModDB before the hotfix landed. Re-download from the GitHub release page or git clone the repo. The 0.2.3 release has the corrected patch.

Temperature shows "°C" instead of "°C".

Fixed in 0.2.2 (hotfix) and included in 0.2.3. The lang file merge step read UTF-8 files through the system codepage on Windows PowerShell 5.1, corrupting non-ASCII characters. The scripts now use explicit UTF-8 encoding on every file read/write.

The game crashes at startup with "blur.vsh ... unexpected $end" even after reinstalling.

The .vanilla cache from a previous install holds a truncated shader that survives reinstalls. Since 0.2.3, the installer validates shader content (not just file size) and discards a corrupt cache automatically. If you hit this on an older version, delete the .vanilla folder next to the Optimum source and re-run the installer.

The handbook crashes or loads blank with many mods (NullReferenceException in GetHeldItemInfo).

Fixed in 0.2.3. A mod's Harmony patch throwing inside GetHeldItemInfo no longer kills the handbook loading thread. The affected item is skipped and the mod named in the client log.

The game crashes when I open Settings (ArgumentException: duplicate key "optimum").

Fixed in 0.2.4. The IL hook that injects the Optimum tab button fired at two sites in the same composition pass, adding the toggle button twice to the same GuiComposer dictionary. The hook now checks whether it already inserted the call before injecting again.

The Linux installer says .NET 10 SDK is missing, but I installed it.

Fixed in 0.2.4. Previous versions only checked the system PATH. If you installed via dotnet-install.sh --install-dir ~/.dotnet without exporting PATH, the installer missed it. It now probes ~/.dotnet, /usr/share/dotnet, /usr/lib/dotnet, and /snap/dotnet-sdk/current in addition to PATH.

Build from source fails with JSON encoding errors on Arch Linux (Makefile path).

Fixed in 0.2.4. The make deploy lang merge used Python open() without an encoding argument. Under a C or POSIX locale (no UTF-8 default), the merge failed or corrupted non-ASCII characters. The Makefile now passes encoding='utf-8-sig' on reads and encoding='utf-8' on writes, matching the packaging scripts.

The 0.2.5 installer failed with ClientLinux.cs: No such file or directory on Windows.

Fixed in 0.2.6. The 0.2.5 datapath.cfg feature patched ClientLinux.cs, a file that only exists when you decompile the Linux client. The Windows client names its entry class ClientWindows, so the patch found no target and the installer aborted. The logic now lives in ClientProgram.Main inside VintagestoryLib, which every platform shares. Update to 0.2.6, or on 0.2.5 rename patches/Vintagestory/ClientLinux.cs.patch to ClientLinux.cs.patch.disabled and re-run the installer (this workaround disables the custom data folder feature).

All 50 patches fail on Windows (0 applied, 50 failed).

Your git has core.autocrlf=true (the Windows default), which converts all checkouts to CRLF. The patches use LF, so every line differs. Fixed in 0.2.7: the bootstrap normalizes line endings in fork checkouts before applying patches. On older versions, run git config --global core.autocrlf false, delete the build folder (C:\opt-bld\Optimum-*), and re-run the installer.