Prerequisites

You'll need to have these libraries and their development headers installed in order to build CataclysmBN:

• General
  • cmake >= 3.2.4
  • clang >= 22
  • gcc-libs or equivalent C++ runtime libraries
  • glibc
  • zlib
  • bzip2
  • sqlite3
  • SDL >= 3.0.0 *
  • SDL_shadercross >= 3.0.0 *
• Curses
  • ncurses
• Tiles
  • SDL_image >= 3.0.0 (with PNG and JPEG support) *
  • SDL_mixer >= 3.0.0 (with Ogg Vorbis support) *
  • SDL_ttf >= 3.0.0 *
  • freetype
• Sound
  • vorbis
  • libbz2
  • libz

In order to compile localization files, you'll also need gettext package.

Build Environment

You can obtain the source code tarball for the latest version from git.

git clone --filter=blob:none https://github.com/cataclysmbn/Cataclysm-BN.git
cd Cataclysm-BN

UNIX Environment

Obtain packages specified above with your system package manager.

• For Ubuntu-based distros (26.04 onwards):

sudo apt install git cmake ninja-build mold clang-22 llvm-22 ccache \
libsdl3-dev libsdl3-image-dev libsdl3-ttf-dev \
libfreetype-dev bzip2 zlib1g-dev libvorbis-dev libncurses-dev \
gettext libflac++-dev libsqlite3-dev zlib1g-dev

• For Fedora-based distros:

sudo dnf install git cmake ninja-build mold clang llvm ccache \
SDL3-devel SDL3_image-devel SDL3_ttf-devel \
freetype glibc bzip2 zlib-ng libvorbis ncurses gettext flac-devel \
sqlite-devel zlib-devel

Verifying Compiler Version

You need Clang 22 or newer to build CataclysmBN. You can check your compiler version with:

$ clang++ --version
clang version 22.1.6 (Fedora 22.1.6-1.fc44)
Target: x86_64-redhat-linux-gnu
Thread model: posix
InstalledDir: /usr/bin

sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-22 100
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-22 100

sudo update-alternatives --install /usr/bin/llvm-ar llvm-ar /usr/bin/llvm-ar-22 100
sudo update-alternatives --install /usr/bin/llvm-ranlib llvm-ranlib /usr/bin/llvm-ranlib-22 100

macOS Environment

Install dependencies via Homebrew:

brew install cmake ninja ccache sdl3 sdl3_image sdl3_ttf sdl3_mixer \
  freetype gettext sqlite pkg-config ncurses flac

Windows Subsystem for Linux (WSL)

Follow the same instructions for UNIX environment; it just works (TM)

If you plan on using tiles, make sure you have the latest WSL 2 that supports GUI and have installed matching drivers.

Windows Environment (MSYS2)

1. Follow steps from here: https://msys2.github.io/
2. Install CataclysmBN build deps:

pacman -S mingw-w64-x86_64-toolchain msys/git \
   	  mingw-w64-x86_64-cmake \
   	  mingw-w64-x86_64-SDL2_{image,mixer,ttf} \
   	  ncurses-devel \
      gettext \
      base-devel

This should get your environment set up to build console and tiles version of windows.

CMake Build

CMake has separate configuration and build steps. Configuration is done using CMake itself, and the actual build is done using build-system agnostic cmake --build ..

There are two ways to build CataclysmBN with CMake: inside the source tree or outside of it. Out-of-source builds have the advantage that you can have multiple builds with different options from one source directory.

Build with Presets (Recommended)

There's multiple predefined build presets available, which simplifies build process to just two commands.

For Linux:

cmake --preset linux-slim
cmake --build --preset linux-slim --target cataclysm-bn-tiles

For macOS:

cmake --preset osx-arm-slim
cmake --build --preset osx-arm-slim

This will place the executable into out/build/linux-slim/ or out/build/osx-arm-slim/ respectively.

cmake --build --preset linux-slim --target cataclysm-bn-tiles cata_test-tiles

cmake --build --preset linux-slim --target cataclysm-bn-tiles --parallel 4

Build without Presets

To build CataclysmBN out of source:

mkdir -p out/build/custom
cmake -B out/build/custom -DCMAKE_BUILD_TYPE=Release
cmake --build out/build/custom

The above example creates a build directory under out/build/, but that's not required - you can just as easily create it in a completely different location.

To install CataclysmBN after building (as root using su or sudo if necessary):

cmake --install out/build/custom

Creating Distribution Packages

Use a build preset to create a portable distribution package:

# Configure for tiles distribution
cmake --preset dist-tiles

# Build the game and tools
cmake --build --preset dist-tiles

# Create distribution package
cmake --install build --prefix cataclysmbn-linux-tiles

This creates a self-contained directory with the following structure:

cataclysmbn-linux-tiles/
├── cataclysm-bn-tiles     # Game executable
├── cataclysm-launcher     # Launcher script
├── json_formatter         # JSON formatting tool
├── data/                  # Game data files
├── gfx/                   # Tilesets
├── lang/                  # Translations
├── doc/                   # Documentation
├── README.md
├── LICENSE.txt
└── VERSION.txt

To create a tarball for distribution:

tar -czvf cataclysmbn-linux-tiles.tar.gz cataclysmbn-linux-tiles

Portable vs System Install

Build for Visual Studio / MSBuild

CMake can generate .sln and .vcxproj files used either by Visual Studio itself or by MSBuild command line compiler (if you don't want a full fledged IDE) and have more "native" binaries than what MSYS/Cygwin can provide.

At the moment only a limited combination of options is supported (tiles only, no localizations, no backtrace).

Get the tools:

• CMake from the official site - https://cmake.org/download/.
• Microsoft compiler - https://visualstudio.microsoft.com/downloads/?q=build+tools , choose "Build Tools for Visual Studio 2017". When installing chose "Visual C++ Build Tools" options.
  • alternatively, you can get download and install the complete Visual Studio, but that's not required.

Get the required libraries:

• SDL2 (you need the "(Visual C++ 32/64-bit)" version. Same below)
• SDL2_ttf
• SDL2_image
• SDL2_mixer (optional, for sound support)
• Unsupported (and unused in the following instructions) optional libs:
  • ncurses - ???

Unpack the archives with the libraries.

Open windows command line (or powershell), set the environment variables to point to the libs above as follows (adjusting the paths as appropriate):

set SDL2DIR=C:\path\to\SDL2-devel-2.0.9-VC
set SDL2TTFDIR=C:\path\to\SDL2_ttf-devel-2.0.15-VC
set SDL2IMAGEDIR=C:\path\to\SDL2_image-devel-2.0.4-VC
set SDL2MIXERDIR=C:\path\to\SDL2_mixer-devel-2.0.4-VC

(for powershell the syntax is $env:SDL2DIR="C:\path\to\SDL2-devel-2.0.9-VC").

Run the CMake configuration step

cd <path to cbn sources>
cmake -B out/build/msbuild -DTILES=ON -DLANGUAGES=none -DBACKTRACE=OFF -DSOUND=ON

Build!

cmake --build out/build/msbuild --config Release --parallel 2

The --parallel 2 flag controls build parallelism - you can omit it if you wish. The --config Release flag selects the optimized Visual Studio configuration. If you omit it, the Debug configuration would be built instead.

The resulting files will be put into a Release directory inside your source Cataclysm-BN folder. To make them run you'd need to first move them to the source Cataclysm-BN directory itself (so that the binary has access to the game data), and second put the required .dlls into the same folder - you can find those inside the directories for dev libraries under lib/x86/ or lib/x64/ (you likely need the x86 ones even if you're on 64-bit machine).

The copying of dlls is a one-time task, but you'd need to move the binary out of Release/ each time it's built. To automate it a bit, you can configure cmake and set the desired binaries destination directory with -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE= option (and similar for CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG).

Run the game. Should work.

Build Options

To change build options, you may either pass the options on the command line:

cmake -DOPTION_NAME1=option_value1 [-DOPTION_NAME2=option_value2 [...]]

Or use either the ccmake or cmake-gui front-ends, which display all options and their cached values on a console and graphical UI, respectively.

cmake --preset linux-slim
ccmake out/build/linux-slim

cmake --preset linux-slim
cmake-gui -S . -B out/build/linux-slim

CMake specific options

• CMAKE_BUILD_TYPE=<build type>

Selects a specific build configuration when compiling. release produces the default, optimized (-Os) build for regular use. debug produces a slower and larger unoptimized (-O0) build with full debug symbols, which is often needed for obtaining detailed backtraces when reporting bugs.

NOTE: By default, CMake will produce debug builds unless a different configuration option is passed in the command line.

• CMAKE_INSTALL_PREFIX=<full path>

Installation prefix for binaries, resources, and documentation files.

CataclysmBN specific options

Build Presets

Check the cmake docs for more information

python3 -m pip install dmgbuild biplist

Building with Translations Locally

Starting in 2026, translation files (.po files) are no longer kept in the repository. CI pulls them from Transifex, stores them in workflow artifacts, and uses them to build release packages.

For local builds, use one of the following:

Option 1: Build Without Translations (Fastest)

If you are not working on translations, disable them:

cmake --preset linux-full -DLANGUAGES=none
cmake --build --preset linux-full

Option 2: Pull Translations from Transifex

If you need to test translations locally and have Transifex access:

1. Install the Transifex CLI:

curl -sL https://github.com/transifex/cli/releases/download/v1.6.17/tx-linux-amd64.tar.gz | sudo tar zxvf - -C /usr/bin tx

2. Pull the translation files:

tx pull --force --all

3. Build with translations enabled:

cmake --preset linux-full -DLANGUAGES=all
cmake --build --preset linux-full

Option 3: Download the translations Workflow Artifact

If you do not have Transifex access, use the artifact produced by the translation workflow:

1. Open a recent successful workflow run in Actions
2. Download the translations artifact
3. Extract lang/po and src/lang_stats.inc into your local checkout
4. Build normally with -DLANGUAGES=all