Instanced queries

[SanderMertens]

Instanced queries introduce a number of behavior changes that will:

• match components shared from prefabs by default
• abstract away the difference between shared/non-shared terms by default

In practice this means that by default all terms of a query/system can be iterated as arrays, regardless of whether they are from a prefab, parent or other externally referenced entities.

for (int i = 0; i < it->count; i ++) {
  p[i].x += p_parent[i].x
}

The old behavior (accessing components from prefab, parent, referenced entities as pointers vs. arrays) is now available as an "instanced query" (similar to instanced rendering, where the same resource is reused for multiple instances).

It can be enabled with an "instanced" flag in ecs_filter_dec_t (the filter field in ecs_query_desc_t and the query.filter field in ecs_system_desc_t):

ecs_filter_init(world, &f, &(ecs_filter_desc_t) {
  .terms = { {component_a}, {component_b} },
  .instanced = true
});

or in C++:

auto q = world.query_builder<Position, Velocity>().instanced().build();

Using each() in the C++ API always uses an instanced iterator.

[Hexlord]

In practice this means that by default all terms of a query/system can be iterated as arrays, regardless of whether they are from a prefab, parent or other externally referenced entities.

That sounds a bit like a performance degradation due to iter always having a count of 1? So while the cache utilization is still optimal, we spend a lot more instructions on the surrogate for-loop that is always a length of 1 for queries containing shared component. It is probably not a big problem though, to be fair.

[SanderMertens]

It is a performance degradation, but only when a result contains shared terms, which is determined on a per-result basis. If a query matches two tables, the result for table one has shared fields & the other one hasn't, only the first one will always have a count of 1 (this can happen with matching prefabs).

If your query however has a singleton or requests a component from a single entity & is not instanced, then the iterator will always return a single entity. To go back to the old behavior, use .instanced().