Skip to content

User Guide

Jump to bottom
Daniel Nylander edited this page Aug 14, 2026 · 12 revisions

User Guide

Updated for v1.1.126. The launcher caches unchanged data-scan results and asks which verified version to launch when several versions are present.

Captive runtime verification uses the original DOS files through DOSBox-X. The real intro and holomap route-selection boundary are verified; the original runtime still owns arrival, landing and dungeon transitions.

Do not treat a static frame, guessed coordinate, generated route, or debugger register snapshot as a completed Captive transition. Continue only when the original CAPPO runtime visibly reaches destination orbit and produces the real landing and dungeon frames.

System requirements

  • OS: Linux (x86_64), macOS 14+ (Apple Silicon), Windows 10+, Android 8+, iOS 15+
  • Dependencies: SDL3, zlib (bundled in release builds)
  • Game data: original Captive and/or Liberation media files (not included)

Installation

From release packages

Download from GitHub Releases:

Platform Package
Linux (Debian/Ubuntu) opencaptive_X.Y.Z_amd64.deb
Linux (Fedora/RHEL) opencaptive-X.Y.Z.x86_64.rpm
Linux (universal) opencaptive-x86_64.AppImage
macOS (Apple Silicon) OpenCaptive-macos-arm64.dmg
Windows OpenCaptive-X.Y.Z-setup-x64.exe
Android opencaptive-arm64.apk
iOS opencaptive-arm64.ipa

Building from source

Requires CMake 3.20+, a C17 compiler (clang or MSVC), SDL3, zlib and Ninja.

cmake -S . -B build -DCMAKE_C_COMPILER=cc -G Ninja
ninja -C build

Release build:

cmake -S . -B build -DCMAKE_C_COMPILER=cc -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja -C build

Run tests:

ctest --test-dir build -j4 --output-on-failure

Running

Basic usage

opencaptive --data /path/to/your/media
opencaptive --data /path/to/your/media --game captive
opencaptive --data /path/to/your/media --game liberation
opencaptive --data /path/to/your/media --lang sv

Default data paths

  • Linux / macOS: ~/.opencaptive
  • Windows: installdir\data (relative to the installation directory)
  • Android: /sdcard/OpenCaptive
  • iOS: Documents/OpenCaptive

Command-line flags

Game selection

Flag Description
--data <path> Path to game data directory
--game <name> Select game: captive or liberation
--lang <code> Language code (see Internationalization below)
--verify-data <scope> Verify data integrity: captive, liberation, or all

Display settings

Flag Description
--fullscreen Start in fullscreen mode
--scale <N> Window scale factor (1-8, default: 3)
--scanlines Enable scanline effect
--crt Enable CRT curvature effect
--bilinear Enable bilinear texture filtering
--integer-scaling Force integer scaling (default: on)
--no-integer-scaling Allow non-integer scaling
--vsync Enable vertical sync (default: on)
--no-vsync Disable vertical sync
--fps <N> FPS limit: 0 (unlimited), 30, 60, 120 (default: 60)
--brightness <N> Brightness level 0-100 (default: 50)
--contrast <N> Contrast level 0-100 (default: 50)
--renderer <mode> Render mode: original or enhanced
--platform <name> Platform variant: dos, amiga, or atarist

Information

Flag Description
--help, -h Show all available options
--version, -v Show version and author

Start Menu

The start menu uses an 8-item card layout:

Top row: game cards

  • Captive card — click or press Enter to start a new Captive game
  • Liberation card — click or press Enter to start a new Liberation game
  • Each card displays a checkmark (green) if game data passes SHA-256 verification, or a cross (red) if data is missing or fails verification

Continue row

Appears only when save files exist (opencaptive.sav or liberation.sav). Resumes from the most recent save.

Lower rows

  • Settings — opens the 24-item settings panel
  • About — version, credits, and license information
  • Controls — input reference
  • Quit — exit the application

Keyboard shortcuts in the start menu

  • D — opens the Data Scanner (scans the data path, reports ZIP count, per-game SHA-256 verification status)
  • F1 — opens the Controls reference overlay
  • F10 — opens the in-game Runtime Options popup; display changes and optional cheats apply immediately. Use arrow keys and Enter, then F10 or Escape to close.

Settings

The settings panel contains 24 configurable items with vertical scrolling:

Setting Values
Renderer Auto / GPU / Software
Window Size Preset dimensions
Scale 1x through 5x
Fullscreen On / Off
Integer Scale On / Off
VSync On / Off
FPS Limit Unlimited / 30 / 60 / 120
Filtering Nearest / Bilinear
Scanlines On / Off
CRT Curve On / Off
Brightness 0-100%
Contrast 0-100%
Gamma 0-100%
Volume 0-100%
Music On / Off
SFX On / Off
Reverb On / Off
Sample Rate 22050 / 44100 / 48000
Game Speed 50-200%
Mouse Sensitivity 1-10
Data Path Editable text field
Language 19 languages (see below)
Enhanced On / Off
Back Return to start menu

Controls

Movement

Key Action
W / Up Move forward
S / Down Move backward
A / Left Turn left
D / Right Turn right

Combat

Key Action
Space Fire weapon
Enter Use item / interact

User interface

Key Action
Tab Cycle droids
I Inventory
M Minimap
Shift+M City map (Liberation only)

System

Key Action
F5 Save game
F9 Load game
F6 Cycle save slots
F7 Debug HUD
F8 Minimap toggle
F10 Runtime Options: live display effects, overlays, and cheats

Menu and help

Key Action
H Help screen
ESC Pause menu
F1 Controls reference

Speed

Key Action
Numpad + Increase game speed (if enabled)
Numpad - Decrease game speed (if enabled)

Internationalization

OpenCaptive supports 19 languages, selectable via --lang <code> or in the Settings menu:

Code Language
en English
sv Swedish
cs Czech
da Danish
de German
es Spanish
fi Finnish
fr French
hu Hungarian
it Italian
ja Japanese
ko Korean
nl Dutch
no Norwegian
pl Polish
pt Portuguese
ro Romanian
ru Russian
zh Chinese

Game Data

Content identity

OpenCaptive identifies all game files by SHA-256 content hash, never by filename. This means files can have any name and be placed in any directory structure.

Supplying data

Place ZIP archives containing your original game media in the data directory. OpenCaptive transparently scans:

  • ZIP archives (including nested ZIPs)
  • ADF disk images
  • ISO tracks (BIN/CUE)

Verification requirements

Game Verified files needed
Captive 12
Liberation 7

Data Scanner

Press D in the start menu to open the Data Scanner. It scans the configured data path and reports:

  • Number of ZIP archives found
  • Per-game SHA-256 verification status for each required file

CLI verification

opencaptive --data /path/to/media --verify-data all
opencaptive --data /path/to/media --verify-data captive
opencaptive --data /path/to/media --verify-data liberation

Diagnostics

Headless smoke test (Unix):

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
  timeout 5 ./build/opencaptive --data /path/to/media --game captive

The expected result is a timeout exit after the game loop starts, with log lines for texture loading and verified startup.

Captive DOSBox-X verification

Use the original data directory and the repository helper:

tools/run_captive_dosbox_x.sh /path/to/original/captive

Select VGA, click the game viewport, wait for the intro, and use the original keypad controls. Keypad 7 begins transit; wait for the original in-orbit state before keypad 9. A route that only reaches FLIGHT PATH SET is not evidence of arrival. See Captive DOSBox-X Startup for the complete checklist.

When Captive is started from the OpenCaptive menu, the original CAPTIVE.BAT 1 chain runs in a normal DOSBox-X window. DOSBox-X owns the original intro, timer, audio, keyboard and mouse. Debugger/FIFO sessions are for diagnostics only and are not the normal play route.

Clone this wiki locally