Sander Mertens/flecs: Release v4.0.1-alpha

Name: flecs

Released: 2024-04-05

Release Assets:

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.

Post v4 feedback in this discussion post: https://github.com/SanderMertens/flecs/discussions/1181 or on the Flecs discord server, whichever you prefer!