Build OpenXcom3D from source

OpenXcom3D is OpenXcom Extended with a first-person 3D battlescape. Its repository holds one patch for OXCE, not a program that builds by itself: you take OXCE at the right commit, apply the patch and compile. This page walks you through it.

Only want to play? The ready builds for Linux and Windows need no compiling: here's how to play them, with every key, setting and feature.

  • About 15 minutes
  • About 1.5 GB free
  • Your own copy of UFO or TFTD
The 3D view: a city street at dusk, street lamps along the road, a soldier's rifle in the corner.
Where you'll be at the end: a battle in 3D (press F8).

On Linux the game builds with the compiler and SDL 1.2 libraries of your distribution. Pick your system in the bar above, and the page shows only its steps.

On Windows the game builds with MinGW-w64 from MSYS2: the compiler, CMake and the SDL 1.2 libraries all come from its package manager. The result is a Windows program like the release's. (Visual Studio isn't tested; MSYS2 is.)

This is how the release's Windows zip is made: on Linux, with llvm-mingw (Clang for Windows), downloaded by the build script. The scripts build the SDL libraries from their sources too, check every download against its SHA-256, and pack the zip.

The short way: with the tools from step 2 and Python 3, the installer does steps 3 to 5 in one go: it says what's missing, clones OXCE, applies the patch, builds, and sets up a profile that finds your Steam games.

Terminal
git clone https://github.com/b0realis/OpenXcom3D.git
cd OpenXcom3D
python3 install.py --from-source

Then start it with ~/Games/OpenXcom3D/play.sh. Below is the same by hand, to see each part.

  1. Have the original game ready

    You need your own copy of X-COM: UFO Defense (UFO: Enemy Unknown) and/or X-COM: Terror From The Deep, from Steam or GOG. Nothing of it comes with OpenXcom3D.

    What the game needs is the folder with GEODATA, GEOGRAPH, MAPS and UFOGRAPH in it. On Steam that's:

    • ~/.local/share/Steam/steamapps/common/XCom UFO Defense/XCOM
    • ~/.local/share/Steam/steamapps/common/X-COM Terror from the Deep/TFD
    • C:\Program Files (x86)\Steam\steamapps\common\XCom UFO Defense\XCOM
    • C:\Program Files (x86)\Steam\steamapps\common\X-COM Terror from the Deep\TFD

    The zip you build finds them in Steam by itself on the Windows machine, as the release does.

  2. Install the build tools

    Git, CMake, a C++ compiler, and the SDL 1.2 libraries (on current distributions that's sdl12-compat, SDL 1.2 on top of SDL2, which works fine):

    Debian, Ubuntu, Mint

    Terminal
    sudo apt install git cmake g++ make pkg-config libsdl1.2-dev libsdl-mixer1.2-dev libsdl-image1.2-dev libsdl-gfx1.2-dev zlib1g-dev libglu1-mesa-dev curl

    Fedora

    Terminal
    sudo dnf install git cmake gcc-c++ make pkgconf sdl12-compat-devel SDL_image-devel SDL_mixer-devel SDL_gfx-devel zlib-devel mesa-libGLU-devel curl

    Arch, Manjaro

    Terminal
    sudo pacman -S --needed base-devel git cmake sdl12-compat sdl_image sdl_mixer sdl_gfx glu zlib curl

    Download MSYS2 from msys2.org and install it (the default folder, C:\msys64, is fine). Then open MSYS2 UCRT64 from the Start menu: the prompt says UCRT64. Every command on this page goes into that window.

    First bring MSYS2 up to date. If it closes the window, open MSYS2 UCRT64 again and run the same command once more:

    MSYS2 UCRT64
    pacman -Syu

    Then the compiler, CMake, Ninja, pkg-config and the SDL 1.2 libraries:

    MSYS2 UCRT64
    pacman -S --needed git curl mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-pkgconf mingw-w64-ucrt-x86_64-SDL mingw-w64-ucrt-x86_64-SDL_image mingw-w64-ucrt-x86_64-SDL_mixer mingw-w64-ucrt-x86_64-SDL_gfx mingw-w64-ucrt-x86_64-zlib

    Only the usual build tools: the Windows compiler (llvm-mingw 20260922, LLVM 23) is downloaded by the build script into the build folder, nothing is installed.

    Debian, Ubuntu, Mint

    Terminal
    sudo apt install build-essential git cmake pkg-config curl xz-utils zip

    Fedora

    Terminal
    sudo dnf install gcc make git cmake pkgconf curl xz zip

    Arch, Manjaro

    Terminal
    sudo pacman -S --needed base-devel git cmake curl xz zip
  3. Get OXCE and apply the patch

    OXCE at exactly the commit OpenXcom3D is made for, then the patch on top of it:

    TerminalMSYS2 UCRT64
    git clone --branch oxce-plus https://github.com/MeridianOXC/OpenXcom.git
    cd OpenXcom
    git checkout f0134ef8065799c7723953d64b565f7832bfd782
    curl -LO https://raw.githubusercontent.com/b0realis/OpenXcom3D/main/openxcom3d.patch
    git apply openxcom3d.patch

    git apply says nothing when it works. The commit is OXCE 8.7.1 (2026-09-29); the patch adds the add-on (src/FirstPerson/), small hooks in OXCE, and the mod that switches it on (mod/OpenXcom3D/).

    The OpenXcom3D repository (its build scripts and the patch), with OXCE cloned into it as OpenXcom, at exactly the commit OpenXcom3D is made for, and the patch applied:

    Terminal
    git clone https://github.com/b0realis/OpenXcom3D.git
    cd OpenXcom3D
    git clone --branch oxce-plus https://github.com/MeridianOXC/OpenXcom.git
    git -C OpenXcom checkout f0134ef8065799c7723953d64b565f7832bfd782
    git -C OpenXcom apply ../openxcom3d.patch
  4. Build it

    In the OpenXcom folder (a few minutes):

    Terminal
    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DDEV_BUILD=OFF -DBUILD_PACKAGE=OFF
    cmake --build build -j 4

    The game is build/bin/openxcom, with OXCE's own data next to it in build/bin/. With more memory, a bigger -j builds faster.

    In the OpenXcom folder (several minutes). The options matter, see below:

    MSYS2 UCRT64
    mkdir -p build/sdl && cp /ucrt64/lib/libSDL.dll.a build/sdl/libSDL.a
    cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DDEV_BUILD=OFF -DBUILD_PACKAGE=OFF -DDEPS_DIR=none -DPKG_CONFIG_ARGN=--static -DEXTRA_XCOM_LIBS="-L$(cygpath -m "$PWD/build/sdl");$(pkg-config --static --libs libpng16 libjpeg libtiff-4 libwebp vorbisfile mad | tr -d '\r' | tr ' ' ';');-l:libFLAC.dll.a;-l:libmikmod.dll.a;-lwinmm"
    cmake --build build
    ldd build/bin/openxcom.exe | grep -o '/ucrt64/bin/[^ ]*' | xargs -r cp -t build/bin/
    • -DDEPS_DIR=none: without it, OXCE takes the Visual Studio libraries folder (deps) in its source and fails to link.
    • OXCE links MinGW builds statically, and MSYS2's SDL_image and SDL_mixer don't name the image and sound libraries they need. -DPKG_CONFIG_ARGN=--static and EXTRA_XCOM_LIBS add them.
    • MSYS2's SDL 1.2 is sdl12-compat, which has no static library: the first line copies its import library to build/sdl/libSDL.a, where the static link takes it, so the game uses SDL.dll.
    • FLAC and MikMod come from their DLLs (MSYS2's SDL_mixer asks for them so; -lwinmm is Windows' own MIDI, which the old SDL used to bring along), and sdl12-compat runs on SDL2.dll (sdl2-compat) and SDL3.dll: the last line copies every DLL the game needs from MSYS2 (ldd lists them) next to it.

    The game is build/bin/openxcom.exe, with OXCE's own data next to it in build/bin/.

    In the OpenXcom3D folder: the Windows compiler and the libraries first (about 5 minutes, once), then the game, then the zip:

    Terminal
    sh tools/windows/build_libs.sh
    sh tools/windows/configure.sh
    make -C OpenXcom/build-win64 -j 4
    sh tools/make_release_windows.sh

    build_libs.sh puts the compiler and the libraries in OpenXcom/build-win64/deps; make_release_windows.sh checks that the game needs nothing but Windows and its two DLLs, and packs release/OpenXcom3D-…-windows-x86_64.zip.

  5. Set up a profile and play

    A profile folder of its own keeps your saves apart from any other OXCE. Put the mod in it and the game data next to the mod. Still in the OpenXcom folder:

    Terminal
    mkdir -p ~/openxcom3d/mods
    cp -r mod/OpenXcom3D ~/openxcom3d/mods/
    ln -s "$HOME/.local/share/Steam/steamapps/common/XCom UFO Defense/XCOM" ~/openxcom3d/UFO
    build/bin/openxcom -data build/bin/ -user ~/openxcom3d/ -cfg ~/openxcom3d/

    For TFTD, link its folder as ~/openxcom3d/TFTD the same way. Steam elsewhere (~/.steam/steam, a Flatpak, another disk) or a game from GOG: link (or copy) its folder, the one from step 1, as UFO or TFTD.

    MSYS2 UCRT64
    mkdir -p ~/openxcom3d/mods
    cp -r mod/OpenXcom3D ~/openxcom3d/mods/
    cp -r "/c/Program Files (x86)/Steam/steamapps/common/XCom UFO Defense/XCOM" ~/openxcom3d/UFO
    build/bin/openxcom.exe -data build/bin/ -user ~/openxcom3d/ -cfg ~/openxcom3d/

    For TFTD, copy its folder to ~/openxcom3d/TFTD the same way. In MSYS2, ~ is C:\msys64\home\you, and /c/ is drive C.

    The OpenXcom3D mod switches itself on the first time the game finds it. Start a game, or New Battle, and in battle press F8 (or the 3D button at the top left). Mouse to look, W A S D to walk, the left button to fire, F8 back to the map.

    Copy release/OpenXcom3D-…-windows-x86_64.zip to the Windows machine, unpack it somewhere of yours (Documents, the Desktop, C:\Games; not Program Files), and double-click play.bat.

    It finds UFO and TFTD in Steam by itself (or a UFO / TFTD folder next to it) and links them into its user folder. In battle press F8. The game isn't signed, so Windows may warn the first time: More info, then Run anyway.

If something goes wrong

The usual snags, and what to do. Every key and setting of the game, and how each plays: the play guide; the whole story in the manual.

The OpenXcom3D repository has no CMakeLists.txt and doesn't build

That's right: it holds the patch (and the add-on's source, for reading), not OXCE. Build OXCE with the patch applied, as in step 3.

git apply: “patch does not apply” or “corrupt patch”

Check that OXCE is at the right commit: git log -1 --format=%H in the OpenXcom folder should say f0134ef8065799c7723953d64b565f7832bfd782. On a newer OXCE the patch doesn't fit.

On Windows, Git for Windows turns line ends into CRLF by default (core.autocrlf), and the patch then doesn't match. Use MSYS2's own git as in step 2, or run git config --global core.autocrlf false and clone again.

A patch saved from a browser page is HTML, not the patch: download it with the curl line (the raw link).

CMake: “Package 'sdl', required by 'virtual:world', not found”

The SDL 1.2 development packages are missing: install them as in step 2.

The window isn't the UCRT64 one (its prompt says MSYS or MINGW64), or the packages aren't installed. Open MSYS2 UCRT64 and run the pacman -S line from step 2.

Run tools/windows/build_libs.sh before configure.sh.

Linking fails: “undefined reference to png_…, jpeg_…, TIFF…, FLAC__…”

The build was configured without the options from step 4. Delete the build folder (rm -rf build) and run the cmake -S . -B build … line from step 4 as it is, all of it on one line.

“The code execution cannot proceed because libFLAC.dll (or SDL.dll) was not found”

The DLLs aren't next to the game: run the ldd … | xargs -r cp -t build/bin/ line from step 4. ldd build/bin/openxcom.exe lists every DLL the game loads; the ones under /ucrt64/bin go next to it.

CMake: “Compatibility with CMake < 3.10 has been removed”

OXCE asks for CMake 3.5 or newer, which CMake 4.2 still accepts (with a warning you can ignore). If yours refuses, add -DCMAKE_POLICY_VERSION_MINIMUM=3.10 to the cmake -S . -B build line.

F8 does nothing, and there's no 3D button

The OpenXcom3D mod isn't on. Open Options → Mods and switch on OpenXcom3D - First-Person View. (This build switches it on by itself the first time it finds it; if you switched it off since, it stays off.)

If the mod says it needs another engine, the game wasn't built from the patched source: check step 3.

“No X-COM installations found”, or the game asks for data

The game data isn't in the profile. ~/openxcom3d/UFO must be the folder from step 1 itself, with GEODATA, GEOGRAPH, MAPS and UFOGRAPH directly in it (not one folder up, not one down).

The window closes at once, with an X error about GLX

The system's OpenGL is broken. The game runs without it like this:

Terminal
SDL12COMPAT_OPENGL_SCALING=0 SDL_RENDER_DRIVER=software build/bin/openxcom -data build/bin/ -user ~/openxcom3d/ -cfg ~/openxcom3d/
Can I use Visual Studio instead?

OXCE's Visual Studio project lists the add-on, but that build isn't tested. MSYS2, as on this page, is.

Which DLLs does the zip's game load?

Only Windows' own and the two it comes with, SDL.dll (sdl12-compat 1.2.74) and SDL2.dll; the C++ runtime, SDL_image, SDL_mixer, SDL_gfx and their codecs are linked in. tools/windows/check.sh checks that, and that no home folder paths are in it.