Flecs v4.0.1-alpha

What is this?

This is an early preview of the upcoming v4 release! 🎉

You can use this release to familiarize and play around with the new APIs and features before v4 comes out. The biggest difference between v3 and v4 is a new query engine that unifies filters, queries and rules in a single API.

Overview

• All tests are passing on all platforms and compilers
• The query API is mostly stable
• Examples have been updated to the new APIs
• Many parts of the API have been simplified
• The release mostly works with the explorer and query editor

Code examples

// A system with query variables
world.system<Position>("SpaceshipsDockedToPlanet")
  .with<SpaceShip>()
  .with<DockedTo>("$obj")
  .with<Planet>().src("$obj")
  .each([](flecs::entity spaceship, Position& p) {
    // ...
  });

// By default queries are uncached. This is similar to a v3 filter/rule
world.query_builder<Position>()
  .with(flecs::ChildOf, "$parent")
  .each([](Position& p) {
    // ...
  });

// Adding .cached() enables caching, which is similar to a v3 query.
// Only the terms that are cacheable will be cached. This allows 
// for queries that are partially cached, which is not possible in v3.
auto q = world.query_builder<Position>()
  .with(flecs::ChildOf, "$parent")
  .cached()
  .build();
  
q.each([](Position& p) {
  // ...
});

// Queries can be named. This associates the query with an entity
// with the same name. Queries that are associated with an entity
// are cached. This means that by default all system queries enable 
// caching, just like in v3.
auto q = world.query_builder<Position>("Children")
  .with(flecs::ChildOf, "$parent")
  .build();

q.each([](Position& p) {
  // ...
});

// Queries that are associated with an entity need to be explicitly
// destructed. This is the same behavior as `flecs::entity`.
// Queries that are not associated with an entity are cleaned up
// when they go out of scope. This is the same behavior as
// `flecs::world` (RAII).
q.destruct();

flecs::world world_a;
{
  // World objects can now be copied. This just creates a handle to
  // the existing world, it doesn't create/copy a new world.
  flecs::world world_b = world_a;
}

void Move(ecs_iter_t *it) {
  Position *p = ecs_field(it, Position, 0); // Field indices now start from 0!
  Velocity *v = ecs_field(it, Velocity, 1);
  
  for (int i = 0; i < it->count; i ++) {
    p[i].x += v[i].x;
    p[i].y += v[i].y;
  }
}

The release should be stable enough for experimentation.

What is missing?

• The APIs are not yet finalized. Big changes are still underway, especially in the C API
• A few new features are still in development
• There are a handful of known bugs that still need to be fixed
• Performance testing hasn't finished yet
• Documentation has not been updated yet

When will v4 come out?

There is still a lot that needs to happen before the release. The goal is to release around the end of April, with a higher probability of it being later than earlier.

Where can I share feedback?

Post v4 feedback in this discussion post: #1181 or on the Flecs discord server, whichever you prefer!

⚠️ Do not use this release in an actual project! ⚠️