flecs

Discord Chat CI build Build Status codecov

Flecs is a fast and lightweight Entity Component System for C89 / C99 / C++11 that packs a lot of punch in a small footprint:

  • Blazing fast iteration speeds with direct access to raw C arrays across multiple components
  • Built-in support for entity hierarchies, prefabs, nested prefabs and prefab variants
  • An efficient lock-free architecture allows for modifying entities across multiple threads
  • Expressive entity queries with support for and, or, not and optional operators
  • Systems that are time triggered, rate triggered, run every frame or run only when needed
  • A customizable core that lets you include only the features you need

This is Flecs v2, which is a breaking change from v1. For the last v1 release, see: https://github.com/SanderMertens/flecs/releases/tag/v1.3

What is an Entity Component System?

ECS (Entity Component System) is a design pattern often found in gaming and simulation which produces code that is fast and reusable. Dynamic omposition is a first-class citizen in ECS, and there is a strict separation between data and behavior. A framework is an Entity Component System if it:

  • Has entities that are unique identifiers
  • Has components that are plain data types
  • Has systems which are behavior matched with entities based on their components

Documentation

Example

This is a simple flecs example in the C++11 API:

struct Position {
    float x;
    float y;
};

struct Speed {
    float value;
};

int main(int argc, char *argv[]) {
    flecs::world world;

    flecs::system<Position, Speed>(world)
        .each([](flecs::entity e, Position& p, Speed& s) {
            p.x += s.value * e.delta_time();
            p.y += s.value * e.delta_time();
        });

    flecs::entity(world, "MyEntity")
        .set<Position>({0, 0})
        .set<Speed>({1});

    while (world.progress()) { }
}

Building

The easiest way to add Flecs to a project is to add flecs.c and flecs.h to your source code. These files can be added to both C and C++ projects (the C++ API is embedded in flecs.h). Alternatively you can also build Flecs as a library by using the cmake, meson, bazel or bake buildfiles.

Custom builds

The Flecs source has a modular design which makes it easy to strip out code you don't need. At its core, Flecs is a minimalistic ECS library with a lot of optional features that you can choose to include or not. This section of the manual describes how to customize which features to include.

Modules

The following modules are available in flecs-hub and are compatible with v2:

Module Description
flecs.meta Reflection for Flecs components
flecs.json JSON serializer for Flecs components
flecs.rest A REST interface for introspecting & editing entities
flecs.player Play, stop and pause simulations
flecs.dash Web-frontend for remote monitoring and debugging of Flecs apps
flecs.components.geometry Components that describe geometry
flecs.components.graphics Components used for computer graphics
flecs.components.gui Components used to describe GUI components
flecs.components.http Components describing an HTTP server
flecs.components.input Components that describe keyboard and mouse input
flecs.components.physics Components that describe physics and movement
flecs.systems.civetweb A civetweb-based implementation of flecs.components.http