command_buffer.h

#pragma once
#include "gaia/config/config.h"
 
#include <cstdint>
#include <type_traits>
 
#include "gaia/cnt/darray_ext.h"
#include "gaia/cnt/dbitset.h"
#include "gaia/cnt/sarray_ext.h"
#include "gaia/ecs/archetype.h"
#include "gaia/ecs/command_buffer_fwd.h"
#include "gaia/ecs/common.h"
#include "gaia/ecs/component.h"
#include "gaia/ecs/component_cache.h"
#include "gaia/ecs/component_cache_item.h"
#include "gaia/ecs/id.h"
#include "gaia/ecs/world.h"
#include "gaia/ser/ser_buffer_binary.h"
 
namespace gaia {
  namespace ecs {
    struct AccessContextST {
      void lock() {}
      void unlock() {}
    };
 
    struct AccessContextMT {
      mt::SpinLock m_lock;
 
      void lock() {
        m_lock.lock();
      }
 
      void unlock() {
        m_lock.unlock();
      }
    };
 
    namespace detail {
      template <typename AccessContext, bool Optimize>
      class CommandBuffer final {
        enum class OpType : uint8_t {
          NONE = 0,
          ADD_ENTITY,
          CPY_ENTITY,
          INSTANTIATE_ENTITY,
          DEL_ENTITY,
          ADD_COMPONENT,
          ADD_COMPONENT_DATA,
          SET_COMPONENT,
          DEL_COMPONENT,
        };
 
        enum : uint8_t {
          F_ADD = 1 << 0, //
          F_ADD_DATA = 1 << 1, //
          F_SET = 1 << 2, //
          F_DEL = 1 << 3 //
        };
 
        struct Op {
          OpType type;
          uint32_t off;
          Entity target;
          Entity other;
          Entity pairTarget = EntityBad;
          uint32_t order = 0;
        };
 
        ecs::World& m_world;
        cnt::darray_ext<Op, 128> m_ops;
        cnt::darray_ext<Entity, 128> m_temp2real;
        cnt::dbitset<mem::DefaultAllocatorAdaptor> m_tmpFlags;
        uint32_t m_nextTemp = 0;
        bool m_needsSort = false;
 
        ser::bin_stream m_data;
        AccessContext m_acc;
 
      public:
        explicit CommandBuffer(World& world): m_world(world) {}
        ~CommandBuffer() = default;
 
        CommandBuffer(CommandBuffer&&) = delete;
        CommandBuffer(const CommandBuffer&) = delete;
        CommandBuffer& operator=(CommandBuffer&&) = delete;
        CommandBuffer& operator=(const CommandBuffer&) = delete;
 
        GAIA_NODISCARD Entity add() {
          core::lock_scope lock(m_acc);
 
          Entity temp = add_temp();
          push_op({OpType::ADD_ENTITY, 0, temp, EntityBad});
          return temp;
        }
 
        GAIA_NODISCARD Entity copy(Entity entityFrom) {
          core::lock_scope lock(m_acc);
 
          Entity temp = add_temp();
          push_op({OpType::CPY_ENTITY, 0, temp, entityFrom});
          return temp;
        }
 
        GAIA_NODISCARD Entity instantiate(Entity prefabEntity) {
          return instantiate(prefabEntity, EntityBad);
        }
 
        GAIA_NODISCARD Entity instantiate(Entity prefabEntity, Entity parentInstance) {
          core::lock_scope lock(m_acc);
 
          Entity temp = add_temp();
          push_op({OpType::INSTANTIATE_ENTITY, 0, temp, prefabEntity, parentInstance});
          return temp;
        }
 
        void instantiate_n(Entity prefabEntity, uint32_t count) {
          instantiate_n(prefabEntity, EntityBad, count, []([[maybe_unused]] Entity) {});
        }
 
        void instantiate_n(Entity prefabEntity, Entity parentInstance, uint32_t count) {
          instantiate_n(prefabEntity, parentInstance, count, []([[maybe_unused]] Entity) {});
        }
 
        template <typename Func>
        void instantiate_n(Entity prefabEntity, uint32_t count, Func func) {
          instantiate_n(prefabEntity, EntityBad, count, func);
        }
 
        template <typename Func>
        void instantiate_n(Entity prefabEntity, Entity parentInstance, uint32_t count, Func func) {
          static_assert(
              std::is_invocable_v<Func, Entity>,
              "Command-buffer instantiate_n callbacks receive temporary Entity handles");
          if (count == 0U)
            return;
 
          GAIA_FOR(count) {
            const Entity temp = instantiate(prefabEntity, parentInstance);
            func(temp);
          }
        }
 
        template <typename T>
        void add(Entity entity) {
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          // Make sure the component is registered
          const auto& item = comp_cache_add<T>(m_world);
 
          push_op({OpType::ADD_COMPONENT, 0, entity, item.entity});
        }
 
        void add(Entity entity, Entity other) {
          core::lock_scope lock(m_acc);
 
          if (other.pair()) {
            push_op({OpType::ADD_COMPONENT, 0, entity, m_world.get(other.id()), m_world.get(other.gen())});
            return;
          }
 
          push_op({OpType::ADD_COMPONENT, 0, entity, other});
        }
 
        void add(Entity entity, const Pair& pair) {
          core::lock_scope lock(m_acc);
 
          push_op({OpType::ADD_COMPONENT, 0, entity, pair.first(), pair.second()});
        }
 
        template <typename T>
        void add(Entity entity, Entity object, T&& value) {
          static_assert(core::is_raw_v<T>);
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          Entity other = object;
          Entity pairTarget = EntityBad;
          if (object.pair()) {
            other = m_world.get(object.id());
            pairTarget = m_world.get(object.gen());
          }
 
          const auto& item = comp_cache_add<T>(m_world);
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::ADD_COMPONENT_DATA, pos, entity, other, pairTarget});
        }
 
        template <typename T>
        void add(Entity entity, const Pair& pair, T&& value) {
          static_assert(core::is_raw_v<T>);
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          const auto& item = comp_cache_add<T>(m_world);
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::ADD_COMPONENT_DATA, pos, entity, pair.first(), pair.second()});
        }
 
        template <typename T, std::enable_if_t<!is_pair<std::remove_cv_t<std::remove_reference_t<T>>>::value, int> = 0>
        void add(Entity entity, T&& value) {
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          // Make sure the component is registered
          const auto& item = comp_cache_add<T>(m_world);
 
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::ADD_COMPONENT_DATA, pos, entity, item.entity});
        }
 
        template <typename T>
        void set(Entity entity, T&& value) {
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          // Make sure the component is registered
          const auto& item = comp_cache(m_world).template get<T>();
 
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::SET_COMPONENT, pos, entity, item.entity});
        }
 
        template <typename T>
        void set(Entity entity, Entity object, T&& value) {
          static_assert(core::is_raw_v<T>);
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          Entity other = object;
          Entity pairTarget = EntityBad;
          if (object.pair()) {
            other = m_world.get(object.id());
            pairTarget = m_world.get(object.gen());
          }
 
          const auto& item = comp_cache(m_world).template get<T>();
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::SET_COMPONENT, pos, entity, other, pairTarget});
        }
 
        template <typename T>
        void set(Entity entity, const Pair& pair, T&& value) {
          static_assert(core::is_raw_v<T>);
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          const auto& item = comp_cache(m_world).template get<T>();
          const auto pos = m_data.tell();
          auto serializer = ser::make_serializer(m_data);
          save_value(serializer, item, value);
          push_op({OpType::SET_COMPONENT, pos, entity, pair.first(), pair.second()});
        }
 
        void del(Entity entity) {
          core::lock_scope lock(m_acc);
 
          push_op({OpType::DEL_ENTITY, 0, entity, EntityBad});
        }
 
        template <typename T>
        void del(Entity entity) {
          verify_comp<T>();
          core::lock_scope lock(m_acc);
 
          // Make sure the component is registered
          const auto& item = comp_cache(m_world).template get<T>();
 
          push_op({OpType::DEL_COMPONENT, 0, entity, item.entity});
        }
 
        void del(Entity entity, Entity object) {
          core::lock_scope lock(m_acc);
 
          if (object.pair()) {
            push_op({OpType::DEL_COMPONENT, 0, entity, m_world.get(object.id()), m_world.get(object.gen())});
            return;
          }
 
          push_op({OpType::DEL_COMPONENT, 0, entity, object});
        }
 
        void del(Entity entity, const Pair& pair) {
          core::lock_scope lock(m_acc);
 
          push_op({OpType::DEL_COMPONENT, 0, entity, pair.first(), pair.second()});
        }
 
      private:
        template <typename T>
        static void save_value(ser::serializer& serializer, const ComponentCacheItem& item, const T& value) {
          if constexpr (mem::is_soa_layout_v<T>) {
#if GAIA_ASSERT_ENABLED
            serializer.check(value);
#endif
            serializer.save(value);
          } else {
            item.save(serializer, &value, 0, 1, 1);
          }
        }
 
        GAIA_NODISCARD bool is_rel(OpType t) const {
          return (uint32_t)t >= (uint32_t)OpType::ADD_COMPONENT;
        }
 
        GAIA_NODISCARD bool is_tmp(Entity e) const {
          return e.data.tmp != 0;
        }
 
        GAIA_NODISCARD Entity resolve(Entity e) const {
          if (!is_tmp(e))
            return e;
 
          const auto ti = e.id();
          if (ti < m_temp2real.size())
            return m_temp2real[ti];
 
          return EntityBad;
        }
 
        GAIA_NODISCARD Entity resolve_object(const Op& op) const {
          if (op.pairTarget == EntityBad)
            return resolve(op.other);
 
          const auto relation = resolve(op.other);
          const auto target = resolve(op.pairTarget);
          if (relation == EntityBad || target == EntityBad)
            return EntityBad;
 
          return (Entity)Pair(relation, target);
        }
 
        void allocate_instantiate_group(uint32_t firstIdx) {
          const Op& first = m_ops[firstIdx];
          const Entity prefab = resolve(first.other);
          if (prefab == EntityBad)
            return;
 
          Entity parent = EntityBad;
          if (first.pairTarget != EntityBad) {
            parent = resolve(first.pairTarget);
            if (parent == EntityBad)
              return;
          }
 
          cnt::darray_ext<uint32_t, 16> tempIds;
          for (uint32_t j = firstIdx; j < m_ops.size(); ++j) {
            const Op& op = m_ops[j];
            if (op.type != OpType::INSTANTIATE_ENTITY || op.other != first.other || op.pairTarget != first.pairTarget)
              continue;
            if (!is_tmp(op.target))
              continue;
 
            const uint32_t ti = op.target.id();
            if (ti >= m_temp2real.size() || m_temp2real[ti] != EntityBad || is_canceled_temp(ti))
              continue;
 
            tempIds.push_back(ti);
          }
 
          if (tempIds.empty())
            return;
 
          if (tempIds.size() == 1) {
            m_temp2real[tempIds[0]] =
                parent == EntityBad ? m_world.instantiate(prefab) : m_world.instantiate(prefab, parent);
            return;
          }
 
          uint32_t mapped = 0;
          auto mapRoot = [&](Entity instance) {
            GAIA_ASSERT(mapped < tempIds.size());
            m_temp2real[tempIds[mapped++]] = instance;
          };
          if (parent == EntityBad)
            m_world.instantiate_n(prefab, tempIds.size(), mapRoot);
          else
            m_world.instantiate_n(prefab, parent, tempIds.size(), mapRoot);
          GAIA_ASSERT(mapped == tempIds.size());
        }
 
        void replay_add(Entity target, Entity object) {
          if (object.pair()) {
            World::EntityBuilder(m_world, target).add(Pair(m_world.get(object.id()), m_world.get(object.gen())));
            return;
          }
 
          const auto* pItem = m_world.comp_cache().find(object);
          if (pItem != nullptr && pItem->comp.storage_type() == DataStorageType::Sparse) {
            const auto mode = m_world.sparse_storage_mode(object);
            GAIA_ASSERT(mode != World::SparseStorageMode::None);
            auto& store = m_world.sparse_component_store_erased_mut(object, *pItem);
            (void)store.func_add(store.pStore, target);
            m_world.finish_sparse_component_add_inter(target, object, mode);
            return;
          }
 
          World::EntityBuilder(m_world, target).add(object);
        }
 
        void replay_del(Entity target, Entity object) {
          if (object.pair())
            m_world.del(target, Pair(m_world.get(object.id()), m_world.get(object.gen())));
          else
            m_world.del(target, object);
        }
 
        template <bool Reset = false>
        void replay_data(Entity target, Entity object, uint32_t dataPos, bool finishWrite = true) {
          auto serializer = ser::make_serializer(m_data);
          serializer.seek(dataPos);
          const auto* pItem =
              object.pair() ? m_world.comp_cache().find_pair_payload(object) : m_world.comp_cache().find(object);
          GAIA_ASSERT(pItem != nullptr);
          if (pItem == nullptr)
            return;
          const auto& item = *pItem;
 
          if (m_world.component_uses_sparse_storage(object)) {
            const auto payload = m_world.mut_raw(target, object);
            GAIA_ASSERT(payload.valid());
            if (payload.valid()) {
              if constexpr (Reset) {
                if (item.func_ctor != nullptr)
                  item.func_ctor(payload.data, 1);
              }
              item.load(serializer, payload.data, 0, 1, 1);
            }
            if (finishWrite)
              m_world.finish_write(target, object);
            return;
          }
 
          const auto& ec = target.pair() ? m_world.fetch(target) : m_world.m_recs.entities[target.id()];
          const auto row = ec.row;
          const auto compIdx = ec.pChunk->comp_idx(object);
          if constexpr (Reset)
            ec.pChunk->call_ctor(row, compIdx, item);
          auto* pComponentData = (void*)ec.pChunk->comp_ptr_mut(compIdx, 0);
          item.load(serializer, pComponentData, row, row + 1, ec.pChunk->capacity());
          if (finishWrite)
            m_world.finish_write(target, object);
        }
 
        void replay_add_data(Entity target, Entity object, uint32_t dataPos) {
          const auto* pItem =
              object.pair() ? m_world.comp_cache().find_pair_payload(object) : m_world.comp_cache().find(object);
          GAIA_ASSERT(pItem != nullptr);
          if (pItem == nullptr)
            return;
          const auto& item = *pItem;
          if (gaia::ecs::component_uses_sparse_storage(item.comp)) {
            const auto mode = m_world.sparse_storage_mode(object);
            GAIA_ASSERT(mode != World::SparseStorageMode::None);
            auto& store = m_world.sparse_component_store_erased_mut(object, item);
            auto* pPayload = store.func_add(store.pStore, target);
 
            auto serializer = ser::make_serializer(m_data);
            serializer.seek(dataPos);
            item.load(serializer, pPayload, 0, 1, 1);
            m_world.finish_sparse_component_add_inter(target, object, mode);
            return;
          }
 
          World::EntityBuilder builder(m_world, target);
#if GAIA_OBSERVERS_ENABLED
          auto addDiffCtx = m_world.m_observers.prepare_diff(
              m_world, ObserverEvent::OnAdd, EntitySpan{&object, 1}, EntitySpan{&target, 1});
#endif
          builder.add_inter_init(object);
          builder.commit();
          replay_data(target, object, dataPos, false);
          m_world.notify_add_single(target, object);
#if GAIA_OBSERVERS_ENABLED
          m_world.m_observers.finish_diff(m_world, GAIA_MOV(addDiffCtx));
#endif
        }
 
        void replay_op(const Op& op, Entity target, Entity object) {
          switch (op.type) {
            case OpType::DEL_COMPONENT:
              replay_del(target, object);
              break;
            case OpType::ADD_COMPONENT:
              replay_add(target, object);
              break;
            case OpType::ADD_COMPONENT_DATA:
              replay_add_data(target, object, op.off);
              break;
            case OpType::SET_COMPONENT:
              replay_data(target, object, op.off);
              break;
            default:
              break;
          }
        }
 
        GAIA_NOINLINE void
        replay_merged(uint32_t i, uint32_t j, Entity target, Entity object, uint8_t mask, uint32_t dataPos) {
          // Reduce ordinary component lifetimes when intermediate mutations have no ECS side effects.
          bool canReduce = !object.pair() && object.id() > GAIA_ID(LastCoreComponent).id() &&
                           !m_world.m_hasRequiresPolicy && !m_world.m_hasCantCombinePolicy &&
                           !m_world.has_direct(object, Requires);
#if GAIA_OBSERVERS_ENABLED
          canReduce = canReduce && !m_world.m_observers.has_on_add_observers() &&
                      !m_world.m_observers.has_on_del_observers() && !m_world.m_observers.has_on_set_observers(object);
#endif
          const bool initial = canReduce && m_world.has_direct(target, object);
          const bool hasAdd = (mask & (F_ADD | F_ADD_DATA)) != 0;
          const auto* pItem = canReduce ? m_world.comp_cache().find(object) : nullptr;
          if (pItem != nullptr) {
            // Tags with constructors need World's chunk-backed construction path.
            canReduce = pItem->func_dtor == nullptr && (pItem->comp.size() != 0 || pItem->func_ctor == nullptr);
#if GAIA_ENABLE_ADD_DEL_HOOKS
            canReduce = canReduce && pItem->hooks().func_add == nullptr && pItem->hooks().func_del == nullptr;
#endif
#if GAIA_ENABLE_SET_HOOKS
            canReduce = canReduce && pItem->hooks().func_set == nullptr;
#endif
          }
          if (canReduce) {
            const bool hasData = (mask & (F_ADD_DATA | F_SET)) != 0;
            GAIA_ASSERT(!hasData || hasAdd);
            if (!hasAdd) {
              if (initial)
                replay_del(target, object);
            } else if (hasData) {
              if (initial)
                replay_data<true>(target, object, dataPos);
              else
                replay_add_data(target, object, dataPos);
            } else if (initial) {
              // Bare re-adds run their default constructor without moving the entity.
              if (pItem != nullptr && pItem->func_ctor != nullptr) {
                const auto payload = m_world.mut_raw(target, object);
                GAIA_ASSERT(payload.valid());
                pItem->func_ctor(payload.data, 1);
                m_world.finish_write(target, object);
              }
            } else {
              replay_add(target, object);
            }
            return;
          }
 
          for (uint32_t k = i; k < j; ++k) {
            const Op& op = m_ops[k];
            // Merged groups may contain redundant deletes of an absent component.
            if (op.type != OpType::DEL_COMPONENT || m_world.has_direct(target, object))
              replay_op(op, target, object);
          }
        }
 
        GAIA_NOINLINE bool replay_batch(uint32_t& p, uint32_t q, Entity target) {
          if (target.pair() || m_world.m_hasRequiresPolicy || m_world.m_hasCantCombinePolicy)
            return false;
#if GAIA_OBSERVERS_ENABLED
          if (m_world.m_observers.has_on_add_observers() || m_world.m_observers.has_on_del_observers())
            return false;
#endif
          struct Group {
            Entity object;
            uint32_t dataPos;
            uint8_t mask;
            bool initial;
          };
          cnt::sarray_ext<Group, ChunkHeader::MAX_COMPONENTS> groups;
          bool hasStructural = false;
          const Archetype* pArchetype = nullptr;
          uint32_t end = p;
          for (uint32_t i = p; i < q;) {
            // Allocation records were already applied; entity deletion remains deferred.
            if (m_ops[i].type < OpType::ADD_COMPONENT) {
              ++i;
              continue;
            }
            if (m_ops[i].pairTarget != EntityBad || groups.size() == groups.capacity())
              break;
            const Entity object = resolve_object(m_ops[i]);
            if (object == EntityBad || object.pair() || object.id() <= GAIA_ID(LastCoreComponent).id())
              break;
            const auto* pItem = m_world.comp_cache().find(object);
            if (pItem != nullptr) {
              if (pItem->comp.storage_type() == DataStorageType::Sparse || pItem->func_dtor != nullptr ||
                  (pItem->comp.size() == 0 && pItem->func_ctor != nullptr))
                break;
#if GAIA_ENABLE_ADD_DEL_HOOKS
              if (pItem->hooks().func_add != nullptr || pItem->hooks().func_del != nullptr)
                break;
#endif
#if GAIA_ENABLE_SET_HOOKS
              if (pItem->hooks().func_set != nullptr)
                break;
#endif
            }
#if GAIA_OBSERVERS_ENABLED
            if (m_world.m_observers.has_on_set_observers(object))
              break;
#endif
            if (m_world.component_is_non_fragmenting(object))
              break;
            if (pArchetype == nullptr)
              pArchetype = m_world.fetch(target).pArchetype;
            Group group{object, 0, 0, pArchetype->has(object)};
            const Entity key = m_ops[i].other;
            do {
              const Op& op = m_ops[i];
              switch (op.type) {
                case OpType::ADD_COMPONENT:
                  group.mask |= F_ADD;
                  break;
                case OpType::ADD_COMPONENT_DATA:
                  group.mask |= F_ADD_DATA;
                  group.dataPos = op.off;
                  break;
                case OpType::SET_COMPONENT:
                  group.mask |= F_SET;
                  group.dataPos = op.off;
                  break;
                case OpType::DEL_COMPONENT:
                  group.mask = F_DEL;
                  break;
                default:
                  break;
              }
              ++i;
            } while (i < q && m_ops[i].other == key && m_ops[i].pairTarget == EntityBad);
            if ((group.mask & F_DEL) != 0 && m_world.has_direct(object, Requires))
              break;
            const bool hasAdd = (group.mask & (F_ADD | F_ADD_DATA)) != 0;
            hasStructural |= hasAdd ? !group.initial : ((group.mask & F_DEL) != 0 && group.initial);
            groups.push_back(group);
            end = i;
          }
          if (groups.size() < 2)
            return false;
 
          if (hasStructural) {
            World::EntityBuilder builder(m_world, target);
            for (const auto& group: groups) {
              const bool hasAdd = (group.mask & (F_ADD | F_ADD_DATA)) != 0;
              if (hasAdd && !group.initial)
                builder.add_inter_init(group.object);
              else if (!hasAdd && (group.mask & F_DEL) != 0 && group.initial)
                builder.del_inter(group.object);
            }
            builder.commit();
          }
 
          // Restore surviving payloads only after the destination storage is available.
          for (const auto& group: groups) {
            const bool hasAdd = (group.mask & (F_ADD | F_ADD_DATA)) != 0;
            const bool hasDel = (group.mask & F_DEL) != 0;
            if (hasDel && !hasAdd) {
              GAIA_ASSERT((group.mask & F_SET) == 0);
              continue;
            }
            if ((group.mask & (F_ADD_DATA | F_SET)) != 0) {
              if (hasDel && group.initial)
                replay_data<true>(target, group.object, group.dataPos);
              else
                replay_data(target, group.object, group.dataPos, !hasAdd);
            } else if (hasDel && group.initial) {
              const auto* pItem = m_world.comp_cache().find(group.object);
              if (pItem != nullptr && pItem->func_ctor != nullptr) {
                const auto& ec = m_world.fetch(target);
                ec.pChunk->call_ctor(ec.row, ec.pChunk->comp_idx(group.object), *pItem);
                m_world.finish_write(target, group.object);
              }
            }
          }
          p = end;
          return true;
        }
 
        GAIA_NODISCARD bool is_canceled_temp(uint32_t idx) const {
          const uint32_t base = idx * 3;
          if (base + 2 >= m_tmpFlags.size())
            return false;
 
          const bool destroy = m_tmpFlags.test(base);
          const bool usedOther = m_tmpFlags.test(base + 2);
 
          // If deleted in this batch and not referenced by others, cancel entirely
          return destroy && !usedOther;
        }
 
        GAIA_NODISCARD Entity add_temp() {
          m_temp2real.push_back(EntityBad);
          Entity tmp(m_nextTemp++, 0, true, false);
          // Use the unused flag to mark temporary entities
          tmp.data.tmp = 1;
          return tmp;
        }
 
        GAIA_NODISCARD static bool less_op_key(const Op& a, const Op& b) {
          if (a.target != b.target)
            return a.target < b.target;
 
          const bool aIsPair = a.pairTarget != EntityBad;
          const bool bIsPair = b.pairTarget != EntityBad;
          if (aIsPair != bIsPair)
            return !aIsPair;
          if (aIsPair)
            return false;
 
          if (a.other != b.other)
            return a.other < b.other;
          return false;
        }
 
        void check_sort(const Op& op) {
          if (!m_ops.empty() && less_op_key(op, m_ops.back()))
            m_needsSort = true;
        }
 
        void push_op(Op&& op) {
          if constexpr (Optimize) {
            op.order = m_ops.size();
            check_sort(op);
          }
          m_ops.push_back(GAIA_MOV(op));
        }
 
        void replay_plain() {
          for (const Op& op: m_ops) {
            switch (op.type) {
              case OpType::ADD_ENTITY:
                m_temp2real[op.target.id()] = m_world.add();
                break;
              case OpType::CPY_ENTITY:
                m_temp2real[op.target.id()] = m_world.copy(resolve(op.other));
                break;
              case OpType::INSTANTIATE_ENTITY:
                m_temp2real[op.target.id()] = op.pairTarget == EntityBad ?
                    m_world.instantiate(resolve(op.other)) :
                    m_world.instantiate(resolve(op.other), resolve(op.pairTarget));
                break;
              case OpType::DEL_ENTITY:
                m_world.del(resolve(op.target));
                break;
              default:
                replay_op(op, resolve(op.target), resolve_object(op));
                break;
            }
          }
        }
 
        void clear() {
          m_ops.clear();
          m_temp2real.clear();
          m_tmpFlags.reset();
          m_nextTemp = 0;
          m_data.reset();
 
          m_needsSort = false;
        }
 
      public:
        void commit() {
          core::lock_scope lock(m_acc);
 
          if (m_ops.empty())
            return;
 
          GAIA_PROF_SCOPE(cmdbuf::commit);
 
          if constexpr (!Optimize)
            replay_plain();
          else
            commit_optimized();
          clear();
        }
 
      private:
        void commit_optimized() {
          // Build flags + allocate entities
          if (m_nextTemp > 0) {
            GAIA_PROF_SCOPE(cmdbuf::alloc);
 
            // Bit layout for each temporary entity:
            // bit 0 -> marked for destruction (DEL_ENTITY recorded)
            // bit 1 -> used as a relation target (appeared as target in component ops)
            // bit 2 -> used as a relation source / dependency (appeared as other in component ops)
            m_tmpFlags.resize(m_nextTemp * 3);
 
            // Pre-map surviving temps for ADD/CPY/INSTANTIATE (avoid allocating canceled temps)
            if (m_temp2real.size() < m_nextTemp) {
              const auto from = m_temp2real.size();
              m_temp2real.resize(m_nextTemp);
              GAIA_FOR2(from, m_nextTemp) m_temp2real[i] = EntityBad;
            }
 
            // Build all flags
            for (const Op& o: m_ops) {
              // Set flag bits
              if (is_tmp(o.target)) {
                const uint32_t ti = o.target.id();
 
                if (o.type == OpType::DEL_ENTITY)
                  m_tmpFlags.set((ti * 3) + 0, true);
                else if (is_rel(o.type))
                  m_tmpFlags.set((ti * 3) + 1, true);
              }
 
              if (is_tmp(o.other) && o.other.id() < m_tmpFlags.size())
                m_tmpFlags.set((o.other.id() * 3) + 2, true);
              if (is_tmp(o.pairTarget) && o.pairTarget.id() < m_tmpFlags.size())
                m_tmpFlags.set((o.pairTarget.id() * 3) + 2, true);
            }
 
            // Allocate real entities for the surviving temporaries
            for (uint32_t i = 0; i < m_ops.size(); ++i) {
              const Op& o = m_ops[i];
              if (!is_tmp(o.target))
                continue;
 
              const uint32_t ti = o.target.id();
              if (is_canceled_temp(ti) || m_temp2real[ti] != EntityBad)
                continue;
 
              if (o.type == OpType::ADD_ENTITY) {
                m_temp2real[ti] = m_world.add();
              } else if (o.type == OpType::CPY_ENTITY) {
                const Entity src = resolve(o.other);
                if (src != EntityBad)
                  m_temp2real[ti] = m_world.copy(src);
              } else if (o.type == OpType::INSTANTIATE_ENTITY) {
                allocate_instantiate_group(i);
              }
            }
          }
 
          // Sort by (target, other), reduce each component group, apply relations.
          // Preserve recorded order within each component group and each target's pair operations.
          if (m_needsSort) {
            GAIA_PROF_SCOPE(cmdbuf::sort);
 
            m_needsSort = false;
            core::sort(m_ops.begin(), m_ops.end(), [](const Op& a, const Op& b) {
              if (less_op_key(a, b))
                return true;
              if (less_op_key(b, a))
                return false;
              return a.order < b.order;
            });
          }
 
          // Replay batched operations
          Entity lastKey = EntityBad;
          Entity lastResolved = EntityBad;
          auto resolve_cached = [&](Entity e) {
            if (e == lastKey)
              return lastResolved;
            lastKey = e;
            return lastResolved = resolve(e);
          };
 
          cnt::darray_ext<Entity, 16> deleteTargets;
          {
            GAIA_PROF_SCOPE(cmdbuf::merges);
            for (uint32_t p = 0; p < m_ops.size();) {
              GAIA_PROF_SCOPE(cmdbuf::merge);
 
              const Entity tgtKey = m_ops[p].target;
 
              const bool tgtIsTemp = is_tmp(tgtKey);
              const uint32_t ti = tgtIsTemp ? tgtKey.id() : 0u;
              const Entity tgtReal =
                  tgtIsTemp ? (ti < m_temp2real.size() ? m_temp2real[ti] : EntityBad) : resolve_cached(tgtKey);
 
              // Range for this target
              uint32_t q = p;
              bool hasDelEntity = false;
              while (q < m_ops.size() && m_ops[q].target == tgtKey) {
                if (m_ops[q].type == OpType::DEL_ENTITY)
                  hasDelEntity = true;
                ++q;
              }
 
              // Skip canceled or non-existent temporary entities
              if (tgtReal == EntityBad) {
                p = q;
                continue;
              }
              if (tgtIsTemp && is_canceled_temp(ti)) {
                p = q;
                continue;
              }
 
              if GAIA_UNLIKELY (m_ops[p].other != m_ops[q - 1].other &&
                  (m_ops[p].type != OpType::SET_COMPONENT || m_ops[q - 1].type != OpType::SET_COMPONENT) &&
                  replay_batch(p, q, tgtReal) && p == q) {
                if (hasDelEntity)
                  deleteTargets.push_back(tgtReal);
                p = q;
                continue;
              }
 
              // Emit relation groups.
              // Inside [p..q) range (same target), process groups by 'other'.
              // We perform per-component reduction.
              for (uint32_t i = p; i < q;) {
                const Entity othKey = m_ops[i].other;
                const Entity pairTargetKey = m_ops[i].pairTarget;
                const Entity othReal = resolve_object(m_ops[i]);
 
                // Group ops with same (target, other)
                uint32_t j = i + 1;
                while (j < q && m_ops[j].other == othKey && m_ops[j].pairTarget == pairTargetKey)
                  ++j;
 
                if (tgtReal != EntityBad) {
                  const uint32_t groupSize = j - i;
                  // Fast path - single op
                  if (groupSize == 1) {
                    replay_op(m_ops[i], tgtReal, othReal);
                  }
                  // Slow path: merge multiple ops
                  else {
                    uint8_t mask = 0;
                    uint32_t dataPos = 0;
 
                    for (uint32_t k = i; k < j; ++k) {
                      const Op& op = m_ops[k];
                      switch (op.type) {
                        case OpType::ADD_COMPONENT:
                          mask |= F_ADD;
                          break;
                        case OpType::ADD_COMPONENT_DATA:
                          mask |= F_ADD_DATA;
                          dataPos = op.off;
                          break;
                        case OpType::SET_COMPONENT:
                          mask |= F_SET;
                          dataPos = op.off;
                          break;
                        case OpType::DEL_COMPONENT:
                          // A delete discards payloads from the preceding component lifetime.
                          mask = F_DEL;
                          break;
                        default:
                          break;
                      }
                    }
 
                    const bool hasAdd = mask & F_ADD;
                    const bool hasAddData = mask & F_ADD_DATA;
                    const bool hasSet = mask & F_SET;
                    const bool hasDel = mask & F_DEL;
 
                    // 1) DEL present: reduce the surviving component lifetime.
                    // Replay in order when World policies or observable side effects require it.
                    if (hasDel) {
                      replay_merged(i, j, tgtReal, othReal, mask, dataPos);
                    }
                    // 2) ADD_WITH_DATA or ADD+SET = ADD_WITH_DATA
                    else if (hasAddData || (hasAdd && hasSet)) {
                      replay_add_data(tgtReal, othReal, dataPos);
                    }
                    // 3) ADD only
                    else if (hasAdd) {
                      replay_add(tgtReal, othReal);
                    }
                    // 4) SET only
                    else if (hasSet) {
                      replay_data(tgtReal, othReal, dataPos);
                    }
                  }
                }
 
                // Advance to next component group
                i = j;
              }
 
              // Apply deletions after every relationship operation so sorting target groups cannot
              // invalidate an endpoint that a later group still needs to resolve.
              if (hasDelEntity)
                deleteTargets.push_back(tgtReal);
 
              // Advance to next target group
              p = q;
            }
          }
          for (auto entity: deleteTargets) {
            if (m_world.valid(entity))
              m_world.del(entity);
          }
        }
      };
    } // namespace detail
 
    using CommandBufferST = detail::CommandBuffer<AccessContextST>;
    using CommandBufferMT = detail::CommandBuffer<AccessContextMT>;
    using CommandBufferPlainST = detail::CommandBuffer<AccessContextST, false>;
    using CommandBufferPlainMT = detail::CommandBuffer<AccessContextMT, false>;
 
    inline CommandBufferST* cmd_buffer_st_create(World& world) {
      return new CommandBufferST(world);
    }
    inline void cmd_buffer_destroy(CommandBufferST& cmdBuffer) {
      delete &cmdBuffer;
    }
    inline void cmd_buffer_commit(CommandBufferST& cmdBuffer) {
      cmdBuffer.commit();
    }
 
    inline CommandBufferMT* cmd_buffer_mt_create(World& world) {
      return new CommandBufferMT(world);
    }
    inline void cmd_buffer_destroy(CommandBufferMT& cmdBuffer) {
      delete &cmdBuffer;
    }
    inline void cmd_buffer_commit(CommandBufferMT& cmdBuffer) {
      cmdBuffer.commit();
    }
  } // namespace ecs
} // namespace gaia