systems/immediate

• C

  View on GitHub

  #include <immediate.h>
  #include <stdio.h>
   
  // When an application calls ecs_progress(), the world is put in readonly mode.
  // This ensures that systems (on multiple threads) can safely iterate 
  // components, without having to worry about components moving around while 
  // they're being read. This has as side effect that any operations (like adding
  // or removing components) are not visible until the end of the frame (see the
  // sync_point example for more details).
  // Sometimes this is not what you want, and you need a change to be visible
  // immediately. For these use cases, applications can use an immediate system.
  // This temporarily takes the world out of readonly mode, so a system can make
  // changes that are directly visible.
  // Because they mutate the world directly, immediate systems are never ran on
  // more than one thread, and no other systems are ran at the same time.
   
  ECS_DECLARE(Waiter);
  ECS_DECLARE(Plate);
   
  // System that assigns plates to waiter. By making this system immediate
  // plate assignments are assigned directly (not deferred) to waiters, which 
  // ensures that we won't assign plates to the same waiter more than once.
  void AssignPlate(ecs_iter_t *it) {
      ecs_world_t *ecs = it->stage;
      ecs_query_t *q_waiter = it->ctx; // Get query from system context
   
      // Iterate unassigned plates
      for (int i = 0; i < it->count; i ++) {
          ecs_entity_t plate = it->entities[i];
   
          // Find an available waiter
          ecs_iter_t qit = ecs_query_iter(ecs, q_waiter);
          ecs_entity_t waiter = ecs_iter_first(&qit); // Get first matching entity
          if (waiter) {
              // An available waiter was found, assign a plate to it so that the
              // next plate will no longer find it.
              ecs_add_pair(it->world, waiter, Plate, plate);
   
              ecs_add_pair(ecs, plate, Waiter, waiter);
   
              printf("Assigned %s to %s!\n",
                  ecs_get_name(ecs, waiter),
                  ecs_get_name(ecs, plate));
   
          } else {
              // No available waiters, can't assign the plate
          }
      }
  }
   
  int main(int argc, char *argv[]) {
      ecs_world_t *ecs = ecs_init_w_args(argc, argv);
   
      ECS_TAG_DEFINE(ecs, Waiter);
      ECS_TAG_DEFINE(ecs, Plate);
   
      // Create query to find all waiters without a plate
      ecs_query_t *q_waiter = ecs_query(ecs, {
          .terms = {
              { .id = Waiter },
              { .id = ecs_pair(Plate, EcsWildcard), .oper = EcsNot }
          }
      });
   
      // Find all plates without a Waiter
      ecs_system(ecs, {
          .entity = ecs_entity(ecs, { .name = "AssignPlate" }),
          .phase = EcsOnUpdate,
          .query.terms = {
              { .id = Plate },
              { .id = ecs_pair(Waiter, EcsWildcard), .oper = EcsNot }
          },
          .callback = AssignPlate,
          .ctx = q_waiter,
          .immediate = true // disable readonly mode for this system
      });
   
      // Create a few plates and waiters
      ecs_entity_t waiter_1 = ecs_entity(ecs, { .name = "waiter_1" });
      ecs_add_id(ecs, waiter_1, Waiter);
      ecs_entity_t waiter_2 = ecs_entity(ecs, { .name = "waiter_2" });
      ecs_add_id(ecs, waiter_2, Waiter);
      ecs_entity_t waiter_3 = ecs_entity(ecs, { .name = "waiter_3" });
      ecs_add_id(ecs, waiter_3, Waiter);
   
      ecs_entity_t plate_1 = ecs_entity(ecs, { .name = "plate_1" });
      ecs_add_id(ecs, plate_1, Plate);
      ecs_entity_t plate_2 = ecs_entity(ecs, { .name = "plate_2" });
      ecs_add_id(ecs, plate_2, Plate);
      ecs_add_pair(ecs, plate_2, Waiter, waiter_1); // already assigned
      ecs_entity_t plate_3 = ecs_entity(ecs, { .name = "plate_3" });
      ecs_add_id(ecs, plate_3, Plate);
   
      // Also assign plate_2 to waiter_1
      ecs_add_pair(ecs, waiter_1, Plate, plate_2);
   
      // Run the system
      ecs_progress(ecs, 0);
   
      return ecs_fini(ecs);
      
      // Output:
      //  Assigned waiter_3 to plate_1!
      //  Assigned waiter_2 to plate_3!
  }

• C++

  View on GitHub

  #include <immediate.h>
  #include <iostream>
   
  // When an application calls world.progress(), the world is put in readonly mode.
  // This ensures that systems (on multiple threads) can safely iterate 
  // components, without having to worry about components moving around while 
  // they're being read. This has as side effect that any operations (like adding
  // or removing components) are not visible until the end of the frame (see the
  // sync_point example for more details).
  // Sometimes this is not what you want, and you need a change to be visible
  // immediately. For these use cases, applications can use an immediate system.
  // This temporarily takes the world out of readonly mode, so a system can make
  // changes that are directly visible.
  // Because they mutate the world directly, immediate systems are never ran on
  // more than one thread, and no other systems are ran at the same time.
   
  struct Waiter { };
  struct Plate { };
   
  int main(int, char *[]) {
      flecs::world ecs;
   
      // Create query to find all waiters without a plate
      flecs::query<> q_waiter = ecs.query_builder()
          .with<Waiter>()
          .without<Plate>(flecs::Wildcard)
          .build();
   
      // System that assigns plates to waiter. By making this system immediate
      // plate assignments are assigned directly (not deferred) to waiters, which 
      // ensures that we won't assign plates to the same waiter more than once.
      ecs.system("AssignPlate")
          .with<Plate>()
          .without<Waiter>(flecs::Wildcard)
          .immediate()
          .each([&](flecs::iter& it, size_t i) {
              flecs::entity plate = it.entity(i);
   
              // Find an available waiter
              flecs::entity waiter = q_waiter.first();
              if (waiter) {
                  waiter.mut(it.world()).add<Plate>(plate);
   
                  plate.add<Waiter>(waiter);
   
                  std::cout << "Assigned " 
                      << waiter.name() << " to " 
                      << plate.name() << "!\n";
              } else {
                  // No available waiters, can't assign the plate
              }
          });
   
      // Create a few plates and waiters
      flecs::entity waiter_1 = ecs.entity("waiter_1").add<Waiter>();
      ecs.entity("waiter_2").add<Waiter>();
      ecs.entity("waiter_3").add<Waiter>();
   
      ecs.entity("plate_1").add<Plate>();
      flecs::entity plate_2 = ecs.entity("plate_2").add<Plate>();
      ecs.entity("plate_3").add<Plate>();
   
      waiter_1.add<Plate>(plate_2);
      plate_2.add<Waiter>(waiter_1);
   
      // run systems
      ecs.progress();
   
      // Output:
      //  Assigned waiter_3 to plate_1!
      //  Assigned waiter_2 to plate_3!
  }