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:
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!
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++).
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_STATICIf 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.
Make sure to view the documentation at https://www.flecs.dev/ !
- FAQ
- Quickstart
- Query Manual
- Relationships Manual
- JSON Format Manual
- REST API Manual
- Manual
- API reference
- C examples
- C++ examples
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()) { }
}If you have a project you'd like to share, let me know on Discord!
https://store.steampowered.com/app/690290/Territory_Control_2/
https://nicok.itch.io/sol-survivor-demo
https://github.com/ConfettiFX/The-Forge
https://github.com/clibequilibrium/EquilibriumEngine
https://thepunkcollective.itch.io/gravitas
https://github.com/foxnne/aftersun
https://www.flecs.dev/tower_defense/etc (repository)
https://www.flecs.dev/city (repository)
- Bgfx/Imgui module
- Tower defense example
- Flecs + UE4 is magic
- Quickstart with Flecs in UE4
- Automatic component registration in UE4
- Building a space battle with Flecs in UE4
- Flecs + SDL + Web ASM example (live demo)
- Flecs + Raylib example
- Flecs + gunslinger example
- Flecs based 3D game engine with editor
- Where are my entities and components
- Archetypes and vectorization
- Making the most of entity identifiers
- Building games in ECS with entity relationships
- Why storing state machines in ECS is a bad idea
- Why vanilla ECS is not enough
- ECS: From tool to paradigm
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_SYSTEMAdditionally, you can also specify addons to exclude from a build by adding NO to the define:
#define FLECS_NO_LOGThe 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 |
| Units | Builtin unit types | FLECS_UNITS |
| Meta_C | (C) Utilities for auto-inserting reflection data | FLECS_META_C |
| 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 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.sdl2 | SDL window creation & input management |
| flecs.systems.sokol | Sokol-based renderer |
| flecs.game | Generic game systems, like a camera controller |
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 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