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
SceneSerializerwalks 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.
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(...)
}
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
- Declare the struct in
Components.hwith default values. - Give it an
Encode/Decodepair inComponentSerializers.h(each key read with a fallback, so an older file still loads). - Add one line to
SceneComponentRegistry()inSceneSerializer.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 (EditorAPIGetComponent/SetComponentField). - Optionally, a hand-made inspector card in
editor/src/panels/ComponentInspector*.cpp. - 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
GameObjectz 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
TransformComponentjest 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;
SceneSerializerprzechodzi 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.
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(...)
}
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
- Zadeklaruj strukturę w
Components.hz wartościami domyślnymi. - Daj jej parę
Encode/DecodewComponentSerializers.h(każdy klucz czytany z wartością zastępczą, żeby starszy plik dalej się wczytywał). - Dodaj jedną linijkę do
SceneComponentRegistry()wSceneSerializer.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 (EditorAPIGetComponent/SetComponentField). - Opcjonalnie: ręcznie zrobiona karta inspektora w
editor/src/panels/ComponentInspector*.cpp. - 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.