Implement set_group() for systems

SanderMertens · SanderMertens · commit ae6c1b471bb0 · 2026-03-09T15:16:10.000-07:00
diff --git a/distr/flecs.c b/distr/flecs.c
@@ -75943,6 +75943,10 @@ ecs_entity_t flecs_run_system(
     qit.callback_ctx = system_data->callback_ctx;
     qit.run_ctx = system_data->run_ctx;
 
+    if (system_data->group_id_set) {
+        ecs_iter_set_group(&qit, system_data->group_id);
+    }
+
     if (stage_count > 1 && system_data->multi_threaded) {
         wit = ecs_worker_iter(it, stage_index, stage_count);
         it = &wit;
@@ -76275,6 +76279,23 @@ const ecs_system_t* ecs_system_get(
     return flecs_poly_get(world, entity, ecs_system_t);
 }
 
+void ecs_system_set_group(
+    ecs_world_t *world,
+    ecs_entity_t system,
+    uint64_t group_id)
+{
+    ecs_check(world != NULL, ECS_INVALID_PARAMETER, NULL);
+    ecs_check(system != 0, ECS_INVALID_PARAMETER, NULL);
+
+    ecs_system_t *system_data = flecs_poly_get(world, system, ecs_system_t);
+    ecs_check(system_data != NULL, ECS_INVALID_PARAMETER, NULL);
+
+    system_data->group_id = group_id;
+    system_data->group_id_set = true;
+error:
+    return;
+}
+
 void FlecsSystemImport(
     ecs_world_t *world)
 {
diff --git a/distr/flecs.h b/distr/flecs.h
@@ -13231,6 +13231,12 @@ typedef struct ecs_system_t {
     /** System query */
     ecs_query_t *query;
 
+    /** Query group to iterate */
+    uint64_t group_id;
+
+    /** True if a query group is configured */
+    bool group_id_set;
+
     /** Tick source associated with system */
     ecs_entity_t tick_source;
 
@@ -13287,6 +13293,21 @@ const ecs_system_t* ecs_system_get(
     const ecs_world_t *world,
     ecs_entity_t system);
 
+/** Set query group for system.
+ * This operation configures a system created with a grouped query to only
+ * iterate results for the specified group id. The group filter is applied to
+ * both manual runs and pipeline execution.
+ *
+ * @param world The world.
+ * @param system The system.
+ * @param group_id The query group id to iterate.
+ */
+FLECS_API
+void ecs_system_set_group(
+    ecs_world_t *world,
+    ecs_entity_t system,
+    uint64_t group_id);
+
 #ifndef FLECS_LEGACY
 
 /** Forward declare a system. */
@@ -34477,6 +34498,17 @@ struct system final : entity
         return flecs::query<>(ecs_system_get(world_, id_)->query);
     }
 
+    system& set_group(uint64_t group_id) {
+        ecs_system_set_group(world_, id_, group_id);
+        return *this;
+    }
+
+    template <typename Group>
+    system& set_group() {
+        ecs_system_set_group(world_, id_, _::type<Group>().id(world_));
+        return *this;
+    }
+
     system_runner_fluent run(ecs_ftime_t delta_time = 0.0f, void *param = nullptr) const {
         return system_runner_fluent(world_, id_, 0, 0, delta_time, param);
     }
diff --git a/include/flecs/addons/cpp/mixins/system/impl.hpp b/include/flecs/addons/cpp/mixins/system/impl.hpp
@@ -90,6 +90,17 @@ struct system final : entity
         return flecs::query<>(ecs_system_get(world_, id_)->query);
     }
 
+    system& set_group(uint64_t group_id) {
+        ecs_system_set_group(world_, id_, group_id);
+        return *this;
+    }
+
+    template <typename Group>
+    system& set_group() {
+        ecs_system_set_group(world_, id_, _::type<Group>().id(world_));
+        return *this;
+    }
+
     system_runner_fluent run(ecs_ftime_t delta_time = 0.0f, void *param = nullptr) const {
         return system_runner_fluent(world_, id_, 0, 0, delta_time, param);
     }
diff --git a/include/flecs/addons/system.h b/include/flecs/addons/system.h
@@ -120,6 +120,12 @@ typedef struct ecs_system_t {
     /** System query */
     ecs_query_t *query;
 
+    /** Query group to iterate */
+    uint64_t group_id;
+
+    /** True if a query group is configured */
+    bool group_id_set;
+
     /** Tick source associated with system */
     ecs_entity_t tick_source;
 
@@ -176,6 +182,21 @@ const ecs_system_t* ecs_system_get(
     const ecs_world_t *world,
     ecs_entity_t system);
 
+/** Set query group for system.
+ * This operation configures a system created with a grouped query to only
+ * iterate results for the specified group id. The group filter is applied to
+ * both manual runs and pipeline execution.
+ *
+ * @param world The world.
+ * @param system The system.
+ * @param group_id The query group id to iterate.
+ */
+FLECS_API
+void ecs_system_set_group(
+    ecs_world_t *world,
+    ecs_entity_t system,
+    uint64_t group_id);
+
 #ifndef FLECS_LEGACY
 
 /** Forward declare a system. */
diff --git a/src/addons/system/system.c b/src/addons/system/system.c
@@ -93,6 +93,10 @@ ecs_entity_t flecs_run_system(
     qit.callback_ctx = system_data->callback_ctx;
     qit.run_ctx = system_data->run_ctx;
 
+    if (system_data->group_id_set) {
+        ecs_iter_set_group(&qit, system_data->group_id);
+    }
+
     if (stage_count > 1 && system_data->multi_threaded) {
         wit = ecs_worker_iter(it, stage_index, stage_count);
         it = &wit;
@@ -425,6 +429,23 @@ const ecs_system_t* ecs_system_get(
     return flecs_poly_get(world, entity, ecs_system_t);
 }
 
+void ecs_system_set_group(
+    ecs_world_t *world,
+    ecs_entity_t system,
+    uint64_t group_id)
+{
+    ecs_check(world != NULL, ECS_INVALID_PARAMETER, NULL);
+    ecs_check(system != 0, ECS_INVALID_PARAMETER, NULL);
+
+    ecs_system_t *system_data = flecs_poly_get(world, system, ecs_system_t);
+    ecs_check(system_data != NULL, ECS_INVALID_PARAMETER, NULL);
+
+    system_data->group_id = group_id;
+    system_data->group_id_set = true;
+error:
+    return;
+}
+
 void FlecsSystemImport(
     ecs_world_t *world)
 {
diff --git a/test/addons/project.json b/test/addons/project.json
@@ -189,6 +189,7 @@
                 "register_run_after_callback",
                 "register_callback_after_run_ctx",
                 "register_run_after_callback_ctx",
+                "set_group",
                 "run_w_query_next",
                 "missing_callback"
             ]
diff --git a/test/addons/src/SystemMisc.c b/test/addons/src/SystemMisc.c
@@ -1806,6 +1806,91 @@ static void Run_w_query_next(ecs_iter_t *it) {
     run_invoked ++;
 }
 
+static
+uint64_t SystemMisc_group_by_rel(
+    ecs_world_t *world,
+    ecs_table_t *table,
+    ecs_id_t id,
+    void *ctx)
+{
+    (void)ctx;
+
+    ecs_id_t match;
+    if (ecs_search(world, table, ecs_pair(id, EcsWildcard), &match) != -1) {
+        return ECS_PAIR_SECOND(match);
+    }
+
+    return 0;
+}
+
+static
+uint64_t system_misc_expected_group;
+
+static
+void SystemMisc_grouped_dummy(ecs_iter_t *it) {
+    test_uint(ecs_iter_get_group(it), system_misc_expected_group);
+    probe_iter(it);
+}
+
+static
+void SystemMisc_reset_probe(Probe *ctx) {
+    ecs_os_zeromem(ctx);
+}
+
+void SystemMisc_set_group(void) {
+    ecs_world_t *world = ecs_init();
+
+    ecs_entity_t Rel = ecs_entity(world, {0});
+    ecs_entity_t TgtA = ecs_entity(world, {0});
+    ecs_entity_t TgtB = ecs_entity(world, {0});
+    ecs_entity_t TgtC = ecs_entity(world, {0});
+    ECS_TAG(world, Tag);
+
+    ecs_entity_t e1 = ecs_new_w_pair(world, Rel, TgtA);
+    ecs_entity_t e2 = ecs_new_w_pair(world, Rel, TgtB);
+    ecs_new_w_pair(world, Rel, TgtC);
+    ecs_entity_t e4 = ecs_new_w_pair(world, Rel, TgtA);
+    ecs_entity_t e5 = ecs_new_w_pair(world, Rel, TgtB);
+    ecs_entity_t e6 = ecs_new_w_pair(world, Rel, TgtC);
+
+    ecs_add(world, e4, Tag);
+    ecs_add(world, e5, Tag);
+    ecs_add(world, e6, Tag);
+
+    Probe ctx = {0};
+    ecs_set_ctx(world, &ctx, NULL);
+
+    ecs_entity_t system = ecs_system_init(world, &(ecs_system_desc_t){
+        .query.terms = {{ .id = ecs_pair(Rel, EcsWildcard) }},
+        .query.group_by = Rel,
+        .query.group_by_callback = SystemMisc_group_by_rel,
+        .callback = SystemMisc_grouped_dummy
+    });
+    test_assert(system != 0);
+
+    system_misc_expected_group = TgtB;
+    ecs_system_set_group(world, system, TgtB);
+    ecs_run(world, system, 0, NULL);
+
+    test_int(ctx.invoked, 2);
+    test_int(ctx.count, 2);
+    probe_has_entity(&ctx, e2);
+    probe_has_entity(&ctx, e5);
+
+    SystemMisc_reset_probe(&ctx);
+
+    system_misc_expected_group = TgtA;
+    ecs_system_set_group(world, system, TgtA);
+    ecs_run(world, system, 0, NULL);
+
+    test_int(ctx.invoked, 2);
+    test_int(ctx.count, 2);
+    probe_has_entity(&ctx, e1);
+    probe_has_entity(&ctx, e4);
+
+    ecs_fini(world);
+}
+
 void SystemMisc_run_w_query_next(void) {
     ecs_world_t *world = ecs_init();
 
diff --git a/test/addons/src/main.c b/test/addons/src/main.c
@@ -181,6 +181,7 @@ void SystemMisc_register_callback_after_run(void);
 void SystemMisc_register_run_after_callback(void);
 void SystemMisc_register_callback_after_run_ctx(void);
 void SystemMisc_register_run_after_callback_ctx(void);
+void SystemMisc_set_group(void);
 void SystemMisc_run_w_query_next(void);
 void SystemMisc_missing_callback(void);
 
@@ -1245,6 +1246,10 @@ bake_test_case SystemMisc_testcases[] = {
         "register_run_after_callback_ctx",
         SystemMisc_register_run_after_callback_ctx
     },
+    {
+        "set_group",
+        SystemMisc_set_group
+    },
     {
         "run_w_query_next",
         SystemMisc_run_w_query_next
@@ -2663,6 +2668,7 @@ const char* MultiThread_worker_kind_param[] = {"thread", "task"};
 bake_test_param MultiThread_params[] = {
     {"worker_kind", (char**)MultiThread_worker_kind_param, 2}
 };
+
 const char* MultiThreadStaging_worker_kind_param[] = {"thread", "task"};
 bake_test_param MultiThreadStaging_params[] = {
     {"worker_kind", (char**)MultiThreadStaging_worker_kind_param, 2}
@@ -2687,7 +2693,7 @@ static bake_test_suite suites[] = {
         "SystemMisc",
         NULL,
         NULL,
-        71,
+        72,
         SystemMisc_testcases
     },
     {
diff --git a/test/cpp/project.json b/test/cpp/project.json
@@ -675,6 +675,7 @@
                 "register_twice_w_run",
                 "register_twice_w_run_each",
                 "register_twice_w_each_run",
+                "set_group",
                 "run_w_0_src_query"
             ]
         }, {
diff --git a/test/cpp/src/System.cpp b/test/cpp/src/System.cpp
diff --git a/test/cpp/src/main.cpp b/test/cpp/src/main.cpp

Original file line number	Diff line number	Diff line change
`@@ -189,6 +189,7 @@`
`189`	`189`	`"register_run_after_callback",`
`190`	`190`	`"register_callback_after_run_ctx",`
`191`	`191`	`"register_run_after_callback_ctx",`
	`192`	`+ "set_group",`
`192`	`193`	`"run_w_query_next",`
`193`	`194`	`"missing_callback"`
`194`	`195`	`]`
Original file line number	Diff line number	Diff line change
`@@ -675,6 +675,7 @@`
`675`	`675`	`"register_twice_w_run",`
`676`	`676`	`"register_twice_w_run_each",`
`677`	`677`	`"register_twice_w_each_run",`
	`678`	`+ "set_group",`
`678`	`679`	`"run_w_0_src_query"`
`679`	`680`	`]`
`680`	`681`	`}, {`