Skip to content
BranchesTags

Repository files navigation

ChainedEngine

Custom C++/C# Game Engine with Editor, OpenGL Renderer, and Managed Scripting

C++23 License: MIT Workflow Status Linux Windows OpenGL

ChainedEngine is a modular C++23 game engine with editor tooling, runtime packaging, ECS architecture, physics, OpenGL 4.3+ rendering, and managed C# gameplay scripting via Coral. Ships with a parkour game Chained Decos.

Game Screenshot

Note

Active development is ongoing. Features and workflows continue to evolve, but this README is maintained to reflect the current repository state.

Table of Contents

Overview

Chained Decos and Chained Engine target Windows and Linux.

  • OpenGL 4.3+ rendering pipeline with PBR, fog, and shadow mapping
  • ECS-driven scene model using EnTT
  • YAML-based project and scene serialization
  • Editor with hierarchy/inspector/panels and in-editor play mode
  • Managed C# gameplay scripting through Coral (.NET/CoreCLR)
  • UDP networking with client/server model, UPnP port forwarding, and encryption
  • Project export pipeline with compressed asset packs (ZSTD)
  • Visual Animation Graph system (.chag)

Inspiration: ChainedEngine is inspired by Hazel by TheCherno, with significant custom additions — C# scripting via Coral, Jolt physics, animation graph system, project export pipeline, and multi-platform support.

Editor Screenshot 1 Editor Screenshot 2

Quick Start

Clone:

git clone --recurse-submodules https://github.com/IOleg-crypto/ChainedEngine.git
cd ChainedEngine
git submodule update --init --recursive

Configure + Build + Run:

# Linux
cmake --preset linux-clang
cmake --build --preset linux-clang --parallel
./build/linux-clang/bin/ChainedEditor

# Windows (MSYS2 Clang)
cmake --preset windows-clang
cmake --build --preset windows-clang --parallel
.\build\windows-clang\bin\ChainedEditor.exe

# Windows (MSVC Ninja)
cmake --preset windows-msvc
cmake --build --preset windows-msvc --parallel

# Windows (VS 2026 .sln)
cmake --preset windows-vs2026

Editor play mode: Press PLAY to enter simulation and capture cursor. Press Escape to return to editor interaction.

Build

Presets

Preset Generator Compiler Use case
windows-clang Ninja Multi-Config Clang (MSYS2) Primary dev
windows-msvc Ninja Multi-Config MSVC (cl) MSVC Ninja
windows-vs2026 Visual Studio 18 2026 MSVC VS solution / CI
linux-clang Ninja Multi-Config Clang Linux CI
linux-gcc Ninja Multi-Config GCC Linux
windows-gcc Ninja Multi-Config GCC (MinGW) MinGW

Key CMake variables:

  • CH_ACTIVE_GAME — chaineddecos (default) or testproject. Build-time only. Switching requires reconfigure.
  • BUILD_TESTS — ON by default.
  • CH_ENGINE_SHARED — OFF by default (static engine).

If you use Clang on Windows and see Intellisense errors in VS Code, ensure .vscode/settings.json points to the correct build dir:

"clangd.arguments": ["--compile-commands-dir=${workspaceFolder}/build/windows-clang"]

Run

Binaries are generated under build/{preset}/bin/:

# Editor
./build/linux-clang/bin/ChainedEditor
.\build\windows-clang\bin\ChainedEditor.exe

# Runtime
./build/linux-clang/bin/ChainedRuntime path/to/project.chproject
.\build\windows-clang\bin\ChainedRuntime.exe --project path\to\project.chproject --name "My Runtime" --width 1600 --height 900

Runtime CLI: --project / -p, --name, --width, --height.

Working with Projects

The engine supports multiple game projects under game/. Currently:

  • chaineddecos — the main parkour game
  • testproject — a lightweight sandbox for testing features

Switching the Active Game

cmake -S . -B build/windows-clang -DCH_ACTIVE_GAME=testproject

Or in VS Code: Command Palette → CMake: Edit CMake Cache (UI) → change CH_ACTIVE_GAME.

Creating a New Project

Use the scaffolding script:

python tools/create_game.py MyGame
python tools/create_game.py MyGame --csproj assets/scripts/MyGame.Scripts.csproj

This creates game/mygame/ with:

  • CMakeLists.txt — wired into the build via auto-discovery
  • src/main.cpp — CreateApplication entry point
  • MyGame.chproject — project metadata
  • assets/scripts/ — for C# scripts

New games are auto-discovered by the root CMakeLists.txt — any directory under game/ with a CMakeLists.txt is included when CH_ACTIVE_GAME matches.

Editor‑created projects

The editor (Project → New Project) now also generates CMake build scaffolding:

  • {project}/CMakeLists.txt — chained_add_game() boilerplate
  • {project}/src/main.cpp — CreateApplication entry point

For a standalone build, move the project directory under game/ (e.g. game/mygame/) so it is auto‑discovered by the root CMakeLists.txt.

Project Configuration (.chproject)

Each game has a YAML metadata file defining its entry scene, physics, rendering, and window settings. See User Guide for the full reference.

Project Structure

  • engine/ — core engine modules (graphics, scene, physics, audio, platform, assets, networking)
  • editor/ — ChainedEditor application and editor panels/tools
  • runtime/ — ChainedRuntime application and runtime layer
  • engine/scripting/ — script host, glue bindings, and managed build integration
  • game/chaineddecos/ — main game project
  • game/testproject/ — alternate sandbox project
  • tests/ — native C++ tests (GoogleTest)
  • thirdparty/ — third-party dependencies (git submodules)
  • tools/ — build scripts, glue code generator, resource sync

Dependencies

Library Purpose
EnTT ECS framework
Assimp 3D model import
Coral C#/C++ interop
ImGui + ImGuizmo Editor UI
GLFW + GLAD Window/OpenGL
GLM Math library
yaml-cpp YAML serialization
GoogleTest Unit/integration tests
JoltPhysics Physics simulation
zstd + pack (cfnptr) Asset pack compression
miniaudio Audio
spdlog Logging
stb Image loading
cereal Binary serialization
reflect-cpp Runtime reflection
ENet UDP networking
libsodium Encryption (xchacha20poly1305)
miniupnpc UPnP port forwarding

Always init submodules before building:

git submodule update --init --recursive

Prerequisites

Tool Version Notes
CMake 3.31+ Required by top-level CMakeLists
Compiler C++23 Clang 18+, MSVC (VS2022+), or MSYS2/MinGW-w64
Ninja Latest Recommended for fast parallel builds
.NET SDK 10.0.x Required for managed scripting
Graphics Driver OpenGL 4.3+ Needed for rendering

Linux packages (Ubuntu reference):

sudo apt-get install -y build-essential cmake ninja-build \
  libgl1-mesa-dev libx11-dev libxrandr-dev libxinerama-dev \
  libxcursor-dev libxi-dev libasound2-dev libglu1-mesa-dev \
  pkg-config libgtk-3-dev libdrm-dev libgbm-dev \
  xvfb libxkbcommon-x11-0 libgl1-mesa-dri mesa-utils

Testing

Native tests use GoogleTest + CTest, split into unit (fast, no engine runtime) and integration (full engine) targets.

# Run all tests
ctest --test-dir build/windows-clang --output-on-failure

# Unit tests only
ctest --test-dir build/windows-clang -L Unit --output-on-failure

# Integration tests only
ctest --test-dir build/windows-clang -L Integration --output-on-failure

Managed (C#) tests require .NET SDK 10.0.x on PATH. Without it, the scripting target is silently skipped.

CI/CD

CI workflow (.github/workflows/ci.yml) fans out to:

  • Format Check (format.yml): clang-format-18 --dry-run -Werror on changed C++ files
  • Linux Builds (linux.yml): Debug + Release under xvfb + Mesa software rendering
  • Windows Builds (windows.yml): Debug + Release matrix (Clang, MSVC, GCC)

Debug builds use -DENABLE_SANITIZERS=ON (ASan + UBSan). CTest output is captured as JUnit XML.

Deploy workflow (.github/workflows/deploy-sdk.yml): triggered by v* tags, packages ChainedEditor + ChainedRuntime artifacts.

Troubleshooting

  • Submodule errors: git submodule update --init --recursive
  • Generator conflicts: Reconfigure from a clean build folder when switching generator families
  • No managed build: Ensure dotnet SDK 10.0.x is on PATH
  • Linux headless: Install packages from Prerequisites, use xvfb + Mesa
  • Stale files after CH_ACTIVE_GAME change: Reconfigure the build directory, don't just rebuild

Known Issues

  • Font system needs rework for in-scene text and editor
  • Some native tests are being reworked and may be skipped in CI
  • Runtime and editor workflows are under active iteration
  • Virtual file system is planned/in-progress
  • Runtime may have bugs and issues — known problems include font rendering, physics edge cases, and occasional crashes under specific scenarios

Documentation

Full guides and references:

Document Description
User Guide Step-by-step: build, run, create scenes, write scripts, export
Engine Architecture Bootstrapping, system initialization, main loop
Component Reference All ECS components, adding new ones
Scripting API C# API reference: lifecycle, entities, input, UI
Scripting Interop C++/C# bridge internals
Animation Graphs Visual animation graph system tutorial
Export Guide Project packaging and distribution
FAQ Common patterns and solutions

Contributing

  • Open issues for bugs/regressions
  • Submit pull requests for fixes and improvements
  • Platform/build workflow improvements are especially helpful

License

This project is licensed under MIT. See license for details.

About

"Custom C++/C# game engine with ImGui editor, OpenGL 4.3 renderer, C# scripting via Coral, and ECS architecture. Ships with a parkour game "Chained Decos"

Topics

cmakecppcross-platformgame-developmentimguiopenglraylibraylib-cpprlimgui

Resources

Readme
Activity

Stars

5 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages