How to Use the Flecs Explorer to Debug Entities in Equilibrium Engine

Enable the REST server by passing true to the enable_rest parameter in engine_init(), then navigate to http://localhost:<PORT>/explorer/ in your browser to inspect live ECS entities and components.

The Equilibrium Engine provides built-in debugging capabilities through the Flecs ECS library's REST API and web-based Flecs Explorer. This tool allows developers to inspect entity hierarchies, view component data as JSON, and run live queries against the running game state without modifying source code. This guide explains how to enable and use the Flecs Explorer in the clibequilibrium/equilibriumengine repository.

Enabling the REST Server for Flecs Explorer Access

The Flecs Explorer requires the REST server component (EcsRest) to be active on the ECS world. In equilibrium/engine.c, the engine_init() function accepts an enable_rest boolean parameter that controls this behavior.

When enable_rest is true, the engine attaches the EcsRest component to the world with automatic port assignment:

engine_t engine_init(int32_t num_threads, bool enable_rest) {
    // ... initialization code ...
    if (enable_rest) {
        /* Attach the REST server component – Flecs will start a HTTP listener */
        ecs_set(engine.world, EcsWorld, EcsRest, {.port = 0});
    }
    // ...
}

Setting .port = 0 allows Flecs to select an available TCP port automatically and print it to the console.

To enable the REST server:

1. Pass true as the second argument to engine_init().
2. Run your application.
3. Check the console output for a line similar to: info: Flecs REST server listening on port 27784.

The printed port number is the one you will use to access the web interface.

Accessing the Flecs Explorer Web Interface

Once the REST server is running, you can access the Flecs Explorer through any modern web browser. The Explorer is served as a static single-page application from the /explorer/ endpoint.

Navigate to:

http://localhost:<PORT>/explorer/

Replace <PORT> with the port number displayed in your console output.

The Flecs Explorer interface provides:

• Entity Hierarchy: Browse all entities in the ECS world in a tree view.
• Component Inspection: Click any entity to view its attached components as JSON payloads.
• Live Queries: Execute ECS queries in real-time using the query box at the top of the interface.
• Synchronized State: Changes made through code or the ImGui Entity Inspector appear immediately in the Explorer.

How the Flecs Explorer Works Internally

The Flecs Explorer functionality is implemented within the bundled Flecs library (3rdparty/flecs/flecs.c and 3rdparty/flecs/flecs.h). Understanding the internal architecture helps troubleshoot connection issues.

The REST server is defined by the EcsRest component (declared in flecs.h at line 8863). When active, Flecs registers a system named DequeueRest (implemented in flecs.c around line 32232) that processes incoming HTTP requests on each frame.

The Explorer web UI itself is served as a static HTML/JavaScript bundle from the /explorer/ path (implementation around line 35490 in flecs.c). This means no external internet connection or additional installation is required—the entire interface is embedded in the engine binary.

Alternative: In-Engine Debugging with the ImGui Entity Inspector

While the Flecs Explorer provides a comprehensive web-based interface, Equilibrium Engine also includes an in-engine debugging tool for quick iteration without leaving the application window.

The ImGui Entity Inspector is implemented in editor/systems/imgui_entity_inspector.c and registered via the ImguiEntityInspectorImport function. When active, it renders a dockable window displaying:

• A left pane listing all entities filtered by the Entity tag.
• A right pane showing editable components for the selected entity.
• Controls to create new entities or remove existing components.

Both the ImGui inspector and Flecs Explorer display the same underlying ECS data; you can use whichever fits your workflow.

Complete Example Code

The following example demonstrates initializing the Equilibrium Engine with the REST server enabled, allowing immediate access to the Flecs Explorer:

#include "equilibrium/engine.h"

int main(void) {
    /* Initialise the engine with 4 worker threads and enable the REST server */
    engine_t eng = engine_init(4, true);

    /* Main loop – runs systems, renders, and processes input */
    while (engine_update(&eng)) {
        /* Application-specific work goes here */
    }

    return 0;
}

After compiling and running this code, check the console for the port number and navigate to http://localhost:<PORT>/explorer/ to begin debugging.

Summary

• Enable the Flecs Explorer by passing true to the enable_rest parameter in engine_init() defined in equilibrium/engine.c.
• The REST server automatically selects an available port (when set to 0) and prints it to the console.
• Access the web interface at http://localhost:<PORT>/explorer/ to inspect entities, view component JSON, and run live queries.
• The Explorer is served internally by the Flecs library (3rdparty/flecs/flecs.c) and requires no external dependencies.
• Use the ImGui Entity Inspector in editor/systems/imgui_entity_inspector.c as an alternative for in-engine debugging.

Frequently Asked Questions

How do I find the port number for the Flecs Explorer?

When you initialize the engine with enable_rest set to true, Flecs automatically selects an available TCP port if you specify 0 (which Equilibrium Engine does in equilibrium/engine.c). The port number is printed to the console in a message similar to info: Flecs REST server listening on port 27784. Use this number in your browser URL.

Can I use the Flecs Explorer in a production build?

While technically possible by enabling the REST server in production, it is generally not recommended for shipped games due to security and performance considerations. The REST server exposes your entire ECS world via HTTP, which could allow unauthorized access to game state or impact frame times. Use the Flecs Explorer primarily during development and debugging sessions.

What is the difference between the Flecs Explorer and the ImGui Entity Inspector?

The Flecs Explorer is a web-based interface served by the Flecs REST API that runs in any browser, providing a comprehensive view of entity hierarchies, component JSON data, and live query capabilities. The ImGui Entity Inspector is an in-engine overlay implemented in editor/systems/imgui_entity_inspector.c that provides immediate visual feedback without leaving the application window, suitable for quick iteration during gameplay. Both tools display the same underlying ECS data.

Do I need to install additional dependencies to use the Flecs Explorer?

No. The Flecs Explorer is bundled with the Flecs library included in Equilibrium Engine. The web interface is embedded as a static HTML/JavaScript bundle within 3rdparty/flecs/flecs.c (around line 35490) and served automatically when the REST server is enabled. You only need a web browser to access it.

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