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

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, 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 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:

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:

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

The root 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:

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:

#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.

Minimal Application Skeleton

Create a main.c file with the following structure:

#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 (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:

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) 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:

/* 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:

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

3. Load from your main loop:

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:

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

This registers the EcsRest component on the world (see 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 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.

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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}