Flecs Explorer

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

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

Usage

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.

Connecting 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: http://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:

Host the explorer locally

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 http://localhost:8000 to open the explorer.

Run the explorer as Docker image

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 http://localhost to open the explorer.

Statistics

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:

URL options

The following options can be added to the URL:

Always connect to remote app (will keep trying to connect to localhost:27750)

?remote=true

Always connect to app on same URL as explorer (will keep trying to connect to url:27750)

?remote_self=true

Never connect to remote app (will always use the webasm version of flecs that runs in the browser)

?local=true

Specify a custom host to connect to (sets remote to true)

?host=10.20.30.40:1234

Building the playground

The playground (etc/flecs_explorer.wasm) runs a box world in the browser and opens box's etc/scenes/town.flecs scene. It renders with WebGPU, so it needs a browser with WebGPU support.

Box is pinned at the commit in BOX_COMMIT. box.sh clones ../box into .box, checks out that commit and builds it into the local bake environment. Bake arguments are passed through:

./box.sh --target em --cfg release
bake3 --target em --cfg release --local-env
cp .bake/local_env/build/flecs.explorer/wasm32-Emscripten-release/flecs_explorer.{js,wasm} etc/

To move the pin, write the new commit to BOX_COMMIT and run box.sh again. Box's etc folder is embedded in the wasm image at etc/.