Skip to content

Packaging

Jump to bottom
Zaldaryon edited this page Aug 28, 2026 · 12 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 Installer Scripts

The original per-platform scripts copy the published files into the user's VS directory. The maintained path is the Optimum.Installer wizard and Optimum.Cli (see below).

Script Platform
scripts/install-windows.ps1 Windows (PowerShell panel, 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

Installer Packaging

Optimum.Installer (the Avalonia wizard) and Optimum.Cli are packaged separately from the game folder above.

  • ci-installer.yml builds and tests Optimum.Installer.slnf on every push that touches the installer projects, plus a Velopack pack smoke test.
  • release-installer.yml is workflow_dispatch. It packs self-contained win-x64 and linux-x64 builds with Velopack (an installed copy then updates itself), builds osx-arm64 and osx-x64 for archival, and renames the user-facing assets to Optimum-v<version>-<rid>-Installer.<ext>:
RID Assets
win-x64 Optimum-v<version>-win-x64-Setup.exe, Optimum-v<version>-win-x64-Installer-Portable.zip
linux-x64 Optimum-v<version>-linux-x64-Installer.AppImage
osx-arm64 / osx-x64 Optimum-v<version>-osx-<arch>-Installer.pkg, -Installer-Portable.zip (built, not published)

The .nupkg update payloads and the releases.<channel>.json feed keep their Velopack names. Nothing is code-signed yet, so the Windows Setup.exe trips SmartScreen and the macOS .pkg trips Gatekeeper.

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. Create a signed commit: git commit -S -m "🔖 v0.3.14"
  3. Create a signed tag: git tag -s v0.3.14 -m "Optimum v0.3.14"
  4. Push the branch and tag: git push origin main v0.3.14
  5. Publish the source-only release: gh release create v0.3.14 --title "v0.3.14" --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