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 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.1.1" 

and start hacking away!

Make sure to check out the Rust docs (improvements coming soon), 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: Alpha release

The project is in the alpha release stage where the core functionality and some addons of Flecs have been ported and are available to use today. While there has been a lot of thought put into the current API, it's still in an experimental phase. The project aims to hit stable when all the soundness/safety issues are resolved and the API has been finalized with all of Flecs functionality. We encourage you to explore, test, and provide feedback, but please be aware of potential bugs and breaking changes as we continue to refine the API and add new features.

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

Safety

One important safety factor that has yet to be addressed is having multiple aliases to the same component. This is a known issue and is being worked on. It will be addressed through a table column lock mechanism.

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, performance improvements are planned to be made in the future.

The progress

For detailed feature progress, please visit the issues page.

• Core library
• Addons (Meta + Json + Script are a WIP, expected to be released by end of August, experimental phase sooner)
• Documentation Most functions are documented and contain a C++ alias. Flecs documentation site contains Rust code. The remaining % is for adding mostly doc test examples and refining the Rust docs page.
• Test suite (entity, query, observers systems test cases are done)
• Examples For the current feature set, all examples are done.

The Aim

The plan is to match feature parity of the C++ API, starting with the core library (done!) 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, Apples)>();

    // 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?

• Meta, Json, Script addons. This will allow for reflection, serialization, and scripting capabilities for creating entities and components. See the Flecs documentation for more information.
• Wasm unknown unknown. The project is currently in the process of supporting wasm32-unknown-unknown target. This is expected to land in some shape or form by the end of August.
• API refinements, resolving safety issues & documentation.
• 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>()
  .each(|| { });
  

  • [DSL API]

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

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

  world.set(GameTime { delta_time: 0.0 });
  

  • [Builder API]

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

  • [DSL API]

  system!(world, &R($))
  .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 hierchies 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

Projects using Flecs Rust API

This list contains projects that are not under NDA.

If you want to showcase your project, feel free to open a PR to add it to the list.

• [Hyperion]: It switched from using Envio ECS to Flecs, with great performance improvements. It's quest is to break the world record minecraft event of 10000 players.

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, Bruce, and Andrew.