michaelbartnett/flecs

Introduction

Flecs is a fast and lightweight Entity Component System that lets you build games and simulations with millions of entities (join the Discord!). Here are some of the framework's highlights:

Fast and portable zero dependency C99 API
Modern type-safe C++11 API that doesn't use STL containers
First open source ECS with full support for Entity Relationships!
Fast native support for hierarchies and prefabs
Minimal ECS core with optional addons
Entire codebase builds in less than 5 seconds
Runs in the browser without modifications with emscripten
Cache friendly archetype/SoA storage that can process millions of entities every frame
Supports entities with hundreds of components and applications with tens of thousands of archetypes
Automatic component registration that works out of the box across shared libraries/DLLs
Write free functions with queries or run code automatically in systems
Run games on multiple CPU cores with a fast lockless scheduler
Compiles warning-free on 8 compilers on all major platforms, with CI running more than 4000 tests
Integrated reflection framework with JSON serializer and support for runtime components
Unit annotations for components
Powerful query language with support for joins and inheritance
Statistics addon for profiling ECS performance
A web-based dashboard (demo, code) for inspecting entities, running ECS queries and monitoring games:

What is an Entity Component System?

ECS is a new way of organizing code and data that lets you build games that are larger, more complex and are easier to extend.

Something is called an ECS when it:

Has entities that uniquely identify objects in a game
Has components which are datatypes that can be added to entities
Has systems which are functions that run for all entities matching a component query

For example, a game has a Move system that has a query with two components, Position, Velocity. When the system is ran it is dynamically matched with all entities that have at least these two components.

For more info on ECS, check the ECS FAQ!

Getting Started

To use Flecs, add the flecs.c and flecs.h files to your project. When importing the files into a C++ project, make sure to compile flecs.c as C code (for example by using gcc and clang instead of g++ and clang++).

The ECS core compiles as C99 code and can be compiled with -std=c99. Some addons that are enabled by default require functionality that is not part of C99 for things like measuring time and HTTP sockets (for using the explorer), which can throw compiler errors. To fix these, either compile the code with -std=gnu99 or add -D_XOPEN_SOURCE=600.

Flecs can also be built as a standalone library, by using the cmake, meson, bazel or bake build files. If you are using a custom build file to compile Flecs as a library, make sure to define flecs_EXPORTS, for example by adding -Dflecs_EXPORTS to the compiler command.

If you want to use the flecs.c and flecs.h files to build a standalone library, make sure to remove this line from the top of the flecs.h file:

#define flecs_STATIC

If you are building on Windows with mingw/gcc/clang, add -lWs2_32 to the linker command (only needed for the HTTP/REST addons).

Make sure to compile C++ files as at least C++11 by adding -std=c++0x or higher to gcc/clang compile commands.

By default Flecs includes many features that may not be useful for every project. Builds can be customized to minimize the overhead of the library. See the Addons section for more information on customized builds.

Show me the code!

C99 example:

typedef struct {
  float x, y;
} Position, Velocity;

void Move(ecs_iter_t *it) {
  Position *p = ecs_field(it, Position, 1);
  Velocity *v = ecs_field(it, Velocity, 2);

  for (int i = 0; i < it->count; i++) {
    p[i].x += v[i].x;
    p[i].y += v[i].y;
  }
}

int main(int argc, char *argv[]) {
  ecs_world_t *ecs = ecs_init();

  ECS_COMPONENT(ecs, Position);
  ECS_COMPONENT(ecs, Velocity);

  ECS_SYSTEM(ecs, Move, EcsOnUpdate, Position, Velocity);

  ecs_entity_t e = ecs_new_id(ecs);
  ecs_set(ecs, e, Position, {10, 20});
  ecs_set(ecs, e, Velocity, {1, 2});

  while (ecs_progress(ecs, 0)) { }
}

Same example in C++11:

struct Position {
  float x, y;
};

struct Velocity {
  float x, y;
};

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

  ecs.system<Position, const Velocity>()
    .each([](Position& p, const Velocity& v) {
      p.x += v.x;
      p.y += v.y;
    });

  auto e = ecs.entity()
    .set([](Position& p, Velocity& v) {
      p = {10, 20};
      v = {1, 2};
    });

  while (ecs.progress()) { }
}

Projects using Flecs

If you have a project you'd like to share, let me know on Discord!

Resources

Documentation

Flecs Documentation

Resources provided by the community ❤️

Flecs links

Addons

Flecs has a modular architecture that makes it easy to only build the features you really need. By default all addons are built. To customize a build, first define FLECS_CUSTOM_BUILD, then add defines for the addons you need. For example:

#define FLECS_CUSTOM_BUILD  // Don't build all addons
#define FLECS_SYSTEM        // Build FLECS_SYSTEM

Additionally, you can also specify addons to exclude from a build by adding NO to the define:

#define FLECS_NO_LOG

The following addons can be configured:

Addon	Description	Define
Cpp	C++11 API	FLECS_CPP
Module	Organize game logic into reusable modules	FLECS_MODULE
System	Create & run systems	FLECS_SYSTEM
Pipeline	Automatically schedule & multithread systems	FLECS_PIPELINE
Timer	Run systems at time intervals or at a rate	FLECS_TIMER
Meta	Flecs reflection system	FLECS_META
Meta_C	(C) Utilities for auto-inserting reflection data	FLECS_META_C
Units	Builtin unit types	FLECS_UNITS
Expr	String format optimized for ECS data	FLECS_EXPR
JSON	JSON format	FLECS_JSON
Doc	Add documentation to components, systems & more	FLECS_DOC
Coredoc	Documentation for builtin components & modules	FLECS_COREDOC
Http	Tiny HTTP server for processing simple requests	FLECS_HTTP
Rest	REST API for showing entities in the browser	FLECS_REST
Parser	Create entities & queries from strings	FLECS_PARSER
Plecs	Small utility language for asset/scene loading	FLECS_PLECS
Rules	Powerful prolog-like query language	FLECS_RULES
Snapshot	Take snapshots of the world & restore them	FLECS_SNAPSHOT
Stats	See what's happening in a world with statistics	FLECS_STATS
Monitor	Periodically collect & store statistics	FLECS_MONITOR
Log	Extended tracing and error logging	FLECS_LOG
Journal	Journaling of API functions	FLECS_JOURNAL
App	Flecs application framework	FLECS_APP
OS API Impl	Default OS API implementation for Posix/Win32	FLECS_OS_API_IMPL

Flecs Hub

Flecs Hub is a collection of repositories that show how Flecs can be used to build game systems like input handling, hierarchical transforms and rendering.

Module	Description
flecs.components.cglm	Component registration for cglm (math) types
flecs.components.input	Components that describe keyboard and mouse input
flecs.components.transform	Components that describe position, rotation and scale
flecs.components.physics	Components that describe physics and movement
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.systems.transform	Hierarchical transforms for scene graphs
flecs.systems.physics	Systems for moving objects and collision detection
flecs.systems.sokol	Sokol-based renderer
flecs.game	Generic game systems, like a camera controller

Language bindings

The following language bindings have been developed with Flecs! Note that these are projects built and maintained by helpful community members, and may not always be up to date with the latest commit from master!

Supporting Flecs ♥️

Supporting Flecs goes a long way towards keeping the project going and the community alive! If you like the project, consider:

Giving it a star 🌟
Becoming a sponsor: https://github.com/sponsors/SanderMertens

michaelbartnett / flecs

Introduction

What is an Entity Component System?

Getting Started

Show me the code!

Projects using Flecs

Territory Control

Sol Survivor

The Forge

Equilibrium Engine

Gravitas

After Sun

Tower defense (open source demo)

Procedural City (open source demo)