component_cache.h

#pragma once
#include "gaia/config/config.h"
 
#include <cinttypes>
#include <cstdint>
#include <cstring>
#include <type_traits>
 
#include "gaia/cnt/map.h"
#include "gaia/core/hashing_string.h"
#include "gaia/ecs/component.h"
#include "gaia/ecs/component_cache_item.h"
#include "gaia/ecs/component_desc.h"
#include "gaia/ecs/id.h"
#include "gaia/meta/type_info.h"
#include "gaia/util/logging.h"
#include "gaia/util/str.h"
 
namespace gaia {
  namespace ecs {
    class World;
 
    class GAIA_API ComponentCache final {
      friend class World;
 
      struct ResolvedLookupEntry {
        const ComponentCacheItem* pItem = nullptr;
        uint32_t matches = 0;
      };
 
      cnt::map<uint32_t, const ComponentCacheItem*> m_compByEntityId;
      SymbolTable m_symbols;
      cnt::map<ComponentLookupHash, const ComponentCacheItem*> m_compByTypeHash;
 
      cnt::map<ComponentCacheItem::SymbolLookupKey, const ComponentCacheItem*> m_compBySymbol;
      cnt::map<ComponentCacheItem::SymbolLookupKey, ResolvedLookupEntry> m_compByPath;
      cnt::map<ComponentCacheItem::SymbolLookupKey, ResolvedLookupEntry> m_compByShortSymbol;
 
      void clear() {
        m_compByTypeHash.clear();
        m_compBySymbol.clear();
        m_compByPath.clear();
        m_compByShortSymbol.clear();
 
        for (auto [entityId, pItem]: m_compByEntityId) {
          (void)entityId;
          ComponentCacheItem::destroy(const_cast<ComponentCacheItem*>(pItem));
        }
 
        m_compByEntityId.clear();
        m_symbols.clear();
      }
 
      GAIA_NODISCARD static bool is_internal_symbol(util::str_view symbol) noexcept {
        constexpr char InternalPrefix[] = "gaia::ecs::";
        constexpr uint32_t InternalPrefixLen = (uint32_t)(sizeof(InternalPrefix) - 1);
        return symbol.size() >= InternalPrefixLen && memcmp(symbol.data(), InternalPrefix, InternalPrefixLen) == 0;
      }
 
      static ComponentCacheItem::SymbolLookupKey short_name_key(const ComponentCacheItem& item) noexcept {
        const auto symbol = item.symbol_name();
        const auto* pName = symbol.data();
        const auto len = symbol.size();
        for (uint32_t i = len; i > 1; --i) {
          const auto idx = i - 1;
          if (pName[idx] != ':' || pName[idx - 1] != ':')
            continue;
 
          return ComponentCacheItem::SymbolLookupKey(pName + idx + 1, len - idx - 1, 0);
        }
 
        return ComponentCacheItem::SymbolLookupKey();
      }
 
      GAIA_NODISCARD static util::str_view short_symbol_view(const ComponentCacheItem& item) noexcept {
        const auto symbol = item.symbol_name();
        if (is_internal_symbol(symbol))
          return {};
 
        const auto shortName = short_name_key(item);
        if (shortName.str() == nullptr || shortName.len() == 0)
          return {};
 
        return util::str_view(shortName.str(), shortName.len());
      }
 
      GAIA_NODISCARD static ComponentCacheItem::SymbolLookupKey lookup_key(util::str_view value) noexcept {
        return value.empty() ? ComponentCacheItem::SymbolLookupKey()
                             : ComponentCacheItem::SymbolLookupKey(value.data(), value.size(), 0);
      }
 
      GAIA_NODISCARD static util::str_view normalize_name_view(const char* name, uint32_t len = 0) noexcept {
        if (name == nullptr)
          return {};
 
        const auto l = len == 0 ? (uint32_t)GAIA_STRLEN(name, ComponentCacheItem::MaxNameLength) : len;
        GAIA_ASSERT(l < ComponentCacheItem::MaxNameLength);
        return util::str_view(name, l);
      }
 
#if GAIA_ASSERT_ENABLED
      void validate_runtime_type(const ecs::ComponentDesc& desc) const noexcept {
        const auto& runtimeType = desc.runtimeType;
        ser::serialization_type_id type = ser::serialization_type_id::ignore;
        if (runtimeType.typeKind == RuntimeTypeKind::Enum || runtimeType.typeKind == RuntimeTypeKind::Bitmask) {
          GAIA_ASSERT(runtime_primitive_serialization_type(runtimeType.underlyingType, type));
          GAIA_ASSERT(runtimeType.elementType == EntityBad);
          GAIA_ASSERT(runtimeType.elementCount == 0);
          GAIA_ASSERT(runtimeType.opaqueAsType == EntityBad);
          return;
        }
 
        if (runtimeType.typeKind == RuntimeTypeKind::Array) {
          GAIA_ASSERT(runtimeType.underlyingType == EntityBad);
          GAIA_ASSERT(runtimeType.elementType != EntityBad);
          GAIA_ASSERT(runtimeType.elementCount > 0);
          GAIA_ASSERT(runtimeType.fields == nullptr);
          GAIA_ASSERT(runtimeType.fieldCount == 0);
          GAIA_ASSERT(runtimeType.constants == nullptr);
          GAIA_ASSERT(runtimeType.constantCount == 0);
          GAIA_ASSERT(runtimeType.opaqueAsType == EntityBad);
          const auto* pElementType = find(runtimeType.elementType);
          GAIA_ASSERT(pElementType != nullptr);
          const auto elementSize = pElementType != nullptr ? pElementType->comp.size() : 0;
          const auto elementAlignment = pElementType != nullptr ? pElementType->comp.alig() : 0;
          GAIA_ASSERT(elementSize > 0);
          if (elementSize > 0) {
            GAIA_ASSERT(runtimeType.elementCount <= UINT32_MAX / elementSize);
            GAIA_ASSERT(desc.size == elementSize * runtimeType.elementCount);
          }
          GAIA_ASSERT(desc.alig == elementAlignment);
          return;
        }
 
        if (runtimeType.typeKind == RuntimeTypeKind::Vector) {
          GAIA_ASSERT(runtimeType.underlyingType == EntityBad);
          GAIA_ASSERT(runtimeType.elementType != EntityBad);
          GAIA_ASSERT(runtimeType.elementCount == 0);
          GAIA_ASSERT(runtimeType.fields == nullptr);
          GAIA_ASSERT(runtimeType.fieldCount == 0);
          GAIA_ASSERT(runtimeType.constants == nullptr);
          GAIA_ASSERT(runtimeType.constantCount == 0);
          GAIA_ASSERT(runtimeType.opaqueAsType == EntityBad);
          if (runtimeType.sequenceAdapter == nullptr) {
            GAIA_ASSERT(desc.size == 0);
            GAIA_ASSERT(desc.soa == 0);
          } else {
            GAIA_ASSERT(runtimeType.sequenceAdapter->count != nullptr);
            GAIA_ASSERT(runtimeType.sequenceAdapter->element != nullptr);
          }
          GAIA_ASSERT(find(runtimeType.elementType) != nullptr);
  #if GAIA_JSON_ENABLED
          GAIA_ASSERT(runtimeType.jsonEncoding != RuntimeJsonEncoding::Utf8String || runtimeType.elementType == Char8);
  #endif
          return;
        }
  #if GAIA_JSON_ENABLED
        GAIA_ASSERT(runtimeType.jsonEncoding == RuntimeJsonEncoding::Default);
  #endif
 
        if (runtimeType.typeKind == RuntimeTypeKind::Opaque) {
          GAIA_ASSERT(runtimeType.underlyingType == EntityBad);
          GAIA_ASSERT(runtimeType.elementType == EntityBad);
          GAIA_ASSERT(runtimeType.elementCount == 0);
          GAIA_ASSERT(runtimeType.fields == nullptr);
          GAIA_ASSERT(runtimeType.fieldCount == 0);
          GAIA_ASSERT(runtimeType.constants == nullptr);
          GAIA_ASSERT(runtimeType.constantCount == 0);
          GAIA_ASSERT(runtimeType.opaqueAsType != EntityBad);
          if (runtimeType.opaqueAdapter != nullptr)
            GAIA_ASSERT(runtimeType.opaqueAdapter->project != nullptr);
          GAIA_ASSERT(find(runtimeType.opaqueAsType) != nullptr);
          return;
        }
 
        GAIA_ASSERT(runtimeType.underlyingType == EntityBad);
        GAIA_ASSERT(runtimeType.elementType == EntityBad);
        GAIA_ASSERT(runtimeType.elementCount == 0);
        GAIA_ASSERT(runtimeType.opaqueAsType == EntityBad);
        GAIA_ASSERT(runtimeType.sequenceAdapter == nullptr);
        GAIA_ASSERT(runtimeType.opaqueAdapter == nullptr);
      }
 
      void validate_runtime_fields(const ecs::ComponentDesc& desc) const noexcept {
        const auto& runtimeType = desc.runtimeType;
        if (runtimeType.fieldCount == 0)
          return;
 
        GAIA_ASSERT(runtimeType.fields != nullptr);
        if (runtimeType.fields == nullptr)
          return;
 
        GAIA_FOR(runtimeType.fieldCount) {
          const auto& field = runtimeType.fields[i];
          GAIA_ASSERT(!field.name.empty());
          GAIA_ASSERT(field.name.size() < ComponentCacheItem::MaxNameLength);
          GAIA_ASSERT(field.unit.size() < RuntimeFieldDesc::MaxUnitLength);
          GAIA_ASSERT(field.type != EntityBad);
          GAIA_ASSERT(
              (field.flags & (RuntimeFieldFlag_HasMinimum | RuntimeFieldFlag_HasMaximum)) !=
                  (RuntimeFieldFlag_HasMinimum | RuntimeFieldFlag_HasMaximum) ||
              field.minimum <= field.maximum);
          GAIA_ASSERT((field.flags & RuntimeFieldFlag_HasStep) == 0 || field.step > 0.0);
  #if GAIA_JSON_ENABLED
          GAIA_ASSERT(
              field.jsonEncoding != RuntimeJsonEncoding::Utf8String || (field.type == Char8 && field.count != 0));
  #endif
 
          const auto* pType = find(field.type);
          GAIA_ASSERT(pType != nullptr);
          GAIA_ASSERT(pType == nullptr || pType->typeKind != RuntimeTypeKind::Array || field.count == 0);
          const auto elementSize = pType != nullptr ? pType->comp.size() : 0;
          GAIA_ASSERT(elementSize > 0);
          const auto elementCount = ComponentCacheItem::field_element_count(field);
          GAIA_ASSERT(elementCount > 0);
          GAIA_ASSERT(field.offset <= desc.size);
          const auto availableSize = field.offset <= desc.size ? desc.size - field.offset : 0;
          GAIA_ASSERT(elementSize <= availableSize);
          GAIA_ASSERT(elementCount <= availableSize / elementSize);
 
          GAIA_FOR2_(i + 1, runtimeType.fieldCount, otherIdx) {
            const auto& other = runtimeType.fields[otherIdx];
            const bool sameLen = field.name.size() == other.name.size();
            const bool sameName = sameLen && field.name.data() != nullptr && other.name.data() != nullptr &&
                                  strncmp(field.name.data(), other.name.data(), field.name.size()) == 0;
            GAIA_ASSERT(!sameName);
          }
        }
      }
 
      static void validate_runtime_constants(const ecs::ComponentDesc& desc) noexcept {
        const auto& runtimeType = desc.runtimeType;
        if (runtimeType.constantCount == 0)
          return;
 
        GAIA_ASSERT(runtimeType.typeKind == RuntimeTypeKind::Enum || runtimeType.typeKind == RuntimeTypeKind::Bitmask);
        GAIA_ASSERT(runtimeType.constants != nullptr);
        if (runtimeType.constants == nullptr)
          return;
 
        GAIA_FOR(runtimeType.constantCount) {
          const auto& constant = runtimeType.constants[i];
          GAIA_ASSERT(!constant.name.empty());
          GAIA_ASSERT(constant.name.size() < ComponentCacheItem::MaxNameLength);
 
          GAIA_FOR2_(i + 1, runtimeType.constantCount, otherIdx) {
            const auto& other = runtimeType.constants[otherIdx];
            const bool sameLen = constant.name.size() == other.name.size();
            const bool sameName = sameLen && constant.name.data() != nullptr && other.name.data() != nullptr &&
                                  strncmp(constant.name.data(), other.name.data(), constant.name.size()) == 0;
            GAIA_ASSERT(!sameName);
            GAIA_ASSERT(constant.value != other.value);
          }
        }
      }
 
      void
      validate_typed_runtime_type(const ComponentCacheItem& item, const RuntimeTypeDesc& runtimeType) const noexcept {
        ecs::ComponentDesc desc{};
        desc.size = item.comp.size();
        desc.alig = item.comp.alig();
        desc.storageType = item.comp.storage_type();
        desc.soa = item.comp.soa();
        desc.pSoaSizes = item.soaSizes;
        desc.runtimeType = runtimeType;
        validate_runtime_type(desc);
        validate_runtime_fields(desc);
        validate_runtime_constants(desc);
      }
#endif
 
      static bool build_default_path(util::str& out, util::str_view symbol) {
        out.clear();
        bool changed = false;
        out.reserve(symbol.size());
        for (uint32_t i = 0; i < symbol.size(); ++i) {
          if (i + 1 < symbol.size() && symbol.data()[i] == ':' && symbol.data()[i + 1] == ':') {
            out.append('.');
            ++i;
            changed = true;
            continue;
          }
 
          out.append(symbol.data()[i]);
        }
 
        if (!changed)
          out.clear();
 
        return changed;
      }
 
      static bool build_scoped_path(util::str& out, util::str_view scopePath, util::str_view leaf) {
        out.clear();
        if (scopePath.empty() || leaf.empty())
          return false;
 
        out.reserve(scopePath.size() + 1 + leaf.size());
        out.append(scopePath);
        out.append('.');
        out.append(leaf);
        return true;
      }
 
      static void initialize_names(ComponentCacheItem& item, util::str_view scopePath = {}) {
        item.path.clear();
        const auto symbol = item.symbol_name();
        if (is_internal_symbol(symbol))
          return;
 
        const auto shortName = short_name_key(item);
        const bool hasShortName =
            shortName.str() != nullptr && shortName.len() != 0 && shortName.len() != symbol.size();
        const auto leaf = hasShortName ? util::str_view{shortName.str(), shortName.len()} : symbol;
 
        if (!build_scoped_path(item.path, scopePath, leaf))
          (void)build_default_path(item.path, symbol);
      }
 
      static void add_lookup_mapping(
          cnt::map<ComponentCacheItem::SymbolLookupKey, ResolvedLookupEntry>& map, util::str_view view,
          const ComponentCacheItem& item) {
        if (view.empty())
          return;
 
        const auto key = lookup_key(view);
        const auto it = map.find(key);
        if (it == map.end()) {
          map.emplace(key, ResolvedLookupEntry{&item, 1});
          return;
        }
 
        auto& entry = it->second;
        GAIA_ASSERT(entry.matches != 0);
        ++entry.matches;
      }
 
      void add_path_mapping(const ComponentCacheItem& item) {
        add_lookup_mapping(m_compByPath, item.path.view(), item);
      }
 
      static void push_unique_entity(cnt::darray<Entity>& out, Entity entity) {
        if (entity == EntityBad)
          return;
 
        for (const auto existing: out) {
          if (existing == entity)
            return;
        }
 
        out.push_back(entity);
      }
 
      void remove_path_mapping(const ComponentCacheItem& item) {
        const auto pathValue = item.path.view();
        if (pathValue.empty())
          return;
 
        const auto key = lookup_key(pathValue);
        const auto it = m_compByPath.find(key);
        if (it == m_compByPath.end())
          return;
 
        auto& entry = it->second;
        GAIA_ASSERT(entry.matches != 0);
 
        if (entry.matches == 1) {
          GAIA_ASSERT(entry.pItem == &item);
          m_compByPath.erase(it);
          return;
        }
 
        const auto remainingMatches = entry.matches - 1;
        if (entry.pItem != &item) {
          entry.matches = remainingMatches;
          return;
        }
 
        const ComponentCacheItem* pReplacement = nullptr;
        for (const auto& [entityId, pItem]: m_compByEntityId) {
          (void)entityId;
          GAIA_ASSERT(pItem != nullptr);
          if (pItem == &item)
            continue;
 
          if (pItem->path.view() != pathValue)
            continue;
 
          pReplacement = pItem;
          break;
        }
 
        GAIA_ASSERT(pReplacement != nullptr);
        // The map key borrows the representative path storage, so replace it before the old path changes.
        m_compByPath.erase(it);
        if (pReplacement != nullptr)
          m_compByPath.emplace(
              lookup_key(pReplacement->path.view()), ResolvedLookupEntry{pReplacement, remainingMatches});
      }
 
      void add_name_mappings(ComponentCacheItem& item, util::str_view scopePath) {
        m_compBySymbol.emplace(lookup_key(item.symbol_name()), &item);
        initialize_names(item, scopePath);
        add_path_mapping(item);
        add_lookup_mapping(m_compByShortSymbol, short_symbol_view(item), item);
      }
 
      ComponentCacheItem& add_item(const ComponentCacheItem* pItem, util::str_view scopePath) {
        GAIA_ASSERT(pItem != nullptr);
        GAIA_ASSERT(pItem->entity.id() == pItem->comp.id());
        m_compByEntityId.emplace(pItem->entity.id(), pItem);
 
        auto& item = *const_cast<ComponentCacheItem*>(pItem);
        item.m_ownerCache = this;
        add_name_mappings(item, scopePath);
        return item;
      }
 
      GAIA_NODISCARD const ComponentCacheItem* find_item(ComponentLookupHash hash) const noexcept {
        const auto it = m_compByTypeHash.find(hash);
        return it != m_compByTypeHash.end() ? it->second : nullptr;
      }
 
      template <typename T>
      void add_hash_mapping(const ComponentCacheItem& item) {
        const auto hash = detail::ComponentDesc<T>::hash_lookup();
        const auto it = m_compByTypeHash.find(hash);
        if (it == m_compByTypeHash.end()) {
          m_compByTypeHash.emplace(hash, &item);
          return;
        }
 
        GAIA_ASSERT(it->second == &item);
      }
 
    public:
      ComponentCache() = default;
 
      ~ComponentCache() {
        clear();
      }
 
      ComponentCache(ComponentCache&&) = delete;
      ComponentCache(const ComponentCache&) = delete;
      ComponentCache& operator=(ComponentCache&&) = delete;
      ComponentCache& operator=(const ComponentCache&) = delete;
 
      template <typename T>
      GAIA_NODISCARD GAIA_FORCEINLINE const ComponentCacheItem& add(Entity entity, util::str_view scopePath = {}) {
        static_assert(!is_pair<T>::value);
        GAIA_ASSERT(!entity.pair());
 
        const auto* pItem = find_item(detail::ComponentDesc<T>::hash_lookup());
        if (pItem != nullptr)
          return *pItem;
 
        const auto* pNewItem = ComponentCacheItem::create<T>(entity, m_symbols);
        GAIA_ASSERT(entity.id() == pNewItem->comp.id());
        const auto& item = add_item(pNewItem, scopePath);
        add_hash_mapping<T>(item);
        return item;
      }
 
      template <typename T>
      GAIA_NODISCARD GAIA_FORCEINLINE const ComponentCacheItem&
      add(Entity entity, const RuntimeTypeDesc& runtimeType, util::str_view scopePath = {}) {
        static_assert(!is_pair<T>::value);
        GAIA_ASSERT(!entity.pair());
 
        const auto* pItem = find_item(detail::ComponentDesc<T>::hash_lookup());
        if (pItem != nullptr)
          return *pItem;
 
        const auto* pNewItem = ComponentCacheItem::create<T>(entity, m_symbols, runtimeType);
        GAIA_ASSERT(entity.id() == pNewItem->comp.id());
#if GAIA_ASSERT_ENABLED
        validate_typed_runtime_type(*pNewItem, runtimeType);
#endif
        const auto& item = add_item(pNewItem, scopePath);
        add_hash_mapping<T>(item);
        return item;
      }
 
      GAIA_NODISCARD ComponentCacheItem&
      add(Entity entity, const ecs::ComponentDesc& desc, util::str_view scopePath = {}) {
        GAIA_ASSERT(entity != EntityBad);
        GAIA_ASSERT(!entity.pair());
        GAIA_ASSERT(!desc.name.empty());
        GAIA_ASSERT(desc.name.size() < ComponentCacheItem::MaxNameLength);
 
        {
          const auto* pExisting = symbol(desc.name);
          if (pExisting != nullptr)
            return *find(pExisting->entity);
        }
 
#if GAIA_ASSERT_ENABLED
        validate_runtime_type(desc);
        validate_runtime_fields(desc);
        validate_runtime_constants(desc);
#endif
 
        const auto* pItem = ComponentCacheItem::create(entity, m_symbols, desc);
        GAIA_ASSERT(entity.id() == pItem->comp.id());
        return add_item(pItem, scopePath);
      }
 
      GAIA_NODISCARD const ComponentCacheItem* find(Entity entity) const noexcept {
        if (entity.pair())
          return nullptr;
 
        const auto it = m_compByEntityId.find(entity.id());
        return it != m_compByEntityId.end() ? it->second : nullptr;
      }
 
      GAIA_NODISCARD const ComponentCacheItem* find_pair_payload(Entity pair) const noexcept {
        if (!pair.pair())
          return nullptr;
 
        const auto relationIt = m_compByEntityId.find(pair.id());
        const auto* pRelation = relationIt != m_compByEntityId.end() ? relationIt->second : nullptr;
        if (pRelation != nullptr && pRelation->comp.size() != 0U)
          return pRelation;
 
        const auto targetIt = m_compByEntityId.find(pair.gen());
        const auto* pTarget = targetIt != m_compByEntityId.end() ? targetIt->second : nullptr;
        return pTarget != nullptr && pTarget->comp.size() != 0U ? pTarget : pRelation;
      }
 
      GAIA_NODISCARD ComponentCacheItem* find(Entity entity) noexcept {
        return const_cast<ComponentCacheItem*>(const_cast<const ComponentCache*>(this)->find(entity));
      }
 
      GAIA_NODISCARD const ComponentCacheItem& get(Entity entity) const noexcept {
        GAIA_ASSERT(!entity.pair());
        const auto* pItem = find(entity);
        GAIA_ASSERT(pItem != nullptr);
        return *pItem;
      }
 
      GAIA_NODISCARD ComponentCacheItem& get(Entity entity) noexcept {
        auto* pItem = find(entity);
        GAIA_ASSERT(pItem != nullptr);
        return *pItem;
      }
 
    private:
      GAIA_NODISCARD util::str_view symbol_name(const ComponentCacheItem& item) const noexcept {
        return item.symbol_name();
      }
 
      GAIA_NODISCARD util::str_view path_name(const ComponentCacheItem& item) const noexcept {
        return item.path.view();
      }
 
      bool path(ComponentCacheItem& item, util::str_view name) noexcept {
        if (path_name(item) == name)
          return true;
 
        if (name.empty()) {
          remove_path_mapping(item);
          item.path.clear();
          return true;
        }
 
        if (name.size() >= ComponentCacheItem::MaxNameLength)
          return false;
 
        remove_path_mapping(item);
        item.path.assign(name);
        add_path_mapping(item);
        return true;
      }
 
      bool path(ComponentCacheItem& item, const char* name, uint32_t len = 0) noexcept {
        return path(item, normalize_name_view(name, len));
      }
 
      GAIA_NODISCARD const ComponentCacheItem* symbol(util::str_view name) const noexcept {
        GAIA_ASSERT(name.size() < ComponentCacheItem::MaxNameLength);
        const auto it = m_compBySymbol.find(lookup_key(name));
        return it != m_compBySymbol.end() ? it->second : nullptr;
      }
 
      GAIA_NODISCARD const ComponentCacheItem* symbol(const char* name, uint32_t len = 0) const noexcept {
        GAIA_ASSERT(name != nullptr);
        return symbol(normalize_name_view(name, len));
      }
 
      GAIA_NODISCARD const ComponentCacheItem* path(util::str_view name) const noexcept {
        GAIA_ASSERT(name.size() < ComponentCacheItem::MaxNameLength);
        const auto it = m_compByPath.find(lookup_key(name));
        if (it == m_compByPath.end())
          return nullptr;
 
        return it->second.matches == 1 ? it->second.pItem : nullptr;
      }
 
      GAIA_NODISCARD const ComponentCacheItem* path(const char* name, uint32_t len = 0) const noexcept {
        GAIA_ASSERT(name != nullptr);
        return path(normalize_name_view(name, len));
      }
 
      GAIA_NODISCARD const ComponentCacheItem* short_symbol(util::str_view name) const noexcept {
        GAIA_ASSERT(name.size() < ComponentCacheItem::MaxNameLength);
        const auto it = m_compByShortSymbol.find(lookup_key(name));
        if (it == m_compByShortSymbol.end())
          return nullptr;
 
        return it->second.matches == 1 ? it->second.pItem : nullptr;
      }
 
      GAIA_NODISCARD const ComponentCacheItem* short_symbol(const char* name, uint32_t len = 0) const noexcept {
        GAIA_ASSERT(name != nullptr);
        return short_symbol(normalize_name_view(name, len));
      }
 
      void add_path_matches(cnt::darray<Entity>& out, util::str_view name) const {
        if (name.empty())
          return;
 
        const auto it = m_compByPath.find(lookup_key(name));
        if (it == m_compByPath.end())
          return;
 
        const auto& entry = it->second;
        GAIA_ASSERT(entry.matches != 0);
 
        if (entry.matches == 1) {
          GAIA_ASSERT(entry.pItem != nullptr);
          push_unique_entity(out, entry.pItem->entity);
          return;
        }
 
        for (const auto& [entityId, pItem]: m_compByEntityId) {
          (void)entityId;
          GAIA_ASSERT(pItem != nullptr);
          if (pItem->path.view() == name)
            push_unique_entity(out, pItem->entity);
        }
      }
 
    public:
      template <typename T>
      GAIA_NODISCARD const ComponentCacheItem* find() const noexcept {
        static_assert(!is_pair<T>::value);
        return find_item(detail::ComponentDesc<T>::hash_lookup());
      }
 
      template <typename T>
      GAIA_NODISCARD const ComponentCacheItem& get() const noexcept {
        static_assert(!is_pair<T>::value);
        const auto* pItem = find<T>();
        GAIA_ASSERT(pItem != nullptr);
        return *pItem;
      }
 
#if GAIA_ENABLE_HOOKS
 
      static ComponentCacheItem::Hooks& hooks(const ComponentCacheItem& cacheItem) noexcept {
        return const_cast<ComponentCacheItem&>(cacheItem).hooks();
      }
 
#endif
 
      void diag() const {
        const auto registeredTypes = m_compByEntityId.size();
        GAIA_LOG_N("Registered components: %u", registeredTypes);
 
        auto logDesc = [](const ComponentCacheItem& item) {
          const auto symbol = item.symbol_name();
          GAIA_LOG_N(
              "    hash:%016" PRIx64 ", size:%3u B, align:%3u B, [%u:%u] %.*s [%s]", item.hashLookup.hash,
              item.comp.size(), item.comp.alig(), item.entity.id(), item.entity.gen(), (int)symbol.size(),
              symbol.data(), EntityKindString[item.entity.kind()]);
        };
        for (const auto& [entityId, pItem]: m_compByEntityId) {
          (void)entityId;
          GAIA_ASSERT(pItem != nullptr);
          logDesc(*pItem);
        }
      }
    };
  } // namespace ecs
} // namespace gaia