UFOpaedia - User contributions [en]

Installing (OpenApoc)

2026-03-01T23:32:12Z

Deldonut1: Major rewrite: updated installation steps for current releases; added GOG and Steam instructions; added troubleshooting

'''Installing (OpenApoc)''' covers how to download, install, and run [https://github.com/OpenApoc/OpenApoc OpenApoc] on Windows, Linux, and macOS. OpenApoc is an open-source reimplementation of [[Apocalypse|X-COM: Apocalypse]] and requires the original game files to play.

'''Note:''' OpenApoc is currently in '''alpha''' state. Expect bugs, crashes, and incomplete features. Please report issues on the [https://github.com/OpenApoc/OpenApoc/issues bug tracker].

== System Requirements ==

* '''Video card''': OpenGL 2.0 compatible
* '''Original game files''': X-COM: Apocalypse (from [https://store.steampowered.com/app/7660/XCOM_Apocalypse/ Steam], [https://www.gog.com/game/xcom_apocalypse GOG], or the original retail CD)
* '''Windows only''': Latest [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist Visual C++ Redistributable]

=== Supported Platforms ===

* Windows (x64)
* Linux
* macOS (including Apple Silicon)

== Downloading OpenApoc ==

=== GitHub Releases (Recommended) ===

The primary download location for OpenApoc is the '''[https://github.com/OpenApoc/OpenApoc/releases GitHub Releases]''' page. This provides the latest official Windows builds.

# Visit [https://github.com/OpenApoc/OpenApoc/releases https://github.com/OpenApoc/OpenApoc/releases]
# Download the appropriate installer or zip package
# Run the installer and follow the prompts

'''Note:''' Linux and macOS users must compile from source. See '''[[Compiling (OpenApoc)]]''' for instructions.

=== AppVeyor CI Builds (Experimental) ===

For users who want the very latest (and potentially unstable) development builds, experimental Windows x64 builds are available from AppVeyor:

# Visit [https://ci.appveyor.com/project/OpenApoc/openapoc/history https://ci.appveyor.com/project/OpenApoc/openapoc/history]
# Look for a build with a '''green''' bar indicating a successful build (use "Show More" to list additional builds if needed)
# Click on the green build entry
# Click '''ARTIFACTS'''
# Download the file ending in <code>.exe</code> that does '''not''' contain "debug" in the filename
# Run the downloaded installer

'''Warning:''' AppVeyor CI builds are experimental and may contain untested changes. Only Windows x64 builds are available from AppVeyor. For stable releases, use GitHub Releases instead.

== Setting Up Original Game Files ==

OpenApoc requires the original X-COM: Apocalypse game data to run. The game files must include the '''music tracks'''; pirated or incomplete disc images that are missing music will cause problems such as crashes and map issues.

=== Steam ===

# Locate your Steam installation of X-COM: Apocalypse
#* The default path is typically: <code>C:\Program Files (x86)\Steam\steamapps\common\X-COM Apocalypse</code>
# Find the <code>cd.iso</code> file in the Steam installation directory
# Copy <code>cd.iso</code> into the OpenApoc <code>data</code> folder

'''Note:''' On Linux, the Steam version of X-COM: Apocalypse will only install if '''Steam Play''' (Proton) is enabled.

=== GOG ===

The GOG version provides the game data as <code>.cue</code> and <code>.bin</code> files. These require a specific setup:

# Locate the GOG installation directory for X-COM: Apocalypse
# Find the <code>XCOM.cue</code> and <code>XCOM.BIN</code> files
# '''Rename''' <code>XCOM.cue</code> to <code>cd.iso</code>
# Place the renamed <code>cd.iso</code> file into the OpenApoc <code>data</code> folder
# Place <code>XCOM.BIN</code> into the OpenApoc <code>data</code> folder '''without renaming it'''

Both files (<code>cd.iso</code> and <code>XCOM.BIN</code>) must be present in the <code>data</code> folder for the GOG version to work correctly.

=== Original Retail CD ===

# Create an ISO disc image from your original X-COM: Apocalypse CD-ROM
#* You can use tools such as [https://www.imgburn.com/ ImgBurn] (Windows) or <code>dd</code> (Linux/macOS) to create the image
# Rename the resulting image file to <code>cd.iso</code>
# Place <code>cd.iso</code> into the OpenApoc <code>data</code> folder

=== Alternative: Specify Location During Installation ===

If you use the Windows installer, you may specify the location of <code>cd.iso</code> during the installation process. In that case, you do not need to manually copy the file into the <code>data</code> folder.

== Running OpenApoc ==

=== Windows ===

After installation, run OpenApoc from the Start Menu shortcut or from the installation directory. Ensure that:

* The <code>data</code> folder (containing <code>cd.iso</code>) is present in the OpenApoc installation directory (unless you specified a different location during install)
* The latest [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist Visual C++ Redistributable] is installed

=== Linux ===

Linux does not have prebuilt packages; you must compile from source (see '''[[Compiling (OpenApoc)]]'''). After building, run the executable from the repository root so that it can find the <code>data</code> folder:

./build/bin/OpenApoc

=== macOS ===

macOS does not have prebuilt packages; you must compile from source (see '''[[Compiling (OpenApoc)]]'''). After building, run the application from the repository root:

open ./build/bin/OpenApoc.app

== Portable Installation ==

The Windows installer offers a '''portable install''' option. When selected, all save games and configuration settings are stored within the installation directory rather than in your user profile. This is useful if you want to:

* Run OpenApoc from a USB drive or external storage
* Keep multiple independent installations with separate settings
* Easily back up or move your entire OpenApoc setup including saves

To use portable mode, select the "portable install" option when running the installer.

== Post-Installation Configuration ==

OpenApoc stores its settings in a file named <code>OpenApoc_settings.conf</code>. For portable installations, this file is located in the installation directory. For standard installations, it is located in your user profile directory.

You can create or edit this file to configure common settings. Below are some useful options.

=== Changing Language to English ===

If OpenApoc displays blank buttons or garbled text because your system language is not English, you can force English by adding the following to <code>OpenApoc_settings.conf</code>:

<pre>
[Framework]
Language=en_GB.UTF-8
</pre>

Restart OpenApoc after saving the file.

=== Fullscreen Mode ===

To run OpenApoc in fullscreen at a specific resolution, add the following to <code>OpenApoc_settings.conf</code>:

<pre>
[Framework.Screen]
Width=1920
Height=1080
Fullscreen=1
</pre>

Adjust the <code>Width</code> and <code>Height</code> values to match your monitor's resolution.

=== Skipping the Intro Movie ===

To skip the intro movie on startup, add the following to <code>OpenApoc_settings.conf</code>:

<pre>
[Game]
SkipIntro=1
</pre>

== Updating OpenApoc ==

When updating to a newer version of OpenApoc, it is recommended to install to a '''new folder''' rather than overwriting the existing installation. In-place updates may cause issues. After verifying that the new version works correctly, you can delete the old installation folder.

Your save games and settings will be preserved if you are using a standard (non-portable) installation, since they are stored in your user profile directory.

== Troubleshooting ==

=== Blank Buttons in the Interface ===

This is a known issue that can occur when your system's native language is not English. OpenApoc has translations in multiple languages, but not all fonts are available yet. To fix this:

* Set the language to English using the <code>OpenApoc_settings.conf</code> file as described in the [[#Changing Language to English|Post-Installation Configuration]] section above
* Check the [https://github.com/OpenApoc/OpenApoc/issues bug tracker] for the latest status of this issue

=== Crashes or Map Problems ===

If you experience crashes at startup or broken maps during gameplay:

* Verify that your <code>cd.iso</code> is a complete copy of the original game including all music tracks
* Incomplete or pirated disc images that are missing music are known to cause these issues
* Re-acquire the game files from a legitimate source (Steam, GOG, or original CD)

=== GOG Version Not Working ===

If the GOG version does not load correctly:

* Ensure you have '''both''' <code>cd.iso</code> (the renamed <code>XCOM.cue</code>) and <code>XCOM.BIN</code> in the <code>data</code> folder
* Ensure <code>XCOM.BIN</code> has '''not''' been renamed

=== Missing Visual C++ Runtime (Windows) ===

If OpenApoc fails to start on Windows with errors about missing DLLs:

* Download and install the latest [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist Visual C++ Redistributable] from Microsoft

=== Getting Help ===

If you encounter issues not covered here:

* Search the [https://github.com/OpenApoc/OpenApoc/issues bug tracker] for known issues
* Join the [https://discord.gg/f8Rayre OpenApoc Discord] server, which is the most active community hub for support and discussion

== See Also ==

* [[Compiling (OpenApoc)]] - Building OpenApoc from source code
* [[Controls (OpenApoc)]] - Keyboard and mouse controls
* [[Coding Style (OpenApoc)]] - Development coding standards
* [[Differences to X-COM (OpenApoc)]] - How OpenApoc differs from the original game
* [[Credits (OpenApoc)]] - Project contributors
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] - Source code repository

[[Category:OpenApoc]]

Modding (OpenApoc)

2026-03-01T23:21:22Z

Deldonut1: New page: comprehensive modding guide covering XML data patching, Lua scripting API, mod loading system, save editing, and community resources

{{DISPLAYTITLE:Modding (OpenApoc)}}

'''Modding''' is a core design goal of [[OpenApoc]]. Nearly every aspect of the game — weapons, vehicles, organisations, research, maps, difficulty settings, economy, and more — is defined in human-readable XML data files that can be overridden or extended by mods. OpenApoc also includes a '''Lua scripting''' system that allows mods to hook into game events and alter game logic at runtime.

This page covers the mod system architecture, the data file format, savegame editing, Lua scripting, configurable mod options, and how to create your own mods.

== Mod System Overview ==

OpenApoc loads game data in layers. The base game data is extracted from the original X-COM: Apocalypse CD image, then OpenApoc's own data patches are applied on top, and finally any enabled mods are loaded in order. Each layer can add new data or override existing values from previous layers.

=== How Mods Are Loaded ===

Mod loading is controlled by two configuration options (found in <code>settings.cfg</code> or set via the launcher):

* '''<code>Game.Mods</code>''' — A colon-separated list of mod directory names to load (relative to the mod directory). Default: <code>base</code>
* '''<code>Game.ModPath</code>''' — The directory containing all mods. Default: <code>./data/mods</code>

When the game starts, it iterates through the mod list in order. For each mod it:

# Reads <code>modinfo.xml</code> from the mod's root directory
# Appends the mod's '''data path''' to the virtual filesystem (making the mod's resources available and able to override earlier files)
# Loads the mod's '''game state''' (XML data that gets merged into the running GameState)
# Loads any '''language patches''' applicable to the current locale
# Executes the mod's '''load script''' (a Lua script run when the mod is first loaded)

Because mods are loaded in the order specified, later mods override earlier ones. The <code>base</code> mod is the foundation and should generally always be listed first.

=== The Launcher ===

The OpenApoc Launcher (a Qt-based GUI) includes a '''Mods''' tab that lets you enable and disable mods without manually editing configuration files. It scans the <code>data/mods/</code> directory for subdirectories containing a valid <code>modinfo.xml</code> and displays them in two lists: enabled mods and disabled mods. You can move mods between the lists and reorder them.

== The modinfo.xml File ==

Every mod must contain a <code>modinfo.xml</code> file in its root directory. This file describes the mod's metadata and tells OpenApoc how to load it. Here is the structure, using the base game mod as an example:

<pre>
<?xml version="1.0"?>
<openapoc_modinfo>
<name>OpenApoc base game</name>
<author>OpenApoc team</author>
<version>0.1</version>
<description>The base OpenApoc game</description>
<link>http://www.openapoc.org</link>
<id>org.openapoc.base</id>
<datapath>data</datapath>
<statepath>base_gamestate</statepath>
<minversion></minversion>
<modloadscript>scripts/org.openapoc.base/onload.lua</modloadscript>
<requires />
<conflicts />
<languages>
<entry>
<ID>en.UTF-8</ID>
<patch></patch>
<data>lang/data/en.UTF-8</data>
</entry>
</languages>
</openapoc_modinfo>
</pre>

=== Field Reference ===

{| class="wikitable"
! Field !! Description
|-
| <code>name</code> || The human-readable name of the mod, displayed in the launcher.
|-
| <code>author</code> || The author(s) of the mod.
|-
| <code>version</code> || A version string (any format; purely informational).
|-
| <code>description</code> || A short description of what the mod does.
|-
| <code>link</code> || A URL for the mod's homepage, forum thread, etc.
|-
| <code>id</code> || A '''unique''' identifier for the mod. Use a reverse-DNS-like format to avoid conflicts, e.g. <code>org.openapoc.mod.YOUR_USERNAME.YOUR_MOD</code>.
|-
| <code>datapath</code> || Path (relative to the mod directory) to a folder whose contents are added to the virtual filesystem. Files here can override any game resource (images, sounds, forms, etc.).
|-
| <code>statepath</code> || Path (relative to the mod directory) to a folder or ZIP archive containing XML game state data to merge into the GameState.
|-
| <code>minversion</code> || The minimum version of OpenApoc required to run this mod (currently informational).
|-
| <code>modloadscript</code> || Path to a Lua script that is executed when the mod is loaded (after game state is merged).
|-
| <code>requires</code> || A list of mod IDs that this mod depends on. Listed as <code><entry>mod.id</entry></code> elements.
|-
| <code>conflicts</code> || A list of mod IDs that this mod is incompatible with.
|-
| <code>languages</code> || Language-specific data and translation patches. Each entry has an <code>ID</code> (locale), optional <code>patch</code> (game state overlay for that language), and optional <code>data</code> (additional data path for that language).
|}

== Data File Structure ==

OpenApoc organises its data in the <code>data/</code> directory. Understanding this structure is essential for modding.

=== Top-Level Directories ===

{| class="wikitable"
! Directory !! Contents
|-
| <code>data/common_patch/</code> || The core game state patch: XML files defining all game objects (weapons, vehicles, organisations, research, etc.). This is the primary source of moddable game data.
|-
| <code>data/difficulty0_patch/</code> through <code>data/difficulty4_patch/</code> || Difficulty-specific overrides applied on top of the common patch. Each corresponds to a difficulty level (0 = Easiest, 4 = Hardest).
|-
| <code>data/resource_patch/</code> || Additional resource patches.
|-
| <code>data/city/</code> || City-related image resources (map overlays, UI elements, building indicators).
|-
| <code>data/battle/</code> || Battle-related data and resources.
|-
| <code>data/maps/</code> || Map data files.
|-
| <code>data/tilesets/</code> || Tileset definitions for map rendering.
|-
| <code>data/forms/</code> || XML UI form definitions (the layout of menus, screens, and dialogs).
|-
| <code>data/fonts/</code> || Font data files.
|-
| <code>data/imagepacks/</code> || Sprite and image pack data.
|-
| <code>data/animationpacks/</code> || Unit animation pack data.
|-
| <code>data/bulletsprites/</code> || Projectile sprite images.
|-
| <code>data/languages/</code> || Translation files for localisation.
|-
| <code>data/scripts/</code> || Lua scripts loaded by the engine (see [[#Lua Scripting|Lua Scripting]]).
|-
| <code>data/mods/</code> || The mods directory, containing all installed mods.
|-
| <code>data/ui/</code> || UI image resources.
|}

=== Game State XML Files ===

The game state is defined by a hierarchy of XML files rooted at <code>gamestate.xml</code>. The root file uses XInclude (<code>xi:include</code>) to pull in individual data files for each object type. The key files in <code>common_patch/gamestate/</code> are:

{| class="wikitable"
! File !! Contents
|-
| <code>agent_equipment.xml</code> || Agent (soldier) weapons, armour, grenades, equipment, and their stats (damage, accuracy, range, weight, etc.).
|-
| <code>agent_types.xml</code> || Agent type definitions (X-COM agents, aliens, civilians, building security, etc.).
|-
| <code>agent_body_types.xml</code> || Physical body type definitions for agents.
|-
| <code>agent_generator.xml</code> || Rules for procedurally generating agents (name lists, stat ranges).
|-
| <code>vehicle_types.xml</code> || Vehicle type definitions (stats, images, type classification such as Road, Flying, ATV, UFO).
|-
| <code>vehicle_equipment.xml</code> || Vehicle weapons and modules (lasers, missiles, engines, shields, etc.).
|-
| <code>vehicle_ammo.xml</code> || Vehicle ammunition definitions (ammo types, capacities, costs).
|-
| <code>organisations.xml</code> || Organisation definitions (Megapol, Marsec, Cult of Sirius, etc.), including their relationships, guard types, and hireable agent types.
|-
| <code>facility_types.xml</code> || Base facility definitions (labs, workshops, living quarters, stores, etc.).
|-
| <code>research.xml</code> || The research tree: topics, dependencies, costs, and what they unlock.
|-
| <code>damage_types.xml</code> || Damage type definitions and damage modifiers.
|-
| <code>ufopaedia.xml</code> || UFOpaedia article definitions and categories.
|-
| <code>ufo_growth_lists.xml</code> || UFO spawning rules per week, controlling the alien invasion progression.
|-
| <code>ufo_incursions.xml</code> || UFO incursion event definitions.
|-
| <code>ufo_mission_preference.xml</code> || UFO mission target preferences.
|}

The root <code>gamestate.xml</code> also contains inline data for game-wide settings such as:

* <code>weekly_rating_rules</code> — Score thresholds that affect government funding changes
* <code>agent_salary</code> — Weekly salary per agent role (Soldier, Physicist, BioChemist, Engineer)
* <code>initial_agents</code> — Number of agents per role at game start
* <code>initial_facilities</code> — Starting base facilities
* <code>initial_agent_equipment</code> — Equipment loadouts for starting agents
* <code>initial_vehicles</code> — Starting vehicles and their equipment
* <code>initial_vehicle_equipment</code> and <code>initial_vehicle_ammo</code> — Spare vehicle equipment and ammo in starting base storage

=== XML Data Format ===

Game state data uses a consistent key/value format. Collections are stored as lists of <code><entry></code> elements, where each entry has a <code><key></code> and a <code><value></code>. The key is a unique string identifier (e.g. <code>VEHICLETYPE_PHOENIX_HOVERCAR</code>, <code>AEQUIPMENTTYPE_MEGAPOL_LASER_SNIPER_GUN</code>).

To override an existing object, you only need to provide the key and the specific fields you want to change. Fields you omit will retain their original values. For example, to change only the manufacturer of the Dimension Probe vehicle:

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<vehicle_types>
<entry>
<key>VEHICLETYPE_DIMENSION_PROBE</key>
<value>
<name>Dimension Probe</name>
<manufacturer>ORG_X-COM</manufacturer>
</value>
</entry>
</vehicle_types>
</pre>

== Savegame Editing ==

One of OpenApoc's key features is its human-readable save game format. All save games are stored as '''XML files inside a ZIP archive''' (with a <code>.zip</code> extension, though they may not have one if unpacked saving is enabled).

=== Save Location ===

By default, saves are stored in the <code>./saves/</code> directory relative to the OpenApoc installation. This can be changed via the <code>Game.Save.Directory</code> configuration option.

=== Save Format ===

The <code>Game.Save.Pack</code> option (default: <code>true</code>) controls whether saves are packed into ZIP archives or saved as a directory of loose XML files. When packed:

* The save file is a standard ZIP archive
* Inside it are multiple XML files following the same structure as the game state data (one XML file per object category)
* The XML files use the same format as the data patches (described above)

=== Editing a Save ===

To edit a saved game:

# Locate the save file in the saves directory
# If it is a ZIP file, extract it using any ZIP-compatible tool (7-Zip, WinRAR, the built-in OS extractor, etc.)
# Edit the desired XML files with a text editor
# If you extracted a ZIP, re-compress the files back into a ZIP archive with the same name
# Load the modified save in OpenApoc

Alternatively, you can set <code>Game.Save.Pack</code> to <code>false</code> in <code>settings.cfg</code>. This causes saves to be written as directories of loose XML files, which makes editing easier since you do not need to extract and repack a ZIP.

Common things to edit in saves include:

* Organisation relationships (in the organisations data)
* Agent stats and equipment
* Vehicle loadouts and positions
* Player funds
* Research progress

'''Tip:''' OpenApoc also supports optional CRC and SHA1 checksums on save files (controlled by <code>Framework.Serialization.CRC</code> and <code>Framework.Serialization.SHA1</code>). If these are enabled, manually editing a save file will invalidate the checksum. By default, both are disabled.

== Lua Scripting ==

OpenApoc integrates '''Lua''' (bundled as a dependency) as a scripting language. Lua scripts can hook into game events, modify game state at runtime, and implement complex game logic that would be difficult to express in static XML data.

=== How Scripts Are Loaded ===

Scripts are loaded via the <code>OpenApoc.Mod.ScriptsList</code> configuration option. This is a '''semicolon-separated''' list of Lua script paths (resolved through the virtual filesystem). The default value is:

<pre>
scripts/openapoc_base.lua;
</pre>

When the game state is initialised, each script in this list is executed in order. Scripts can use the standard Lua <code>dofile()</code> function to include additional scripts.

Additionally, each mod can specify a <code><modloadscript></code> in its <code>modinfo.xml</code>. This script is executed after the mod's game state has been loaded and merged.

=== The OpenApoc Lua API ===

Scripts have access to a global <code>OpenApoc</code> table that provides:

* '''<code>OpenApoc.GameState</code>''' (aliased as <code>GS</code> in the base script) — Direct access to the full game state, including:
** <code>GS.vehicle_types</code> — All vehicle type definitions
** <code>GS.agent_equipment</code> — All agent equipment definitions
** <code>GS.organisations</code> — All organisation definitions
** <code>GS.vehicle_equipment</code> — All vehicle equipment definitions
** <code>GS.vehicle_ammo</code> — All vehicle ammo definitions
** <code>GS.cities</code> — City data
** <code>GS.vehicles</code> — Active vehicle instances
** <code>GS.agents</code> — Active agent instances
** <code>GS.economy</code> — Economy data for all items
** <code>GS.ufo_growth_lists</code> — UFO growth/spawning rules
** <code>GS.gameTime</code> — Current game time
** <code>GS.rng</code> — The game's random number generator
** <code>GS.player</code> — Reference to the player organisation
** <code>GS.difficulty</code> — Current difficulty level (0-4)
** <code>GS.agent_generator</code> — The agent generator (can create new agents)

* '''<code>OpenApoc.Framework</code>''' (aliased as <code>FW</code>) — Framework functions:
** <code>FW.LogInfo(message)</code> — Log an informational message
** <code>FW.LogWarning(message)</code> — Log a warning
** <code>FW.LogError(message)</code> — Log an error

* '''<code>OpenApoc.Framework.Config</code>''' (aliased as <code>CFG</code>) — Configuration access:
** <code>CFG.getBool('Section.Key')</code> — Read a boolean config value
** <code>CFG.getInt('Section.Key')</code> — Read an integer config value
** <code>CFG.getString('Section.Key')</code> — Read a string config value
** <code>CFG.getFloat('Section.Key')</code> — Read a float config value
** <code>CFG.describe('Section', 'Key')</code> — Get the description of a config option

* '''<code>OpenApoc.enum</code>''' — Game enumerations (e.g. <code>OpenApoc.enum.VehicleType.Type.ATV</code>, <code>OpenApoc.enum.VehicleType.Type.Road</code>, <code>OpenApoc.enum.VehicleType.Type.UFO</code>)

=== Hooks ===

The scripting system uses a hook-based architecture. Scripts register functions in <code>OpenApoc.hook</code> that the engine calls at specific points during gameplay. The available hooks are:

{| class="wikitable"
! Hook Name !! When It Is Called
|-
| <code>newGame</code> || When a new game is started (before initial state setup).
|-
| <code>newGamePostInit</code> || After the new game's initial state has been fully set up (registered in the base Lua script, not called directly by C++; chained from <code>newGame</code> flow).
|-
| <code>applyMods</code> || When mod-related game state changes should be applied (e.g. toggling vehicle types based on config options).
|-
| <code>updateEndOfDay</code> || At the end of each in-game day.
|-
| <code>updateEndOfWeek</code> || At the end of each in-game week (used for economy updates and UFO growth).
|}

Scripts should chain hooks rather than replace them, preserving any previously registered hook:

<pre>
local oldHook = OpenApoc.hook.updateEndOfWeek
OpenApoc.hook.updateEndOfWeek = function()
if oldHook then oldHook() end
-- your custom logic here
end
</pre>

=== Base Scripts ===

The default <code>scripts/openapoc_base.lua</code> script and its included files implement core game mechanics:

* '''<code>openapoc_base.lua</code>''' — The main script. Provides utility functions (<code>pickRandom</code>, <code>math.clamp</code>, <code>math.round</code>), seeds the RNG on new game start, applies mod options (ATV vehicle types, brainsucker launcher sound, crashing vehicles), spawns developer Easter egg agents, and chains weekly update hooks.
* '''<code>update_economy.lua</code>''' — Implements the weekly economy update (item stock fluctuation and price changes, based on Wong's guide).
* '''<code>update_ufo_growth.lua</code>''' — Implements weekly UFO growth/spawning in the alien dimension, respecting per-week growth lists and vehicle limits.

=== Mod Load Scripts ===

The base mod's load script (<code>scripts/org.openapoc.base/onload.lua</code>) demonstrates how a mod load script works:

<pre>
local OA = OpenApoc
local GS = OpenApoc.GameState
local FW = OpenApoc.Framework

FW.LogInfo("On load script called")

local gamestateString = "submods/org.openapoc.base/difficulty" .. tostring(GS.difficulty)
FW.LogInfo("Loading difficulty patch" .. gamestateString)

GS.appendGameState(GS, gamestateString)

FW.LogInfo("Finished loading difficulty patch")
</pre>

This script uses the current difficulty level to load a difficulty-specific game state patch from a submod directory, allowing different difficulty settings to override game data (such as organisation relationships, city layouts, and alien forces).

=== RNG Methods ===

The random number generator (<code>GS.rng</code>) exposes the following methods for use in Lua scripts:

{| class="wikitable"
! Method !! Description
|-
| <code>GS.rng:randBoundsInclusive(min, max)</code> || Returns a random integer in the range [min, max] (both endpoints included).
|-
| <code>GS.rng:randBoundsExclusive(min, max)</code> || Returns a random integer in the range [min, max) (max excluded).
|-
| <code>GS.rng:seed(value)</code> || Seeds the random number generator with the given value.
|}

Example usage from the base scripts:

<pre>
-- Pick a random element from a Lua table
function pickRandom(t)
return t[GS.rng:randBoundsInclusive(1, #t)]
end

-- Seed the RNG on new game start
GS.rng:seed(os.time())
</pre>

=== GameTime Methods ===

The game time object (<code>GS.gameTime</code>) exposes the following read-only methods:

{| class="wikitable"
! Method !! Returns
|-
| <code>GS.gameTime:getHours()</code> || Current hour of the day
|-
| <code>GS.gameTime:getMinutes()</code> || Current minute of the hour
|-
| <code>GS.gameTime:getDay()</code> || Current day number
|-
| <code>GS.gameTime:getWeek()</code> || Current week number
|}

=== GameState and Object Methods ===

Beyond data access, several game objects expose methods that can be called from Lua scripts:

{| class="wikitable"
! Method !! Description
|-
| <code>GS:appendGameState(path)</code> || Load and merge additional game state XML from the given path into the current GameState. Used by the base mod to apply difficulty patches.
|-
| <code>GS:loadGame(path)</code> || Load a saved game from the given path.
|-
| <code>city:placeVehicle(vehicleType, owner)</code> || Place a new vehicle of the given type in the city, owned by the specified organisation.
|-
| <code>city:placeVehicleInBuilding(vehicleType, owner, building)</code> || Place a new vehicle at a specific building.
|-
| <code>city:placeVehicleAtPosition(vehicleType, owner, position, facing)</code> || Place a new vehicle at specific XYZ coordinates with an optional facing angle.
|-
| <code>agent_generator:createAgent(orgRef, agentTypeRef)</code> || Create a new agent of the given type, hired by the specified organisation. Returns a StateRef to the new agent.
|-
| <code>agent:enterBuilding(buildingRef)</code> || Move an agent into the specified building.
|}

=== The StateRef Pattern ===

When accessing game objects from Lua, it is important to understand the '''StateRef''' pattern. OpenApoc objects exposed to Lua are '''not''' standard Lua tables — they are C++ objects with a custom interface. This has several implications:

* '''Iterating collections:''' Use <code>pairs()</code> to iterate game state collections. The loop yields <code>(id_string, object)</code> pairs:

<pre>
for vt_id, vt_object in pairs(GS.vehicle_types) do
-- vt_id is the string key (e.g. 'VEHICLETYPE_PHOENIX_HOVERCAR')
-- vt_object is the vehicle type object
vt_object.type = OA.enum.VehicleType.Type.ATV
end
</pre>

* '''Passing references to C++ functions:''' StateRefs must be passed as '''strings''' (the object's ID), not as object references:

<pre>
-- Correct: pass the string ID
agent.object:enterBuilding(building.id)
agent.object.homeBuilding = building.id

-- NOT: agent.object:enterBuilding(building.object)
</pre>

* '''Debugging:''' The standard <code>table.dump()</code> function will not work on OpenApoc objects since they are not actual Lua tables. Use <code>FW.LogInfo()</code> to print individual fields instead.

=== Utility Functions ===

The base script (<code>openapoc_base.lua</code>) provides several utility functions that are available to all mod scripts, since it loads first:

{| class="wikitable"
! Function !! Description
|-
| <code>pickRandom(table)</code> || Returns a random element from a Lua table, using the game's RNG for deterministic replay.
|-
| <code>math.clamp(v, min, max)</code> || Clamps a value between min and max.
|-
| <code>math.round(v)</code> || Rounds a number to the nearest integer.
|-
| <code>table.dump(t, nesting)</code> || Debug function that prints a table's contents. Note: does '''not''' work on OpenApoc objects.
|}

== Mod Options ==

OpenApoc provides several configurable options in the '''More Options''' menu under the <code>OpenApoc.Mod</code> section. These are options that can meaningfully change gameplay balance and are considered "mod-like" changes:

{| class="wikitable"
! Option !! Type !! Default !! Description
|-
| <code>MaxTileRepair</code> || Integer || 5 || Maximum number of scenery tiles that Construction Vehicles will repair per night.
|-
| <code>SceneryRepairCostFactor</code> || Float || 10.0 || Percentage of the original price organisations must pay for scenery tile repairs.
|-
| <code>StunHostileAction</code> || Boolean || false || Whether stunning an organisation's units counts as a hostile action (hurts relationships).
|-
| <code>RaidHostileAction</code> || Boolean || false || Whether initiating a raid on a building counts as a hostile action (hurts relationships).
|-
| <code>BSKLauncherSound</code> || Boolean || true || Use the original Brainsucker Launcher sound effect (instead of the generic powers sound).
|-
| <code>InvulnerableRoads</code> || Boolean || false || Makes road scenery tiles indestructible.
|-
| <code>ATVTank</code> || Boolean || true || Makes the Griffon AFV an All-Terrain Vehicle (can travel on roads and fly).
|-
| <code>ATVAPC</code> || Boolean || true || Makes the Wolfhound APC an All-Terrain Vehicle.
|-
| <code>CrashingVehicles</code> || Boolean || false || Vehicles crash when their HP drops below 1/7 of maximum (weapons and modules may be lost).
|-
| <code>ScriptsList</code> || String || <code>scripts/openapoc_base.lua;</code> || Semicolon-separated list of Lua scripts to load at game initialisation.
|}

These options are applied at runtime through the Lua scripting system (in the <code>applyMods</code> hook), so their effects take place each time a game is loaded or started. This means you can change these options between play sessions without starting a new game.

== Creating a Mod ==

=== Basic Steps ===

# '''Create a mod directory''' inside <code>data/mods/</code>. Choose a descriptive name (e.g. <code>my_balance_mod</code>).
# '''Create a <code>modinfo.xml</code>''' file in your mod's root directory (see the [[#The modinfo.xml File|modinfo.xml reference]] above).
# '''Choose a unique ID''' for your mod using reverse-DNS format: <code>org.openapoc.mod.your_name.mod_name</code>.
# '''Create a data directory''' (referenced by <code><datapath></code> in your modinfo.xml) for any resource overrides.
# '''Create a game state directory''' (referenced by <code><statepath></code>) containing XML files that override or extend the base game state.
# '''Optionally create Lua scripts''' for dynamic logic (referenced by <code><modloadscript></code>).
# '''Enable your mod''' by adding its directory name to the <code>Game.Mods</code> option (colon-separated), or by enabling it in the launcher.

=== Mod Directory Structure ===

A typical mod directory might look like this:

<pre>
data/mods/my_mod/
modinfo.xml -- Mod metadata and configuration
my_gamestate/ -- Game state overrides (referenced by <statepath>)
gamestate.xml -- Root game state file with xi:include references
gamestate/
agent_equipment.xml -- Override agent equipment stats
vehicle_types.xml -- Override vehicle stats
organisations.xml -- Override organisation data
data/ -- Data path overrides (referenced by <datapath>)
scripts/
my_mod/
onload.lua -- Mod load script
submods/
my_mod/
custom_patch/ -- Additional game state that can be loaded by scripts
</pre>

=== Tips ===

* You only need to include the XML fields you want to change. Unspecified fields retain their original values.
* Use the <code>common_patch/gamestate/</code> files as a reference for available fields and their expected format.
* The game state is loaded cumulatively: the base data is loaded first (from the original CD and the extractor), then <code>common_patch</code>, then difficulty patches, then mods in order. Your mod's changes are layered on top of all previous data.
* Files in your mod's <code><datapath></code> directory override files with the same relative path from earlier in the load order. This lets you replace images, sounds, form definitions, and other resources.
* Test changes incrementally. Start by modifying a single value (e.g. a weapon's damage) and verify it works before making larger changes.
* Keep your mod's files under a directory named after your mod ID to avoid filename conflicts with other mods.

== Examples ==

=== Changing a Weapon's Stats ===

To increase the damage of the Megapol Laser Sniper Gun, create a file in your mod's game state directory:

<pre>

<?xml version="1.0" encoding="UTF-8"?>
<agent_equipment>
<entry>
<key>AEQUIPMENTTYPE_MEGAPOL_LASER_SNIPER_GUN</key>
<value>
<damage>40</damage>
<accuracy>85</accuracy>
</value>
</entry>
</agent_equipment>
</pre>

=== Making a Vehicle All-Terrain via Lua ===

The base game already demonstrates this pattern. In your mod's Lua script:

<pre>
local OA = OpenApoc
local GS = OpenApoc.GameState

local oldApplyMods = OpenApoc.hook.applyMods
OpenApoc.hook.applyMods = function()
if oldApplyMods then oldApplyMods() end

-- Make the Phoenix Hovercar an ATV
GS.vehicle_types['VEHICLETYPE_PHOENIX_HOVERCAR'].type = OA.enum.VehicleType.Type.ATV
end
</pre>

=== Modifying Organisation Relationships ===

To change starting organisation data, override the organisations XML:

<pre>

<?xml version="1.0" encoding="UTF-8"?>
<organisations>
<entry>
<key>ORG_MEGAPOL</key>
<value>
<average_guards>15</average_guards>
</value>
</entry>
</organisations>
</pre>

=== Adding a Weekly Event via Lua ===

<pre>
local OA = OpenApoc
local GS = OpenApoc.GameState
local FW = OpenApoc.Framework

local oldWeekHook = OpenApoc.hook.updateEndOfWeek
OpenApoc.hook.updateEndOfWeek = function()
if oldWeekHook then oldWeekHook() end

local week = GS.gameTime:getWeek()
FW.LogInfo("Custom mod: Week " .. tostring(week) .. " has ended!")
-- Add your custom weekly logic here
end
</pre>

=== Modifying Equipment Sets and Starting Loadouts ===

The <code>common_patch/gamestate.xml</code> file defines <code>initial_agent_equipment</code>, <code>initial_vehicles</code>, and <code>initial_vehicle_equipment</code>. You can override these in your mod to give the player different starting equipment, vehicles, or base facilities.

== The Base Mod ==

The <code>base</code> mod (<code>data/mods/base/</code>) is OpenApoc's foundational mod that ships with the game. It provides:

* '''Game state data''' in <code>base_gamestate/</code> (the initial game state loaded on top of the extracted CD data and common patches)
* '''Music playlists''' in <code>data/playlists/</code> (city, tactical, action, and alien dimension music)
* '''Difficulty submods''' in <code>data/submods/org.openapoc.base/</code> (difficulty0 through difficulty4, loaded dynamically based on the selected difficulty)
* '''A mod load script''' (<code>data/scripts/org.openapoc.base/onload.lua</code>) that applies difficulty-specific patches at load time
* '''Language support''' with locale-specific data paths

The base mod should generally always be enabled and listed first in the mod load order, as other mods are designed to layer on top of it.

== Community Research Findings ==

The following sections contain additional modding knowledge gathered from the OpenApoc Discord community. These insights supplement the official documentation above and reflect practical experience from active modders and contributors.

=== Data File Architecture and Load Order ===

The XML data system uses a strict layered loading architecture where order matters:

# '''Generated data''' — Extracted from the original CD ISO by the extractor tools.
# '''<code>common_patch</code>''' — Applied on top of generated data, providing OpenApoc's baseline corrections and additions.
# '''Difficulty-specific patch''' (<code>difficulty0_patch</code> through <code>difficulty4_patch</code>) — Overrides for the selected difficulty level.
# '''Mod patches''' — Loaded in the order specified by <code>Game.Mods</code>.

'''Critical caveat''': Difficulty patches load AFTER mods in the current architecture. This means mods cannot directly override difficulty-specific values through XML alone. The workaround is to use '''Lua <code>onload</code> scripts''' (as demonstrated by PR #783) which execute at load time and can programmatically apply difficulty-aware changes. The base mod already uses this pattern to load difficulty patches via <code>onload.lua</code>.

=== The gamestate_common Archive ===

The <code>gamestate_common</code> file is a '''ZIP archive with no file extension'''. This catches many new modders off guard. To inspect or edit it, either:

* Open it directly with 7-Zip (which recognises the ZIP signature regardless of extension).
* Rename it to <code>gamestate_common.zip</code> and open with any ZIP tool.

The same applies to difficulty-specific archives (e.g., <code>difficulty0_patched</code>, <code>difficulty1_patched</code>, etc.).

=== Key XML Files Reference ===

Beyond the table in the [[#Game State XML Files|Game State XML Files]] section, these files are particularly important for modding:

{| class="wikitable"
! File !! Modding Use
|-
| <code>economy.xml</code> || Controls the market: item availability, base prices, stock levels, and weekly fluctuation.
|-
| <code>equipment_sets_by_level.xml</code> || Defines human tech loadouts per game progression level (what equipment organisations use as the game advances).
|-
| <code>equipment_sets_by_score.xml</code> || Defines alien loadouts per difficulty level. Found in the <code>difficulty''X''_patched</code> archives rather than in <code>common_patch</code>.
|}

=== The modinfo.xml System ===

The mod system (introduced in PR #725) uses '''additive patching'''. When creating a mod, your XML files should only include the specific values you want to CHANGE. You do not need to reproduce the entire structure of the file you are patching. Unspecified fields retain their values from the previous layer.

=== Image and Sound Overrides via datapath ===

A mod's <code><datapath></code> entry in <code>modinfo.xml</code> adds a directory to the virtual filesystem. Files placed here can override any game resource — images, sounds, form definitions, etc. — by mirroring the original ISO's directory structure. For example, to replace a weapon sprite, place your replacement image at the same relative path the game expects within your mod's data directory.

=== SerializationTool for Delta Patches ===

The '''SerializationTool''' (in the <code>tools/</code> directory) can generate minimal delta patches between two game states. This is useful for creating mods that only contain the differences from a base state, rather than duplicating entire data files.

=== Sound Format Support ===

OpenApoc supports the following sound formats for modding:

* '''Raw PCM audio''': Referenced as <code>RAWSOUND:samplerate:path</code> (e.g., <code>RAWSOUND:22050:sounds/myeffect.raw</code>).
* '''WAV''': Standard WAV files.
* '''OGG Vorbis''': Compressed audio via libvorbis.

=== Palette System ===

The game uses different palette systems in different contexts:

* '''Cityscape''': Uses a 3-palette blend system that transitions between day, twilight, and night palettes based on the time of day.
* '''Battlescape''': Uses a static palette. A dynamic palette system was planned but ultimately cut from the implementation.

Modders creating custom sprites should be aware of which palette context their assets will be used in.

=== Armour Stat Mapping ===

When modding armour pieces, each armour slot maps to a specific agent stat bonus:

{| class="wikitable"
! Armour Slot !! Stat Affected
|-
| Legs || Speed
|-
| Arms || Accuracy
|-
| Helmet || Reactions
|-
| Chest || Bravery
|}

=== Sprite Workflow and Asset Creation ===

Creating a single new weapon item is a significant undertaking. Community estimates suggest approximately '''12 hours of work''', of which only about 15 minutes is XML editing. The remaining time is spent on sprite creation. A complete weapon requires:

* '''Equip screen icon''' — The inventory sprite shown in the equipment screen.
* '''Dropped/thrown sprites''' — Sprites for the item when on the ground or in flight.
* '''Shadow sprites''' — Corresponding shadow sprites for dropped/thrown states.
* '''Handob sprites''' — The weapon as held by an agent, requiring sprites for each facing direction.
* '''UFOpaedia image''' — The full-size reference image displayed in the in-game encyclopedia.

=== Common Modding Pitfalls ===

The following issues are frequently encountered by new modders:

* '''CRC check errors''': If <code>Framework.Serialization.CRC</code> is enabled, manually editing <code>gamestate_common</code> or save files will invalidate the checksum. Disable CRC checking in <code>settings.cfg</code> when modding.
* '''Case sensitivity in file paths''': Some platforms (especially Linux) are case-sensitive in file path resolution. Ensure your file references match the actual case exactly.
* '''<code>op='delete'</code> deletes the WHOLE list''': The XML <code>op='delete'</code> attribute removes the entire list element, not just a single entry. There is currently no mechanism to delete individual entries from a list — you can only replace the entire list.
* '''Duplicate objects from serialization''': When creating new objects via mods, ensure unique keys. Duplicate keys can cause the serialization system to create duplicate entries with unpredictable behavior.
* '''New game required''': Always start a '''new game''' when changing mod XML data. Saves embed the game state at save time, so loading an old save will not pick up your XML changes.
* '''Mod requires/conflicts not enforced''': The <code><requires></code> and <code><conflicts></code> fields in <code>modinfo.xml</code> are defined in the format but not yet enforced by the engine. Version checking (<code><minversion></code>) is also informational only.

=== Damage Type Limitations ===

Damage types are currently '''hardcoded''' in the engine. There is no modding capability for defining custom damage types. The available damage types are those defined in <code>damage_types.xml</code>, but their underlying behavior (penetration logic, resistance calculations, special effects like fire or stun) is implemented in C++ code.

=== Additional Known Limitations ===

* '''Physics and radii''': Vehicle and projectile physics radii values are not moddable through XML or Lua.
* '''Organisation long-term relationships''': Only short-term relationship values are exposed in the game state. Long-term relationship tracking is not currently available for modding.

== Map Modding Tools ==

While OpenApoc does not yet include a built-in map editor, several community tools exist for creating and editing maps:

* '''XME (Xenonaut Map Editor)''' — The primary tool for editing cityscape and alien dimension maps. Latest version: 095b1 (beta 1.0).
* '''TacEdit''' — A tool for validating that tactical maps are correctly structured and will load properly.
* '''A-Patcher''' — A hex-patching tool that can enable the hidden built-in map editor in the original X-COM: Apocalypse executable. Useful for creating maps compatible with OpenApoc's map format.

== Community Mods ==

The following mods serve as references for what OpenApoc's modding system can accomplish:

* '''[https://github.com/OpenApoc/extended_weapons_mod Extended Weapons Mod (EWM)]''' by filmboy84 — The primary test platform for OpenApoc's modding system. Includes weapons ported from UFO: Enemy Unknown and Terror from the Deep, new alien types, over 2,000 additional agent names, and various balance adjustments.
* '''[https://github.com/Jarskih/openapoc-balance-mod OpenApoc Balance Mod]''' by Jarskih — Difficulty and balance adjustments.

These mods are useful references for modders looking for real-world examples of mod structure, XML patching, and Lua scripting.

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Differences to X-COM (OpenApoc)]] — How OpenApoc differs from the original game
* [[Installing (OpenApoc)]] — Installation instructions
* [[Compiling (OpenApoc)]] — Building from source
* [[Hidden Features (OpenApoc)]] — Hidden features and debug commands
* [[Apocalypse]] — The original X-COM: Apocalypse
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/modding.md OpenApoc Wiki: Modding] — Extended modding documentation

[[Category:OpenApoc]]

Coding Style (OpenApoc)

2026-03-01T23:05:58Z

Deldonut1: Re-add 9 coding conventions from CODE_STYLE.md that were missing: comments style, trivial one-line functions, ownership guidance, static_assert, iterator exception, forward declaration limits, Yoda conditionals, numeric_limits, short variable names

{{DISPLAYTITLE:Coding Style (OpenApoc)}}
This document specifies the guidelines for writing and formatting the C++ code that forms the core of '''[[OpenApoc]]'''.

OpenApoc uses '''C++17'''. This requires reasonably modern compilers ('''GCC 8+''', '''MSVC 2019+''', '''Clang 7+''' have been tested). You should avoid using compiler-specific extensions where possible. Exceptions exist, but should be wrapped in an <code>#ifdef</code>.

Code formatting is enforced by '''[https://clang.llvm.org/docs/ClangFormat.html clang-format]''' (version '''18'''). The configuration file <code>.clang-format</code> in the root of the OpenApoc source repository defines the project style.

Static analysis is enforced by '''[https://clang.llvm.org/extra/clang-tidy/ clang-tidy]''' (version '''18'''). The CI pipeline rejects unformatted code and code that fails tidy checks.

It is highly recommended to run <code>clang-format</code> on all modified files before committing:

<pre>clang-format -i path/to/file.cpp path/to/file.h</pre>

When run from the root of the OpenApoc source repository, it automatically uses the supplied <code>.clang-format</code> configuration file.

When using the CMake build system, there are dedicated targets:

<pre>
# Format all source files (from build directory)
cmake --build build -t format-sources

# Run static analysis (from build directory)
cmake --build build -t tidy
</pre>

== Indent ==

* Tabs for indenting, spaces for alignment, indenting by 1 tab for each new scope

<pre>
void function()
{
reallyLongFunctionNameWithLotsOfArguments(argOne, argTwo,
argThree);
}
</pre>

* Avoid going over '''100 columns''' (at tab width of 4 spaces)
** If you find yourself going over this, it's often a hint to try to pull things out of loops / into functions
** Don't break strings up to fit this; it looks ugly and makes things harder to read
* If you have to break, indent the following line by an extra tab
** When breaking a single statement, break the line '''before''' the next operator. Avoid having an operator as the last thing on a line.

<pre>
void reallyLongFunctionNameIMeanThisIsReallyBadlyNamed(int parameterOne,
int paramTwo, char theThirdOne)
{
if (parameterOne == yetAnotherReallyLongCondition
&& youHaveBetterThingsToDo)
{
doWhatever();
}
}
</pre>

== Whitespace ==

* Spaces before and after operators

<pre>
a = b;
a && b;
a + b;
</pre>

* Space after <code>if</code>/<code>while</code>/<code>else</code>/<code>for</code>, space after <code>:</code>/<code>;</code> in <code>for</code>

<pre>
for (auto &a : b)
</pre>

* No spaces after function name (or function-like keywords like <code>sizeof</code>), but space after flow control keywords, space after comma for multiple arguments

<pre>
func(a, b);
if (a == 0)
</pre>

* References and pointers: <code>&</code> and <code>*</code> align right (to the variable), not to the type

<pre>
float *pointerToFloat;
Type &ref;
</pre>

== Scope ==

* Indent 1 tab for each new scope
* New scope is '''always''' surrounded by <code>{}</code> braces, even for single-statement blocks
* Opening brace <code>{</code> goes on the '''next''' line at the indent of the enclosing scope ('''Allman style''')
* Closing brace <code>}</code> at the same indent as the opening <code>{</code>
* New scopes are caused by:
** Functions
** Conditional blocks (<code>if</code>/<code>else</code>/<code>while</code>/<code>for</code>)
** <code>switch</code>/<code>case</code>

<pre>
void functionDefinition()
{
newScopeHere();
}
</pre>

<pre>
if (x)
{
doWhatever();
}
else if (y)
{
doWhateverTheSecond();
}
else
{
doThatLastThing();
}
</pre>

* <code>switch</code> always has a <code>default</code> case unless switching over an <code>enum class</code> where every value is handled
* All <code>case</code> sections should have a <code>break</code>
* <code>case</code> braces <code>{}</code> are optional, based on whether new stack variables are needed

<pre>
switch (a)
{
case A:
doSomething();
break;
case B:
{
auto newVariable = getSomething();
useIt(newVariable);
break;
}
default:
break;
}
</pre>

* '''Exception''': Trivial functions (a single statement fitting within 100 columns) may use the definition and body on one line:

<pre>
int getX() const { return x; }
</pre>

This is enforced by <code>clang-format</code> (<code>AllowShortFunctionsOnASingleLine: All</code>).

== Naming ==

{| class="wikitable"
! Style !! Used For
|-
| <code>CamelCase</code> || Classes, enums, <code>enum class</code> members, namespaces, template parameters
|-
| <code>camelBack</code> || Methods, member variables, function parameters, local variables
|-
| <code>SHOUTY_CAPS</code> || Constants, macros
|-
| <code>lower_case</code> || Labels
|}

Short variable names (<code>i</code>, <code>x</code>, <code>y</code>) are fine when the meaning is obvious from context.

== Types ==

* Use <code>auto</code> liberally, especially when the type is obvious from the right-hand side. Use <code>auto &</code> to avoid copies.
* Use <code>enum class</code> over plain <code>enum</code>
* Use <code>struct</code> only for data-only types; structs must '''never''' use access modifiers
* No C-style casts — use <code>static_cast<></code>, <code>dynamic_cast<></code>, <code>reinterpret_cast<></code>
* Prefer <code>{}</code> brace initialization
* Prefer <code>std::numeric_limits<></code> over C-style <code>MAX_INT</code> / <code>INT_MAX</code> macros

== Smart Pointers ==

OpenApoc provides short aliases in <code>library/sp.h</code>:

{| class="wikitable"
! Alias !! Equivalent
|-
| <code>sp<T></code> || <code>std::shared_ptr<T></code>
|-
| <code>up<T></code> || <code>std::unique_ptr<T></code>
|-
| <code>wp<T></code> || <code>std::weak_ptr<T></code>
|-
| <code>mksp<T>(args...)</code> || <code>std::make_shared<T>(args...)</code>
|-
| <code>mkup<T>(args...)</code> || <code>std::make_unique<T>(args...)</code>
|}

* '''No naked <code>new</code>''' — always wrap in smart pointers immediately
* Prefer <code>up<></code> (exclusive ownership) over <code>sp<></code> unless shared ownership is genuinely needed
* Use <code>std::move()</code> to transfer <code>up<></code> ownership
* '''Ownership guideline''': If ownership of a member is tied to the class, use a direct member (no pointer). If a reference owned by another object is guaranteed to outlive the class, use a <code>&reference</code> member. Otherwise use <code>up<></code> or <code>sp<></code> depending on whether ownership is exclusive or shared.

== Templates ==

* Template type parameters should use <code>CamelCase</code>
* Place <code>template<...></code> on the line above the function/class declaration

<pre>
template <typename ValueType>
ValueType doSomething(ValueType input)
{
return input;
}
</pre>

== Class Declarations ==

* <code>public:</code>/<code>private:</code>/<code>protected:</code> written at class indent level (not indented further)
* Always explicitly write <code>private:</code>, even though it is the default
* <code>virtual</code> only on the base class; <code>override</code> on derived classes — never both together
* All classes with virtual methods must have a virtual destructor
* Use <code>= default</code> instead of empty <code>{}</code> constructor/destructor bodies
* Use member initializer lists; initializer order must match declaration order

<pre>
class MyClass : public BaseClass
{
private:
int memberVariable = 0;
UString name;
public:
MyClass() = default;
~MyClass() override = default;

void doSomething() override;
int getValue() const;
};
</pre>

== Functions ==

* Functions should be named <code>camelBack</code>
* Use '''early return''' — prefer separate <code>if (cond) return;</code> checks over deeply nested conditionals
* '''<code>const</code> aggressively''': const member functions, const parameters, const return types, const local variables
* Range-for loops: <code>for (auto &element : container)</code> / <code>for (const auto &element : container)</code>
** '''Exception''': When removing elements during iteration, use an iterator-based loop instead of range-for
* Prefer <code>emplace()</code> over <code>insert()</code> in STL containers

== General Code ==

* Use anonymous namespaces instead of <code>static</code> for file-local functions and classes

<pre>
namespace
{
void helperFunction()
{
// file-local helper
}
} // anonymous namespace
</pre>

* All project code lives in <code>namespace OpenApoc {}</code>. Namespace content is '''not''' indented. Closing brace gets a comment:

<pre>
namespace OpenApoc
{

class MyClass
{
// ...
};

} // namespace OpenApoc
</pre>

* Use <code>static_assert()</code> to verify assumptions about alignment, packing (e.g., when reading structs from original game files), or template restrictions
* Avoid Yoda conditionals — write <code>var == 1</code>, not <code>1 == var</code>

== Comments ==

* Prefer <code>//</code> for single-line comments
* Multi-line <code>/* */</code> comments: align the <code>*</code> on each intermediate line
* Use <code>//TODO:</code> and <code>//FIXME:</code> markers to flag work-in-progress or known issues
* Do not comment for the sake of it — if the code can be made clearer, prefer that over adding a comment

== Logging ==

Uses '''fmt-style format strings''' with positional <code>{0}</code>, <code>{1}</code> placeholders ('''not''' printf-style):

<pre>
#include "framework/logger.h"

LogInfo("Loaded mod \"{0}\"", modName);
LogWarning("Value {0} exceeds limit {1}", value, limit);
LogError("Failed to load file \"{0}\"", path);
</pre>

* <code>LogInfo</code> — general information
* <code>LogWarning</code> — recoverable errors
* <code>LogError</code> — fatal errors

== Strings ==

Use '''<code>UString</code>''' (from <code>library/strings.h</code>) for all strings. All <code>char*</code>/<code>std::string</code> values are assumed UTF-8.

String formatting uses the <code>fmt</code> library:

<pre>
#include "library/strings_format.h"

UString result = OpenApoc::format("Player has {0} credits and {1} agents", credits, agentCount);
</pre>

Translation:

<pre>
UString translated = tr("English text to translate");
</pre>

== Includes and Headers ==

* Use <code>#pragma once</code> (no traditional include guards)
* '''Include order''': Local headers first, then system headers. Each block alphabetically sorted.
* Local headers use paths '''relative to the OpenApoc root''': <code>"framework/logger.h"</code>, not <code>"../logger.h"</code> or <code>"logger.h"</code>
* '''Prefer forward declarations''' over <code>#include</code> in headers where possible
** Forward declarations are '''not possible''' for templates, non-class types (e.g., <code>enum class</code>), and superclasses. When in doubt, try building without the include and see what fails.

<pre>
#pragma once

#include "library/sp.h"
#include "library/strings.h"

#include <vector>

namespace OpenApoc
{

class ForwardDeclaredType;

class MyClass
{
private:
int member = 0;
public:
void publicFunction();
};

} // namespace OpenApoc
</pre>

== Key Review Expectations ==

These patterns are consistently enforced during code review:

# '''const correctness''' — if something can be <code>const</code>, it must be <code>const</code>
# '''Readable conditionals''' — avoid embedded comments in complex conditionals; prefer early-exit checks
# '''One logical change per PR''' — keep changes focused for clean history and bisectability
# '''Use <code>auto</code>''' — when the type is already visible on the RHS
# '''Prefer exclusive ownership''' — use <code>up<></code> over <code>sp<></code> when shared ownership is not required

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Compiling (OpenApoc)]] — Build instructions for developers
* [https://github.com/OpenApoc/OpenApoc/blob/master/CODE_STYLE.md CODE_STYLE.md] — Full coding style specification in the repository
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/development/coding-style.md OpenApoc Wiki: Coding Style] — Extended coding style documentation
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code repository
* [https://discord.gg/f8Rayre OpenApoc Discord] — Community discussion and support

[[Category:OpenApoc]]

Hidden Features (OpenApoc)

2026-03-01T23:05:23Z

Deldonut1: Major rewrite: documented full debug mode and cheat system with hotkey tables

OpenApoc includes an extensive '''debug and cheat system''' not present in the original game. Debug hotkeys are toggled with '''F1''' in both the Cityscape and Battlescape. When enabled, various diagnostic and cheat functions become available.

'''Note:''' The "Show debug commands on screen" option in the More Options menu controls whether debug command buttons are visible in the UI.

== General Debug ==

Press '''F1''' to toggle debug mode on/off. When debug mode is active, some normal hotkeys are overridden by debug functions.

== Cityscape Debug ==

{| class="wikitable"
! Key !! Action
|-
| Ctrl + Alt + Shift + Left Click || Destroy scenery tile at cursor
|-
| Ctrl + Alt + Shift + Right Click || Collapse building at cursor
|-
| A || Give every vehicle weapon and ammo to current base
|-
| W || Warp to alien dimension and back
|-
| R || Repair all scenery in the city (instant, ignores repair rules)
|-
| Shift + R || Repair scenery using game repair logic (charges building owners, checks support) without requiring construction vehicles; single repair pass
|-
| B || Spawn UFO on base assault mission
|-
| U || Spawn three crashed UFOs
|-
| X || Crash every vehicle on map
|-
| - (Minus) || Destroy all currently selected vehicles (both owned and other)
|-
| P || Regenerate dimension gate portals in current city
|-
| PgUp / PgDown || Display only one map layer (other layers become transparent)
|}

=== Cityscape Diagnostic Overlays ===

{| class="wikitable"
! Key !! Action
|-
| F2 || Show road pathfinding map
|-
| F3 || Highlight walk mode, collapsing tiles, basement tiles
|-
| F4 || Show aliens in buildings on strategy map
|-
| F5 || Show vehicle paths (blue = flying, yellow = ground)
|-
| F6 || Dump voxelmap for line of sight to tileviewvoxels.png
|-
| F7 || Dump voxelmap for line of sight to tileviewvoxels.png (fast mode, 1/4 of points)
|-
| F8 || Dump voxelmap for line of fire to tileviewvoxels.png
|-
| F9 || Dump voxelmap for line of fire to tileviewvoxels.png (fast mode, 1/4 of points)
|-
| F10 || Highlight tubes in city
|-
| F11 || Highlight roads in city
|-
| F12 || Highlight hills in city
|-
| T || Show vehicle target lines (green = X-COM targeting, red = other targeting, yellow = mutual targeting)
|}

=== Cityscape Numpad Filters ===

These filters work with the F10/F11/F12 overlays:

{| class="wikitable"
! Key !! Action
|-
| Numpad 1, 3, 7, 9 || Show only roads/tubes with an outgoing connection in that direction
|-
| Numpad 2 || Show only tubes with an outgoing connection downward
|-
| Numpad 8 || Show only tubes with an outgoing connection upward
|-
| Numpad 0 || Show all roads/tubes again (reset filter)
|-
| Numpad 5 || Toggle display mode:
* For tubes: switch between tiles with defined tube passability, or also include tiles belonging to buildings
* For roads: switch between tiles marked as "road", or also include tiles marked with road direction
* For hills: switch between tiles marked as "road", or also include tiles marked with hill direction
|}

== Battlescape Debug ==

{| class="wikitable"
! Key !! Action
|-
| Middle Click || Activate teleportation mode for selected unit (regardless of whether it holds a charged teleporter)
|-
| E || Force end current turn in turn-based mode
|-
| R || Reveal whole map and show debug lines for which unit sees which unit
|-
| S || Stun unit under cursor
|-
| Ctrl + S || Stun units in small area around cursor
|-
| Shift + S || Stun everything '''except''' unit under cursor
|-
| Shift + Ctrl + S || Stun everything '''except''' units in small area around cursor
|-
| K || Remove unit under cursor from map (same modifiers as S — Ctrl for area, Shift for inverse). Units count as retreated.
|-
| P || Lower morale of every unit to trigger low morale events
|-
| Shift + P || Give every unit 0 psi defense and 100 psi energy/attack
|-
| H || Restore stats of every unit, heal stun damage and fatal wounds
|-
| T || Restore TU of every player unit
|-
| F || Re-link support lines for battlescape map parts
|-
| Q || Reset AI movement order for unit at selected tile (forces prone stance change)
|-
| Numpad 0 || Spawn vortex mine explosion at cursor
|-
| Numpad 1-9 || Spawn a high-damage shot at cursor in specified direction (5 = downward)
|-
| F6 || Dump voxelmap for line of sight to tileviewvoxels.png
|-
| F7 || Dump voxelmap for line of sight (fast mode, 1/4 of points)
|-
| F8 || Dump voxelmap for line of fire to tileviewvoxels.png
|-
| F9 || Dump voxelmap for line of fire (fast mode, 1/4 of points)
|}

== Base Screen Debug ==

{| class="wikitable"
! Key !! Action
|-
| F10 (on Base View) || Instantly finish all facility construction
|-
| F10 (on Research Screen) || Set research project to require only 100 more points (effectively completes the project at next update if at least 2 scientists are assigned)
|}

== Cheat Menu ==

In addition to debug hotkeys, OpenApoc provides a dedicated '''Cheat Options''' screen accessible from the More Options menu:

{| class="wikitable"
! Option !! Description !! Default
|-
| Infinite Ammo || Unlimited ammunition for all X-COM agents and vehicles || OFF
|-
| Damage Inflicted Multiplier || Multiplier for damage dealt by X-COM (0x - 5x) || 1.0x
|-
| Damage Received Multiplier || Multiplier for damage taken by X-COM (0x - 5x) || 1.0x
|-
| Hostiles Multiplier || Multiplier for number of hostile units spawned (0.5x - 3x) || 1.0x
|-
| Stat Growth Multiplier || Multiplier for agent stat growth rate (0x - 99.5x) || 1.0x
|}

Additional cheat buttons available:
* Give All Research
* Make All Organizations Friendly / Hostile
* Make All Organizations Utopia / Chaos
* Modify Funds
* Go to End of Day — advance clock to 23:59:59 of current day
* Go Forward 1 Day — skip exactly 1 day forward
* Go Forward 1 Week — skip exactly 7 days forward
* Go to End of Week — advance to last day of current week at 23:59:59
* Go to End of Month — advance to last day of current month at 23:59:59

== See Also ==

* [[Controls (OpenApoc)]] — standard (non-debug) controls
* [[Improvements (OpenApoc)]] — toggle-able gameplay improvements
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/debug-mode.md OpenApoc Wiki: Debug Mode] — Extended debug and hidden features documentation
* [[OpenApoc]] — main OpenApoc page

[[Category:OpenApoc]]

Controls (OpenApoc)

2026-03-01T22:48:54Z

Deldonut1: Expand Space key examples, add Ctrl-additive selection notes, add More Options feature toggle references

OpenApoc aims to implement all controls from the original game while introducing new hotkeys to improve interface usability. A key addition is the '''improved city control scheme''' — a completely new, consistent control system using modifier keys. This can be disabled via the "Improved city control scheme" option in the More Options menu to restore vanilla behavior.

For debug and cheat hotkeys, see [[Hidden Features (OpenApoc)]].

== General UI Hotkeys ==

{| class="wikitable"
! Key !! Action
|-
| Mousewheel || Scroll lists
|-
| Esc || Go back, close form, "Cancel" option
|-
| Enter || Go forward, "Confirm" option, first option (e.g., real-time in briefing)
|-
| Space || Skip, second non-cancel option (e.g., "No" in "Yes/No/Cancel" dialogue, equip button in squad assignment, checkbox to pause when event happens again, turn-based in briefing)
|}

== General Hotkeys ==

{| class="wikitable"
! Key !! Action
|-
| Middle Click || Move camera to location
|-
| Arrow Keys || Move camera around
|-
| Tab || Toggle map
|-
| Space || Pause / Resume time (including turn-based)
|-
| Esc || Options menu
|-
| C || Toggle follow mode
|-
| M || Show message log
|-
| Home || Zoom to last event
|}

== Cityscape Controls ==

=== Vanilla Controls Note ===

The original game's city controls were inconsistent and limited:
* Right-clicking moved the map in city but not in battle
* No quick access to frequently used screens (equipment, location, base)
* Alt/Shift hotkeys acted as if clicking a corresponding button — missing a target changed your selection mode

OpenApoc introduces a new, consistent control scheme explained below. To restore vanilla controls, disable "Improved city control scheme" in the More Options menu. With vanilla controls:
* Right click moves screen to cursor
* Alt + Left Click orders vehicle attack
* Shift + Left Click orders moving to building
* Left-clicking on building always opens building screen
* No OpenApoc mouse controls will function

=== Cityscape Mouse (Improved Scheme) ===

{| class="wikitable"
! Input !! Action
|-
| Left Click on building || Open building screen (base screen if it contains a base)
|-
| Right Click on building || Open building screen
|-
| Shift + Left Click || Order attack vehicle
|-
| Shift + Right Click || Order follow vehicle / go to location
|-
| Alt + Shift + Left Click || Order attack building
|-
| Alt + Shift + Right Click || Order go to building
|-
| Alt + Left Click || Open UFOpaedia for object (vehicle type, building function, or projectile source)
|-
| Alt + Right Click || Open UFOpaedia for object's owner (vehicle or building)
|}

==== Modifier Keys ====

{| class="wikitable"
! Modifier !! Effect
|-
| Ctrl (agent move orders) || Force agents to move on foot (never call taxi); allows use of personal teleporter
|-
| Ctrl (vehicle move orders) || Allow manual use of city teleporter buildings
|-
| Ctrl (attack orders) || Force vehicles to attack target (instead of recovering UFOs or escorting owned vehicles)
|}

'''Note:''' In vanilla, attacking owned vehicles was impossible. OpenApoc enables this via the <code>OpenApoc.NewFeature.AllowAttackingOwnedVehicles</code> option (on by default).

=== Cityscape Mouse on Vehicle / Agent Icons ===

{| class="wikitable"
! Input !! Action
|-
| Shift + Right Click || Open location screen
|-
| Ctrl + Shift + Right Click || Open equipment screen
|-
| Alt + Shift + Right Click || Open equipment screen
|}

=== Cityscape Unit Selection ===

{| class="wikitable"
! Input !! Action
|-
| Left Click || Select agent/vehicle (as the only object selected)
|-
| Ctrl + Left Click || Add agent/vehicle to selection and make it first in the list
|-
| Right Click || Remove agent/vehicle from selection
|}

'''Note:''' Ctrl makes selection additive.

=== Cityscape Keyboard ===

{| class="wikitable"
! Key !! Action
|-
| 0, 1, 2, 3, 4, 5 || Control game speed
|-
| N || Manual control (with vanilla scheme: M is manual control and there is no way to open message log)
|}

== Vehicle Equipment ==

{| class="wikitable"
! Input !! Action
|-
| Shift + Click || Auto-equip item into first available slot, or auto-remove to base stores
|}

== Agent Equipment ==

Standard selection controls apply, with the option to de-select with right click.

{| class="wikitable"
! Input !! Action
|-
| Shift + Click || Auto-equip item into first available slot, or auto-remove to base stores / ground
|-
| Ctrl + Click on weapon || Remove clip from weapon
|-
| 1 through 0 || Apply saved equipment template to every selected agent
|-
| Ctrl + 1 through 0 || Remember current agent's equipment set as a template
|}

'''Note:''' Equipment templates require the <code>OpenApoc.NewFeature.EnableAgentTemplates</code> option (enabled by default).

== Battlescape Mouse ==

{| class="wikitable"
! Input !! Action
|-
| Left Click || Order unit to execute action (move / throw / psi attack / teleport), open probed unit's screen, use item
|-
| Right Click || Turn towards cursor, focus enemy (real-time), use item's "auto" function (e.g., prime grenade for impact)
|-
| Shift + Left Click || Force-fire at target tile, shot moving parallel to ground
|-
| Shift + Alt + Left Click || Force-fire at target tile, shot aimed at tile's ground
|}

==== Modifier Keys ====

{| class="wikitable"
! Modifier !! Effect
|-
| Alt (movement) || Unit keeps facing the target while moving (strafing or moving backwards)
|-
| Alt (firing at tile) || Shot aims at the ground of the tile rather than at the unit's level
|-
| Shift || Turns cursor into attack mode
|}

=== Battlescape Unit Selection ===

{| class="wikitable"
! Input !! Action
|-
| Left Click || Select unit (as the only unit selected)
|-
| Ctrl + Left Click || Add unit to selection and make it first in the list
|-
| Right Click || Remove unit from selection
|}

'''Note:''' Ctrl makes selection additive.

== Battlescape Keyboard ==

=== Movement and Fire Modes ===

{| class="wikitable"
! Key !! Action
|-
| PgUp / PgDown || Change map levels
|-
| V || Toggle layering
|-
| F2 || Prone mode
|-
| F3 || Walk mode
|-
| F4 || Run mode
|-
| F5 || Cease fire mode
|-
| F6 || Aimed mode
|-
| F7 || Snap mode
|-
| F8 || Auto mode
|-
| F9 || Evasive mode
|-
| F10 || Normal mode
|-
| F11 || Aggressive mode
|-
| Backspace || Kneel mode
|}

=== Squad and Unit Selection ===

{| class="wikitable"
! Key !! Action
|-
| 1 through 6 || Select squad
|-
| Shift + 1 through 6 || Select unit in current squad (as the only unit selected)
|-
| Shift + Ctrl + 1 through 6 || Add unit to selection and make it first in the list
|-
| Alt + 1 through 6 || Cycle through spotted enemies of the selected unit
|}

=== Actions ===

{| class="wikitable"
! Key !! Action
|-
| Enter || Open inventory
|-
| [ || Throw right hand item
|-
| ] || Throw left hand item
|-
| ' || Drop right hand item
|-
| \ || Drop left hand item
|-
| Y || Confirm priming
|-
| N || Cancel priming
|-
| E || End your turn (turn-based mode)
|-
| S || Open save menu
|-
| L || Open load menu
|-
| J || Make unit jump (down from a cliff)
|}

== Notes ==

Some controls are affected by options in the '''More Options''' menu:
* <code>OpenApoc.NewFeature.BattlescapeVertScroll</code> — mousewheel changes vertical level in the battlescape
* <code>OpenApoc.NewFeature.SingleSquadSelect</code> — single-click squad button selects squad (instead of requiring double-click)
* <code>OpenApoc.NewFeature.LeftClickIconEquip</code> — left-clicking a vehicle/agent icon opens the equipment screen

== See Also ==

* [[Hidden Features (OpenApoc)]] — debug hotkeys and cheat system
* [[Improvements (OpenApoc)]] — toggle-able gameplay improvements
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/controls.md OpenApoc Wiki: Controls] — Extended controls documentation
* [[OpenApoc]] — main OpenApoc page

[[Category:OpenApoc]]

Improvements (OpenApoc)

2026-03-01T22:44:01Z

Deldonut1: Major rewrite: documented all 54+ More Options menu settings with descriptions and defaults

OpenApoc introduces dozens of optional gameplay improvements and enhancements beyond the original ''[[Apocalypse|X-COM: Apocalypse]]''. All of these can be toggled on or off through the '''More Options''' menu accessible from the in-game options screen.

For a complete list of differences from the original game (including technical improvements, controls, and bug fixes), see [[Differences to X-COM (OpenApoc)]].

== Cityscape Improvements ==

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Improved city control scheme || Completely new control scheme using modifier keys for direct orders, UFOpaedia lookups, and additive selection. See [[Controls (OpenApoc)]] for details. Can be disabled to restore vanilla controls. || ON
|-
| Ferry checks relationship when buying || Transtellar checks its relationship with X-COM before providing transport services. In the original, transports were always available regardless of relationship. || ON
|-
| Allow manual use of teleporters in city || Players can manually route vehicles through teleporter buildings for quick transport across the city. || ON
|-
| Allow manual ferrying of cargo and non-combatants || Manual control over ferry transport of cargo and non-combat personnel. || ON
|-
| Allow soldiers to call taxi || Soldiers can use taxis for transport. In the original, only civilians could use taxis. || ON
|-
| Allow attacking owned vehicles || X-COM can attack its own vehicles. This was impossible in the original game. || ON
|-
| Call existing transport || Reuses existing transport vehicles instead of spawning new ones each time. || ON
|-
| Recover dropped equipment || Equipment dropped by agents in the city is automatically recovered and returned to base stores. || ON
|-
| Enforce vehicle cargo limits || Strict enforcement of vehicle cargo capacity. When disabled, vehicles can carry unlimited cargo (original behavior was inconsistent). || OFF
|-
| Nearby vehicle loot pickup || Nearby X-COM vehicles can collect loot from crash sites and battles, not just the vehicle that initiated the mission. || ON
|-
| Building loot deposit || Recovered loot can be deposited inside buildings for later collection. || ON
|-
| Armored roads || Roads have damage reduction, making them harder to destroy during city combat. || ON
|-
| Ground vehicles crash on lost support || Ground vehicles without road support crash. Weapons and modules may be lost in the crash. || ON
|-
| Dimension gate crash || Vehicles incapable of dimensional travel crash when entering dimension gates. || ON
|-
| Out of fuel crash || Vehicles crash when their fuel runs out completely. || ON
|-
| Collapse raided building || Buildings collapse after a successful raid operation. || OFF
|-
| Retaliation on unintentional hit || Any stray shot hitting a hostile building provokes immediate retaliation. || OFF
|-
| Market on right || Market stock displayed on the right side of the transaction screen (swap from default left). || ON
|-
| Left click icon for equip || Left-clicking a unit's icon opens the equipment screen directly. || OFF
|-
| Skip turbo movement || Performance optimization that skips turbo movement calculations. || OFF
|-
| ATV UFO missions || All Terrain Vehicles (Griffon, Wolfhound APC) can initiate UFO recovery missions. || ON
|-
| Show current dimension vehicles || Vehicle list filters to show only vehicles in the current dimension (or entering/leaving). || ON
|-
| Non-X-COM vehicle prefix || Non-X-COM vehicles are prefixed with * in vehicle lists for easy identification. || ON
|-
| Iso-only follow || Disables automatic camera following in strategy (isometric) view. || OFF
|-
| Currency formatting || Monetary values displayed with locale-appropriate currency formatting (e.g., $1,234,567). || ON
|}

== Battlescape Improvements ==

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Instant explosion damage || Explosions cause damage immediately rather than with a visual delay. || ON
|-
| UFO damage model || Uses the ''[[X-COM|UFO: Enemy Unknown]]'' damage randomization model (0-200% of base damage) instead of Apocalypse's narrower damage range. || OFF
|-
| Gravlift sounds || Sound effects play when units enter or exit gravlifts. || ON
|-
| Realistic throwing || Units must face the target and be in the correct stance before throwing items. When disabled, throws are instant regardless of facing. || ON
|-
| Payload explosion || Carried ammunition detonates when a unit or vehicle is destroyed, causing additional explosions. || ON
|-
| Display unit paths || Movement paths are visually displayed during tactical combat, showing where units will move. || ON
|-
| Additional unit icons || Extra status icons shown on the unit panel for fatal wounds and psionic effects. || ON
|-
| Force-firing parallel || Force-fire mode allows shots aimed parallel to the ground plane (useful for suppression). || ON
|-
| LOS for psi maintenance || Psionic attacks require maintained line of sight to the target. When disabled, psi effects persist without LOS. || OFF
|-
| Vehicle shield sound || Different sound effect when vehicle shields absorb damage, providing audio feedback. || ON
|-
| Run and kneel || Units default to running movement and kneeling stance. || ON
|-
| Auto-reload || Weapons automatically reload from carried ammunition when a clip is expended. || ON
|-
| Same ammo type reload || Auto-reload only uses the same ammunition type that was previously loaded (won't switch ammo types). || ON
|-
| Mousewheel vertical scroll || Mouse scroll wheel changes the displayed map level in battlescape. || ON
|-
| Single squad select || Single-click on squad number buttons selects the entire squad (instead of requiring double-click). || OFF
|-
| Disable scroll sounds || Turns off the scrolling sound effect when moving the map. || OFF
|}

== General Improvements ==

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Debug commands visible || Displays debug/cheat command buttons in the interface. See [[Hidden Features (OpenApoc)]] for details. || ON
|-
| Advanced inventory controls || Shift+click for auto-equip/remove, Ctrl+click to remove clips from weapons. || ON
|-
| Agent equipment templates || Save and load agent equipment loadouts with number keys (Ctrl+1-0 to save, 1-0 to apply to all selected agents). || ON
|-
| Seed RNG || Seeds the random number generator at game start for varied gameplay each time. || ON
|-
| Mouse capture || Captures the mouse cursor within the game window, preventing it from leaving the window boundary. || OFF
|}

== Mod Options ==

These options modify game balance or add non-standard features:

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Max tile repair per night || Maximum number of scenery tiles construction vehicles repair each night (configurable 0-100). || 5
|-
| Scenery repair cost factor || Percentage of original price organizations pay for scenery tile repair (configurable 0-100%). || 10%
|-
| Stunning hurts relationships || Stunning units belonging to an organization damages X-COM's relationship with that organization. || OFF
|-
| Raid hurts relationships || Initiating a raid on a building damages the relationship with its owner organization. || OFF
|-
| Original BSK Launcher sound || Uses the original game's Brainsucker Launcher sound effect. || ON
|-
| Invulnerable roads || Roads cannot be damaged or destroyed by any weapons. || OFF
|-
| Griffon ATV || The Griffon AFV becomes an all-terrain vehicle capable of off-road movement. || ON
|-
| Wolfhound ATV || The Wolfhound APC becomes an all-terrain vehicle capable of off-road movement. || ON
|-
| Low HP vehicle crash || Vehicles crash when their health drops critically low. Weapons and modules may be lost. || OFF
|}

== Pause Notifications ==

OpenApoc adds a comprehensive '''configurable notification system''' that pauses the game when specific events occur. Each notification can be individually toggled in the options. These are not present in the original game.

=== City Notifications ===
* UFO spotted
* Vehicle damage (light / moderate / heavy / destroyed)
* Vehicle escaping (damaged and returning to base)
* Vehicle out of ammo / low fuel
* Agent died / arrived at base
* Cargo / transfer / recovery arrived at base
* Vehicle repaired / rearmed / refuelled
* Not enough ammo / fuel
* Unauthorized vehicle detected
* X-COM base destroyed

=== Battle Notifications ===
* Hostile spotted / died
* Unknown unit died
* Agent died / brainsucked
* Agent critically wounded / badly injured / injured
* Agent under fire / unconscious / left combat zone
* Agent frozen / berserk / panicked / panic over
* Psionic attack on unit / unit under psionic control / freed from control

== See Also ==

* [[Differences to X-COM (OpenApoc)]] — comprehensive differences from the original game
* [[Controls (OpenApoc)]] — full control scheme reference
* [[Hidden Features (OpenApoc)]] — debug hotkeys and cheat system
* [[Modding (OpenApoc)]] — modding documentation
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/new-features.md OpenApoc Wiki: New Features] — Extended improvements documentation
* [[OpenApoc]] — main OpenApoc page

[[Category:OpenApoc]]

Credits (OpenApoc)

2026-03-01T22:28:22Z

Deldonut1: Fix RedRobin84 name: replace HTML entity with UTF-8 character Č

{{DISPLAYTITLE:Credits (OpenApoc)}}
'''[[OpenApoc]]''' is a community-driven open-source project. It is near impossible to adequately credit everyone involved — this page attempts to recognise the key contributors whose work has shaped the project.

== Project Founder ==

* '''[[User:PmProg|PmProg]] - Marq Watkin''' — Founded the OpenApoc project in July 2014

== Lead Developer ==

* '''[[User:JonnyH|JonnyH]] - Jonathan Hamilton''' — Game UI, AI, Cityscape, Battlescape, Framework, rendering engine, serialisation, and overall architecture. By far the largest contributor to the codebase.

== Core Contributors ==

Listed alphabetically. Contributions span code, testing, translation, reverse-engineering, modding, and community management.

{| class="wikitable sortable"
|-
! Contributor !! Primary Contributions
|-
| '''[[User:Atrosha|Atrosha]] - Panasenko Vasiliy Sergeevich''' || Many fixes, UI of agent characteristics (Rest In Peace; 1980–2021)
|-
| '''[[User:Deldonut1|deldonut1]]''' (Ayrton Denner) || Gameplay improvements, bug fixes, documentation, wiki
|-
| '''[[User:Empty`void|emptyVoid]]''' || Code contributions, bug fixes
|-
| '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar''' || Game archivist, testing, modding (Extended Weapons Mod), original game historian
|-
| '''[[User:FranciscoDA|FranciscoDA / Flacko]]''' || UI improvements (hover screens), Win installer, code contributions
|-
| '''[[User:Ivan_Shibanov|Shellstorm - Ivan Shibanov]]''' || Fixes, AI, Economics, Diplomatic Rift
|-
| '''[[User:Istrebitel|Istrebitel]]''' || Game UI, AI, Battlescape, data extraction, Skirmish Mode, debug system, hotkey set, 40+ improvements and options interface, video making
|-
| '''[[User:Jarskih|Jarskih]] - Jari Hanski''' || Many fixes
|-
| '''Kgd192''' || Code contributions
|-
| '''Kurtsley''' || Gameplay bug fixes, code improvements (2024–2025)
|-
| '''Luis Camara''' || Code contributions
|-
| '''[[User:Makus|Makus]]''' || Community & PR, website hosting, designer, Russian translation, VK group founder, FB page editor, YouTube channel editor
|-
| '''[[User:PmProg|PmProg]] - Marq Watkin''' || Framework core, UI framework core, Game UI, FB poster, YouTube channel admin
|-
| '''[[User:Redv|redv]]''' || Vehicle location screen, drag-and-drop mechanics, many fixes
|-
| '''[[User:Roger|Roger]]''' || Documentation fixes
|-
| '''[[User:Sfalexrog|sfalexrog]] - Alexey Rogachevskiy''' || Android core, .cue image loader, audio backend core, fixes
|-
| '''[[User:Skin36|Skin36]]''' || Reverse engineering (OG disassembly), Russian translation, fire rate and accuracy formula documentation
|-
| '''[[User:SupSuper|SupSuper]] - Daniel Albano''' || Base management, tooltips, fixes, Game UI, founder of OpenXcom, Community & PR
|}

== Additional Contributors ==

The following people have also contributed code, translations, bug reports, or other valuable work:

{| class="wikitable sortable"
|-
! Contributor !! Contributions
|-
| '''[[User:5thAvenue|5thAvenue]]''' || Initial French translation
|-
| '''Andy51''' (Andrey Isakov) || Code contributions
|-
| '''Anders Sandberg Nordbø''' || Code contributions
|-
| '''Andre Haberle''' || Code contributions
|-
| '''AndreyCreator''' || Code contributions
|-
| '''Ashenomo''' || Code contributions
|-
| '''[[User:Blackwolf-Kuzoku|Blackwolf-Kuzoku]]''' || Initial German translation
|-
| '''Dan Church''' (h3xx) || Code contributions
|-
| '''Dl471''' || Code contributions
|-
| '''Dmitry Marakasov''' (AMDmi3) || Code contributions
|-
| '''[[User:Jay_Atkinson|DoxaLogosGit - Jay Atkinson]]''' || Build instructions fix
|-
| '''Gnegno84''' (Marcello Santambrogio) || Code contributions
|-
| '''Johnny Solbu''' (solbu) || Code contributions
|-
| '''Gsw88''' || Code contributions
|-
| '''Hambones82''' (Josh Hamberger) || Code contributions
|-
| '''Kaja47''' || Code contributions
|-
| '''[[User:Kammerer|Kammerer]]''' || Russian translation, fonts, researcher
|-
| '''Killermosi''' (Silviu Ghita) || Code contributions
|-
| '''Kirill Mishustin''' (TreacherousOne) || Code contributions
|-
| '''[[User:Kkmic|kkmic]]''' || Build fixes, readme fixes
|-
| '''Kovarny''' || Code contributions
|-
| '''NagyAlex96''' || Code contributions
|-
| '''Pkubaj''' || Code contributions
|-
| '''[[User:Przemyslaw_Onak|Przemyslaw Onak]]''' || Saved game & serialization fixes
|-
| '''RedRobin84''' (Martin Červenka) || Code contributions
|-
| '''ShadowDancer''' || Code contributions
|-
| '''SiemensSchuckert''' || Code contributions
|-
| '''[[User:SolariusScorch|SolariusScorch]]''' || Small language fixes
|-
| '''[[User:Sonicelo|Sonicelo]] - Gregor Su&scaron;anj''' || Windows build fixes
|-
| '''[[User:Sparkstar|sparkstar]]''' || GameUI fixes
|-
| '''[[User:Steve_Schnepp|steveschnepp - Steve Schnepp]]''' || Vagrant build
|-
| '''StewartM''' (Stewart Matheson) || Code contributions
|-
| '''SuperUserCode''' || Code contributions
|-
| '''Volkov "BabyWolf" Semjon''' || Code contributions
|-
| '''[[User:Xracer|Xracer]]''' || Initial Spanish translation
|-
| '''[[User:Zigmar|zigmar / zigmar-ems]] - Pavel Antokolsky''' || UI Scaling
|}

== Testing ==

* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''
* '''Quickmind / Quickmind01'''
* '''Yataka Shimaoka'''
* '''[[EmperorLol|EmperorLol - Laurie Blake]]'''
* '''Jigoku-Panzer - Dean Martin'''

== Modding Structure and Testing ==

* '''[[User:JonnyH|JonnyH]] - Jonathan Hamilton'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''
* '''[[User:Istrebitel|Istrebitel]]'''
* '''Voiddweller'''
* '''[[User:Skin36|Skin36]]'''

== Reversing and Research ==

* '''[[User:Skin36|Skin36]]'''

== Translation ==

* '''[[User:5thAvenue|5thAvenue]]''' — Initial French translation
* '''[[User:Blackwolf-Kuzoku|Blackwolf-Kuzoku]]''' — Initial German translation
* '''[[User:Kammerer|Kammerer]]''' — Russian translation, Fonts, Researcher
* '''[[User:Skin36|Skin36]]'''
* '''[[User:SolariusScorch|SolariusScorch]]''' — Small language fixes
* '''[[User:Xracer|Xracer]]''' — Initial Spanish translation

== Project Coordination, Writing, Video Making and Social Media ==

* '''[[User:Istrebitel|Istrebitel]]'''
* '''[[User:Makus|Makus]]'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''

== Community Administration and Moderation ==

* '''[[User:PmProg|PmProg]] - Marq Watkin'''
* '''[[User:Makus|Makus]]'''
* '''[[User:SolariusScorch|SolariusScorch]]'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''

== Art and Design ==

* '''[[User:Makus|Makus]]'''

== Resources and Management ==

* '''GitHub:''' [[User:JonnyH|JonnyH]], [[User:Istrebitel|Istrebitel]], [[User:FilmBoy84|FilmBoy84]], Quickmind
* '''Forum:''' [[User:JonnyH|JonnyH]] (domain), [[User:Makus|Makus]] (hosting and scripts)
* '''Facebook:''' [[User:JonnyH|JonnyH]] (admin), [[User:FilmBoy84|FilmBoy84]] (editor), [[User:Makus|Makus]] (editor)
* '''YouTube:''' [[User:JonnyH|JonnyH]] (admin), [[User:FilmBoy84|FilmBoy84]] (editor), [[User:Makus|Makus]] (editor)
* '''Reddit:''' [[User:Istrebitel|Istrebitel]] (starter), [[User:Makus|Makus]] (editor), [[User:FilmBoy84|FilmBoy84]] (editor)
* '''Vkontakte:''' [[User:Makus|Makus]] (starter, editor), [[User:Skin36|Skin36]], [[User:Istrebitel|Istrebitel]]
* '''Twitter:''' [[User:Makus|Makus]]

== Additional Community Members ==

It's near impossible to adequately credit everyone that has laid a hand on an open-source project, so here are the main sources. Rest assured if you helped us, we are thankful for it.

* [https://github.com/OpenApoc/OpenApoc/graphs/contributors All contributors on GitHub]
* [https://www.transifex.com/x-com-apocalypse/teams/ All translators on Transifex]
* [http://openapoc.org/widget-pages/team/ All testers]
* [http://openapoc.org/ All forum members]
* All platform porters
* And the rest of the community at large: Players, fans, press members, let's players, etc. You know who you are.

== Third-Party Code ==

=== External Dependencies ===

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://www.libsdl.org SDL2]''' || Windowing, input, audio
|-
| '''[https://boost.org Boost]''' (locale, program-options, uuid, crc) || Localisation, settings management, hash functions
|-
| '''[https://xiph.org/vorbis/ LibVorbis]''' || Ogg Vorbis music decoding
|-
| '''[https://www.qt.io/ Qt]''' (Qt5 or Qt6 base) || Launcher GUI (optional)
|-
| '''[https://nongnu.org/libunwind/download.html libunwind]''' || Debug backtracing (Linux only)
|}

=== Bundled Dependencies (Submodules) ===

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://github.com/fmtlib/fmt fmtlib (fmt)]''' || C++ string formatting library
|-
| '''[https://glm.g-truc.net GLM]''' || Math library (vectors, matrices, etc.)
|-
| '''[https://sourceforge.net/projects/libsmacker/ libsmacker]''' || Decoder for <code>.smk</code> video files
|-
| '''[https://github.com/lvandeve/lodepng lodepng]''' || Reading/writing PNG image files
|-
| '''[https://www.lua.org/ Lua]''' || Scripting language
|-
| '''[https://github.com/Neargye/magic_enum magic_enum]''' || Header-only C++17 static reflection for enums
|-
| '''[https://github.com/richgel999/miniz miniz]''' || Zlib-compatible compression library
|-
| '''[https://icculus.org/physfs/ PhysFS]''' (patched) || Reading data from <code>.iso</code> files and directory trees
|-
| '''[https://pugixml.org pugixml]''' || XML library for game data files
|}

== Acknowledgements ==

* '''Julian Gollop''' — Original designer of X-COM: Apocalypse. Has publicly endorsed the OpenApoc project.
* '''MicroProse / Mythos Games''' — Original developers of X-COM: Apocalypse (1997)
* The [https://www.ufopaedia.org/index.php UFOpaedia] community for maintaining comprehensive X-COM documentation

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Compiling (OpenApoc)]] — Building from source (for potential contributors)
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code and issue tracker
* [https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki] — Extended developer and game mechanics documentation
* [https://discord.gg/f8Rayre OpenApoc Discord] — Community discussion

[[Category:OpenApoc]]

Differences to X-COM (OpenApoc)

2026-03-01T21:59:45Z

Deldonut1: Major rewrite: comprehensive comparison between OpenApoc and original game across all systems

'''OpenApoc''' is an open-source C++17 reimplementation of ''[[Apocalypse|X-COM: Apocalypse]]'' (1997). While aiming to faithfully recreate the original game, OpenApoc introduces many improvements, bug fixes, and new features. All new gameplay features are '''optional''' and can be toggled through the '''More Options''' menu.

This page documents the known differences between OpenApoc and the original game. For general OpenApoc information, see the [[OpenApoc]] main page.

== Technical Improvements ==

OpenApoc runs natively on modern hardware and operating systems, removing the need for DOS emulation:

* '''Platform support''': Windows (MSVC 2019+), Linux (GCC 8+/Clang 7+), and macOS (including Apple Silicon)
* '''Modern resolutions''': Supports any screen resolution and display scaling, with windowed, fullscreen, and borderless modes
* '''Performance''': Runs at 60 FPS with OpenGL 2.0+ / GLES 3.0 rendering
* '''Human-readable save games''': Game state is stored as XML in ZIP archives, editable with any text editor
* '''Mod support''': Full modding via XML data files, Lua scripting, and a configurable mod loading system
* '''Multi-monitor support''': Can be placed on any display in multi-monitor setups
* '''Configurable audio''': Separate volume controls for music and sound effects

== New Gameplay Options ==

All new gameplay features are accessible through the '''More Options''' menu and can be individually enabled or disabled. Default values are listed — '''ON''' means the feature is enabled by default in OpenApoc.

=== Cityscape Options ===

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Improved city control scheme || Completely new control scheme with modifier keys (see [[#Improved Controls|Improved Controls]] section). Can be disabled to restore vanilla controls. || ON
|-
| Ferry checks relationship when buying || Transtellar checks its relationship with X-COM before providing transport services || ON
|-
| Allow manual use of teleporters in city || Players can manually route vehicles through teleporter buildings for quick transport || ON
|-
| Allow manual ferrying of cargo and non-combatants || Manual control over ferry transport of cargo and non-combat personnel || ON
|-
| Allow soldiers to call taxi || Soldiers can use taxis for transport (restricted to civilians in the original) || ON
|-
| Allow attacking owned vehicles || Allows X-COM to attack its own vehicles (impossible in the original game) || ON
|-
| Call existing transport instead of spawning them || Reuses existing transport vehicles instead of spawning new ones || ON
|-
| Attempt to recover agent equipment dropped in city || Equipment dropped by agents in the city is automatically recovered || ON
|-
| Enforce vehicle cargo limits || Strict enforcement of vehicle cargo capacity || OFF
|-
| Allow nearby vehicles to pick up loot || Nearby X-COM vehicles can collect loot from crash sites || ON
|-
| Allow loot to be stashed in the building || Recovered loot can be deposited in buildings || ON
|-
| Armored roads || Roads have damage reduction, making them harder to destroy || ON
|-
| Unsupported ground vehicles crash || Ground vehicles without road support will crash (weapons and modules may be lost) || ON
|-
| Vehicles crash when entering dimension gates || Vehicles incapable of dimensional travel crash when entering gates || ON
|-
| Vehicles crash when out of fuel || Vehicles crash when their fuel runs out || ON
|-
| Successful raid collapses building || Buildings collapse after a successful raid || OFF
|-
| Any hit on hostile building provokes retaliation || Stray shots hitting hostile buildings trigger retaliation || OFF
|-
| Put market stock on the right side || Market stock displayed on the right side of the transaction screen || ON
|-
| Left clicking icon opens equip menu || Left-clicking a unit's icon opens the equipment screen || OFF
|-
| Skip turbo movement calculations || Performance optimization that skips turbo movement math || OFF
|-
| Allow ATVs to initiate UFO recovery missions || All Terrain Vehicles can start UFO recovery missions || ON
|-
| Show vehicles in current dimension only || Vehicle list filters to show only the current dimension || ON
|-
| Add prefix to non-X-COM vehicles || Non-X-COM vehicles are prefixed with * in vehicle lists for easy identification || ON
|-
| Don't follow vehicles in strategy view || Disables automatic camera following in strategy (isometric) view || OFF
|-
| Use currency formatting || Monetary values displayed with currency formatting (e.g., $1,234,567) || ON
|}

'''Other Cityscape differences:'''
* Aircraft weapons may be unequipped (not possible in the original game)

=== Battlescape Options ===

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Explosions damage instantly || Explosions cause damage immediately rather than with a delay || ON
|-
| X-Com 1 (UFO) Damage model (0-200%) || Uses the ''[[X-COM|UFO: Enemy Unknown]]'' damage randomization model (0-200% of base damage) instead of Apocalypse's model || OFF
|-
| Gravlift sounds || Sound effects play when units enter or exit gravlifts || ON
|-
| Throwing requires proper facing and pose || Units must face the target and be in the correct stance before throwing || ON
|-
| Ammunition explodes when blown up || Carried ammunition detonates when a unit or vehicle is destroyed || ON
|-
| Display unit paths in battle || Movement paths are visually displayed during tactical combat || ON
|-
| Display additional unit icons (fatal, psi) || Extra status icons shown for fatal wounds and psionic effects || ON
|-
| Allow force-firing parallel to the ground || Force-fire mode allows shots aimed parallel to the ground plane || ON
|-
| Require LOS to maintain psi attack || Psionic attacks require maintained line of sight to the target || OFF
|-
| Hitting vehicle shield produces alternate sound || Different sound effect when vehicle shields absorb damage || ON
|-
| All units run and kneel by default || Units default to running movement and kneeling stance || ON
|-
| Automatically reload weapons when empty || Weapons auto-reload from carried ammunition when a clip is expended || ON
|-
| Weapons autoreload only same ammo type || Auto-reload only uses the same ammunition type that was previously loaded || ON
|-
| Mousewheel changes vertical level in battlescape || Mouse scroll wheel changes the displayed map level || ON
|-
| Select squad with single click || Single-click squad number buttons to select the entire squad || OFF
|-
| Disable scrolling sounds || Turns off the sound effect when scrolling the map || OFF
|}

=== General Options ===

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Show debug commands on screen || Displays debug/cheat command buttons in the interface || ON
|-
| Allow unloading clips and quick equip || Advanced inventory controls: Shift+click for auto-equip, Ctrl+click to remove clips || ON
|-
| Enable agent equipment templates || Save and load agent equipment loadouts with number keys (Ctrl+1-0 to save, 1-0 to apply) || ON
|-
| Seed RNG on game start || Seeds the random number generator at game start for varied gameplay || ON
|-
| Enable mouse capture for the window || Captures the mouse cursor within the game window || OFF
|}

=== Mod Options ===

{| class="wikitable sortable"
! Option !! Description !! Default
|-
| Max tile repair per night || Maximum number of scenery tiles construction vehicles repair each night (0-100) || 5
|-
| Scenery repair cost factor || Percentage of original price organizations pay for scenery repair (0-100%) || 10%
|-
| Stunning hurts relationships || Stunning units belonging to an organization damages X-COM's relationship with them || OFF
|-
| Initiating raid hurts relationships || Starting a raid on a building damages the relationship with its owner || OFF
|-
| (MOD) Original Brainsucker Launcher SFX || Uses the original game's Brainsucker Launcher sound effect || ON
|-
| (MOD) Invulnerable roads || Roads cannot be damaged or destroyed || OFF
|-
| (MOD) Griffon becomes All-Terrain || The Griffon AFV becomes an all-terrain vehicle capable of off-road movement || ON
|-
| (MOD) Wolfhound APC becomes All-Terrain || The Wolfhound APC becomes an all-terrain vehicle || ON
|-
| Vehicles crash on low HP || Vehicles crash when their health drops critically low (weapons and modules may be lost) || OFF
|}

=== Cheat Options ===

OpenApoc provides a dedicated cheat menu not present in the original game:

{| class="wikitable"
! Option !! Description !! Default
|-
| Infinite ammo || Unlimited ammunition for all X-COM agents and vehicles || OFF
|-
| Damage inflicted multiplier || Multiplier for damage dealt by X-COM (0x - 5x) || 1.0x
|-
| Damage received multiplier || Multiplier for damage taken by X-COM (0x - 5x) || 1.0x
|-
| Hostiles multiplier || Multiplier for the number of hostile units spawned (0.5x - 3x) || 1.0x
|-
| Stat growth multiplier || Multiplier for agent stat growth rate (0x - 99.5x) || 1.0x
|}

Additional cheat buttons: Give All Research, Make All Orgs Friendly/Hostile, Make All Orgs Utopia/Chaos, Modify Funds, Set Time Before Midnight, Fast Forward to End of Day/Week/Month.

== Improved Controls ==

The original game's city controls were inconsistent and limited. OpenApoc introduces a completely new control scheme using modifier keys. This can be disabled via the "Improved city control scheme" option to restore vanilla behavior.

=== Cityscape Mouse Controls ===

{| class="wikitable"
! Input !! Action
|-
| Left Click on building || Open building screen (base screen if building contains a base)
|-
| Right Click on building || Open building screen
|-
| Shift + Left Click || Order attack vehicle
|-
| Shift + Right Click || Order follow vehicle / go to location
|-
| Alt + Shift + Left Click || Order attack building
|-
| Alt + Shift + Right Click || Order go to building
|-
| Alt + Left Click || Open UFOpaedia for object (vehicle type, building function, projectile source)
|-
| Alt + Right Click || Open UFOpaedia for object's owner
|-
| Ctrl + move order (agents) || Force agents to move on foot (never call taxi), allows personal teleporter use
|-
| Ctrl + move order (vehicles) || Allows manual use of city teleporters
|-
| Ctrl + attack order || Forces vehicles to attack target (instead of UFO recovery or escort)
|-
| Ctrl + Left Click (selection) || Add unit/vehicle to selection (additive selection)
|-
| Right Click (selection) || Remove unit/vehicle from selection
|-
| Middle Click || Move camera to location
|}

=== Cityscape Mouse on Vehicle/Agent Icons ===

{| class="wikitable"
! Input !! Action
|-
| Shift + Right Click || Open location screen
|-
| Ctrl + Shift + Right Click || Open equipment screen
|-
| Alt + Shift + Right Click || Open equipment screen
|}

=== Agent Equipment Controls ===

{| class="wikitable"
! Input !! Action
|-
| Shift + Click || Auto-equip item to first available slot, or auto-remove to stores/ground
|-
| Ctrl + Click on weapon || Remove clip from weapon
|-
| 1-0 || Apply saved equipment template to all selected agents
|-
| Ctrl + 1-0 || Save current agent's equipment set as a template
|}

=== Battlescape Mouse Controls ===

{| class="wikitable"
! Input !! Action
|-
| Left Click || Order unit to execute action (move/throw/psi/teleport), open probed unit screen, use item
|-
| Right Click || Turn towards cursor, focus enemy (real-time), use item auto-function (e.g., prime grenade for impact)
|-
| Shift + Left Click || Force-fire at target tile, shot parallel to ground
|-
| Shift + Alt + Left Click || Force-fire at target tile, shot aimed at tile's ground
|-
| Alt + move order || Unit keeps facing target while moving (strafe/backpedal)
|-
| Ctrl + Left Click || Add unit to selection (additive)
|-
| Right Click || Remove unit from selection
|}

=== Battlescape Keyboard ===

{| class="wikitable"
! Key !! Action
|-
| PgUp / PgDown || Change map levels
|-
| V || Toggle layering
|-
| F2-F4 || Movement modes: Prone / Walk / Run
|-
| F5-F8 || Fire modes: Cease / Aimed / Snap / Auto
|-
| F9-F11 || Behavior: Evasive / Normal / Aggressive
|-
| Backspace || Toggle kneel
|-
| 1-6 || Select squad
|-
| Shift + 1-6 || Select specific unit in current squad
|-
| Shift + Ctrl + 1-6 || Add unit to selection
|-
| Alt + 1-6 || Cycle through spotted enemies of unit
|-
| Enter || Open inventory
|-
| [ / ] || Throw right / left hand item
|-
| ' / \ || Drop right / left hand item
|-
| E || End turn (turn-based mode)
|-
| J || Make unit jump (down from a cliff)
|-
| S / L || Open save / load menu
|}

=== General Controls ===

{| class="wikitable"
! Key !! Action
|-
| Mousewheel || Scroll lists
|-
| Esc || Go back, close form, cancel
|-
| Enter || Confirm, go forward
|-
| Space || Pause/Resume time
|-
| Tab || Toggle map
|-
| C || Toggle follow mode
|-
| M || Show message log
|-
| Home || Zoom to last event
|-
| Arrows || Move camera
|-
| 0-5 (Cityscape) || Control game speed
|}

== Pause Notifications ==

OpenApoc adds a comprehensive '''configurable notification system''' that can pause the game when specific events occur. Each notification can be individually toggled. These are not present in the original game.

=== City Notifications ===
* UFO spotted
* Vehicle damage (light / moderate / heavy / destroyed)
* Vehicle escaping (damaged and returning to base)
* Vehicle out of ammo
* Vehicle low on fuel
* Agent died
* Agent arrived at base
* Cargo / Transfer / Recovery arrived at base
* Vehicle repaired / rearmed / refuelled
* Not enough ammo / fuel
* Unauthorized vehicle detected
* X-COM base destroyed

=== Battle Notifications ===
* Hostile spotted / died
* Unknown unit died
* Agent died / brainsucked
* Agent critically wounded / badly injured / injured
* Agent under fire
* Agent unconscious / left combat zone
* Agent frozen / berserk / panicked / panic over
* Psionic attack on unit / unit under psionic control / freed from control

== Original Game Bugs Fixed ==

OpenApoc fixes or avoids several [[Known Bugs (Apocalypse)|known bugs]] from the original game:

* '''UFO speed bug''': Fixed alien craft having 0 speed in certain conditions
* '''Infiltration screen overflow''': Fixed infiltration screen going blank when exceeding 42 days
* '''Security Station turrets''' (partial): In the original turn-based mode, Security Station turrets did not have their TUs refreshed at the start of turns, rendering them mostly useless after the first shot
* '''Sound issues''': Fixed OGG Vorbis music playback issues that could occur in the original
* '''Learning AI''': The original game's advertised "learning AI" was effectively non-functional — it stopped working after saving the game and depended on specific CD-ROM file locations. OpenApoc does not attempt to replicate this broken feature
* '''Brainsucker Pod handling''': Various fixes for Brainsucker Pod inventory issues, storage space, and alien containment display

== Modding Support ==

Unlike the original game, OpenApoc is designed with modding in mind:

* '''XML data files''': Nearly all game data (units, weapons, vehicles, buildings, organizations) is defined in editable XML files
* '''Mod loading system''': Mods are loaded from a configurable directory (default: <code>./data/mods</code>), specified as a colon-separated list
* '''Lua scripting''': A Lua scripting system allows custom AI and game logic modifications. Scripts are loaded via the <code>OpenApoc.Mod.ScriptsList</code> configuration option
* '''Editable save games''': Since saves are XML in ZIP archives, game state can be manually edited

== Features Not Yet Implemented ==

As of early 2026, OpenApoc is in '''alpha''' state. The following features from the original game are not yet fully implemented:

=== Core Gameplay ===
* Victory and defeat screens
* Alien Takeover screen
* Full organization diplomacy with dual relationship values (the original tracked two separate relationship scores per organization)
* Overspawn mechanic
* Full dynamic action music structure
* Agent name generator

=== AI and Movement ===
* Advanced battle AI: cover usage, flanking, grenade throwing, retreat and regrouping behaviors
* Intelligent alien movement patterns within the city
* True ground vehicle movement with lanes, highways, and overtaking behavior
* Evasive/Normal/Aggressive unit AI behavior modes (buttons exist but AI differentiation is incomplete)

=== Other ===
* Proper portal locations in the Alien Dimension
* Full graphs and statistics feedback screens
* Organization vehicle AI (buying, selling, managing their own fleets)
* Coloured text support in some UI elements

For the full development roadmap, see the [https://github.com/OpenApoc/OpenApoc/issues/263 Playable Alpha], [https://github.com/OpenApoc/OpenApoc/issues/264 Beta], and [https://github.com/OpenApoc/OpenApoc/issues/265 Release 1.0] milestone issues on GitHub.

== Debug Mode ==

OpenApoc includes an extensive debug system not present in the original game. Debug hotkeys are toggled with '''F1''' in both the cityscape and battlescape. When enabled, various diagnostic and cheat functions become available:

=== Cityscape Debug ===
* Ctrl+Alt+Shift+Click: Destroy scenery / collapse building
* Spawn UFOs, repair scenery, warp to alien dimension
* Display road pathfinding, walk modes, alien positions, vehicle paths
* Dump voxel maps for line of sight/fire analysis
* Highlight tubes, roads, and hills with directional filters

=== Battlescape Debug ===
* Teleport units, stun/remove units, restore stats
* Reveal entire map with line-of-sight visualization
* Modify morale and psionic stats
* Spawn explosions and directional shots
* Re-link support lines for map parts

=== Base Screen Debug ===
* Instantly finish all facility construction
* Near-instantly complete research projects

== See Also ==

* [[OpenApoc]] — main OpenApoc page
* [[Apocalypse]] — original X-COM: Apocalypse game page
* [[Known Bugs (Apocalypse)]] — bugs in the original game
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/comparison/differences.md OpenApoc Wiki: Differences] — Extended comparison documentation
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — source code and issue tracker
* [https://github.com/OpenApoc/OpenApoc/blob/master/README_HOTKEYS.txt README_HOTKEYS.txt] — complete hotkey reference

[[Category:OpenApoc]]

Credits (OpenApoc)

2026-03-01T21:48:39Z

Deldonut1: Major rewrite: full contributor list from git history with roles; acknowledgements section

{{DISPLAYTITLE:Credits (OpenApoc)}}
'''[[OpenApoc]]''' is a community-driven open-source project. It is near impossible to adequately credit everyone involved — this page attempts to recognise the key contributors whose work has shaped the project.

== Project Founder ==

* '''[[User:PmProg|PmProg]] - Marq Watkin''' — Founded the OpenApoc project in July 2014

== Lead Developer ==

* '''[[User:JonnyH|JonnyH]] - Jonathan Hamilton''' — Game UI, AI, Cityscape, Battlescape, Framework, rendering engine, serialisation, and overall architecture. By far the largest contributor to the codebase.

== Core Contributors ==

Listed alphabetically. Contributions span code, testing, translation, reverse-engineering, modding, and community management.

{| class="wikitable sortable"
|-
! Contributor !! Primary Contributions
|-
| '''[[User:Atrosha|Atrosha]] - Panasenko Vasiliy Sergeevich''' || Many fixes, UI of agent characteristics (Rest In Peace; 1980–2021)
|-
| '''[[User:Deldonut1|deldonut1]]''' (Ayrton Denner) || Gameplay improvements, bug fixes, documentation, wiki
|-
| '''[[User:Empty`void|emptyVoid]]''' || Code contributions, bug fixes
|-
| '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar''' || Game archivist, testing, modding (Extended Weapons Mod), original game historian
|-
| '''[[User:FranciscoDA|FranciscoDA / Flacko]]''' || UI improvements (hover screens), Win installer, code contributions
|-
| '''[[User:Ivan_Shibanov|Shellstorm - Ivan Shibanov]]''' || Fixes, AI, Economics, Diplomatic Rift
|-
| '''[[User:Istrebitel|Istrebitel]]''' || Game UI, AI, Battlescape, data extraction, Skirmish Mode, debug system, hotkey set, 40+ improvements and options interface, video making
|-
| '''[[User:Jarskih|Jarskih]] - Jari Hanski''' || Many fixes
|-
| '''Kgd192''' || Code contributions
|-
| '''Kurtsley''' || Gameplay bug fixes, code improvements (2024–2025)
|-
| '''Luis Camara''' || Code contributions
|-
| '''[[User:Makus|Makus]]''' || Community & PR, website hosting, designer, Russian translation, VK group founder, FB page editor, YouTube channel editor
|-
| '''[[User:PmProg|PmProg]] - Marq Watkin''' || Framework core, UI framework core, Game UI, FB poster, YouTube channel admin
|-
| '''[[User:Redv|redv]]''' || Vehicle location screen, drag-and-drop mechanics, many fixes
|-
| '''[[User:Roger|Roger]]''' || Documentation fixes
|-
| '''[[User:Sfalexrog|sfalexrog]] - Alexey Rogachevskiy''' || Android core, .cue image loader, audio backend core, fixes
|-
| '''[[User:Skin36|Skin36]]''' || Reverse engineering (OG disassembly), Russian translation, fire rate and accuracy formula documentation
|-
| '''[[User:SupSuper|SupSuper]] - Daniel Albano''' || Base management, tooltips, fixes, Game UI, founder of OpenXcom, Community & PR
|}

== Additional Contributors ==

The following people have also contributed code, translations, bug reports, or other valuable work:

{| class="wikitable sortable"
|-
! Contributor !! Contributions
|-
| '''[[User:5thAvenue|5thAvenue]]''' || Initial French translation
|-
| '''Andy51''' (Andrey Isakov) || Code contributions
|-
| '''Anders Sandberg Nordbø''' || Code contributions
|-
| '''Andre Haberle''' || Code contributions
|-
| '''AndreyCreator''' || Code contributions
|-
| '''Ashenomo''' || Code contributions
|-
| '''[[User:Blackwolf-Kuzoku|Blackwolf-Kuzoku]]''' || Initial German translation
|-
| '''Dan Church''' (h3xx) || Code contributions
|-
| '''Dl471''' || Code contributions
|-
| '''Dmitry Marakasov''' (AMDmi3) || Code contributions
|-
| '''[[User:Jay_Atkinson|DoxaLogosGit - Jay Atkinson]]''' || Build instructions fix
|-
| '''Gnegno84''' (Marcello Santambrogio) || Code contributions
|-
| '''Johnny Solbu''' (solbu) || Code contributions
|-
| '''Gsw88''' || Code contributions
|-
| '''Hambones82''' (Josh Hamberger) || Code contributions
|-
| '''Kaja47''' || Code contributions
|-
| '''[[User:Kammerer|Kammerer]]''' || Russian translation, fonts, researcher
|-
| '''Killermosi''' (Silviu Ghita) || Code contributions
|-
| '''Kirill Mishustin''' (TreacherousOne) || Code contributions
|-
| '''[[User:Kkmic|kkmic]]''' || Build fixes, readme fixes
|-
| '''Kovarny''' || Code contributions
|-
| '''NagyAlex96''' || Code contributions
|-
| '''Pkubaj''' || Code contributions
|-
| '''[[User:Przemyslaw_Onak|Przemyslaw Onak]]''' || Saved game & serialization fixes
|-
| '''RedRobin84''' (Martin &Ccaron;ervenka) || Code contributions
|-
| '''ShadowDancer''' || Code contributions
|-
| '''SiemensSchuckert''' || Code contributions
|-
| '''[[User:SolariusScorch|SolariusScorch]]''' || Small language fixes
|-
| '''[[User:Sonicelo|Sonicelo]] - Gregor Su&scaron;anj''' || Windows build fixes
|-
| '''[[User:Sparkstar|sparkstar]]''' || GameUI fixes
|-
| '''[[User:Steve_Schnepp|steveschnepp - Steve Schnepp]]''' || Vagrant build
|-
| '''StewartM''' (Stewart Matheson) || Code contributions
|-
| '''SuperUserCode''' || Code contributions
|-
| '''Volkov "BabyWolf" Semjon''' || Code contributions
|-
| '''[[User:Xracer|Xracer]]''' || Initial Spanish translation
|-
| '''[[User:Zigmar|zigmar / zigmar-ems]] - Pavel Antokolsky''' || UI Scaling
|}

== Testing ==

* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''
* '''Quickmind / Quickmind01'''
* '''Yataka Shimaoka'''
* '''[[EmperorLol|EmperorLol - Laurie Blake]]'''
* '''Jigoku-Panzer - Dean Martin'''

== Modding Structure and Testing ==

* '''[[User:JonnyH|JonnyH]] - Jonathan Hamilton'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''
* '''[[User:Istrebitel|Istrebitel]]'''
* '''Voiddweller'''
* '''[[User:Skin36|Skin36]]'''

== Reversing and Research ==

* '''[[User:Skin36|Skin36]]'''

== Translation ==

* '''[[User:5thAvenue|5thAvenue]]''' — Initial French translation
* '''[[User:Blackwolf-Kuzoku|Blackwolf-Kuzoku]]''' — Initial German translation
* '''[[User:Kammerer|Kammerer]]''' — Russian translation, Fonts, Researcher
* '''[[User:Skin36|Skin36]]'''
* '''[[User:SolariusScorch|SolariusScorch]]''' — Small language fixes
* '''[[User:Xracer|Xracer]]''' — Initial Spanish translation

== Project Coordination, Writing, Video Making and Social Media ==

* '''[[User:Istrebitel|Istrebitel]]'''
* '''[[User:Makus|Makus]]'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''

== Community Administration and Moderation ==

* '''[[User:PmProg|PmProg]] - Marq Watkin'''
* '''[[User:Makus|Makus]]'''
* '''[[User:SolariusScorch|SolariusScorch]]'''
* '''[[User:FilmBoy84|FilmBoy84]] - Jacob Deuchar'''

== Art and Design ==

* '''[[User:Makus|Makus]]'''

== Resources and Management ==

* '''GitHub:''' [[User:JonnyH|JonnyH]], [[User:Istrebitel|Istrebitel]], [[User:FilmBoy84|FilmBoy84]], Quickmind
* '''Forum:''' [[User:JonnyH|JonnyH]] (domain), [[User:Makus|Makus]] (hosting and scripts)
* '''Facebook:''' [[User:JonnyH|JonnyH]] (admin), [[User:FilmBoy84|FilmBoy84]] (editor), [[User:Makus|Makus]] (editor)
* '''YouTube:''' [[User:JonnyH|JonnyH]] (admin), [[User:FilmBoy84|FilmBoy84]] (editor), [[User:Makus|Makus]] (editor)
* '''Reddit:''' [[User:Istrebitel|Istrebitel]] (starter), [[User:Makus|Makus]] (editor), [[User:FilmBoy84|FilmBoy84]] (editor)
* '''Vkontakte:''' [[User:Makus|Makus]] (starter, editor), [[User:Skin36|Skin36]], [[User:Istrebitel|Istrebitel]]
* '''Twitter:''' [[User:Makus|Makus]]

== Additional Community Members ==

It's near impossible to adequately credit everyone that has laid a hand on an open-source project, so here are the main sources. Rest assured if you helped us, we are thankful for it.

* [https://github.com/OpenApoc/OpenApoc/graphs/contributors All contributors on GitHub]
* [https://www.transifex.com/x-com-apocalypse/teams/ All translators on Transifex]
* [http://openapoc.org/widget-pages/team/ All testers]
* [http://openapoc.org/ All forum members]
* All platform porters
* And the rest of the community at large: Players, fans, press members, let's players, etc. You know who you are.

== Third-Party Code ==

=== External Dependencies ===

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://www.libsdl.org SDL2]''' || Windowing, input, audio
|-
| '''[https://boost.org Boost]''' (locale, program-options, uuid, crc) || Localisation, settings management, hash functions
|-
| '''[https://xiph.org/vorbis/ LibVorbis]''' || Ogg Vorbis music decoding
|-
| '''[https://www.qt.io/ Qt]''' (Qt5 or Qt6 base) || Launcher GUI (optional)
|-
| '''[https://nongnu.org/libunwind/download.html libunwind]''' || Debug backtracing (Linux only)
|}

=== Bundled Dependencies (Submodules) ===

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://github.com/fmtlib/fmt fmtlib (fmt)]''' || C++ string formatting library
|-
| '''[https://glm.g-truc.net GLM]''' || Math library (vectors, matrices, etc.)
|-
| '''[https://sourceforge.net/projects/libsmacker/ libsmacker]''' || Decoder for <code>.smk</code> video files
|-
| '''[https://github.com/lvandeve/lodepng lodepng]''' || Reading/writing PNG image files
|-
| '''[https://www.lua.org/ Lua]''' || Scripting language
|-
| '''[https://github.com/Neargye/magic_enum magic_enum]''' || Header-only C++17 static reflection for enums
|-
| '''[https://github.com/richgel999/miniz miniz]''' || Zlib-compatible compression library
|-
| '''[https://icculus.org/physfs/ PhysFS]''' (patched) || Reading data from <code>.iso</code> files and directory trees
|-
| '''[https://pugixml.org pugixml]''' || XML library for game data files
|}

== Acknowledgements ==

* '''Julian Gollop''' — Original designer of X-COM: Apocalypse. Has publicly endorsed the OpenApoc project.
* '''MicroProse / Mythos Games''' — Original developers of X-COM: Apocalypse (1997)
* The [https://www.ufopaedia.org/index.php UFOpaedia] community for maintaining comprehensive X-COM documentation

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Compiling (OpenApoc)]] — Building from source (for potential contributors)
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code and issue tracker
* [https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki] — Extended developer and game mechanics documentation
* [https://discord.gg/f8Rayre OpenApoc Discord] — Community discussion

[[Category:OpenApoc]]

Controls (OpenApoc)

2026-03-01T21:26:27Z

Deldonut1: Major rewrite: complete controls reference for v0.0.49+; added Cityscape and Battlescape hotkey tables

OpenApoc aims to implement all controls from the original game while introducing new hotkeys to improve interface usability. A key addition is the '''improved city control scheme''' — a completely new, consistent control system using modifier keys. This can be disabled via the "Improved city control scheme" option in the More Options menu to restore vanilla behavior.

For debug and cheat hotkeys, see [[Hidden Features (OpenApoc)]].

== General UI Hotkeys ==

{| class="wikitable"
! Key !! Action
|-
| Mousewheel || Scroll lists
|-
| Esc || Go back, close form, "Cancel" option
|-
| Enter || Go forward, "Confirm" option, first option (e.g., real-time in briefing)
|-
| Space || Skip, second non-cancel option (e.g., turn-based in briefing, equip button in squad assignment)
|}

== General Hotkeys ==

{| class="wikitable"
! Key !! Action
|-
| Middle Click || Move camera to location
|-
| Arrow Keys || Move camera around
|-
| Tab || Toggle map
|-
| Space || Pause / Resume time (including turn-based)
|-
| Esc || Options menu
|-
| C || Toggle follow mode
|-
| M || Show message log
|-
| Home || Zoom to last event
|}

== Cityscape Controls ==

=== Vanilla Controls Note ===

The original game's city controls were inconsistent and limited:
* Right-clicking moved the map in city but not in battle
* No quick access to frequently used screens (equipment, location, base)
* Alt/Shift hotkeys acted as if clicking a corresponding button — missing a target changed your selection mode

OpenApoc introduces a new, consistent control scheme explained below. To restore vanilla controls, disable "Improved city control scheme" in the More Options menu. With vanilla controls:
* Right click moves screen to cursor
* Alt + Left Click orders vehicle attack
* Shift + Left Click orders moving to building
* Left-clicking on building always opens building screen
* No OpenApoc mouse controls will function

=== Cityscape Mouse (Improved Scheme) ===

{| class="wikitable"
! Input !! Action
|-
| Left Click on building || Open building screen (base screen if it contains a base)
|-
| Right Click on building || Open building screen
|-
| Shift + Left Click || Order attack vehicle
|-
| Shift + Right Click || Order follow vehicle / go to location
|-
| Alt + Shift + Left Click || Order attack building
|-
| Alt + Shift + Right Click || Order go to building
|-
| Alt + Left Click || Open UFOpaedia for object (vehicle type, building function, or projectile source)
|-
| Alt + Right Click || Open UFOpaedia for object's owner (vehicle or building)
|}

==== Modifier Keys ====

{| class="wikitable"
! Modifier !! Effect
|-
| Ctrl (agent move orders) || Force agents to move on foot (never call taxi); allows use of personal teleporter
|-
| Ctrl (vehicle move orders) || Allow manual use of city teleporter buildings
|-
| Ctrl (attack orders) || Force vehicles to attack target (instead of recovering UFOs or escorting owned vehicles)
|}

'''Note:''' In vanilla, attacking owned vehicles was impossible. OpenApoc enables this via the "Allow attacking owned vehicles" toggle (on by default).

=== Cityscape Mouse on Vehicle / Agent Icons ===

{| class="wikitable"
! Input !! Action
|-
| Shift + Right Click || Open location screen
|-
| Ctrl + Shift + Right Click || Open equipment screen
|-
| Alt + Shift + Right Click || Open equipment screen
|}

=== Cityscape Unit Selection ===

{| class="wikitable"
! Input !! Action
|-
| Left Click || Select agent/vehicle (as the only object selected)
|-
| Ctrl + Left Click || Add agent/vehicle to selection and make it first in the list
|-
| Right Click || Remove agent/vehicle from selection
|}

=== Cityscape Keyboard ===

{| class="wikitable"
! Key !! Action
|-
| 0, 1, 2, 3, 4, 5 || Control game speed
|-
| N || Manual control (with vanilla scheme: M is manual control and there is no way to open message log)
|}

== Vehicle Equipment ==

{| class="wikitable"
! Input !! Action
|-
| Shift + Click || Auto-equip item into first available slot, or auto-remove to base stores
|}

== Agent Equipment ==

Standard selection controls apply, with the option to de-select with right click.

{| class="wikitable"
! Input !! Action
|-
| Shift + Click || Auto-equip item into first available slot, or auto-remove to base stores / ground
|-
| Ctrl + Click on weapon || Remove clip from weapon
|-
| 1 through 0 || Apply saved equipment template to every selected agent
|-
| Ctrl + 1 through 0 || Remember current agent's equipment set as a template
|}

== Battlescape Mouse ==

{| class="wikitable"
! Input !! Action
|-
| Left Click || Order unit to execute action (move / throw / psi attack / teleport), open probed unit's screen, use item
|-
| Right Click || Turn towards cursor, focus enemy (real-time), use item's "auto" function (e.g., prime grenade for impact)
|-
| Shift + Left Click || Force-fire at target tile, shot moving parallel to ground
|-
| Shift + Alt + Left Click || Force-fire at target tile, shot aimed at tile's ground
|}

==== Modifier Keys ====

{| class="wikitable"
! Modifier !! Effect
|-
| Alt (movement) || Unit keeps facing the target while moving (strafing or moving backwards)
|-
| Alt (firing at tile) || Shot aims at the ground of the tile rather than at the unit's level
|-
| Shift || Turns cursor into attack mode
|}

=== Battlescape Unit Selection ===

{| class="wikitable"
! Input !! Action
|-
| Left Click || Select unit (as the only unit selected)
|-
| Ctrl + Left Click || Add unit to selection and make it first in the list
|-
| Right Click || Remove unit from selection
|}

== Battlescape Keyboard ==

=== Movement and Fire Modes ===

{| class="wikitable"
! Key !! Action
|-
| PgUp / PgDown || Change map levels
|-
| V || Toggle layering
|-
| F2 || Prone mode
|-
| F3 || Walk mode
|-
| F4 || Run mode
|-
| F5 || Cease fire mode
|-
| F6 || Aimed mode
|-
| F7 || Snap mode
|-
| F8 || Auto mode
|-
| F9 || Evasive mode
|-
| F10 || Normal mode
|-
| F11 || Aggressive mode
|-
| Backspace || Kneel mode
|}

=== Squad and Unit Selection ===

{| class="wikitable"
! Key !! Action
|-
| 1 through 6 || Select squad
|-
| Shift + 1 through 6 || Select unit in current squad (as the only unit selected)
|-
| Shift + Ctrl + 1 through 6 || Add unit to selection and make it first in the list
|-
| Alt + 1 through 6 || Cycle through spotted enemies of the selected unit
|}

=== Actions ===

{| class="wikitable"
! Key !! Action
|-
| Enter || Open inventory
|-
| [ || Throw right hand item
|-
| ] || Throw left hand item
|-
| ' || Drop right hand item
|-
| \ || Drop left hand item
|-
| Y || Confirm priming
|-
| N || Cancel priming
|-
| E || End your turn (turn-based mode)
|-
| S || Open save menu
|-
| L || Open load menu
|-
| J || Make unit jump (down from a cliff)
|}

== See Also ==

* [[Hidden Features (OpenApoc)]] — debug hotkeys and cheat system
* [[Improvements (OpenApoc)]] — toggle-able gameplay improvements
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/controls.md OpenApoc Wiki: Controls] — Extended controls documentation
* [[OpenApoc]] — main OpenApoc page

[[Category:OpenApoc]]

Compiling (OpenApoc)

2026-03-01T21:21:45Z

Deldonut1: Added reference to build documentation

{{DISPLAYTITLE:Compiling (OpenApoc)}}
This page describes how to compile '''[[OpenApoc]]''' from source on Windows, Linux, and macOS.

OpenApoc is written in '''C++17''' and uses '''[https://cmake.org CMake]''' (minimum version '''3.30''') as its build system. It targets GCC 8+, Clang 7+, and MSVC 2019+ (Visual Studio 2017 or later).

'''Important:''' You will need a copy of the original X-COM: Apocalypse CD image (<code>cd.iso</code>) placed in the <code>data/</code> directory of the source tree. The build process extracts game data tables from this file.

== Prerequisites ==

All platforms require:

* '''[https://git-scm.com Git]''' — to clone the repository and fetch submodules
* '''[https://cmake.org CMake] 3.30''' or newer
* A C++17-capable compiler:
** '''GCC 8+''' (Linux)
** '''Clang 7+''' (Linux / macOS)
** '''MSVC 2019+''' / Visual Studio 2017 or later (Windows)
* The original '''X-COM: Apocalypse''' disc image (<code>cd.iso</code>) — placed in <code>data/</code>

== External Dependencies ==

The following libraries must be installed on your system (or via vcpkg on Windows). These are '''not''' bundled with the source code:

{| class="wikitable"
|-
! Library !! Purpose !! Notes
|-
| '''[https://www.libsdl.org SDL2]''' || Windowing, input, audio || Required on all platforms
|-
| '''[https://boost.org Boost]''' (locale, program-options, uuid, crc) || Localisation, settings management, hash functions || Only these specific Boost libraries are needed
|-
| '''[https://xiph.org/vorbis/ LibVorbis]''' || Ogg Vorbis music decoding || Required on all platforms
|-
| '''[https://www.qt.io/ Qt]''' (Qt5 or Qt6 base) || Launcher GUI || Optional; can be disabled with <code>BUILD_LAUNCHER=OFF</code>
|-
| '''[https://nongnu.org/libunwind/download.html libunwind]''' || Debug backtracing || Linux only; not needed on Windows or macOS
|}

'''Note:''' Previous versions of this wiki page incorrectly listed <code>tinyformat</code>, <code>libboost-filesystem-dev</code>, <code>libboost-system-dev</code>, and <code>qtdeclarative5-dev</code> as dependencies. These are '''not''' required. The formatting library is <code>fmtlib</code> (bundled as a submodule), and only <code>boost-locale</code> and <code>boost-program-options</code> (plus <code>boost-uuid</code> and <code>boost-crc</code>) are needed from Boost.

== Bundled Dependencies (Submodules) ==

The following libraries are included as Git submodules in the <code>dependencies/</code> directory and are built automatically as part of the OpenApoc build. You do '''not''' need to install these separately:

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://glm.g-truc.net GLM]''' || Math library (vectors, matrices, etc.)
|-
| '''[https://sourceforge.net/projects/libsmacker/ libsmacker]''' || Decoder for <code>.smk</code> video files
|-
| '''[https://github.com/lvandeve/lodepng lodepng]''' || Reading/writing PNG image files
|-
| '''[https://www.lua.org/ Lua]''' || Scripting language
|-
| '''[https://github.com/richgel999/miniz miniz]''' || Zlib-compatible compression library
|-
| '''[https://icculus.org/physfs/ PhysFS]''' (patched) || Reading data from <code>.iso</code> files and directory trees
|-
| '''[https://pugixml.org pugixml]''' || XML library for game data files
|-
| '''[https://github.com/fmtlib/fmt fmtlib (fmt)]''' || C++ string formatting library
|-
| '''[https://github.com/Neargye/magic_enum magic_enum]''' || Header-only C++17 static reflection for enums
|}

To fetch or update all submodules, run:

git submodule update --init --recursive

== Building on Windows ==

=== Requirements ===

* '''[https://visualstudio.microsoft.com/vs/ Visual Studio]''' 2017 or later, with the "Desktop Development with C++" workload installed
* '''[https://github.com/Microsoft/vcpkg Vcpkg]''' package manager (for external dependencies)

=== Step-by-step ===

# Install Visual Studio with the "Desktop Development with C++" workload.
# Install a Git client (e.g. [https://desktop.github.com/ GitHub Desktop]) and clone the OpenApoc repository.
# Initialize the submodules:
#: <code>git submodule update --init --recursive</code>
# Install [https://github.com/Microsoft/vcpkg Vcpkg] and integrate it with Visual Studio.
# Install the required dependencies via vcpkg. For '''x64''' builds:
#: <code>vcpkg --triplet x64-windows install sdl2 boost-locale boost-program-options boost-uuid boost-crc qt-base6-dev libvorbis</code>
#: For '''x86''' builds, replace <code>x64-windows</code> with <code>x86-windows</code>.
#: To see all supported architectures: <code>vcpkg help triplet</code>
# Copy your <code>cd.iso</code> file into the <code>data/</code> directory.
# Open the OpenApoc directory in Visual Studio. If your version of Visual Studio does not have an "Open Folder" option, generate a project using CMake.
# Set the configuration to '''x64-Release''' (or '''x86-Release''') — must match your vcpkg triplet. Release is recommended because Debug builds are very slow.
# Visual Studio should automatically detect and configure CMake. If you did not integrate vcpkg globally, set the CMake toolchain file manually:
#* '''Visual Studio 2017:''' Add to your CMake settings JSON:
#*: <code>"CMAKE_TOOLCHAIN_FILE": "<path to vcpkg>\\scripts\\buildsystems\\vcpkg.cmake"</code>
#* '''Visual Studio 2019+:''' Build → CMake Settings → Toolchain file → <code><path to vcpkg>\scripts\buildsystems\vcpkg.cmake</code>
# Build the project. The first build may take a while, especially if vcpkg has not yet built all dependencies.

=== Running ===

When running from Visual Studio, the working directory is set to the project root, so the <code>data/</code> folder is found automatically. If running outside Visual Studio, copy the entire <code>data/</code> folder (including <code>cd.iso</code>) into the directory containing <code>openapoc.exe</code>.

== Building on Linux ==

=== Ubuntu (22.04 / 24.04) ===

Install the required packages:

sudo apt-get install libsdl2-dev cmake build-essential git libunwind8-dev \
libboost-locale-dev libboost-program-options-dev qtbase5-dev libvorbis-dev

Clone the repository and initialize submodules:

git clone <nowiki>https://github.com/OpenApoc/OpenApoc.git</nowiki>
cd OpenApoc
git submodule update --init --recursive

Copy the CD image:

cp /path/to/cd.iso data/

Configure and build:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
make -j$(nproc)

Run:

cd ..
./build/bin/OpenApoc

=== Fedora / Red Hat ===

Install the required packages (as root):

yum groupinstall "Development Tools" "Development Libraries"
yum install git SDL2-devel cmake libunwind-devel qt6-qtbase-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

=== Mageia ===

Install the required packages (as root):

urpmi "cmake(sdl2)" libstdc++-static-devel boost-devel boost unwind-devel \
task-c++-devel cmake git qt6-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

=== Optional CMake flags (all distributions) ===

{| class="wikitable"
|-
! Flag !! Default !! Description
|-
| <code>CMAKE_BUILD_TYPE</code> || (none) || Set to <code>RelWithDebInfo</code> for optimized builds with debug symbols, or <code>Release</code> for maximum optimization
|-
| <code>BUILD_LAUNCHER</code> || <code>ON</code> || Build the Qt-based launcher GUI; set to <code>OFF</code> to skip Qt dependency
|-
| <code>USE_SYSTEM_QT</code> || <code>OFF</code> || Use system-installed Qt instead of the vcpkg package
|-
| <code>ENABLE_TESTS</code> || <code>ON</code> || Build unit tests (run with <code>ctest</code> from the build directory)
|-
| <code>LTO</code> || <code>OFF</code> || Enable link-time optimization
|-
| <code>EXTRACT_DATA</code> || <code>ON</code> || Run the data extractor as part of the default build target
|-
| <code>CD_PATH</code> || <code>data/cd.iso</code> || Path to the X-COM: Apocalypse disc image
|}

== Building on macOS ==

Tested on macOS Sequoia 15.6.

=== Requirements ===

* '''[https://brew.sh Homebrew]''' package manager

=== Step-by-step ===

# Install Homebrew if not already present:
#: <code>/bin/bash -c "$(curl -fsSL <nowiki>https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh</nowiki>)"</code>
# Clone the repository and initialize submodules:
#: <code>git clone <nowiki>https://github.com/OpenApoc/OpenApoc.git</nowiki></code>
#: <code>cd OpenApoc</code>
#: <code>git submodule update --init --recursive</code>
# Install dependencies via Homebrew:
#: <code>brew install cmake boost pkg-config sdl2 qt@6 libvorbis</code>
# Add Qt to your PATH. If using '''zsh''' (default since macOS Catalina):
#: <code>echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zprofile</code>
#: If using '''bash''':
#: <code>echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.bashrc</code>
#: Then reload your shell or run <code>source ~/.zprofile</code> (or <code>source ~/.bashrc</code>).
# Copy the CD image:
#: <code>cp /path/to/cd.iso data/</code>
# Configure and build:
#: <code>mkdir build</code>
#: <code>cd build</code>
#: <code>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..</code>
#: <code>make -j$(sysctl -n hw.ncpu)</code>
# Run the application:
#: <code>cd ..</code>
#: <code>open ./build/bin/OpenApoc.app</code>

== Running Tests ==

After building, you can run the unit tests from the build directory:

cd build
ctest

== Common Issues / Troubleshooting ==

=== CMake version too old ===

OpenApoc requires '''CMake 3.30''' or newer. If your distribution ships an older version, download the latest from [https://cmake.org/download/ cmake.org] or install via <code>pip install cmake</code>.

=== Submodule errors / missing dependencies directory ===

If you see errors about missing files in <code>dependencies/</code>, ensure you have initialized the submodules:

git submodule update --init --recursive

If you previously cloned without <code>--recursive</code>, this command will fetch all required submodules.

=== cd.iso not found ===

The build expects the original X-COM: Apocalypse disc image at <code>data/cd.iso</code> by default. You can change this path with:

cmake -DCD_PATH=/path/to/cd.iso ..

Supported formats:
* A standard <code>.iso</code> file (rename to <code>cd.iso</code>)
* A directory containing extracted CD files (name the directory <code>cd.iso</code>)
* GOG <code>.cue</code>/<code>.bin</code> files: rename the <code>.cue</code> file to <code>cd.iso</code> and place the <code>.bin</code> file alongside it in <code>data/</code>

=== Debug builds are very slow ===

This is expected. Use <code>RelWithDebInfo</code> for a build that is optimized but still has debug symbols:

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

=== Missing Qt / launcher build fails ===

If you do not need the launcher GUI, disable it:

cmake -DBUILD_LAUNCHER=OFF ..

=== Windows: Visual C++ Runtime errors ===

When running a pre-built binary on Windows, ensure you have the latest [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist Visual C++ Redistributable] installed.

=== OpenGL requirements ===

OpenApoc requires '''OpenGL 2.0''' capable graphics hardware and drivers.

=== Linux: libunwind not found ===

On Ubuntu/Debian:

sudo apt-get install libunwind8-dev

On Fedora/RHEL:

sudo yum install libunwind-devel

=== macOS: Qt not found by CMake ===

Ensure Qt is on your PATH. After installing via Homebrew:

export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"

Then re-run <code>cmake</code>.

== See Also ==

* [[OpenApoc]] — Main OpenApoc wiki page
* [[Coding Style (OpenApoc)]] — C++ code style guidelines
* [[Differences to X-COM (OpenApoc)]] — How OpenApoc differs from the original game
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/development/building.md OpenApoc Wiki: Building] — Extended build documentation
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code repository
* [https://discord.gg/d6DAHEb OpenApoc Discord] — Community discussion and support

[[Category:OpenApoc]]

Compiling (OpenApoc)

2026-03-01T21:14:53Z

Deldonut1: Major rewrite: updated to C++17/CMake 3.30; corrected dependency list; added macOS and troubleshooting sections

{{DISPLAYTITLE:Compiling (OpenApoc)}}
This page describes how to compile '''[[OpenApoc]]''' from source on Windows, Linux, and macOS.

OpenApoc is written in '''C++17''' and uses '''[https://cmake.org CMake]''' (minimum version '''3.30''') as its build system. It targets GCC 8+, Clang 7+, and MSVC 2019+ (Visual Studio 2017 or later).

'''Important:''' You will need a copy of the original X-COM: Apocalypse CD image (<code>cd.iso</code>) placed in the <code>data/</code> directory of the source tree. The build process extracts game data tables from this file.

== Prerequisites ==

All platforms require:

* '''[https://git-scm.com Git]''' — to clone the repository and fetch submodules
* '''[https://cmake.org CMake] 3.30''' or newer
* A C++17-capable compiler:
** '''GCC 8+''' (Linux)
** '''Clang 7+''' (Linux / macOS)
** '''MSVC 2019+''' / Visual Studio 2017 or later (Windows)
* The original '''X-COM: Apocalypse''' disc image (<code>cd.iso</code>) — placed in <code>data/</code>

== External Dependencies ==

The following libraries must be installed on your system (or via vcpkg on Windows). These are '''not''' bundled with the source code:

{| class="wikitable"
|-
! Library !! Purpose !! Notes
|-
| '''[https://www.libsdl.org SDL2]''' || Windowing, input, audio || Required on all platforms
|-
| '''[https://boost.org Boost]''' (locale, program-options, uuid, crc) || Localisation, settings management, hash functions || Only these specific Boost libraries are needed
|-
| '''[https://xiph.org/vorbis/ LibVorbis]''' || Ogg Vorbis music decoding || Required on all platforms
|-
| '''[https://www.qt.io/ Qt]''' (Qt5 or Qt6 base) || Launcher GUI || Optional; can be disabled with <code>BUILD_LAUNCHER=OFF</code>
|-
| '''[https://nongnu.org/libunwind/download.html libunwind]''' || Debug backtracing || Linux only; not needed on Windows or macOS
|}

'''Note:''' Previous versions of this wiki page incorrectly listed <code>tinyformat</code>, <code>libboost-filesystem-dev</code>, <code>libboost-system-dev</code>, and <code>qtdeclarative5-dev</code> as dependencies. These are '''not''' required. The formatting library is <code>fmtlib</code> (bundled as a submodule), and only <code>boost-locale</code> and <code>boost-program-options</code> (plus <code>boost-uuid</code> and <code>boost-crc</code>) are needed from Boost.

== Bundled Dependencies (Submodules) ==

The following libraries are included as Git submodules in the <code>dependencies/</code> directory and are built automatically as part of the OpenApoc build. You do '''not''' need to install these separately:

{| class="wikitable"
|-
! Library !! Purpose
|-
| '''[https://glm.g-truc.net GLM]''' || Math library (vectors, matrices, etc.)
|-
| '''[https://sourceforge.net/projects/libsmacker/ libsmacker]''' || Decoder for <code>.smk</code> video files
|-
| '''[https://github.com/lvandeve/lodepng lodepng]''' || Reading/writing PNG image files
|-
| '''[https://www.lua.org/ Lua]''' || Scripting language
|-
| '''[https://github.com/richgel999/miniz miniz]''' || Zlib-compatible compression library
|-
| '''[https://icculus.org/physfs/ PhysFS]''' (patched) || Reading data from <code>.iso</code> files and directory trees
|-
| '''[https://pugixml.org pugixml]''' || XML library for game data files
|-
| '''[https://github.com/fmtlib/fmt fmtlib (fmt)]''' || C++ string formatting library
|-
| '''[https://github.com/Neargye/magic_enum magic_enum]''' || Header-only C++17 static reflection for enums
|}

To fetch or update all submodules, run:

git submodule update --init --recursive

== Building on Windows ==

=== Requirements ===

* '''[https://visualstudio.microsoft.com/vs/ Visual Studio]''' 2017 or later, with the "Desktop Development with C++" workload installed
* '''[https://github.com/Microsoft/vcpkg Vcpkg]''' package manager (for external dependencies)

=== Step-by-step ===

# Install Visual Studio with the "Desktop Development with C++" workload.
# Install a Git client (e.g. [https://desktop.github.com/ GitHub Desktop]) and clone the OpenApoc repository.
# Initialize the submodules:
#: <code>git submodule update --init --recursive</code>
# Install [https://github.com/Microsoft/vcpkg Vcpkg] and integrate it with Visual Studio.
# Install the required dependencies via vcpkg. For '''x64''' builds:
#: <code>vcpkg --triplet x64-windows install sdl2 boost-locale boost-program-options boost-uuid boost-crc qt-base6-dev libvorbis</code>
#: For '''x86''' builds, replace <code>x64-windows</code> with <code>x86-windows</code>.
#: To see all supported architectures: <code>vcpkg help triplet</code>
# Copy your <code>cd.iso</code> file into the <code>data/</code> directory.
# Open the OpenApoc directory in Visual Studio. If your version of Visual Studio does not have an "Open Folder" option, generate a project using CMake.
# Set the configuration to '''x64-Release''' (or '''x86-Release''') — must match your vcpkg triplet. Release is recommended because Debug builds are very slow.
# Visual Studio should automatically detect and configure CMake. If you did not integrate vcpkg globally, set the CMake toolchain file manually:
#* '''Visual Studio 2017:''' Add to your CMake settings JSON:
#*: <code>"CMAKE_TOOLCHAIN_FILE": "<path to vcpkg>\\scripts\\buildsystems\\vcpkg.cmake"</code>
#* '''Visual Studio 2019+:''' Build → CMake Settings → Toolchain file → <code><path to vcpkg>\scripts\buildsystems\vcpkg.cmake</code>
# Build the project. The first build may take a while, especially if vcpkg has not yet built all dependencies.

=== Running ===

When running from Visual Studio, the working directory is set to the project root, so the <code>data/</code> folder is found automatically. If running outside Visual Studio, copy the entire <code>data/</code> folder (including <code>cd.iso</code>) into the directory containing <code>openapoc.exe</code>.

== Building on Linux ==

=== Ubuntu (22.04 / 24.04) ===

Install the required packages:

sudo apt-get install libsdl2-dev cmake build-essential git libunwind8-dev \
libboost-locale-dev libboost-program-options-dev qtbase5-dev libvorbis-dev

Clone the repository and initialize submodules:

git clone <nowiki>https://github.com/OpenApoc/OpenApoc.git</nowiki>
cd OpenApoc
git submodule update --init --recursive

Copy the CD image:

cp /path/to/cd.iso data/

Configure and build:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
make -j$(nproc)

Run:

cd ..
./build/bin/OpenApoc

=== Fedora / Red Hat ===

Install the required packages (as root):

yum groupinstall "Development Tools" "Development Libraries"
yum install git SDL2-devel cmake libunwind-devel qt6-qtbase-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

=== Mageia ===

Install the required packages (as root):

urpmi "cmake(sdl2)" libstdc++-static-devel boost-devel boost unwind-devel \
task-c++-devel cmake git qt6-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

=== Optional CMake flags (all distributions) ===

{| class="wikitable"
|-
! Flag !! Default !! Description
|-
| <code>CMAKE_BUILD_TYPE</code> || (none) || Set to <code>RelWithDebInfo</code> for optimized builds with debug symbols, or <code>Release</code> for maximum optimization
|-
| <code>BUILD_LAUNCHER</code> || <code>ON</code> || Build the Qt-based launcher GUI; set to <code>OFF</code> to skip Qt dependency
|-
| <code>USE_SYSTEM_QT</code> || <code>OFF</code> || Use system-installed Qt instead of the vcpkg package
|-
| <code>ENABLE_TESTS</code> || <code>ON</code> || Build unit tests (run with <code>ctest</code> from the build directory)
|-
| <code>LTO</code> || <code>OFF</code> || Enable link-time optimization
|-
| <code>EXTRACT_DATA</code> || <code>ON</code> || Run the data extractor as part of the default build target
|-
| <code>CD_PATH</code> || <code>data/cd.iso</code> || Path to the X-COM: Apocalypse disc image
|}

== Building on macOS ==

Tested on macOS Sequoia 15.6.

=== Requirements ===

* '''[https://brew.sh Homebrew]''' package manager

=== Step-by-step ===

# Install Homebrew if not already present:
#: <code>/bin/bash -c "$(curl -fsSL <nowiki>https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh</nowiki>)"</code>
# Clone the repository and initialize submodules:
#: <code>git clone <nowiki>https://github.com/OpenApoc/OpenApoc.git</nowiki></code>
#: <code>cd OpenApoc</code>
#: <code>git submodule update --init --recursive</code>
# Install dependencies via Homebrew:
#: <code>brew install cmake boost pkg-config sdl2 qt@6 libvorbis</code>
# Add Qt to your PATH. If using '''zsh''' (default since macOS Catalina):
#: <code>echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zprofile</code>
#: If using '''bash''':
#: <code>echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.bashrc</code>
#: Then reload your shell or run <code>source ~/.zprofile</code> (or <code>source ~/.bashrc</code>).
# Copy the CD image:
#: <code>cp /path/to/cd.iso data/</code>
# Configure and build:
#: <code>mkdir build</code>
#: <code>cd build</code>
#: <code>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..</code>
#: <code>make -j$(sysctl -n hw.ncpu)</code>
# Run the application:
#: <code>cd ..</code>
#: <code>open ./build/bin/OpenApoc.app</code>

== Running Tests ==

After building, you can run the unit tests from the build directory:

cd build
ctest

== Common Issues / Troubleshooting ==

=== CMake version too old ===

OpenApoc requires '''CMake 3.30''' or newer. If your distribution ships an older version, download the latest from [https://cmake.org/download/ cmake.org] or install via <code>pip install cmake</code>.

=== Submodule errors / missing dependencies directory ===

If you see errors about missing files in <code>dependencies/</code>, ensure you have initialized the submodules:

git submodule update --init --recursive

If you previously cloned without <code>--recursive</code>, this command will fetch all required submodules.

=== cd.iso not found ===

The build expects the original X-COM: Apocalypse disc image at <code>data/cd.iso</code> by default. You can change this path with:

cmake -DCD_PATH=/path/to/cd.iso ..

Supported formats:
* A standard <code>.iso</code> file (rename to <code>cd.iso</code>)
* A directory containing extracted CD files (name the directory <code>cd.iso</code>)
* GOG <code>.cue</code>/<code>.bin</code> files: rename the <code>.cue</code> file to <code>cd.iso</code> and place the <code>.bin</code> file alongside it in <code>data/</code>

=== Debug builds are very slow ===

This is expected. Use <code>RelWithDebInfo</code> for a build that is optimized but still has debug symbols:

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

=== Missing Qt / launcher build fails ===

If you do not need the launcher GUI, disable it:

cmake -DBUILD_LAUNCHER=OFF ..

=== Windows: Visual C++ Runtime errors ===

When running a pre-built binary on Windows, ensure you have the latest [https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist Visual C++ Redistributable] installed.

=== OpenGL requirements ===

OpenApoc requires '''OpenGL 2.0''' capable graphics hardware and drivers.

=== Linux: libunwind not found ===

On Ubuntu/Debian:

sudo apt-get install libunwind8-dev

On Fedora/RHEL:

sudo yum install libunwind-devel

=== macOS: Qt not found by CMake ===

Ensure Qt is on your PATH. After installing via Homebrew:

export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"

Then re-run <code>cmake</code>.

== See Also ==

* [[OpenApoc]] — Main OpenApoc wiki page
* [[Coding Style (OpenApoc)]] — C++ code style guidelines
* [[Differences to X-COM (OpenApoc)]] — How OpenApoc differs from the original game
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code repository
* [https://discord.gg/d6DAHEb OpenApoc Discord] — Community discussion and support

[[Category:OpenApoc]]

What it should be. Design doc (OpenApoc)

2026-03-01T21:09:18Z

Deldonut1: Added See Also section and Category tag, fixed some typos

[[File:Big Apoc Concept Logo.png|right|260px]]
{{tocrightsticky}}
<div style="width:-webkit-calc(100% - 20em);width: -moz-calc(100% - 20em);width: -o-calc(100% - 20em);width: calc(100% - 20em);text-align:justify;">

<pre style="background:#121619;color:#939393;font-family: Arial; font-size: 1.2em; border-radius: 5px;"> The purpose of this work is to make OpenApoc more balanced, to provide a variety of interesting gameplay solutions, and to make the game more complex and deep (especially in superhuman and god mode). Balance changes are designed to increase the number of viable strategies in the game, so that one universal set of equipment is not used for each agent and the same tactics in each mission. The document was written without regard to the difficulties of translating such ideas as an attempt to get closer to the ideal. An attempt was also made to develop the theme of the main antagonists of the game. A lot of ideas were borrowed from everywhere, if you find out or want to add your own idea - there is a Discussion. This work is dedicated to fans and developers of OpenApoc and Apoc and all XCom fans in general. </pre>

<pre style="background:#edb500;color:#444444;font-family: Arial; font-size: 1.2em; border-radius: 5px;"> This page is mainly translated from Russian using translator sites and and some parts of the texts is manually edited to make it more clear. Please understand this fact, if you want to correct something, you can write in Discussion</pre>

= Big Apoc Concept =

* '''This a WIP page, please feel free to add your own ideas here or in [[Talk:What_it_should_be._Design_doc_(OpenApoc)|Discussion]]'''
* Ⓜ - big changes in the code that require, most likely, a separate mod
* Ⓒ - functions that were cut from the original or were in the plans
* Ⓘ - features that have images in ufopedias and in the game and are already imported into OpenApoc but do not have mechanics

= General provisions =

* I must say that in the future some of the original “problems” of the original could have been considered, of course, if not for the premature release of the game.
* You need to create a simple intro video or a simple LORE Apo slideshow of factions of various types of sentient beings and the struggle between them.
* You need to create a simple introductory video or a simple slideshow on the basics of tactical combat for task forces. studopedia.info/2-2651.html

=Menu mechanics =

The ability to arrange vehicles and agents in an order that I choose. I find it ANNOYING that my main team of 18 agents who I hired from the beginning, gets messed up by new hires being inserted between those agents.

=Cityscape gameplay, balance=

# The armor and durability of UFO vehicles must be doubled - UFOs must pose a real threat and this is better than doubling their numbers.
# The very first types of UFOs should be types 3 and 4, and types 1 and 2 simply escort them in large quantities.
# Ⓜ XCOM can execute third-party contracts:
## reflection of the raid on the building of criminals using alien weapons,
## raid on clearing a building from a gang using alien weapons,
## raid on the cleaning up laboratory engaged in research and development of alien weapons
## capture of the leader of the organization that was captured by aliens (100%) after which you can start reducing the percentage of infiltration by aliens by conducting raids,
## saving the sectoids from research conducted over them to replenish psi recruits (and increase the rating),
## saving androids enslaved and used as machines (and rating upgrades),
## reflection of the attacks and raids of the Cult of Sirius on other organizations that they will start when the infiltration reaches 100%

=Battlescape gameplay, balance=

# From the very beginning of the game, agents with high skills but for high salaries should also be available for hire.
# In the UFO ships from the very beginning of the game there should be random crews from all possible types of aliens, random numbers including Psimorph or Micronoid Aggregate.
# In each crew of a ship, a UFO must be at least 1-2 Micronoid Aggregate.
# Psimorph and Micronoid Aggregate should never attack first, and will go into melee only if all the other aliens are dead and there is no way to retreat.
# If Psimorph or Micronoid Aggregate is present on a mission, all agents should be seriously reduced in morale, as a result of its powerful psy field.
## Such a field is exhausting, therefore, Stamina and Bravery noticeably sags, first Stamina and after Bravery and Accuracy.
## Androids are immune to the effects of the psi field — another reason to take them on a mission.
# All psionics in the game must see the victim in person, or at least through the eyes of another fighter
# If Stamina drops to zero, then Accuracy should decrease dramatically.
# Androids should not be under the control of the Brainsackers
# If 30-50% of the aliens were killed in a collision with X-COM, the rest must leave the battlefield and move to another building.

== Weapons and Technologies ==
# Anti-alien toxins are extinguished by shield-destroyers.
# "Toxin A" "Toxin B" "Toxin C" are blocked by shields-destroyers.
# Personal teleporters cannot be used for agents (only organic can teleport).
# Ⓜ Criminal gangs should have a lot of old weapons familiar to us (Kalashnikov or M16) which can be picked up from their dead bodies.
# Ⓜ Criminal groups should very rarely have weapons from the first wars against aliens, but not necessarily cartridges for them, you can pick them up from their dead bodies.
# Ⓜ The game should just have a black market
# Ⓜ Hackers. The ability of agents to break open at the beginning of the mission and take control of the building system: close doors and elevators, isolate aliens in separate rooms, only agents can use doors and elevators.
## Aliens will not be able to escape from the mission or the chance to escape will be reduced in proportion to the number of hackers.
## For this, you may need a hacker set in the form of a device like a laptop that the agent will hold in his hand for the hacking effect to work.
## The fastest hacking androids - another reason to take them on a mission.
## People crack the system longer but the chance for the aliens is less

=Diversity on UFO crash missions=
or '''[MOD concept] Diversity: UFO crash missions'''

Ⓜ Crash clearing missions can be random timers and triggers that can stop the timer. For instance:

There may be several timers and some hidden ones, and some timers will need a trigger for it to appear.
# Kill all aliens
# Kill all Psimorph or Micronoid Aggregate or both because they increase the strength of the psi field (the psi field exhausts and lowers morale so Stamina and Bravery noticeably sag, first Stamina and then Bravery and Accuracy.)
# Capture the UFO control room and Destroy the UFO control system.
# At least 3 agents must penetrate the first level of UFOs and hold it.
# If the timer does not stop the mission will be:
## failed and the UFO will fly away.
## The strength of the psi alien field intensify
## Aliens will begin a massive assault.
## is complicated by the arriving gangs of marauders.
## complicated by the arising cultists of Sirius.
#Types of missions UFO crash should be more diverse, for example:
# Landing a damaged ship is a very difficult task and sometimes a UFO can simply explode without coping with the landing (leaving nothing).
# A damaged UFO that has landed can be destroyed by the organization’s ship next to which the UFO fell.
# After an air battle and an emergency landing, the corpses of aliens who died during the air battle and landing scattered inside the UFO should remain (most aliens are alive).
# Ⓜ It may happen that a UFO will be visually badly damaged, and all that you find is a couple of units of unconscious survivors and a lot of corpses, or all will be dead.
# It may happen that it will be impossible to recover the UFO and the aliens will scatter into the nearest buildings, the UFO will remain empty or there will be only a few spitters and multiworms.
# Ⓜ Arriving on a mission to crash UFOs in slums, we can meet a team of numerous marauders of gang members (who will take aliens in number and leave a lot of corpses) who have already joined the battle from criminal organizations wishing to get alien technology, they can already be outside UFOs and kill several aliens, or already inside the UFOs and kill all aliens and share the prey (Use the weapons of aliens). It's up to you to either kill them or fly away.
# Ⓜ 2 criminal gangs fighting among themselves or a police squad pursuing a criminal gang may also encounter. Gang members attack in groups of 8-20 - Osiron groups are the largest, Psyke groups are the smallest.
# Ⓜ If a UFO crashed near an important public building on a mission, you will find the Security Guard squad holding back the alien forces from spreading.
# Ⓜ Arriving on a mission, we can meet the members of the Cult of Sirius who flew in hoping to make contact and help the aliens. It's not for nothing that UFOpaedia says "This represents a significant threat to X-COM because the cultists will do anything to assist the Aliens in their purpose, whatever that might be." Aliens will infect micronoids and supply the cultists with their weapons and will use them as cannon fodder. Cult members fight in groups of around 10.
# Ⓜ On a downed UFO, there may be sectoids for the rescue of which points will be awarded.
# Ⓜ On a downed UFO, there may be people captured from neighboring buildings for food and for the salvation of which points will be awarded.
# Ⓜ On the mission, there may simply be armed civilians belonging to some unregistered movements and not part of any corporations that are fighting against the total control of corporations (as private organizations, elevating a person over a person).
# Next to the crashed UFO may appear a mission where aliens from UFO storm the building and security reflects the attack.
# Around the crashed UFO can form dangerous abnormal zones (fire tornadoes, poison clouds, smoke, explosions) due to incorrect operation of the damaged ship.
# UFO casing can be home to small insect-like creatures (eg Skincrawlers or Swarm) that mend the casing and can be dangerous to humans by eating or replacing flesh.
# Each crew of a UFO ship (types 3-7) can have 1-2 Micronoid Aggregate.
# Each UFO crew (types 3-7) can have 2-6 Micronoid Headwrappers or Micronoid Mentor.
# Micronoid Headwrappers or Micronoid Mentor are 1/6 Micronoid Aggregate which are located on the head of other aliens and can carry out psi control of both agents and their carriers.
# A combination of different types of the above changes.

=Immersion in the game on missions=
or '''[MOD concept] Immersion: Missions'''

Immersion in the game will also help **quick pop up phrases** that agents or other characters will pronounce when they get into some kind of situation or interacting by clicking on the cursor as is done in fallout 2.

[[File:OpenApoc_Concept_Spot.png|200px]] [[File:OpenApoc_Concept_Fog.png|200px]] [[File:OpenApoc_Concept_Battle.png|200px]]

'''Quick Phrases''' - This mod will help the player plunge into the atmosphere of the game even more with the help of **additional effects and sounds**.

The game has the disadvantage that agents are completely speechless like dolls. Immersion in the game will be helped by quick phrases that agents or other characters will utter when they get into a situation or interact by clicking with the cursor, for example, as done in Fallout 2.

* The content and mood of the phrases may depend on the nature of the agent and its type (hybrid, human, android, alien), this requires a separate mod with the agent's biography ...
* '''Random phrases of civilians when agents are close''' about aliens, about X-Com, about the situation in the city, about personal problems, about politics, shouts, questions, complaints, regrets, ridicule (due to species, race, etc.), admiration at PM celebrities, show off or show off, offer trade exchanges at PM prohibited,

'''The formula for a random phrase can be, for example, this (depending on the situation):'''

> ''' Hold positions '''
> (White): Shout (Chance 0%) + Swear word (Chance 50%) + Phrase (Chance 50%) + Stating 75% + * minor action (сhance 50%)

> ''' Search '''
> (White): Shout (50% chance) + Swear word (50% chance) + Phrase (100% chance) + Stating 25% + * minor action (50% chance)

> ''' Combat and Spot '''
> (Red): Shout (75% Chance) + Swear word (100% Chance) + Phrase (50% Chance) + Statement 100% + * Minor Action (100% Chance)

> ''' Panic '''
> (Blue): Shout (100% chance) + Swear word (75% chance) + Phrase (75% chance) + Stating 0% + * minor action (100% chance)

> '''Example of a phrase in battle:''' Aaahmm, + fuck, + I knew it, + I was wounded in my left arm + * presses the wound with my right hand

# Quick phrase color can show mood and intonation of pronunciation:
## White neutral mood
## Green good mood
## Orange enemy detection, alarm
## Red fight with the enemy, aggression
## Blue fear, panic
## Purple phrases under psi control
# Shout (Shout, shout, shout, shout, shout, click, whoop, shout, shout, chuckle)
# Swearing (usually one word depending on the situation)
# Phrase (statement, opinion of a being about a situation)
# Statement / report (short statement of what happened)
# There can also be minor actions from a third person, separately or added to phrases like:(they can also be unique depending on the type of creature (hybrid, human, android))
## Spitting (if without a helmet)
## Scratching
## Correction of armor or item
## Recharge
## Interception of weapons by hand
## Head gazing
## Humming or whistling motive
## Anecdote
## Clever quote from authors or bible
## Funny phrase (these psimorphs were fucking howling)
## Wish (now would be a beer)
...

'''Triggers for phrases can be (some triggers can be executed with a 50% chance, others 75% and 100%):'''
# 100% chance:
## Alien detection (different random set of phrases for a specific type of alien)
## Detection of a hostile person (a different random set of phrases for a specific type of person and his organization)
## Killing an alien (a different random set of phrases for a specific type of alien)
## Wounding the agent (a different random set of phrases for a specific place of injury or who wounded him, a request for help or anger and threats)
## Murder of a civilian by an agent
## Killing a civilian by an alien
## Killing a civilian by a hostile person
## Killing a hostile person (different random set of phrases for a specific target)
## Phrases of hostile people after detection, injury, killing of agents (a different random set of phrases for a specific type of agent (hybrid, human, android, alien))
## The agent runs out of ammo
## Agent hitting the target and wounding (a different random set of phrases for a specific type of creature and its organization)
## Agent hitting target protected by energy shield. Chance 70%
## Agent hitting a smoke screen
## Agent hitting a paralyzing veil
## Agent hitting a burning zone
## Hitting the agent by an entropy projectile of aliens
## Poisoning an agent with something
# Chance 50%:
## Capture an agent under psi control (a different random set of phrases for a specific type of target)
## Capture an alien agent under psi control (a different random set of phrases for a specific type of target)
## Capture by an agent of a hostile person under psi control (a different random set of phrases for a specific type of person and his organization)
## An agent who came under the control of a brainsucker (micronoids having access to human knowledge can speak)
## Throwing grenades by agent
## Throwing a grenade by an enemy at an agent that falls within a radius around the agent
## Explosion of a grenade harming the agent
## Grenade explosion nearby when the explosion touched the agent but did not harm
## Fall of the agent from a height after the destruction of the floor
## The agent picking up the found item
## Agent whose panic has passed
## Agent panicked
## An agent who woke up after falling into unconsciousness
# 70% chance:
## Long running agent
## Long sitting in one place
## Long stay of the agent in a particular position
## Long stay of the agent in a particular fashion
## A hostile person who woke up after falling into unconsciousness
## Agent after taking off
## Hostile people don't use flying armor ??
## Hostile person after taking off
## Switch to no shoot mode

In the UFO crash mission (not only here but also on the city map), you can add meteorological and other phenomena taking into account the post-apocalyptic state of the earth’s atmosphere and to diversify the game:

# Fog - will affect visibility and accuracy. Motion scanners come in handy here.
# Rain - affects the speed of movement and accuracy, the agent can also slip and fall. Adding rain sounds and sometimes thunder sounds.
# A strong wind, will have its overlay with an animated sprite, will greatly affect the accuracy of shooting. Add the sounds of the wind.
# Storm - rain and heavy rain, thunderstorm, lack of lighting and visibility due to heavy cloud cover. Adding sounds of rain, strong wind and thunder.
# Add sounds of a living city (sounds of cars, sirens, gunfights, and working factories).
# Add the occasional sounds of a damaged UFO similar to creature moans.

Additional weather conditions:
# Snow (falling or falling, or both) the accuracy increases if the snow does not fall. Add snow sounds for step
# Icing (frozen snow after warming) movement is very limited and the risk for the agent to fall.
# Large hail
# Solar radiation or storms.
# Emissions of radiation (local)

Nothing plunges more into the game than the sight of suffering and pain. A fight is never so clean. Aliens and people should not always die immediately, and sometimes shoot back with reduced accuracy (and you will have to finish them off so that they do not shoot or shut up). The wounded can moan for a long time, bleed and move a little, people can scream and call for help or swear using quick phrases. Puddles of blood under them can be added to corpses and wounded. When a bullet enters the body, add a small effect of tearing and scattering of blood and pieces of meat and clothing...

=Final game and Alien dimension=

=Interesting extracts from the real history=

* Brief extracts from the history of the world, theory and speculation may stir up the interest of the reader
** [[Background_ (Apocalypse) | The briefing page for Commander]] Tells us that Megaprime has long been doing something that is not clear and that our main task is to investigate this difficult situation and take action, including the activities of cults. [[X-COM_Timeline | The X-Com Timeline]] page and Phoenix Point history that I want to associate with Apoca [[https://www.youtube.com/watch?v=P4F_8zw0n1s PandoraVirus]] and [[https://phoenixpoint.info/stories/ Phoenix Point stories]] may help to look deeper into the situation in MegaPrime.
** From the story we learn that perhaps [[Cult of Sirius | The cult of Sirius]], [[Hypernews Network (Interceptor) #cultsiriusfound | founded in 2040]]., Has long been influenced by micronoids who were able to escape after the explosion of the city of T'letch. Perhaps the Cult of Sirius is a project whose goal is to overcome the overtone window, the framework of the permissible spectrum of opinions about aliens in public statements from the point of view of public morality, perhaps using new techniques and technologies to influence the subconscious, (alien) technologies.
** The history also preserved information about a variety of other secret, hidden organizations (from ancient priests of Egypt to modern intelligence services), family clans (oligarchies of Egypt, Carthage, Rome, Venice, etc.), genetic lines of people who influenced humanity over the centuries and which are indirectly possibly associated with micronoids.
** According to some information, micronoids are capable of preserving the body of their carrier for thousands of years and it is not clear how much remains from a person in such a being, but not everyone can survive the transformation of their body. Just imagine that such a person can, take a place at the very top of the pyramid of human society, using the psionic capabilities of micronoids, directing and implementing your plans for thousands of years, relentlessly dictating your will to millions of people, without managing conflicts and financial sphere ...
** There is information that micronoids have mutagenic abilities, and perhaps those micronoids that remained on the earth after landing T'letch, guided the evolution of the biosphere and terraformed the Earth’s atmosphere all this time ... No one knows what these organisms are capable of and what forms take under the influence of various conditions. maybe
** Perhaps after the activation of T'letch, the awakened micronoids and micronoids on the earth, preserved for millions of years, united and their activity intensified ...
** Perhaps the city woke up cyclically, changing the face of the earth from time to time ... spreading various forms of life for thousands of years, doing hybridization and experiments, and then, perhaps, collecting the necessary information to improve and adjust their goals. technologies "nullified" the land in the next catastrophe. According to geological and archaeological data, the last known cataclysm was about 12-10 thousand years ago, which carried away a developed civilization, conventionally, the "Atlants", sweeping away the remnants of humanity and ancient knowledge, but thousands and thousands of ruins from megalithic and cyclopean clutches, hundreds of pyramids and giant statues throughout the land as the brightest evidence and witnesses of those times.
*** [[http://www.egyptology.ru/antiq/platon-1.htm Ancient authors described]] those times, the Egyptian priest in a conversation with Solon: <i> "Ah, Solon, Solon! You, the Greeks , always remain children, and there is no elder among the Greeks! " "Why do you say that?" - Solon asked. “All of you are young with your mind,” he replied, “because your minds do not retain in themselves any tradition, which passed from family to family, and any teaching that has turned gray from time. The reason is the same. There have been and will be multiple and different cases of death of people and, moreover, the most terrible - because of fire and water, and others, less significant - because of thousands of other disasters.From here and the story you have about the Phaeton, son of Helios, who allegedly once harnessed his chariot, but he could not direct it along his father’s path, and therefore he burned everything on three mle, and he died, Incinerate Lightning "... So, you store memory only about one flood, and in fact there were many before; </i>
*** In the Necronomicon, a semi-mythical book, other dimensions and various creatures that live there are mentioned. In addition, various creatures and races that inhabited the Earth in previous eras are described. The author of the book spent the decade of the Arabian desert Dahna. According to ancient Arabic belief, it is in Dahna that the entrance to the mysterious city of Irem is hidden, where the knowledge of the Ancients was kept. In addition, on the pages of the manuscript, you can find a detailed description of the process of enslavement of human souls and instructions for creating a psychotronic weapon.
*** The books are not included in the Bible and other sources said that all knowledge was transferred to people by gods or angels. The bible says: “Dead things are formed from under the waters, and the living equations” or “Rephaim tremble under the waters, and those who dwell in them” (Rephaim are giants later called dead, spirits) (Torah Job 26: 5, Job Chapter 26: 5). The Ethiopian Book of Enoch. The third section. XVI Thanks to the knowledge inherited from the guards, the rephaim gained tremendous power over nature: they were able to "cover the firmament, contributing to the reduction of rain" (Breshit slave, 26, 17; Sotah, 34b). They were also engaged in the fact that in the surviving fragments of the Giant Book they are called the calculus of the whole earth: "Let them number all [the earth ...], let them calculate with the help of various calculations" (Giant Book). "[they] were born on earth [and grew up, and matured, and began to devour] (works of hard) labor of all sons of men, and [people] were unable to [feed themselves. And the giants] planned to destroy people [and devour them. And they began to sin and ...] against all the birds and beasts of the earth, [and the reptiles crawling on the earth and animals) in the water] and in the heavens, and sea fishes, and devour each other's flesh and drink blood] " (translation of the Aramaic fragments of the Book of Enoch from Qumran. Fragment 4QЕna ar 1iii 1-23).
*** Rulers and gods enlighteners with reptiloid, amphibian features that brought all knowledge to people at the beginning of foreseeable times (perhaps representatives of the antediluvian races that were used by micronoids during the floods):
**** [https://ru.wikipedia.org/wiki/%D0%9E%D0%B0%D0%BD%D0%BD Oann] - The first of Abgallu who taught the Sumerians
**** [https://ru.wikipedia.org/wiki/%D0%94%D0%B0%D0%B3%D0%BE%D0%BD Dagon] - perhaps one of Abgallu, the god of the Philistines, after they were settled Canaan
**** [https://en.wikipedia.org/wiki/Me_(mythology) Me Mystical Power] and attribute of all the gods of Mesopotamia (perhaps there is a connection with Micronoids)
**** [https://ru.wikipedia.org/wiki/%D0%90%D0%B1%D0%B7%D1%83 Abzu] - the world's ocean of underground fresh water, gods and clay were conceived in it Abzu was created man, the divine "me" was kept there and the assistants of Enki sages Abgallu worked.
**** [https://ru.wikipedia.org/wiki/%D0%90%D0%B1%D0%B3%D0%B0%D0%BB%D0%BB%D1%83 Abgallu] - seven wise men -the helpers of the god of wisdom Enki, created by him, the founders of the seven first Sumerian cities, who taught people everything, they did not eat food, which every night went into the depths of the sea.
**** [https://ru.wikipedia.org/wiki/%D0%AD%D0%B0_(%D0%B1%D0%BE%D0%B3) Enki or Ea] - Son of Enlil, Deity of Wisdom, groundwater (fresh) and underground world, cultural inventions, the creator of the Tigris River; Had epithets "cunning, powerful, intelligent, Mind Extensive." The name Enki means "Lord of the Earth", "Lord of the Bottom"
**** [https://lah.ru/wp-content/uploads/2014/10/E-engura_v2_article.pdf E-engura - Enki submarine] Which was made of metal, made a roar, its walls could give advice , swam to Abzu, "was under a divine ME", "In your heart, a high throne is erected, your door jamb is a sacred heavenly shutter." E-Engure was the abode of the god Enki and his inner circle. Enki did not allow anyone into his abode, including other gods.
**** [https://ru.wikipedia.org/wiki/%D0%9E%D1%81%D0%B8%D1%80%D0%B8%D1%81 Osiris] - the god of Egypt who brought knowledge to people, with green skin or scales.
**** [https://ru.wikipedia.org/wiki/%D0%A4%D1%83_%D0%A1%D0%B8 Fu Xi] is the first emperor of China and his sister-wife who ruled from the depths of the sea .
**** Nagas of India - It is believed that the serpent-nag was a totem of one of the powerful ancient tribes, whose representatives were called Nagas. It is argued that the naga kept the truth secret until people were ripe for understanding.
**** [https://ru.wikipedia.org/wiki/%D0%9A%D0%B5%D0%BA%D1%80%D0%BE%D0%BF%D1%81_(%D1%D1%8B%D0%BD_%D0%93%D0%B5%D0%B8) Tsar Kekrops] is the founder and first king of Attica and Athens, while Phaeton was killed during his death and Devkalion deluge occurred.
**** The symbol of Jesus was a fish
**** [[:File:Vatican-mitre.png | The Pope wears]] to this day, Mithra (infula) and the soutane and very much resemble the Sumerian priests of the demigods Abgallu.
**** [https://en.wikipedia.org/wiki/Nommo Hero Nommo] from the Dogon tribe (Mali, Africa) who flew from Sirius on his ark in which he brought all the ways of being, he is now on the ground and is waiting for a certain time to appear.
**** [https://ru.wikipedia.org/wiki/%D0%9A%D0%B5%D1%82%D1%86%D0%B0%D0%BB%D1%8C%D0%BA%D0%BE%D0%B0%D1%82%D0%BB%D1%8C Quetzalcoatl] - one of the main gods of the Aztec pantheon and pantheons of other civilizations of Central America. According to legends, Quetzalcoatl rules in Tula for more than 20 years, after which it sailed to East. The great ruler taught the people mathematics, medicine, astronomy, writing, jewelry, weaving. Associated with his name, the introduction of the calendar with a cycle of 52 years, the invention of the canons of music and dance. His syncretic and pacifist doctrine of the "tolkokoyotly" provided for the prohibition of human sacrifice, which was not strictly accepted by the priestly tip.
**** [https://tar-s.livejournal.com/1007079.html The goddess Api from the Scythians] - the Goddess of fertility, is the same among the Greeks
** Perhaps they are all these years, centuries or millennia ?, infiltrated various organizations, corporations and governments and have a wide network of agents of influence and incredible access to resources and knowledge.
** Perhaps MegaPrime was their project, for themselves, perhaps it was they using earth technologies, and maybe gaining access to dormant ancient technologies, bases or satellites, associated with another dimension and are the reason why the Gate between Dimensions opened above MegaPrim. And no one can say for sure that the gate did not open ever in the past ..

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Improvements (OpenApoc)]] — Currently implemented optional gameplay improvements
* [[Differences to X-COM (OpenApoc)]] — How OpenApoc differs from the original game
* [[Modding (OpenApoc)]] — Creating mods (some ideas from this page could be implemented as mods)
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/openapoc/roadmap.md OpenApoc Wiki: Development Roadmap] — Official development milestones and progress
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code and issue tracker
* [https://discord.gg/f8Rayre OpenApoc Discord] — Community discussion

[[Category:OpenApoc]]

Coding Style (OpenApoc)

2026-03-01T21:01:43Z

Deldonut1: Major rewrite: updated to C++17/clang-format-18; added smart pointers; logging; strings; review expectations

{{DISPLAYTITLE:Coding Style (OpenApoc)}}
This document specifies the guidelines for writing and formatting the C++ code that forms the core of '''[[OpenApoc]]'''.

OpenApoc uses '''C++17'''. This requires reasonably modern compilers ('''GCC 8+''', '''MSVC 2019+''', '''Clang 7+''' have been tested). You should avoid using compiler-specific extensions where possible. Exceptions exist, but should be wrapped in an <code>#ifdef</code>.

Code formatting is enforced by '''[https://clang.llvm.org/docs/ClangFormat.html clang-format]''' (version '''18'''). The configuration file <code>.clang-format</code> in the root of the OpenApoc source repository defines the project style.

Static analysis is enforced by '''[https://clang.llvm.org/extra/clang-tidy/ clang-tidy]''' (version '''18'''). The CI pipeline rejects unformatted code and code that fails tidy checks.

It is highly recommended to run <code>clang-format</code> on all modified files before committing:

<pre>clang-format -i path/to/file.cpp path/to/file.h</pre>

When run from the root of the OpenApoc source repository, it automatically uses the supplied <code>.clang-format</code> configuration file.

When using the CMake build system, there are dedicated targets:

<pre>
# Format all source files (from build directory)
cmake --build build -t format-sources

# Run static analysis (from build directory)
cmake --build build -t tidy
</pre>

== Indent ==

* Tabs for indenting, spaces for alignment, indenting by 1 tab for each new scope

<pre>
void function()
{
reallyLongFunctionNameWithLotsOfArguments(argOne, argTwo,
argThree);
}
</pre>

* Avoid going over '''100 columns''' (at tab width of 4 spaces)
** If you find yourself going over this, it's often a hint to try to pull things out of loops / into functions
** Don't break strings up to fit this; it looks ugly and makes things harder to read
* If you have to break, indent the following line by an extra tab
** When breaking a single statement, break the line '''before''' the next operator. Avoid having an operator as the last thing on a line.

<pre>
void reallyLongFunctionNameIMeanThisIsReallyBadlyNamed(int parameterOne,
int paramTwo, char theThirdOne)
{
if (parameterOne == yetAnotherReallyLongCondition
&& youHaveBetterThingsToDo)
{
doWhatever();
}
}
</pre>

== Whitespace ==

* Spaces before and after operators

<pre>
a = b;
a && b;
a + b;
</pre>

* Space after <code>if</code>/<code>while</code>/<code>else</code>/<code>for</code>, space after <code>:</code>/<code>;</code> in <code>for</code>

<pre>
for (auto &a : b)
</pre>

* No spaces after function name (or function-like keywords like <code>sizeof</code>), but space after flow control keywords, space after comma for multiple arguments

<pre>
func(a, b);
if (a == 0)
</pre>

* References and pointers: <code>&</code> and <code>*</code> align right (to the variable), not to the type

<pre>
float *pointerToFloat;
Type &ref;
</pre>

== Scope ==

* Indent 1 tab for each new scope
* New scope is '''always''' surrounded by <code>{}</code> braces, even for single-statement blocks
* Opening brace <code>{</code> goes on the '''next''' line at the indent of the enclosing scope ('''Allman style''')
* Closing brace <code>}</code> at the same indent as the opening <code>{</code>
* New scopes are caused by:
** Functions
** Conditional blocks (<code>if</code>/<code>else</code>/<code>while</code>/<code>for</code>)
** <code>switch</code>/<code>case</code>

<pre>
void functionDefinition()
{
newScopeHere();
}
</pre>

<pre>
if (x)
{
doWhatever();
}
else if (y)
{
doWhateverTheSecond();
}
else
{
doThatLastThing();
}
</pre>

* <code>switch</code> always has a <code>default</code> case unless switching over an <code>enum class</code> where every value is handled
* All <code>case</code> sections should have a <code>break</code>
* <code>case</code> braces <code>{}</code> are optional, based on whether new stack variables are needed

<pre>
switch (a)
{
case A:
doSomething();
break;
case B:
{
auto newVariable = getSomething();
useIt(newVariable);
break;
}
default:
break;
}
</pre>

== Naming ==

{| class="wikitable"
! Style !! Used For
|-
| <code>CamelCase</code> || Classes, enums, <code>enum class</code> members, namespaces, template parameters
|-
| <code>camelBack</code> || Methods, member variables, function parameters, local variables
|-
| <code>SHOUTY_CAPS</code> || Constants, macros
|-
| <code>lower_case</code> || Labels
|}

== Types ==

* Use <code>auto</code> liberally, especially when the type is obvious from the right-hand side. Use <code>auto &</code> to avoid copies.
* Use <code>enum class</code> over plain <code>enum</code>
* Use <code>struct</code> only for data-only types; structs must '''never''' use access modifiers
* No C-style casts — use <code>static_cast<></code>, <code>dynamic_cast<></code>, <code>reinterpret_cast<></code>
* Prefer <code>{}</code> brace initialization

== Smart Pointers ==

OpenApoc provides short aliases in <code>library/sp.h</code>:

{| class="wikitable"
! Alias !! Equivalent
|-
| <code>sp<T></code> || <code>std::shared_ptr<T></code>
|-
| <code>up<T></code> || <code>std::unique_ptr<T></code>
|-
| <code>wp<T></code> || <code>std::weak_ptr<T></code>
|-
| <code>mksp<T>(args...)</code> || <code>std::make_shared<T>(args...)</code>
|-
| <code>mkup<T>(args...)</code> || <code>std::make_unique<T>(args...)</code>
|}

* '''No naked <code>new</code>''' — always wrap in smart pointers immediately
* Prefer <code>up<></code> (exclusive ownership) over <code>sp<></code> unless shared ownership is genuinely needed
* Use <code>std::move()</code> to transfer <code>up<></code> ownership

== Templates ==

* Template type parameters should use <code>CamelCase</code>
* Place <code>template<...></code> on the line above the function/class declaration

<pre>
template <typename ValueType>
ValueType doSomething(ValueType input)
{
return input;
}
</pre>

== Class Declarations ==

* <code>public:</code>/<code>private:</code>/<code>protected:</code> written at class indent level (not indented further)
* Always explicitly write <code>private:</code>, even though it is the default
* <code>virtual</code> only on the base class; <code>override</code> on derived classes — never both together
* All classes with virtual methods must have a virtual destructor
* Use <code>= default</code> instead of empty <code>{}</code> constructor/destructor bodies
* Use member initializer lists; initializer order must match declaration order

<pre>
class MyClass : public BaseClass
{
private:
int memberVariable = 0;
UString name;
public:
MyClass() = default;
~MyClass() override = default;

void doSomething() override;
int getValue() const;
};
</pre>

== Functions ==

* Functions should be named <code>camelBack</code>
* Use '''early return''' — prefer separate <code>if (cond) return;</code> checks over deeply nested conditionals
* '''<code>const</code> aggressively''': const member functions, const parameters, const return types, const local variables
* Range-for loops: <code>for (auto &element : container)</code> / <code>for (const auto &element : container)</code>
* Prefer <code>emplace()</code> over <code>insert()</code> in STL containers

== General Code ==

* Use anonymous namespaces instead of <code>static</code> for file-local functions and classes

<pre>
namespace
{
void helperFunction()
{
// file-local helper
}
} // anonymous namespace
</pre>

* All project code lives in <code>namespace OpenApoc {}</code>. Namespace content is '''not''' indented. Closing brace gets a comment:

<pre>
namespace OpenApoc
{

class MyClass
{
// ...
};

} // namespace OpenApoc
</pre>

== Logging ==

Uses '''fmt-style format strings''' with positional <code>{0}</code>, <code>{1}</code> placeholders ('''not''' printf-style):

<pre>
#include "framework/logger.h"

LogInfo("Loaded mod \"{0}\"", modName);
LogWarning("Value {0} exceeds limit {1}", value, limit);
LogError("Failed to load file \"{0}\"", path);
</pre>

* <code>LogInfo</code> — general information
* <code>LogWarning</code> — recoverable errors
* <code>LogError</code> — fatal errors

== Strings ==

Use '''<code>UString</code>''' (from <code>library/strings.h</code>) for all strings. All <code>char*</code>/<code>std::string</code> values are assumed UTF-8.

String formatting uses the <code>fmt</code> library:

<pre>
#include "library/strings_format.h"

UString result = OpenApoc::format("Player has {0} credits and {1} agents", credits, agentCount);
</pre>

Translation:

<pre>
UString translated = tr("English text to translate");
</pre>

== Includes and Headers ==

* Use <code>#pragma once</code> (no traditional include guards)
* '''Include order''': Local headers first, then system headers. Each block alphabetically sorted.
* Local headers use paths '''relative to the OpenApoc root''': <code>"framework/logger.h"</code>, not <code>"../logger.h"</code> or <code>"logger.h"</code>
* '''Prefer forward declarations''' over <code>#include</code> in headers where possible

<pre>
#pragma once

#include "library/sp.h"
#include "library/strings.h"

#include <vector>

namespace OpenApoc
{

class ForwardDeclaredType;

class MyClass
{
private:
int member = 0;
public:
void publicFunction();
};

} // namespace OpenApoc
</pre>

== Key Review Expectations ==

These patterns are consistently enforced during code review:

# '''const correctness''' — if something can be <code>const</code>, it must be <code>const</code>
# '''Readable conditionals''' — avoid embedded comments in complex conditionals; prefer early-exit checks
# '''One logical change per PR''' — keep changes focused for clean history and bisectability
# '''Use <code>auto</code>''' — when the type is already visible on the RHS
# '''Prefer exclusive ownership''' — use <code>up<></code> over <code>sp<></code> when shared ownership is not required

== See Also ==

* [[OpenApoc]] — Main OpenApoc page
* [[Compiling (OpenApoc)]] — Build instructions for developers
* [https://github.com/OpenApoc/OpenApoc/blob/master/CODE_STYLE.md CODE_STYLE.md] — Full coding style specification in the repository
* [https://github.com/ayrtondenner/OpenApoc-wiki/blob/master/development/coding-style.md OpenApoc Wiki: Coding Style] — Extended coding style documentation
* [https://github.com/OpenApoc/OpenApoc OpenApoc on GitHub] — Source code repository
* [https://discord.gg/f8Rayre OpenApoc Discord] — Community discussion and support

[[Category:OpenApoc]]

User:Deldonut1

2026-03-01T20:29:18Z

Deldonut1: Created page with "Hello! I'm '''Ayrton Denner''', a contributor to '''OpenApoc''' and maintainer of the [https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki]. == About == I'm a so..."

Hello! I'm '''Ayrton Denner''', a contributor to '''[[OpenApoc]]''' and maintainer of the [https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki].

== About ==

I'm a software developer, data scientist, AI/ML engineer, and X-COM fan. I contribute to OpenApoc through gameplay improvements, bug fixes, documentation, and community knowledge preservation.

My main focus has been on building comprehensive documentation for the project — both developer-facing (architecture, coding style, build guides) and player-facing (game mechanics, features, comparisons with the original game).

== OpenApoc Contributions ==

* '''Gameplay improvements and bug fixes''' — Code contributions to the [https://github.com/OpenApoc/OpenApoc OpenApoc] project
* '''[https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki]''' — 30+ pages covering original game mechanics, OpenApoc features, development guides, and comparison documentation. Maintained as a git submodule in the OpenApoc repository.
* '''UFOpaedia wiki updates''' — Updating and expanding the OpenApoc pages here on UFOpaedia
* '''Community research''' — Discord knowledge mining (77,000+ messages), reverse-engineering findings documentation, project status assessments

== UFOpaedia Contributions ==

Pages I've created or significantly updated:

* [[OpenApoc]] — Main project page
* [[Installing (OpenApoc)]] — Installation guide
* [[Compiling (OpenApoc)]] — Build instructions
* [[Controls (OpenApoc)]] — Controls reference
* [[Improvements (OpenApoc)]] — Gameplay improvements
* [[Differences to X-COM (OpenApoc)]] — Comparison with the original
* [[Hidden Features (OpenApoc)]] — Debug and cheat system
* [[Modding (OpenApoc)]] — Modding guide
* [[Coding Style (OpenApoc)]] — Code style guidelines
* [[Info (OpenApoc)]] — Project information
* [[Credits (OpenApoc)]] — Contributors list

== Links ==

* [https://github.com/ayrtondenner GitHub — ayrtondenner]
* [https://github.com/ayrtondenner/OpenApoc-wiki OpenApoc Wiki]
* [https://www.linkedin.com/in/ayrton-denner/ LinkedIn]

[[Category:OpenApoc]]