Packaging

Packaging

This page is for developers building release packages. End users just run the installer (see Installation).

What a Release Package Contains

A release package is a self-contained Optimum folder: a fresh copy of a local Vintage Story installation, with the launcher, the Cecil patcher, the runtime donors and the optimized asset overlay added. The engine and built-in mods in that copy stay vanilla — the launcher patches copies of them at startup.

Component	Purpose
Copy of the vanilla install	The game itself, left unmodified
Optimum.exe / Optimum.dll	Launcher: cache validation, splash screen, assembly loading
Optimum.Patcher.dll + Mono.Cecil*.dll	Cecil patcher (transplant, injection, IL hooks)
Optimum.Api.Contracts.dll / Optimum.GameContent.dll	Optimum bridge and runtime mod system
runtimes/<rid>/native/	GLFW and Skia natives for the splash screen
.optimum/donors/	VintagestoryLib.Donor.dll, VintagestoryAPI.Contracts.dll, VSEssentials.Donor.dll, VSSurvivalMod.Donor.dll
.optimum/vanilla/Mods/	Pristine VSEssentials.dll / VSSurvivalMod.dll as patch input
assets/game/shaders/, assets/game/lang/	Optimized shader and Optimum language overlay

Building a Release

make build              # bootstrap + compile donors and launcher
make package            # all targets this host can produce
make package-linux      # tar.gz
make package-appimage   # single .AppImage executable
make package-macos      # .dmg (ARCH=arm64 or x64)
make package-win        # Windows folder + zip (native Windows or WSL)

On Windows, scripts/package.ps1 is the authoritative script: it resolves a local Vintage Story install, runs prepare-runtime-donors.ps1, stages the copy, installs the launcher/patcher/donors, and overlays shaders and lang strings.

Platform Installers

Each platform has an installer script that copies the published files into the user's VS directory:

Script	Platform
scripts/install-windows.ps1	Windows (GUI, Programs & Features)
scripts/install-linux.sh	Linux (interactive terminal)
scripts/install-macos.sh	macOS (interactive terminal)
scripts/uninstall.sh	Linux/macOS removal
scripts/uninstall.ps1	Windows removal

GitHub Release Workflow

Releases are source-only — no binary asset is attached, since Vintage Story is proprietary.

1. Build and verify: make build, make test
2. Tag: git tag -a v0.3.3 -m "Optimum v0.3.3 for Vintage Story 1.22.5"
3. Push: git push --tags
4. gh release create v0.3.3 --title "v0.3.3" --notes-file RELEASE_NOTES.md

Host x Target Matrix

Produce ↓ \ on →	Linux host	macOS host	Windows host
linux-x64	✅ tar.gz / AppImage	✅ tar.gz	✅ tar.gz
osx-x64 / osx-arm64	✅ unsigned .dmg	✅ signed .dmg (hdiutil)	⚠️ .tar.gz fallback
win-x64	✅ WSL, or prefilled official cache	⚠️ prefilled official cache	✅ native

The .dmg files built on Linux are unsigned; macOS Gatekeeper shows a warning on first open, so users right-click > Open to accept. For a notarizable .dmg, build on macOS with an Apple Developer certificate.

ARM note. Vintage Story ships native ARM clients only for macOS (osx-arm64). Linux and Windows have no native ARM client; those packages are x64-only and run on ARM hardware via emulation.