Skip to content

Packaging

Jump to bottom
Therendyl edited this page Jul 30, 2026 · 10 revisions

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. Update docs/patch-shipping-audit-0.3.0.md if the shipping inventory changed
  3. Tag: git tag -a v0.3.0 -m "Optimum v0.3.0 for Vintage Story 1.22.5"
  4. Push: git push --tags
  5. gh release create v0.3.0 --title "v0.3.0" --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.

Clone this wiki locally