Flecs ECS Documentation

Flecs allows queries to detect if components have changed. This is useful for optimizing systems so they only run when necessary.

To use change detection:

1. Use .detect_changes() when building the query.
2. Use .changed() (C++) or .is_changed() (Rust) on the iterator to check if the current table has changed.
3. In C++, if you are using a query to write components (using inout or out terms) but determine no changes are actually needed, call it.skip() to prevent the iterator from marking those components as dirty.

Note: Change detection is only supported for cached queries.

// C++ Example
// Query used for change detection.
flecs::query<const Position> q_read = world.query_builder<const Position>()
  .detect_changes()
  .build();

// Query used to create changes
flecs::query<Position> q_write = world.query<Position>(); // defaults to inout

// Test if changes have occurred for anything matching the query.
bool changed = q_read.changed();

// Setting a component will update the changed state
flecs::entity e = world.entity()
  .set<Position>({10, 20});

q_write.run([](flecs::iter& it) {
  if (it.next()) {
    if (!changed) {
      it.skip();
    }
  }
});

q_read.run([](flecs::iter& it) {
  if (it.next()) {
    if (it.changed()) {
      // Respond to changes
    }
  }
});

Query variables allow you to perform by-name lookups within a hierarchy or constrain query results by setting a variable before iteration.

Lookup Variables: Use $this to refer to the current entity being matched. You can look up child entities by name relative to $this. For example, SpaceShip($this), !Powered($this.cockpit) matches spaceships where the child entity named cockpit does not have the Powered component.

Setting Variables: You can define variables in a query (e.g., $Location) and then set them to a specific entity before iterating. This allows reusing a single query for different constraints, which is more performant than creating multiple queries.

// C++ Example: Defining and setting a variable
auto q = world.query_builder()
  .with<SpaceShip>()
  .with<DockedTo>().second("$Location")
  .with<Planet>().src("$Location")
  .build();

flecs::entity earth = world.entity();

// Constrain results to entities docked to 'earth'
q.iter().set_var("Location", earth).each([]{
  // iterate as usual
});

Cleanup traits do not enforce a strict execution order. This is critical when using OnRemove triggers or hooks, as the order depends on the deletion sequence.

Best Practices for Predictable Cleanup

To ensure predictable cleanup, especially during world teardown:

1. Use Modules: Organize components, triggers, observers, and systems into modules. This ensures they stay alive as long as possible and are deleted after the entities using them.
2. Tag Non-Module Scopes: If you organize entities under a non-module entity in the root, add the EcsModule (or flecs::Module / Ecs.Module) tag to that root to prevent it from being cleaned up prematurely with regular entities.

World Teardown Sequence

When a world is deleted, it follows these steps:

1. Find all root entities: Entities without the builtin ChildOf relationship (excluding empty entities).
2. Query out modules, components, observers, and systems: Prevents components from being deleted before their users, and ensures observers/systems remain active while events are being generated.
3. Query out entities with no children: Reduces complex cleanup logic.
4. Delete root entities.
5. Delete everything else: Remaining entities are deleted; at this stage, cleanup traits are no longer considered and order is undefined.