Web-based UI for monitoring Flecs applications, trying out queries & learning ECS

A live version of the explorer is running @ https://flecs.dev/explorer

The flecs explorer can be used in standalone mode (default) or remote mode. In standalone mode, the application runs 100% in the browser with a webasm build of Flecs. In remote mode, the explorer connects to a running flecs application.

Before connecting the explorer to an application, first make sure that the REST interface is enabled:

In C:

ecs_singleton_set(world, EcsRest, {0});

In C with the app addon:

ecs_app_run(world, &(ecs_app_desc_t) {
  .enable_rest = true
});

In C++:

world.set<flecs::Rest>({});

In C++ with the app addon:

world.app()
  .enable_rest()
  .run();

When the application is running, verify that the server works by going to: https://localhost:27750/entity/flecs

This should return a JSON string that looks similar to:

{"path":"flecs", "type":[{"pred":"Module"}, {"pred":"Identifier", "obj":"Name"}, {"pred":"flecs.doc.Description", "obj":"flecs.doc.Brief", "value":{"value":"Flecs root module"}}, {"pred":"flecs.doc.Description", "obj":"flecs.doc.Link", "value":{"value":"https://github.com/SanderMertens/flecs"}}]}

You can now go to https://flecs.dev/explorer which should automatically connect to your application.

The explorer sends a request with a short timeout to determine if a running application can be found. In some cases this timeout is too short, which can cause the explorer to sometimes not connect. To fix this, add ?remote=true to the URL (See URL options).

Note that no data is sent from your application to a remote machine. The explorer runs 100% in the browser, so any information sent to the explorer uses a local loopback interface (in other words, no information leaves your machine).

The following browsers have known policies that prevent connecting to localhost from a remote URL:

• Safari
• Brave (can be overridden by configuring "Shield" to be down)

To get around this, you can:

If your browser does not support connecting to localhost from a remote URL, or you just prefer to host the explorer yourself, first clone the repository:

git clone https://github.com/flecs-hub/explorer

Then start an HTTP server in the etc folder:

cd explorer/etc
python3 -m http.server

You can now go to https://localhost:8000 to open the explorer.

If you have a docker environment, you can host the explorer by running this command:

docker run --name=explorer -p 80:80 --restart=unless-stopped -d sandermertens/flecs.explorer:latest

You can now go to https://localhost to open the explorer.

The explorer can visualize statistics from Flecs applications. Statistics collection is disabled by default as it is not free. To enable it, import the flecs.monitor module:

In C:

ECS_IMPORT(world, FlecsMonitor);

In C++:

world.import<flecs::monitor>();

Note that the statistics collection systems run as part of the default Flecs pipeline. If your application does not use systems, manually runs systems or uses a custom pipeline statistics collection will not run. To make sure the collection systems are ran, call this once in the main loop of your game:

In C:

ecs_progress(world, 0);

In C++

world.progress();

You should now be able to see statistics in the explorer, which should look like this: