Skip to content

Packaging

Jump to bottom
Zaldaryon edited this page Jun 26, 2026 · 10 revisions

Packaging

Packaging runs locally on your machine as part of the build. Optimum distributes no packages; the per-platform build scripts call these packaging scripts to assemble a ready-to-run client from the official client you downloaded. The optimized DLLs are platform-agnostic .NET IL, so one build can package for every OS. Each packaging script downloads the official Vintage Story client for the target platform, overlays the optimized DLLs and shaders, and rebrands the launcher.

Local Build Outputs

Output Platform Format
Optimum-v0.1.0-win-x64.zip Windows x64 Portable zip
Optimum-v0.1.0-linux-x64.tar.gz Linux x64 tar.gz
Optimum-v0.1.0-mac-arm64.dmg macOS Apple Silicon DMG (drag-to-Applications)
Optimum-v0.1.0-mac-x64.dmg macOS Intel DMG (drag-to-Applications)

Commands

Build all targets the host is capable of:

make package

Or run individual scripts:

pwsh ./scripts/package-linux.ps1               # tar.gz
pwsh ./scripts/package-linux.ps1 -Format zip   # zip
pwsh ./scripts/package-macos.ps1 -Arch arm64   # Apple Silicon .dmg
pwsh ./scripts/package-macos.ps1 -Arch x64     # Intel .dmg
pwsh ./scripts/package.ps1 -Zip                # Windows zip

Build a subset:

pwsh ./scripts/package-all.ps1 -Targets linux-x64,osx-arm64

Host Prerequisites (Linux)

Beyond the build requirements (.NET 10 SDK, bash, git, curl, perl), full packaging on a Linux host needs:

sudo apt install wine64 hfsprogs libbz2-dev cmake git
Tool Purpose
wine64 Runs innounp.exe to extract the Windows Inno Setup installer
hfsprogs Provides mkfs.hfsplus for creating HFS+ disk images
libbz2-dev Build dependency for libdmg-hfsplus
cmake + git Build libdmg-hfsplus from source (one-time compile into .tools/)

On first .dmg build, the script clones mozilla/libdmg-hfsplus into .tools/ and compiles it. This provides the dmg and hfsplus commands needed to create .dmg files without macOS.

On first Windows package build, the script downloads innounp.exe and runs it via wine to extract the Inno Setup installer into .vanilla-win/.

Host x Target Matrix

Produce ↓ \ on → Linux host macOS host Windows host
linux-x64 tar.gz tar.gz tar.gz
osx-x64 / osx-arm64 unsigned .dmg signed .dmg (hdiutil) .tar.gz fallback
win-x64 zip (wine + innounp) zip (wine + innounp) zip (native)

Unsigned DMG Note

The .dmg files built on Linux are unsigned. macOS Gatekeeper shows a one-time warning on first open. Users right-click the app and select Open to accept it. For a notarizable .dmg, build on macOS with an Apple Developer certificate and run codesign + notarytool.

ARM

Vintage Story ships a native ARM client only for macOS (osx-arm64). Linux and Windows have no native ARM client from upstream. Those packages are x64-only. On ARM hardware, the x64 build runs via emulation (box64 on Linux, Windows-on-ARM x64 layer). The scripts do not produce fake arm64 packages for platforms that lack native arm64 binaries.

What the Overlay Contains

Each locally built package includes your downloaded vanilla client plus these replacements:

  • Vintagestory.dll (patched main client)
  • VintagestoryLib.dll (patched engine)
  • VintagestoryAPI.dll (patched API with OptimumConfig)
  • VSEssentials.dll, VSSurvivalMod.dll, VSCreativeMod.dll (patched game mods)
  • cairo-sharp.dll (Cairo fork)
  • assets/game/shaders/bilateralblur.fsh + .vsh (7-tap SSAO blur)
  • assets/game/shaders/chunkliquid.fsh (3x3 foam grid)
  • Renamed launcher (Optimum / Optimum.exe)
  • Rebranded icon and .desktop entry (Linux) or Info.plist (macOS)

Clone this wiki locally