Optimum

Optimum is a high-performance, client-side fork of Vintage Story.

Read the Optimum Privacy Policy for the information handled by the build scripts, installers, launcher, and patcher. The current renderer status and remaining work are tracked in the roadmap.

Features

• Background FPS limiter (30 FPS when alt-tabbed)
• Precise frame pacing (hybrid sleep/yield/spin, fixes stutter)
• Entity shadow distance culling (skip draws beyond 80 blocks)
• Shadow far vegetation skip (skip foliage in far cascade)
• Entity render distance pre-cull (skip render before matrix work)
• Dynamic light radius scaling (35-60 blocks based on view distance)
• Chiseled block LOD (solid cube beyond threshold, 83x vertex reduction)
• Entity repulsion distance gate (skip physics beyond 64 blocks)
• Weather wind throttle (cache lookups for 4 frames)
• Particle distance gate (skip emitters beyond 48 blocks)
• FSR 1.0 upscaling (EASU + RCAS; Quality/Balanced/Performance render scale)
• Smart chunk culling (scale the occlusion-culling threshold with view distance)
• Map page cache (8x8-chunk GPU texture array, single draw call, BC7, disk-persisted)
• Dynamic light scan reuse (reuse the previous frame's scan while standing still)
• Entity light batching (group visible entity light samples per chunk)
• Entity shader state cache (share view/water uniforms and animation UBO per pass)
• Ambient sound position throttling (skip updates when stationary)
• Fly sound volume deduplication (skip updates below 1% change)
• Name-tag frustum reuse (IsRendered flag instead of recomputing)
• Animation check reorder (distance before frustum)
• Lock contention reduction (10 locks to System.Threading.Lock)
• BlockPos reuse in particle ticks (99.9% GC reduction in that path)
• Mouse wheel fix at low sensitivity (#9710)
• Creative search cache crash containment (a mod exception no longer kills the client)
• BFS chunk visibility culling (breadth-first flood over the per-chunk face-connectivity graph, ~5x faster visibility walk)
• GPU indirect draw (glMultiDrawElementsIndirect batching, ~0.05 ms/frame CPU submission)
• SIMD frustum culling (AVX2/NEON acceleration, ~68% elimination rate)
• MeshPart pool (recycles CustomMeshDataPart buffers per chunk, ~88% less per-chunk allocation)
• Item render info reuse (ThreadStatic scratch on the GUI render path, 104 B/slot to 0)
• Ecosystem mod compatibility guard (detects komet, optitime, tungsten, synergy; yields conflicting features automatically)

Some optimizations in this repository do not yet reach the shipped game. The per-patch shipping status is tracked in the release notes for each version.

Getting Started

Optimum supports Windows and Linux; macOS is not supported. The player installer uses an existing Vintage Story installation and a version-matched Optimum delta release to create a separate copy. Release delivery and in-game validation are tracked in the roadmap.

Graphical installer

Optimum.Installer is a cross-platform Avalonia wizard. A publish with the pinned decoder bundle opens the release download route by default: choose an existing matching game folder, select a separate Optimum folder, and install or repair. It checks the downloaded archive and reconstructed files before activating the copy. A locally staged release beside the installer takes priority. Developer builds without a decoder bundle retain the source-build wizard; --developer-build selects it explicitly.

The release-installer.yml workflow packs the Windows and Linux installer builds with Velopack and includes the pinned decoder bundle. Installer assets follow the Optimum-v<version>-<rid>-Installer.<ext> pattern (Optimum-v0.3.17-win-x64-Setup.exe plus a portable zip, Optimum-v0.3.17-linux-x64-Installer.AppImage). Matching delta archives use Optimum-v<optimum-version>-VS<game-version>-<rid>-Delta.zip.

git clone https://github.com/StratumServer/Optimum.git
cd Optimum
make installer-test                 # build and test the installer (no bootstrap)
dotnet run --project Optimum.Installer -c Release

Command line

Optimum.Cli is the same engine without a window, for scripting and CI:

optimum preflight --json                                   # prerequisite report
optimum build --acknowledge-decompile --output /abs/out    # decompile, patch, build, package
optimum build --acknowledge-decompile --acquire-source --output /abs/out # also clone source when outside a checkout
optimum install --package /abs/out/Optimum-v* --install-dir ~/.local/share/optimum
optimum uninstall --install-dir ~/.local/share/optimum

build decompiles your copy of Vintage Story locally and requires --acknowledge-decompile. --acquire-source performs a shallow HTTPS clone at the matching release tag and caches it under the platform's user cache directory. Pass --source-cache <absolute-path> to override the cache root.

The sections below describe the original source-build scripts for developers. They still work, but require build tools and do not use the player release route.

Linux

Interactive installer (guided, checks and installs prerequisites):

git clone https://github.com/StratumServer/Optimum.git
cd Optimum
./scripts/install-linux.sh

The installer shows a ✓/✗ checklist of required tools, offers to install anything missing, asks where to install (default: ~/.local/share/optimum), and creates a menu entry. Run the game from the menu or with ~/.local/share/optimum/optimum-launch.sh.

AppImage (single portable executable, no install):

git clone https://github.com/StratumServer/Optimum.git
cd Optimum
make package-appimage
chmod +x Optimum-v0.3.17-linux-x64.AppImage
./Optimum-v0.3.17-linux-x64.AppImage

If appimagetool is missing, the script downloads it (14MB, once) into .tools/.

Manual build (for development or full control):

git clone https://github.com/StratumServer/Optimum.git
cd Optimum
make check    # report which tools are installed (installs nothing)
make build    # bootstrap + build
make run      # build, deploy, and launch client

Requires .NET 10 SDK, bash, python3, git, curl, perl.

NixOS (non-FHS distribution):

The interactive installer detects NixOS and routes the .NET 10 SDK prerequisite through nixpkgs, since the SDK from dot.net is a glibc build that cannot run there:

nix profile install nixpkgs#dotnet-sdk_10

The packaged launcher and game are glibc binaries as well, so run the AppImage through appimage-run with the runtime dependencies exposed. In the NixOS configuration:

programs.appimage.enable = true;
programs.appimage.binfmt = true;
programs.appimage.package = pkgs.appimage-run.override {
  extraPkgs = pkgs: [
    pkgs.dotnet-runtime
    pkgs.openal
    pkgs.gtk3
  ];
};

Then run the .AppImage normally. dotnet-runtime exposes the .NET runtime for the launcher, and openal and gtk3 cover the game's audio and UI native libraries. Add or remove entries if your build needs a different native set.

Windows

Interactive installer (PowerShell panel; checks prerequisites, offers downloads, choose install folder):

git clone https://github.com/StratumServer/Optimum.git
cd Optimum
.\install-windows.cmd

The installer detects .NET 10 SDK, Git, ilspycmd, and a local Vintage Story install. Missing tools show with a "Download" checkbox that opens the install page. Choose the install directory, click Install. Done.

Manual build (PowerShell):

.\scripts\bootstrap.ps1                        # download, decompile, clone forks, patch
dotnet build VintageStory.slnx -c Release      # compile optimized DLLs
.\scripts\package.ps1                          # build Optimum-v0.3.17-win-x64/ folder
.\scripts\package.ps1 -Zip                     # folder + portable zip

Requires .NET 10 SDK, Git for Windows, and PowerShell 5.1+.

Settings

Optimum persists its runtime settings to ModConfig/optimum.json inside your Vintage Story data path. The file is created with defaults on first run. The .optimum/ directory under the same data path holds launcher state (donor assemblies, the patched-assembly cache, and the shader compatibility report), not user settings.

The data path depends on the platform:

Platform	Data path
Windows	%APPDATA%\VintagestoryData
Linux	~/.config/VintagestoryData

The client reads the file once at startup, so a full restart is required after editing it. When troubleshooting world-generation problems, the four relevant keys are ChunkReadPoolEnabled, ChunkReadPoolWorkers, ChunkDeserializeParallel, and ChunkDeserializeParallelMinY.

On the Vulkan path, connecting an SDL3 controller creates ModConfig/optimum-controllers.json with a separate editable device profile. See controller controls and settings for the current handheld bindings and profile fields.

Experimental Vulkan renderer

The Vulkan backend is opt-in on this branch. Set "Renderer": "vulkan" in the active data path's ModConfig/optimum.json and restart the client. The launcher checks the renderer's Vulkan 1.3 device requirements first and reports a failure before game startup. Optimum --check-vulkan runs that check on its own. The startup log must contain [Optimum] Vulkan renderer; a later window or swapchain failure may still reopen with OpenGL. Set "Renderer": "opengl" to return to the default backend.

Vulkan now uses an SDL3 window and input loop by default, including keyboard, mouse, touch, controller and native IME text input. The startup log reports SDL3 Vulkan window active; no GLFW window. Set OPTIMUM_SDL_WINDOW=0 to use the GLFW Vulkan route for troubleshooting; OpenGL still uses GLFW.

"Taa": true enables temporal antialiasing. With "AmbientOcclusion": "auto", Vulkan selects GTAO while TAA is active and uses the game's SSAO otherwise; OpenGL continues to use the game's SSAO. The TAA sharpen runs after bloom, god rays and final composition. FSR 1's RCAS takes its place when FSR is active. GPU pass timings can be logged with OPTIMUM_VULKAN_PASS_TIMES=1; Vulkan validation can be enabled with OPTIMUM_VULKAN_VALIDATION=1 and OPTIMUM_VULKAN_VALIDATION_FEATURES=sync,best when the validation layer is installed. See Vulkan acceptance for the renderer confirmation, parity and pacing procedures.

Build

Targeting a Vintage Story version

forks.json's vintageStoryVersion picks the default; override per build with VERSION:

make bootstrap VERSION=1.22.7     # official source throughout (default)
make bootstrap VERSION=1.22.6     # decompiles 1.22.6 engine, forks from 1.22.7 source (compatible)
make bootstrap VERSION=1.22.5     # decompiles 1.22.5 engine, forks from 1.22.7 source (compatible)
dotnet build VintageStory.slnx -c Release

When Anego ships a new client version, see docs/vintage-story-version-updates.md for the two ways to target it - bumping forks.json to real upstream source (preferred, always try this first) versus a temporary bridge-patch reconstruction from the compiled client (stopgap, only when upstream source isn't public yet).

Packaging for distribution

The managed patches use platform-agnostic IL. Each package obtains the official client for the target platform, keeps the official files intact, and ships the Optimum launcher, Cecil patcher, runtime donors and optimized shaders. The launcher patches selected assembly copies at startup. A patch reaches players only when a Cecil target, an API rule or a runtime donor manifest owns it.

The complete 0.3.0 shipping inventory appears in docs/patch-shipping-audit-0.3.0.md.

make package              # all targets this host can produce
make package-linux        # tar.gz
make package-appimage     # single .AppImage executable
make package-win          # Windows zip (native Windows or off-platform with innoextract >= 1.11)

Or call the scripts directly:

./scripts/package-linux.sh                     # Optimum-v0.3.17-linux-x64.tar.gz
./scripts/package-linux.sh --format zip
./scripts/package-linux.sh --format appimage   # Optimum-v0.3.17-linux-x64.AppImage
./scripts/package-all.sh                       # all capable targets at once
./scripts/package-all.sh --targets linux-x64

The Linux script renames the launcher to Optimum, repoints run.sh, swaps the window icon, and brands the .desktop entry. Off-Windows Windows packaging downloads the official vs_install_win-x64_<version>.exe into .vanilla/archives/ and extracts it with innoextract 1.11 or newer when no matching .vanilla/win-x64/package-client cache exists. A matching package cache is reused without the extractor, and a fresh extraction leaves the bootstrap/decompile cache at .vanilla/win-x64/vintagestory intact for make run and make patch-il. Pass -ClientArchive to supply the installer when no matching package cache exists.

Host prerequisites for packaging

Beyond the build requirements (.NET 10 SDK, bash, git, curl, perl), packaging needs:

Tool	What it does	Install
appimagetool	Builds .AppImage (downloaded to .tools/ on first use)	auto or sudo apt install appimagetool
pwsh	Windows packaging off-platform (win-x64 target only)	Install PowerShell
innoextract >= 1.11	Extracts the official Inno Setup 6.4.3 Windows client when no matching package cache exists	Current releases (distro 1.9 is too old)
Windows interoperability (wslpath + Windows PowerShell)	Runs the official Inno 6.4.3 installer into a disposable directory when bootstrapping win-x64 from WSL	included with WSL

Linux packaging runs with bash. No PowerShell required for that target.

Host x target matrix

Produce ↓ \ on →	Linux host	Windows host
linux-x64	✅ tar.gz / AppImage	✅ tar.gz
win-x64	✅ pwsh + innoextract >= 1.11, or package-client cache	✅ native

ARM note. Linux and Windows have no native ARM Vintage Story client. Those packages are x64-only; ARM hardware runs them via emulation (box64 on Linux, Windows-on-ARM x64 emulation).

How It Works

Optimum decompiles the official Vintage Story client locally and compiles those sources only as patch donors. It then transplants the tracked changes into the exact official assemblies and writes matching PDBs from the same official DLL/PDB pairs. Your vanilla client or official archive provides the proprietary runtime and assets; no game binaries or symbols are stored in this repository or produced by GitHub CI.

No Harmony overhead. The launcher caches the patched assembly copies for later launches. The game runs native compiled IL.

Acknowledgments

Optimum drew on published techniques from these projects. No source code from any of them appears in this repository; all patches are original implementations against the decompiled vanilla baseline.

• Stratum (MIT) by imtsubaki(tsu), tehtelev, & contributors - multithreaded worldgen architecture, Anego version manifest for downloads, decompile-patch-recompile build model.

License

Optimum is a composite work. Original Optimum tools and project files in LICENSE-SCOPE.md use the MIT License. Patch files, source overlays, and other paths outside that scope retain the historical terms and applicable upstream notices.

Vintage Story and the Anego-derived material remain subject to their upstream terms. See LICENSE, NOTICE, and the preserved historical license in LICENSE-OPTIMUM-LEGACY-GPL-COMMONS.