Add documentation for Inheritable trait

Author: SanderMertens

distr/flecs.c

@@ -34186,7 +34186,7 @@ int flecs_term_finalize(
         }
     }
 
-    if (first_entity) {
+    if (first_entity && !ecs_term_match_0(term)) {
         bool first_is_self = (first_flags & EcsTraverseFlags) == EcsSelf;
         ecs_record_t *first_record = flecs_entities_get(world, first_entity);
         ecs_table_t *first_table = first_record ? first_record->table : NULL;
@@ -72724,7 +72724,7 @@ void flecs_query_validate_final_fields(
         ecs_term_t *term = &terms[i];
         ecs_id_t id = term->id;
 
-        if (!(impl->final_terms & (1 << i))) {
+        if (!(impl->final_terms & (1ull << i))) {
             continue;
         }
 

docs/ComponentTraits.md

@@ -939,6 +939,88 @@ let i = world.entity().is_a_id(e); // not allowed
 
 Queries may use the final trait to optimize, as they do not have to explore subsets of a final entity. For more information on how queries interpret final, see the [Query manual](Queries.md).
 
+## Inheritable trait
+The `Inheritable` trait indicates that a component can be inherited from (it can be used as target of an `IsA` relationship). It is not required to add this trait to components before using them as target of an `IsA` pair, but it can be used to ensure that queries for the component take into account component inheritance.
+
+<div class="flecs-snippet-tabs">
+<ul>
+<li><b class="tab-title">C</b>
+
+```c
+ECS_TAG(world, Unit);
+ecs_add_id(world, Unit, EcsInheritable);
+
+ecs_query_t *q = ecs_query(world, {
+    .terms = {{ Unit }}
+});
+
+ECS_TAG(world, Warrior);
+ecs_add_pair(world, Warrior, EcsIsA, Unit);
+
+ecs_iter_t it = ecs_query_iter(world, q);
+// iterate query
+```
+
+</li>
+<li><b class="tab-title">C++</b>
+
+```cpp
+world.component<Unit>().add(flecs::Inheritable);
+
+auto q = world.query_builder()
+  .with<Unit>()
+  .build();
+
+world.component<Warrior>().is_a<Unit>();
+
+q.each([](flecs::entity unit) {
+    // ...
+});
+```
+
+</li>
+<li><b class="tab-title">C#</b>
+
+```cs
+world.Component<Unit>().Add(Ecs.Inheritable);
+
+auto q = world.QueryBuilder()
+  .With<Unit>()
+  .Build();
+
+q.Each([](Entity unit) {
+    // ...
+});
+```
+
+</li>
+<li><b class="tab-title">Rust</b>
+
+```rust
+world.component::<Unit>().add_trait::<flecs::Inheritable>();
+
+auto q = world.query()
+  .with::<Unit>()
+  .build();
+
+world.component<Warrior>().is_a<Unit>();
+
+q.each_entity(|e|  {
+    // ...
+});
+```
+
+</li>
+</ul>
+</div>
+
+Queries must be aware of (potential) inheritance relationships when they are created. A query will be created with support for inheritance under the following conditions:
+ - If the component has the `Inheritable` trait
+ - If the component is inherited from
+ - If the component inherits from another component and is not `Final`
+
+If a query was not aware of inheritance relationships at creation time and one or more of the components in the query were inherited from, query iteration will fail in debug mode.
+
 ## OnInstantiate trait
 The `OnInstantiate` trait configures the behavior of components when an entity is instantiated from another entity (usually a prefab). Instantiation happens when an `IsA` pair is added to an entity.
 

src/query/engine/eval_iter.c

@@ -288,7 +288,7 @@ void flecs_query_validate_final_fields(
         ecs_term_t *term = &terms[i];
         ecs_id_t id = term->id;
 
-        if (!(impl->final_terms & (1 << i))) {
+        if (!(impl->final_terms & (1ull << i))) {
             continue;
         }
 

src/query/validator.c

@@ -841,7 +841,7 @@ int flecs_term_finalize(
         }
     }
 
-    if (first_entity) {
+    if (first_entity && !ecs_term_match_0(term)) {
         bool first_is_self = (first_flags & EcsTraverseFlags) == EcsSelf;
         ecs_record_t *first_record = flecs_entities_get(world, first_entity);
         ecs_table_t *first_table = first_record ? first_record->table : NULL;

test/query/project.json

@@ -1296,7 +1296,8 @@
                 "inheritable_trait",
                 "query_before_isa_relationship_1st_term",
                 "query_before_isa_relationship_2nd_term",
-                "query_before_isa_relationship_subtype"
+                "query_before_isa_relationship_subtype",
+                "query_before_isa_relationship_0_src"
             ]
         }, {
             "id": "Recycled",

test/query/src/ComponentInheritance.c

@@ -3479,3 +3479,37 @@ void ComponentInheritance_query_before_isa_relationship_subtype(void) {
 
     ecs_fini(world);
 }
+
+void ComponentInheritance_query_before_isa_relationship_0_src(void) {
+    ecs_world_t *world = ecs_mini();
+
+    ECS_TAG(world, Foo);
+    ECS_TAG(world, Unit);
+
+    ecs_query_t *q = ecs_query(world, {
+        .expr = "Foo, Unit()"
+    });
+
+    test_assert(q != NULL);
+
+    ECS_ENTITY(world, Warrior, (IsA, Unit));
+
+    ecs_entity_t e1 = ecs_new_w(world, Foo);
+
+    ecs_iter_t it = ecs_query_iter(world, q);
+    test_bool(true, ecs_query_next(&it));
+    test_uint(1, it.count);
+    test_uint(e1, it.entities[0]);
+    test_uint(Foo, ecs_field_id(&it, 0));
+    test_uint(Unit, ecs_field_id(&it, 1));
+    test_uint(0, ecs_field_src(&it, 0));
+    test_uint(0, ecs_field_src(&it, 1));
+    test_bool(true, ecs_field_is_set(&it, 0));
+    test_bool(false, ecs_field_is_set(&it, 1));
+
+    test_bool(false, ecs_query_next(&it));
+
+    ecs_query_fini(q);
+
+    ecs_fini(world);
+}

test/query/src/main.c

@@ -1258,6 +1258,7 @@ void ComponentInheritance_inheritable_trait(void);
 void ComponentInheritance_query_before_isa_relationship_1st_term(void);
 void ComponentInheritance_query_before_isa_relationship_2nd_term(void);
 void ComponentInheritance_query_before_isa_relationship_subtype(void);
+void ComponentInheritance_query_before_isa_relationship_0_src(void);
 
 // Testsuite 'Recycled'
 void Recycled_setup(void);
@@ -7096,6 +7097,10 @@ bake_test_case ComponentInheritance_testcases[] = {
     {
         "query_before_isa_relationship_subtype",
         ComponentInheritance_query_before_isa_relationship_subtype
+    },
+    {
+        "query_before_isa_relationship_0_src",
+        ComponentInheritance_query_before_isa_relationship_0_src
     }
 };
 
@@ -10751,7 +10756,7 @@ static bake_test_suite suites[] = {
         "ComponentInheritance",
         NULL,
         NULL,
-        35,
+        36,
         ComponentInheritance_testcases
     },
     {