Sources: data/lua/README.md data/lua/manifest.schema.json data/lua/types/ccb_api_v5.d.lua data/lua/reference/ccb_public_api_v5.json data/lua/reference/ccb_public_api_v5_coverage.json tools/lua_api/README.md commit d32b9cc880a8 api-contract

Lua sections need revision: This page contains removed v5 APIs or old runtime examples. Do not use its Lua examples for current development. Start with Platform v1.

Core Development & Contribution Guide¶

This guide describes the complete development lifecycle for contributors writing C++ engine code, fixing bugs, or implementing core mechanics for Cataclysm: Cleanwater Bomb (CCB).

1. Environment Setup¶

🐧 Linux (Ubuntu / Debian / Arch)¶

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config astyle \
    libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev \
    libncursesw5-dev liblua5.4-dev libgettextpo-dev

# Arch Linux
sudo pacman -S base-devel cmake astyle sdl2 sdl2_image sdl2_ttf sdl2_mixer ncurses lua gettext

🪟 Windows (MSVC / Visual Studio 2022)¶

Install Visual Studio 2022 with "Desktop development with C++" and "C++ CMake tools".

Install dependencies via vcpkg:

vcpkg install sdl2 sdl2-image sdl2-ttf sdl2-mixer gettext lua

Open the project root in VS2022 and select the x64-Release or x64-Debug CMake preset.

🤖 Android (Gradle & NDK)¶

cd android/
./gradlew assembleDebug

2. CMake Build Workflows¶

# 1. Configure build directory (Tiles & Sound enabled)
cmake -B build -DCMAKE_BUILD_TYPE=Release -DTILES=ON -DSOUND=ON

# 2. Parallel compilation
cmake --build build -j$(nproc)

# 3. Launch game
./build/cataclysm-tiles

# 4. Build and run unit tests
cmake --build build --target cata_test -j$(nproc)
./build/tests/cata_test

3. C++20 Standards & Astyle Formatting¶

Memory Safety: Prefer std::unique_ptr, std::shared_ptr, std::optional, and game_handle over raw pointers.
Modern Syntax: Leverage structured bindings (auto [k, v]), constexpr, and <ranges>.

Astyle Formatting:

make astyle        # Auto-format modified sources
make astyle-check  # Verify compliance (CI gate)

4. Writing Catch2 Unit Tests¶

TEST_CASE( "weather_forecast_storm_intensity", "[weather]" ) {
    tripoint test_pos( 60, 60, 0 );
    weather_forecast forecast = weather_manager::forecast_at( test_pos, 2 );

    CHECK( forecast.wind_speed >= 0.0f );
    CHECK( forecast.wind_speed <= 300.0f );
}

Run specific test tags:

./build/tests/cata_test "[weather]"

5. Debugging & AddressSanitizer¶

AddressSanitizer Build:¶

cmake -B build-asan -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON
cmake --build build-asan -j$(nproc)

6. Git Workflow & PR Submission¶

Branch from master (git checkout -b feat/my-feature).
Adhere to Atomic Commits with conventional commit messages (feat(map): ..., fix(water): ...).

Run local checks:

make astyle-check
./build/tests/cata_test
python3 tools/agent/check_project_metadata.py

Open Pull Request on GitHub naming the Responsible human.