Ограничения и подводные камни

Производительность

• tc_scene_find_entity_by_name — линейный поиск по всем сущностям. Для частых lookup-ов стоит кэшировать результат или использовать UUID.
• tc_scene_count_components_of_type — линейный проход по intrusive list типа.
• Итерации по сцене и сущностям в основном O(n) по текущему набору.

Fail-soft vs Fail-fast

Большинство функций работают в fail-soft режиме: на невалидном handle/id возвращают NULL, 0 или INVALID, выполняют no-op.

Если нужен fail-fast в debug-сборке, добавляйте assert-ы на уровне вызывающего кода. Core намеренно не аварийно завершается на невалидных входах.

Типы и итерации компонентов

• Type-based итерации завязаны на type_name и записи в component registry. Строковое совпадение должно быть точным.
• Во внутренних буферах для некоторых type-итераций используются массивы ограниченного размера (64).

Слои и фильтры

• В tc_scene_foreach_drawable layer mask трактуется как битовая маска слоёв.
• Поле слоя сущности проверяется как индекс бита. При собственной системе слоёв это нужно учитывать явно: слой 3 = бит 1 << 3, а не число 3.

Миграции сущностей

• tc_entity_pool_migrate переносит компоненты transfer-ом владения, а не копированием. После миграции исходные handle становятся невалидными.
• Корневая сущность при миграции в другой pool становится root; дети переносятся рекурсивно.

SoA-реестр

• SoA type registry глобальный (singleton) на процесс. Идентификаторы SoA-типов имеют runtime-характер и не должны рассматриваться как стабильный ABI.
• Максимум TC_SOA_MAX_TYPES = 64 зарегистрированных SoA-типов.

Иерархия

• API установки parent не выполняет проверку на циклы. Корректность дерева (отсутствие циклов) должен обеспечивать вызывающий код.

Generational handles

• После free generation увеличивается. Старые handle/id становятся невалидными, даже если тот же index переиспользован.
• Не сохраняйте handle между кадрами без проверки alive().