v0.3.14

Optimum v0.3.14

Optimum v0.3.14 targets Vintage Story 1.22.7 and consolidates the fixes merged after v0.3.13 for worldgen safety, chunk lifecycle, installer reliability, shader reloads, and runtime patch validation.

Fixes

• Failed chunk-pool initialization now rolls back cleanly, and chunk readers are disposed during save reload.
• The worldgen safety gate detects Harmony patches on closures and unloads interlock with active worker footprints.
• The map shader cache remains valid through shader reloads, and cloud rendering is retained after resize.
• The patcher tolerates stale or corrupt debug symbols.
• Runtime preflight reuses the configured data path.
• The NixOS installer routes the .NET prerequisite through nixpkgs.
• Packaging supports Inno Setup 6.4.3 and improves package-cache reuse and stale-cache detection.
• VERSION, OptimumConfig.Version, README package examples, and current issue-form examples now use 0.3.14.

Validation

The release tree reports zero build warnings and errors, 666 passing Optimum tests with 34 skips, and 21 passing launcher tests. Clean bootstrap validated 138 patches and applied 116 with zero failures; patch validation reported 68 text patches, 48 Cecil patches, and 22 runtime donors compiled with zero conflicts. Vanilla compatibility reported zero cast divergences, shader validation passed, and the client opened with the expected Game Version: v1.22.7 (Stable) + Optimum v0.3.14 label.

v0.3.13

Optimum v0.3.13

Optimum v0.3.13 targets Vintage Story 1.22.7 and adds shader compatibility reporting plus safer Windows path handling.

New

• The launcher scans installed mod directories and archives for shader paths and render-hook indicators before cache validation.
• The scanner writes .optimum/shader-compatibility.json with source fingerprints, shader owners, conflicts, and disabled optional features.
• The scanner reads metadata and assembly bytes without loading a managed mod assembly. It never replaces a third-party shader.
• Effective shader feature state stays separate from saved preferences. A conflict disables the affected optional feature without rewriting the user's settings.
• A failed scan uses a conservative fallback that keeps the vanilla shader path.
• The API patcher adds ICoreClientAPI.IsTesselationThread(int). Cache validation and launch preflight reject a cached API assembly that lacks the contract.

Fixes

• The Windows installer accepts install and data directories on separate drives.
• The installer rejects drive roots, overlaps with the Vintage Story folder, overlaps with the extracted Optimum workspace, and overlapping install and data paths.
• The installer checks write access before it starts decompilation and packaging.
• The release keeps the prior OIT, shader reload, runtime donor, TerraTag, and type-forward fixes from v0.3.12.

Shader compatibility

The Mod DB shader audit covered 19 shader-tag packages and the three packages named in the Optimum comment thread. Direct shader replacement and shared render-hook packages remain combinations that need a visual test. Natural Foliage stays in the texture-only compatible group.

Validation

The release tree reports zero build warnings and errors, 669 passing tests with 34 skips, 16 passing launcher tests, and 34 passing installer tests. All 14 PowerShell scripts parse on Linux with PowerShell 7. The complete GUI installer still needs a native Windows PowerShell 5.1 host test.

v0.3.12

Fixes the from-source Windows install failing for every user since v0.3.6.

Fixes

• Fixed NETSDK1087 build failure in the runtime donor build (VSEssentials, VSSurvivalMod) on Windows. A PowerShell regex overload ran as replace-all instead of replace-first, duplicating a FrameworkReference item in the generated project file with no error. Multiple users reported this on v0.3.10 and v0.3.11 as "3.11 INSTALL FAILED".
• Fixed the installer hanging at "Setting up build workspace" for several minutes. Robocopy copied hundreds of megabytes of stale build artifacts and local tooling caches into the temporary build folder with no progress output, so a slow copy looked like a frozen installer.
• Fixed Required donor member not found: ChunkMapLayer::coveredPages during the VSEssentials patch step. v0.3.6 renamed the field but left the patcher's injection list pointing at the old name.
• Fixed a MissingMethodException on TyronThreadPool.SetMaxThreadsResult during runtime patch validation. The API patch added thread pool diagnostics properties that the live installer's patcher never wired in.
• Windows CI now runs the actual packaging step (package.ps1) that builds the installed folder, closing the gap that let the NETSDK1087 regression ship in two releases without CI catching it.

Upgrade

Download the source zip below, extract, and re-run your platform installer. Delete any previous .vanilla/ cache to force a clean rebuild.

See the v0.3.12 release notes on the wiki.

v0.3.11

Fixes

• Fixed "Required runtime-donor input not found: ...\AppData\Roaming\runtime-donors\VintagestoryAPI.dll" install failure reported by users on v0.3.10. package.ps1 already isolated -RuntimeDonorDir from the external Vintage Story install path (fixed upstream on 2026-08-14), but that fix never made it into this repo until now.
• Applied the same isolation fix to check-patches.sh.
• Synced this repo up to date with upstream development: scripts/, patches/, sources/, Optimum.Launcher/, Optimum.Patcher/, optimum-api-contracts/, optimum-game-content/.
• Published Optimum.Tests/ and Optimum.Launcher.Tests/ for the first time, plus the CI workflow that runs them.

Validation

• Build: 0 errors
• Tests: 638 pass, 0 fail
• Confirmed the fix is live by re-fetching from GitHub post-push

Upgrade

Download the source zip below, extract, and re-run your platform installer. Delete any previous .vanilla/ cache to force a clean rebuild.

v0.3.10

Fixes

• Synced missing Optimum type source files that caused CS0246 build failures (OptimumBoundedHandoff, OptimumDispatchClaim, OptimumWorkerInstances, OptimumTesselationWorkerRegistry, OptimumWorldgenFootprintLease, OptimumWorldgenFootprintRegistry)
• Removed test project references from VintageStory.slnx that caused MSB3202
• Added VintageStory-core.slnf solution filter for minimal builds
• Icon path fix (moved into Optimum.Launcher/) resolves CS7064 on Windows

Breaking

• Targets Vintage Story 1.22.7 only. Users on 1.22.5 or 1.22.6 must update their game first.

Validation

• Build: 0 errors
• Tests: 638 pass, 0 fail
• Bootstrap: 116 patches, 0 failed

Upgrade

Download the source zip below, extract, and re-run your platform installer. Delete any previous .vanilla/ cache to force a clean rebuild.

v0.3.9

Fixes

• Fixed CS7064 build failure: application icon referenced ../docs/optimum.ico which no longer ships in the source distribution. Icon relocated to Optimum.Launcher/.
• Fixed installer rejecting Vintage Story 1.22.7 (from v0.3.8).

Changes

• Targets Vintage Story 1.22.7 only.
• Tracking hysteresis for entity render/shadow/chisel LOD transitions (from v0.3.8).

Validation

• 638 tests pass, 0 failures.
• Build: 0 errors.

v0.3.8

Changes

• Optimum now targets Vintage Story 1.22.7 only. Players on 1.22.5 or 1.22.6 must update VS first.
• Added tracking hysteresis for entity render distance, shadow cull, and chisel LOD transitions. Entities visible last frame stay visible until exceeding a 10% outer band, preventing flicker at distance boundaries.

Fixes

• Fixed installer rejecting Vintage Story 1.22.7 (forks.json pointed at 1.22.5 in prior releases).
• Fixed CS0012 build failure in runtime donor step (from v0.3.7).

Validation

• 638 tests pass, 0 failures.
• Build: 0 errors.

v0.3.7

Fixes

• Fixed CS0012 build failure in runtime donor step for users with incomplete .NET 10 SDK targeting packs (closes #16).
• Fixed installer rejecting Vintage Story 1.22.7 (forks.json was still pinned to 1.22.5).

Breaking

• Optimum now targets Vintage Story 1.22.7 only. Players on 1.22.5 or 1.22.6 must update VS first.

Validation

• 638 tests pass, 0 failures.
• Build: 0 errors.

v0.3.6

🔖 v0.3.6

Optimum 0.3.6 targets Vintage Story 1.22.7 and fixes community-reported rendering and installer bugs.

Fixes

• Map shader crashes on graphics settings change, Alt+F1 reload, SSAO toggle, or any trigger that calls ShaderRegistry.ReloadShaders(). The instanced-quad map renderer now subscribes to the shader reload event and recreates its program. The Ready guard rejects disposed shader handles.
• TerraTag map overlay incompatibility. The instanced page renderer renders as a background layer, then calls every loaded map component's Render() method. Harmony patches on MultiChunkMapComponent.Render() fire correctly again.
• Dark or transparent rendering at non-native resolution. The OIT system cached a stale framebuffer reference after RebuildFrameBuffers(). It now checks reference identity against the engine's current FBO and recreates textures on the new object.
• Shader errors after window resize or mega screenshot. Same root cause as dark rendering: framebuffer identity check catches the rebuild.
• Windows installer "not of a legal form" error when installing to a bare drive root (e.g. D:\Optimum where the user typed D:). Both the GUI handler and the silent-mode entry point normalize bare drive letters before GetFullPath.
• Runtime TypeLoadException for OptimumBoundedHandoff when entering a world. The api-patcher now injects type-forward metadata (ExportedType rows) into the patched VintagestoryAPI.dll for all types living in Optimum.Api.Contracts.dll. The CLR follows the forward chain without requiring the types compiled into the API assembly.

Known Incompatibility

Coria Ender Shaders patches the same OIT render stage that Optimum guards. The combination crashes with NullReferenceException inside BeforeOIT.OnRenderFrame. Use Ancestral Bliss or Sheyder as shader-mod alternatives.

Validation

The official .NET 10 SDK and ilspycmd 10.1.1.8388 produced the donor tree. Patch validation reported 138 source patches, zero conflicts. The solution built with zero warnings and errors. The test suite passed 631 tests with 34 skips. The runtime patcher applied 126 of 126 required methods and 1 hook. The api-patcher injected 27 type forwards to Optimum.Api.Contracts. Full Linux installation (bootstrap, build, package, install, launch) completed with all 44 shaders compiled and a validated session.

v0.3.5

🔖 v0.3.5

Optimum 0.3.5 continues to target Vintage Story 1.22.5 by default and adds experimental, opt-in support for building and installing against Vintage Story 1.22.6, ahead of Anego publishing matching open-source updates for vsapi/vsessentialsmod/vssurvivalmod.

New

• make bootstrap VERSION=1.22.6 (and install-linux.sh --version 1.22.6, install-windows.ps1 -Version 1.22.6, install-macos.sh with a version-mismatch confirmation) builds and installs Optimum against the real 1.22.6 client. patches-1.22.6-bridge/ reconstructs the confirmed 1.22.6 source-level changes for the three affected fork repos (vsapi, vsessentialsmod, vssurvivalmod) on top of the pinned 1.22.5 refs, plus a one-line version-constant bump (vscreativemod and Cairo need no bridge, confirmed byte-identical to 1.22.6 at the decompiled level). The closed-source engine (VintagestoryLib/Vintagestory) needs no bridging at all: bootstrap.sh/bootstrap.ps1 decompile it fresh from whichever client archive --version/-Version downloads, so it's already 1.22.6-shaped the moment decompilation finishes.
• install-linux.sh prompts for the Vintage Story version interactively when a patches--bridge/ directory offers an alternate to the pinned default, and shows the chosen version in the install summary.
• install-macos.sh (which overlays Optimum's compiled DLLs onto an existing local Vintage Story install rather than downloading one) now detects a version mismatch between that local install and what Optimum was built for, and asks for confirmation before installing a mismatched build instead of doing so silently.
• install-windows.ps1 gained a -Version parameter, threaded through to bootstrap.ps1 and the version-requirement check that previously only accepted the exact version pinned in forks.json with no override. Both the GUI and the headless path now also auto-detect: without an explicit -Version, they build against whichever supported version (pinned or bridge-patched) the locally installed Vintage Story actually is, matching install-linux.sh's existing auto-detection instead of requiring an exact match to the pinned default.
• docs/vintage-story-version-updates.md documents both ways to handle a new Vintage Story release going forward, in order of preference: pin real upstream source once Anego publishes it (always try this first), or bridge-patch from the compiled client as a temporary stopgap (this release's 1.22.6 support).

Fixes

• bootstrap.sh/bootstrap.ps1 no longer silently reuse a stale .vanilla/win-x64 client cached from a previous --version/-Version; the extracted client's own version marker is now checked before reuse, and a mismatch triggers a clean re-extraction.
• package-linux.sh/package-macos.sh had the same stale-cache bug in their own separate per-platform .vanilla caches, with a more serious effect: packaging for a new version after a prior version's package run silently grafted Optimum's patches onto the old version's vanilla VintagestoryLib.dll as the Cecil transplant donor, shipping a client whose engine IL didn't match the version its compiled mod-API assemblies expected. Both scripts now re-extract on a version-marker mismatch, matching the fix already applied to bootstrap.sh.
• check-vanilla-compat.sh no longer asserts a hardcoded game-version string; it now reads the actually-extracted client's own version marker.
• bootstrap.sh's upstream-bridge directory lookup is generic (patches--bridge/) instead of hardcoding 1.22.6, matching a new equivalent implementation added to bootstrap.ps1 (which previously had no bridge-patch support at all - a Windows -Version build of a bridged version would have silently built unpatched, mismatched source).
• install-windows.ps1 silently dropped the real error when the runtime donor build (VSEssentials/VSSurvivalMod) failed, showing only a generic "Runtime donor build failed" message with no compiler output to diagnose it. The install script now streams that output into the log as it happens instead of buffering it until after the (failed) call returns, so the actual dotnet build error is visible.
• Installing to a drive root (C:\Optimum, D:\Optimum) failed at the final cleanup step with "The path is not of a legal form". PowerShell 5.1's Split-Path -Parent strips the trailing backslash from drive roots, turning the parent path into a relative path that Join-Path/New-Item/Move-Item reject. Install-StagedPackage now normalizes that path back to an absolute one, with a regression test covering it.
• prepare-runtime-donors.ps1/.sh wrote the user's Vintage Story install path straight into generated XML for the VSEssentials/VSSurvivalMod runtime donors. An install path containing & (e.g. "C:\Modding & Games...") produced invalid XML, which MSBuild reported as MSB4025 "error occurred while parsing EntityName" and failed the runtime donor build. Both scripts now XML-escape &, <, > in every path written into generated project files.
• A macOS bootstrap downloaded the client archive, then failed on the next line (VintagestoryLib.dll: No such file) because the macOS tarball roots at "Vintage Story.app" instead of "vintagestory" like the Windows/Linux archives. extract_archive now normalises a single extracted root to vintagestory when that directory isn't already present. (#13)
• curl wrote the client and innounp downloads straight to their cache paths, so an interrupted download left a short file that the reuse check only asks whether exists - the next run reported "Using cached" and failed in tar/innounp instead, with nothing pointing at the download. Both downloads now write to a .partial path and move into place only on success; bootstrap.sh also verifies a cached archive reads end to end before trusting it. (#14)

Community contributions

Thanks to @dizzyd for both fixes above:

• #13 - macOS bootstrap archive-root fix
• #14 - atomic client/innounp download, fixing a poisoned-cache bug

Validation

Verified end-to-end on Linux: make bootstrap VERSION=1.22.6 && dotnet build succeeds against the real downloaded 1.22.6 client (95/95 patches applied, 0 build errors, 0 warnings). The packaged install-linux.sh output launches, reaches the login screen with no crash, and completed a real online session (server validation, joined a public multiplayer server, exchanged chat, disconnected cleanly) with no exceptions in client-debug.log or server-debug.log.

Windows and macOS builds are implemented and syntax-validated (pwsh-parsed, bash -n-checked) but not yet retested on those platforms - no Windows or macOS host was available to run them end to end this session.

1.22.5 continues to build and install exactly as before this release (VERSION defaults to forks.json's pinned value).