Codex is a cross-platform 2D game engine with an integrated editor. The engine is written in C++20 and includes:

• ECS-based scene management
• OpenGL rendering and a batched 2D sprite renderer
• Box2D physics
• FMOD Studio audio
• C++ native behaviours and reflection/code generation
• JSON and binary archives
• Virtual filesystems and compressed asset packages
• An ImGui editor with a scene hierarchy, property inspector, profiler, and content browser

Linux, Windows, and macOS CMake presets are provided. The editor and macOS support are under active development.

Codex.nb/
├── codex/          # Engine sources, public headers, assets, and vendored FMOD
├── editor/         # CodexEditor and the native-behaviour project template
├── runtime/        # Standalone shipped runtime target
├── test_work/      # Development/test executable
├── cmake/          # Project CMake helpers
├── scripts/        # Python build and project-generation helpers
├── conanfile.py    # Conan dependency recipe
├── CMakePresets.json
├── builds/         # Generated build trees and Conan files
└── installs/       # Local install trees

Install these tools before building:

The ImGuizmo dependency currently uses a GitHub SSH URL. Your SSH key must therefore be configured for GitHub before the first CMake configure.

FMOD Studio API 2.03.13 is included under codex/vendor/fmod. Its license and redistribution terms still apply.

Conan is a Python application. Install it in a project-local virtual environment instead of modifying the system Python installation.

Run these commands from the repository root:

python3 -m venv .venv
source .venv/bin/activate
pip install conan

conan --version
conan profile detect --force

Activate the environment again when opening a new shell:

source .venv/bin/activate

Run these commands from the repository root:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install conan

conan --version
conan profile detect --force

If PowerShell blocks the activation script, allow locally created scripts for the current user:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

The virtual environment only supplies Python tooling. Compilers, CMake, Git, OpenGL development files, and other platform SDKs remain system packages.

The root conanfile.py currently installs:

• SDL 2, Box2D, ImGui, GLM, EnTT, and stb
• fmt and spdlog
• nlohmann/json and LZ4
• Abseil, magic_enum, and cxxopts

Conan writes its generated CMake toolchain, dependency configuration files, and copied ImGui backend sources to builds/conan. Every configure preset refers to builds/conan/conan_toolchain.cmake, so Conan installation must happen before the first CMake configure.

To install the dependencies manually for a debug build:

conan install . \
  --output-folder=builds/conan \
  --build=missing \
  -s build_type=Debug # or Release

For a release build, use -s build_type=Release. Re-run conan install when conanfile.py changes, after deleting builds/conan, or when switching the dependency build type.

On Linux, the recipe selects SDL’s Wayland support from XDG_SESSION_TYPE. If that variable is absent in your shell, set it before running Conan:

export XDG_SESSION_TYPE=x11       # or: wayland

The recommended interface is scripts/build.py. It can synchronize Conan packages, configure CMake, build, install, and run the editor.

After activating the Python virtual environment:

# First build: install Conan dependencies, configure, build, and install.
python scripts/build.py build --conan-sync --install

# Later debug builds, when dependencies have not changed.
python scripts/build.py build --install

# Build, install, and launch CodexEditor.
python scripts/build.py build --install --run

With no subcommand, the script also defaults to build:

python scripts/build.py --conan-sync --install

The default is the platform’s debug preset with Debug Conan packages. Keep the CMake configuration and Conan library configuration aligned:

python scripts/build.py build \
  --preset linux-any-release \
  --config release \
  --lib-config release \
  --conan-sync \
  --install

Useful commands:

python scripts/build.py list
python scripts/build.py build --help
python scripts/build.py clear --preset linux-any-debug

--run implies --install. --vglrun implies both and launches the editor through VirtualGL.

The equivalent commands without the build helper are:

conan install . \
  --output-folder=builds/conan \
  --build=missing \
  -s build_type=Debug

cmake --preset linux-any-debug
cmake --build builds/linux-any-debug --parallel
cmake --install builds/linux-any-debug

Installed debug and release builds are written below installs/<preset>. Shipping presets install to a system location and may require elevated permissions.

Run python scripts/build.py list to show only the presets available on the current host.

Install a compiler, CMake, Python, Git, and OpenGL/window-system development headers through the distribution package manager. The editor’s native file dialog currently requires pkg-config and GTK 3 development files. Conan builds or downloads the libraries declared in conanfile.py.

Typical package sets are:

sudo apt update
sudo apt install \
  build-essential clang cmake git python3 python3-venv pkg-config libgtk-3-dev \
  libgl1-mesa-dev libx11-dev libxext-dev libxrandr-dev libxi-dev \
  libxcursor-dev libxinerama-dev libxfixes-dev

sudo dnf install \
  gcc-c++ clang cmake git python3 pkgconf-pkg-config gtk3-devel \
  mesa-libGL-devel libX11-devel libXext-devel libXrandr-devel libXi-devel \
  libXcursor-devel libXinerama-devel libXfixes-devel

sudo pacman -S --needed \
  base-devel clang cmake git python pkgconf gtk3 \
  mesa libx11 libxext libxrandr libxi libxcursor libxinerama libxfixes

Wayland builds may require additional Wayland, xkbcommon, and libdecor development packages if Conan has to build SDL from source.

Install:

• Visual Studio 2022 with the Desktop development with C++ workload
• Python 3.10 or newer
• CMake and Git
• Ninja for the windows-msvc-* and windows-llvm-* presets
• LLVM when using a windows-llvm-* preset

Run MSVC and LLVM/Ninja builds from a Developer PowerShell for VS 2022 so the Windows SDK and linker environment are available.

For a Visual Studio solution:

conan install . `
  --output-folder=builds/conan `
  --build=missing `
  -s build_type=Debug

cmake --preset vs2022

Then open builds/vs2022/Codex.sln.

Install the Xcode command-line tools, CMake, Git, and Python 3.10 or newer. Then create the virtual environment, install Conan, and use an osx-* preset.

xcode-select --install
python scripts/build.py build \
  --preset osx-any-debug \
  --lib-config debug \
  --conan-sync \
  --install

The installed editor executable is bin/CodexEditor on Unix and bin/CodexEditor.exe on Windows.

Codex uses FMOD as its audio engine. See the FMOD website for more information.