Entity–Component–System (ECS)

Thread uses EnTT as its ECS backbone. ECS is the data layout that organises everything in a Thread scene:

  • Entity — a 32-bit ID with no data of its own. Equivalent to Unity's GameObject, but stripped down to just an ID.
  • Component — a plain data struct (POD-ish). Each component type has its own packed array inside the registry. Equivalent to fields on a Unity Component, except the data lives in a giant per-type array.
  • System — code that iterates entities matching some set of components and acts on them. The renderer, physics, audio, scripts — all of them are "systems" in this sense.

Why ECS

  • Cache-friendly iteration — components of the same type are contiguous in memory, so a loop over all TransformComponents is fast.
  • Composition over inheritance — an entity is "whatever components are on it". Adding capabilities to an existing entity = add a component.
  • Trivial serialization — each component is a struct; the SceneSerializer walks them generically.

The registry

Every Scene owns one entt::registry. The registry is the database: it allocates entity IDs, stores per-type component arrays ("storages"), and provides views to iterate matching entities.

// inside Scene.h: entt::registry m_Registry;

Creating an entity

Thread::Entity e = scene->CreateEntity("Crate");
e.AddComponent<Thread::PrimitiveComponent>(Thread::PrimitiveType::Cube);
e.AddComponent<Thread::RigidBodyComponent>().Mass = 5.0f;
e.AddComponent<Thread::BoxColliderComponent>();

Scene::CreateEntity always attaches three components automatically: IDComponent (random UUID), TransformComponent (T/R/S), and TagComponent (the name shown in the Hierarchy panel).

Querying

Systems iterate using views. A view of <A, B> walks every entity that has both A and B:

auto view = m_Registry.view<TransformComponent, MeshComponent>();
for (auto entity : view) {
    auto& tc = view.get<TransformComponent>(entity);
    auto& mc = view.get<MeshComponent>(entity);
    // draw mc.MeshData at tc.GetWorldTransform(...)
}
Iteration order: EnTT views walk the dense array of the lead component in reverse insertion order. This affects determinism (e.g. the Hierarchy panel display order). The scene serializer compensates by reversing on write so round-trips preserve order.

Components in Thread

Components are plain data structs in the Thread namespace. A few categories:

  • Spatial / hierarchy — TransformComponent, HierarchyComponent.
  • Identity — IDComponent (UUID), TagComponent (name), EnabledComponent.
  • Rendering — MeshComponent, MaterialComponent, PrimitiveComponent, DirectionalLightComponent / PointLightComponent / AmbientLightComponent, CameraComponent, OutlineComponent.
  • Audio — AudioComponent.
  • Physics — RigidBodyComponent, BoxCollider / SphereCollider / CapsuleCollider, CharacterControllerComponent.
  • Terrain — TerrainComponent (also holds a heightfield body at runtime).
  • Scripting — NativeScriptComponent, AutoRotateComponent.

Adding a new component

  1. Declare the struct in Components.h with default values.
  2. Give it an Encode / Decode pair in ComponentSerializers.h (each key read with a fallback, so an older file still loads).
  3. Add one line to SceneComponentRegistry() in SceneSerializer.cpp: MakeEntry<MyComponent>("MyComponent"). That single registration makes it saved and loaded, listed in the inspector's Add Component ▸ All Components, resettable, multi-editable, and reachable by name from editor tools (EditorAPI GetComponent / SetComponentField).
  4. Optionally, a hand-made inspector card in editor/src/panels/ComponentInspector*.cpp.
  5. If the component has runtime resources (AL source, Jolt body, GPU buffer), free them in Scene::Stop*() and on RemoveComponent.

What to read next

The Scene Systems page covers how to wire a per-frame system that operates on many entities at once — useful when the logic is too broad to live inside a single ScriptableEntity.

Encja–Komponent–System (ECS)

Thread używa EnTT jako kręgosłupa ECS. ECS to układ danych, który porządkuje wszystko w scenie Thread:

  • Encja — 32-bitowe ID bez własnych danych. Odpowiednik GameObject z Unity, ale ograniczony do samego ID.
  • Komponent — zwykła struktura danych. Każdy typ komponentu ma w rejestrze własną upakowaną tablicę. Odpowiednik pól komponentu w Unity, tyle że dane leżą w dużej tablicy na typ.
  • System — kod, który przechodzi po encjach z danym zestawem komponentów i na nich działa. Renderer, fizyka, dźwięk, skrypty — wszystkie są „systemami” w tym sensie.

Dlaczego ECS

  • Iteracja przyjazna cache — komponenty jednego typu leżą w pamięci obok siebie, więc pętla po wszystkich TransformComponent jest szybka.
  • Kompozycja zamiast dziedziczenia — encja to „te komponenty, które ma”. Dodanie możliwości istniejącej encji = dodanie komponentu.
  • Prosta serializacja — każdy komponent to struktura; SceneSerializer przechodzi po nich generycznie.

Rejestr

Każda Scene ma jeden entt::registry. Rejestr to baza danych: przydziela ID encji, przechowuje tablice komponentów per typ („storages”) i daje widoki do iterowania po pasujących encjach.

// w Scene.h: entt::registry m_Registry;

Tworzenie encji

Thread::Entity e = scene->CreateEntity("Crate");
e.AddComponent<Thread::PrimitiveComponent>(Thread::PrimitiveType::Cube);
e.AddComponent<Thread::RigidBodyComponent>().Mass = 5.0f;
e.AddComponent<Thread::BoxColliderComponent>();

Scene::CreateEntity zawsze dodaje trzy komponenty: IDComponent (losowy UUID), TransformComponent (T/R/S) i TagComponent (nazwa w panelu Hierarchy).

Zapytania

Systemy iterują przez widoki. Widok <A, B> przechodzi po każdej encji, która ma i A, i B:

auto view = m_Registry.view<TransformComponent, MeshComponent>();
for (auto entity : view) {
    auto& tc = view.get<TransformComponent>(entity);
    auto& mc = view.get<MeshComponent>(entity);
    // narysuj mc.MeshData w tc.GetWorldTransform(...)
}
Kolejność iteracji: widoki EnTT przechodzą gęstą tablicę głównego komponentu w odwrotnej kolejności wstawiania. Wpływa to na determinizm (np. kolejność w panelu Hierarchy). Serializer sceny kompensuje to, odwracając kolejność przy zapisie, więc zapis i odczyt zachowują porządek.

Komponenty w Thread

Komponenty to zwykłe struktury danych w przestrzeni nazw Thread. Kilka kategorii:

  • Przestrzeń / hierarchia — TransformComponent, HierarchyComponent.
  • Tożsamość — IDComponent (UUID), TagComponent (nazwa), EnabledComponent.
  • Renderowanie — MeshComponent, MaterialComponent, PrimitiveComponent, DirectionalLightComponent / PointLightComponent / AmbientLightComponent, CameraComponent, OutlineComponent.
  • Dźwięk — AudioComponent.
  • Fizyka — RigidBodyComponent, BoxCollider / SphereCollider / CapsuleCollider, CharacterControllerComponent.
  • Teren — TerrainComponent (w czasie działania trzyma też ciało heightfield).
  • Skrypty — NativeScriptComponent, AutoRotateComponent.

Dodawanie nowego komponentu

  1. Zadeklaruj strukturę w Components.h z wartościami domyślnymi.
  2. Daj jej parę Encode / Decode w ComponentSerializers.h (każdy klucz czytany z wartością zastępczą, żeby starszy plik dalej się wczytywał).
  3. Dodaj jedną linijkę do SceneComponentRegistry() w SceneSerializer.cpp: MakeEntry<MyComponent>("MyComponent"). Ta jedna rejestracja sprawia, że komponent jest zapisywany i wczytywany, widoczny w Add Component ▸ All Components inspektora, resetowalny, edytowalny na wielu encjach naraz i dostępny po nazwie z narzędzi edytora (EditorAPI GetComponent / SetComponentField).
  4. Opcjonalnie: ręcznie zrobiona karta inspektora w editor/src/panels/ComponentInspector*.cpp.
  5. Jeśli komponent ma zasoby czasu działania (źródło AL, ciało Jolt, bufor GPU), zwolnij je w Scene::Stop*() i przy RemoveComponent.

Co czytać dalej

Strona Systemy sceny opisuje, jak podpiąć system działający co klatkę na wielu encjach naraz — przydatny, gdy logika jest zbyt szeroka, by żyć w jednym ScriptableEntity.