Repack Mode

Repack Mode

Repack compresses a complete game directory into a standalone installer exe. The end user runs it on a clean machine — no previous game installation required.

---

Compression

LZMA (--codec lzma, default)

Quality key	Description
fast	lzma2-1 — fastest, largest output
normal	lzma2-6 — balanced
max	lzma2-9 — best compression (default)

• 1 thread: uses stdlib lzma (no external dependencies)
• >1 threads: delegates to the xz CLI with --block-size=64MiB so the installer can decompress each block independently across multiple cores

Zstandard (--codec zstd)

Quality key	Description
fast	zstd-1 — fastest
normal	zstd-9 — balanced
max	zstd-19 — best compression
ultra	zstd-22 — maximum compression

• Delegates to the zstd CLI for both single and multi-threaded compression

Installation performance

The installer uses lzma_stream_decoder_mt (liblzma 5.3+) to decompress LZMA streams across all available CPU cores, taking advantage of the independent 64 MB blocks produced by the multi-threaded encoder. ZSTD decompression is single-threaded (ZSTD frames have inter-block dependencies that prevent parallel decoding).

Checking Reduce system load in the installer UI drops the decoder to 1 thread, which is recommended for HDDs to avoid seek thrashing.

---

Large game support

Archives exceeding 3.5 GB auto-split into a base_game.bin sidecar alongside the exe, keeping the exe itself well under the 4 GB FAT32 file size limit. --split-bin forces the split regardless of size.

All sidecar files must be distributed alongside the exe.

Multi-part splits

For distribution on file hosts with upload size caps (e.g. a 2 GB limit), --max-part-size-mb MB splits base_game.bin into fixed-size parts named <name>_base_game.bin.001, .002, ... at build time. The installer reads across parts seamlessly — end users just have to place all .NNN files in the same folder as the exe. If any part is missing at install time, the installer displays which part number is missing.

A CRC32 of every part is embedded in the metadata and verified before decompression starts. If a part is corrupted in transit or partially downloaded, the installer refuses to proceed and tells the user exactly which part number to re-download, instead of failing with a cryptic mid-decompression error.

---

Optional Components

Each component is a folder of files merged on top of the base game during install. Components are shown to the user as:

• Checkboxes — when the group field is blank (independent, togglable)
• Group header + radio buttons — when two or more components share the same group name; the group header is a checkbox that enables or disables the whole group, and the radio buttons beneath it are mutually exclusive within the group

Each component's uncompressed size is displayed next to its label (e.g. "High-res textures (2.1 GB)"). Radio group headers show "(up to X.X GB)" — the largest option in the group, since only one is ever installed.

Components can declare requires dependencies on other components (by 1-based index); the installer auto-enables required components and greys out unavailable ones. Transitive chains (A requires B requires C) are fully resolved — checking A automatically pulls in B and C. Components with sac_warning: true display an amber warning banner when selected, useful for components that may trigger antivirus or Windows Smart App Control. Components with external: true are stored in a separate .bin sidecar file; all components sharing the same group go into the same sidecar.

Up to 16 components are supported.

See CLI-Reference for the full component JSON field reference.

---

Silent Install

The installer supports headless operation:

MyGame_installer.exe /S              # silent install to default path
MyGame_installer.exe /S /D=C:\Games  # silent install to a custom path

/D must be the last argument if used. No UI is shown; the installer exits with code 0 on success and non-zero on failure.

---

Repair / Reinstall Detection

If the installer detects an existing installation (via the registry key), it offers two options:

• Repair — re-extracts only files that fail CRC verification; skips files that are intact
• Reinstall — re-extracts all files unconditionally

---

Repack Project Files (.xpr)

All repack settings are saved as a JSON file. Example:

{
  "app_name": "My Game",
  "app_note": "Complete Edition",
  "version": "1.0",
  "description": "Full game installer",
  "copyright": "© 2025 My Company",
  "contact": "support@example.com",
  "company_info": "My Company",
  "window_title": "My Game Installer",
  "installer_exe_name": "",
  "installer_exe_version": "1.0.0.0",
  "game_dir": "/path/to/game_files",
  "output_dir": "dist/",
  "arch": "x64",
  "codec": "lzma",
  "compression": "max",
  "threads": 8,
  "icon_path": "assets/icon.ico",
  "backdrop_path": "assets/backdrop.jpg",
  "install_registry_key": "SOFTWARE\\MyCompany\\MyGame",
  "run_after_install": "",
  "detect_running_exe": "MyGame.exe",
  "close_delay": 0,
  "required_free_space_gb": 0.0,
  "include_uninstaller": true,
  "verify_crc32": true,
  "shortcut_target": "Bin\\MyGame.exe",
  "shortcut_name": "My Game",
  "shortcut_create_desktop": false,
  "shortcut_create_startmenu": true,
  "components": [
    {
      "label": "High-res textures",
      "folder": "/path/to/hires_textures",
      "default_checked": false,
      "group": "",
      "requires": [],
      "shortcut_target": "",
      "sac_warning": false,
      "external": false
    }
  ]
}