# How to Set Up and Configure Equilibrium Engine for C11 Development: Complete Setup Guide

> Easily set up and configure Equilibrium Engine for C11 development. Follow our guide to install CMake and Clang, build the static library, and integrate it into your project with essential dependencies.

- Repository: [Alexander/equilibriumengine](https://github.com/clibequilibrium/equilibriumengine)
- Tags: getting-started
- Published: 2026-02-27

---

**To set up Equilibrium Engine for C11 development, install CMake and Clang, build the static library using the provided CMake scripts, and link your C project against `libequilibrium.a` with the required SDL2, bgfx, and pthread dependencies.**

Equilibrium Engine is a **data-oriented, multi-threaded C11 game engine** built around the Entity Component System (ECS) pattern using flecs. Setting up and configuring Equilibrium Engine for C11 development involves resolving the toolchain dependencies, building the core static library from [`equilibrium/engine.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/equilibrium/engine.c), and properly linking your project against the engine's public headers and third-party dependencies located in `3rdparty/`.

## Prerequisites for C11 Development

Before building Equilibrium Engine, ensure your system has the following tools installed:

- **CMake ≥ 3.1** – Generates platform-specific build files. The top-level [`CMakeLists.txt`](https://github.com/clibequilibrium/equilibriumengine/blob/main/CMakeLists.txt) orchestrates the build.
- **Clang** – The primary supported compiler for the engine core.
- **Git** – Required to clone the repository and its submodules.

All runtime dependencies—including **bgfx**, **SDL2**, **flecs**, **cr** (for hot-reloading), and **Assimp**—are bundled under `3rdparty/` as pre-built static libraries with accompanying CMake find-scripts. No additional downloads are required.

## Cloning the Repository

Clone the Equilibrium Engine repository to your local machine:

```bash
git clone https://github.com/clibequilibrium/equilibriumengine.git
cd equilibriumengine

```

The source code is organized into three main directories:
- `equilibrium/` – Core engine library written in C11.
- `editor/` – ImGui-based editor written in C++.
- `launcher/` – Minimal sandbox launcher demonstrating engine usage.

## Building the Engine Core

### Generate Build Files

Create a build directory and run CMake to generate the build system:

```bash
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

```

The root [`CMakeLists.txt`](https://github.com/clibequilibrium/equilibriumengine/blob/main/CMakeLists.txt) adds three subdirectories:
1. `equilibrium/` – Builds `libequilibrium.a`.
2. `editor/` – Builds the `equilibrium_editor` binary.
3. `launcher/` – Builds the `launcher` binary.

### Compile the Static Library

Run the build command:

```bash
cmake --build .

```

This produces:
- `bin/Linux/Release/libequilibrium.a` (or equivalent for your platform).
- `bin/Linux/Release/equilibrium_editor` (optional editor).
- `bin/Linux/Release/launcher` (optional sandbox).

If you only need the C engine for your own project, you can link against `libequilibrium.a` and ignore the editor and launcher targets.

## Configuring Your C11 Project

### Include the Public Headers

Your C source files should include the engine's public API headers:

```c
#include "equilibrium/engine.h"
#include "equilibrium/world.h"
#include "equilibrium/components/transform.h"

```

These headers are located in the `equilibrium/` directory and use the `EQUILIBRIUM_API` macro for proper symbol visibility, as defined in [`equilibrium/equilibrium_defines.h`](https://github.com/clibequilibrium/equilibriumengine/blob/main/equilibrium/equilibrium_defines.h).

### Minimal Application Skeleton

Create a [`main.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/main.c) file with the following structure:

```c
#include <stdbool.h>
#include "equilibrium/engine.h"
#include "equilibrium/world.h"
#include "equilibrium/components/transform.h"

int main(void) {
    /* Initialize the engine with 2 threads and no REST API */
    engine_t engine = engine_init(2, false);

    /* Create an entity with a Transform component */
    ecs_entity_t e = ecs_new(engine.world, 0);
    ecs_set(engine.world, e, Transform, {
        .position = {0.0f, 0.0f, 0.0f},
        .rotation = {0.0f, 0.0f, 0.0f},
        .scale    = {1.0f, 1.0f, 1.0f}
    });

    /* Main loop */
    while (engine_update(&engine)) {
        /* Game logic here */
    }

    /* Cleanup handled by engine_update on quit */
    return 0;
}

```

The `engine_init` function is implemented in [`equilibrium/engine.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/equilibrium/engine.c) (lines 28-58), while `engine_update` handles the frame loop and automatic cleanup via `ecs_fini`.

### Building Your C Program

Compile your project against the built engine:

```bash
clang -I../equilibrium -I../3rdparty/flecs -I../3rdparty/cr \
      main.c -L../build/bin/Linux/Release \
      -lequilibrium -lbgfx -lSDL2 -lSDL2main -pthread \
      -o mygame

```

Required linker flags:
- `-lequilibrium` – The engine static library.
- `-lbgfx` – Rendering backend.
- `-lSDL2` – Windowing and input.
- `-pthread` – Required by flecs for multi-threading.

## Enabling Hot-Reloading for Rapid C Development

Equilibrium Engine integrates **cr** ([`cr.h`](https://github.com/clibequilibrium/equilibriumengine/blob/main/cr.h)) to support hot-reloading of C modules without restarting the application.

### Creating a Reloadable Module

1. **Write a shared library** that exports `cr_plugin_load`:

```c
/* mymodule.c */
#include <cr.h>
#include "equilibrium/engine.h"

static void on_update(ecs_world_t *world, const ecs_iter_t *it) {
    /* Per-frame logic */
}

void cr_plugin_load(void) {
    ecs_system(engine.world, {
        .entity = ecs_entity(engine.world, {.name = "MyUpdate"}),
        .query.filter.expr = "OnRender",
        .callback = on_update
    });
}

```

2. **Compile as a shared object**:

```bash
clang -shared -fPIC mymodule.c -o libmymodule.so \
      -I../equilibrium -I../3rdparty/cr

```

3. **Load from your main loop**:

```c
cr_load("libmymodule.so");

```

When the `.so` file is rebuilt, `cr` automatically unloads the old version and invokes the new `cr_plugin_load`, enabling instantaneous iteration cycles.

## Optional: REST API Configuration

To expose a **REST interface** for debugging or external tooling, enable the REST API during initialization:

```c
engine_t engine = engine_init(2, true);  /* true enables REST */

```

This registers the `EcsRest` component on the world (see [`equilibrium/engine.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/equilibrium/engine.c) lines 38-41). The engine runs an internal HTTP server; check the console output for the listening port assigned by flecs.

## Running the Editor and Launcher

After building, verify your setup by running the included tools:

- **Editor**: Execute `bin/Linux/Release/equilibrium_editor` (or platform equivalent). This loads [`editor/editor.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/editor/editor.c) and provides an ImGui-based interface for inspecting entities and modifying components.
- **Launcher**: Run `bin/Linux/Release/launcher` to verify SDL2 window creation and bgfx context initialization via [`launcher/main.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/launcher/main.c).

## Summary

- **Install prerequisites**: CMake ≥ 3.1 and Clang are required to build Equilibrium Engine from source.
- **Build the engine**: Use CMake to generate build files and compile `libequilibrium.a` from [`equilibrium/engine.c`](https://github.com/clibequilibrium/equilibriumengine/blob/main/equilibrium/engine.c).
- **Link your C project**: Include headers from `equilibrium/` and link against the static library with `-lequilibrium -lbgfx -lSDL2 -pthread`.
- **Initialize correctly**: Call `engine_init(threads, enable_rest)` and use `engine_update()` for the main loop.
- **Enable hot-reloading**: Use the `cr` API to load shared libraries via `cr_load()` for rapid iteration without restarts.

## Frequently Asked Questions

### What compiler standards does Equilibrium Engine support?

Equilibrium Engine is written in **C11** and requires a compiler that supports the C11 standard. The build system is tested primarily with **Clang**, though GCC may work with minor adjustments to the CMake configuration.

### How do I enable hot-reloading for my C game code?

To enable hot-reloading, compile your game logic as a **shared library** (`.so` on Linux, `.dll` on Windows) that exports a `cr_plugin_load` function. Load this library using `cr_load()` from your main application. When you rebuild the shared library, Equilibrium Engine automatically unloads the old version and loads the new one without restarting the executable.

### Can I use Equilibrium Engine without the C++ editor?

Yes. The core engine is implemented in **C11** and can be used entirely from C code without linking the C++ editor or launcher. Simply link against `libequilibrium.a` and the required third-party libraries (bgfx, SDL2, flecs) from your pure C project.

### What is the purpose of the REST API in Equilibrium Engine?

The **REST API** exposes the ECS world via HTTP endpoints, allowing external tools and debuggers to inspect entities and components while the engine is running. Enable it by passing `true` as the second argument to `engine_init()`. This is useful for building remote monitoring tools or integrating with external game design applications.