flecs_ecs 0.2.0

flecs_ecs-0.2.0 has been yanked.

Visit the last successful build: flecs_ecs-0.2.2

What is the Flecs Rust API?

The Rust API is a wrapper around the Flecs C API. The API is designed to offer Rust developers an intuitive and streamlined interface to harness the full potential of Flecs.

It's based on V4.1.2 flecs release, blogpost can be found here.

What is Flecs ECS?

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. Due to Flecs C core, it has major bindings in several languages, including C++, C#, and now Rust!
First open source ECS with full support for Entity Relationships!
Fast native support for hierarchies and prefabs
Runs in the browser (Rust instructions TBD / WIP)
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
Flecs is heavily tested, running more than 8000 tests in its core library alone and used in AAA engines. The Rust API itself has 500+ tests and counting.
Integrated (WIP Rust) reflection framework with JSON serializer and support for runtime components
Powerful query language with support for joins and inheritance
Statistics addon for profiling ECS performance
A web-based UI for monitoring & controlling your apps (demo, code):

How to get started?

Add the following to your Cargo.toml:

[dependencies]
flecs_ecs = "0.2.0"

and start hacking away!

Make sure to check out the Rust docs, Flecs docs, and the 70+ examples in the examples directory.

For an example integration of Flecs with the following crates:

WGPU for rendering
winit for windowing
vello for rasterization
parley for text

check out the demo here

Status: Stable

The project is stable and used in production. 1.0 release is planned next quarter.

This library was made publicly available on the release date of Flecs V4 release.

Safety

This crate enables additional runtime checks by default to preserve Rust's borrowing and concurrency guarantees when calling into the underlying C Flecs library. Those checks are provided by the flecs_safety_locks feature (enabled by default) and help prevent unsafe aliasing and concurrent mutable access across Flecs callbacks, systems and queries.

These safety checks imposes a runtime cost. If you fully understand the characteristics of your application and need maximum performance, you may disable flecs_safety_locks (e.g. for a Release). Disabling it will improve throughput but removes the runtime protections and may lead to undefined behavior if the API is used in an unsafe way. This might or might not matter depending on the application.

Performance

From initial benchmarks and tests, the Rust API is on par with C-level performance, except for where overhead was introduced to make the API safe to use in Rust land (e.g. get performance). However, more performance improvements are planned to be made in the future.

The progress

For detailed feature progress, please visit the issues page.

Core library
Addons
Documentation
Test suite
Examples

The Aim

The plan is to match feature parity of the C++ API while also being fully documented and tested and addressing any safety issues that may arise. The project aims to provide a safe, idiomatic, and efficient Rust API for Flecs, while also being a good citizen in the Rust ecosystem.

Contributions

If you're excited about this project and would like to contribute, or if you've found any bugs, please feel free to raise an issue or submit a pull request. We'd love to have your involvement!

License

MIT license, matching Flecs.

Example code


use flecs_ecs::prelude::*;

#[derive(Debug, Component)]
pub struct Position {
    pub x: f32,
    pub y: f32,
}

#[derive(Debug, Component)]
pub struct Velocity {
    pub x: f32,
    pub y: f32,
}

#[derive(Component)]
pub struct Eats;

#[derive(Component)]
pub struct Apples;

fn main() {
    // Create a new world
    let world = World::new();

    // Register system
    world
        .system::<(&mut Position, &Velocity)>()
        .each(|(pos, vel)| {
            pos.x += vel.x;
            pos.y += vel.y;
        });

    // Create an entity with name Bob, add Position and food preference
    let bob = world
        .entity_named("Bob")
        .set(Position { x: 0.0, y: 0.0 })
        .set(Velocity { x: 1.0, y: 2.0 })
        .add((Eats::id(), Apples::id()));

    // Show us what you got
    println!("{}'s got [{:?}]", bob.name(), bob.archetype());

    // Run systems twice. Usually this function is called once per frame
    world.progress();
    world.progress();

    bob.get::<&Position>(|pos| {
        // See if Bob has moved (he has)
        println!("{}'s position: {:?}", bob.name(), pos);
    });

    // Output:
    //  Bob's got [Position, Velocity, (Identifier,Name), (Eats,Apples)]
    //  Bob's position: Position { x: 2.0, y: 4.0 }
}

FAQ

What's next?

Wasm unknown unknown. The project is currently in the process of supporting wasm32-unknown-unknown target. This is expected to land by the end of 2025 in December.
C# scripting support. Integration with Flecs.Net to work seamlessly with Flecs Rust API.
More demos and examples.

How does it compare to other Rust ECS libraries?

Flecs isn't written natively in Rust, it's written in C, but it's a mature and feature-rich ECS library that has been used in AAA games and other commercial software. It's fast, lightweight, and has a lot of features that other ECS libraries don't have.

Some of the features that make Flecs stand out are:

Everything's an entity. Systems, queries and components are all entities.

Focus on builder APIs and DSL macro over the type system:

[Builder API]

world.system::<&A>()
.with(B::id())
.each(|| { });

[DSL API]

system!(world, &A, B)
.each(|| { });

Singletons (Resources) are modelled as a component added to it's own entity.

world.component::<GameTime>().add_trait(flecs::Singleton);
world.set(GameTime { delta_time: 0.0 });

in the API's it gets automatically detected as a Singleton and no extra annotation is needed.

[Builder API]

world.system::<&GameTime>()
.each(|| { });

[DSL API]

system!(world, &GameTime)
.each(|| { });

Systems/observers are based on queries, and will only run if that query matches.
Systems are single-threaded by default and run in order of declaration (See docs for more info on how parallelism and how pipelines work in flecs)
Support for building your own custom Pipeline.
Relationships are first-class citizens in Flecs, allowing for easy creation of hierarchies.
- union relationships, exclusive relationships, oneof constraints, relationship traversal, reflexive relationships
component inheritance
transitivity
query variables
toggleable components
entity disabling
builtin hierarchies with automatic cleanup
prefabs, prefab inheritance, prefab slots, prefab hierarchies
flecs script & flecs script templates
(hierarchical) entity names
archetype-level change detection
query sorting
query grouping
support for unregistration: component, modules (plugins), systems, observers
event propagation, event forwarding
runtime components
runtime reflection with a language agnostic reflection framework
a language agnostic core
etc

Acknowledgements

A big shoutout to Sander Mertens for creating such a wonderful library and the pre-alpha testers who contributed to Flecs Rust API, especially James, Yoge and Andrew.