EntityPool class in Thread

Reuse of prefab instances. Despawn does not destroy an entity — it switches it off, takes its physics bodies out of the world and files it under its prefab; the next Spawn of that prefab finds it, moves it and switches it back on. One pool per scene, reached through Scene::Pool().

Entity arrow = GetScene()->Pool().Spawn("assets/prefabs/arrow.prefab", muzzle, aim);
// …later
GetScene()->Pool().Despawn(arrow);

Why

Firing an arrow used to mean reading a file, parsing YAML, creating entities, resolving every asset the prefab names and building a Jolt body — shape, mass properties, a broadphase slot — and then throwing all of it away a second later. The parse is gone already (every path-based instantiation goes through the prefab cache), but the rest is per-spawn work that a pool removes entirely. For anything a survival game does repeatedly — projectiles, dropped items, respawning creatures, hit effects — that is the difference between free and a hitch.

Methods

Spawn(path, position, eulerRotation)EntityA reused instance if one is parked, a fresh one otherwise. Rotation is in radians, matching TransformComponent::Rotation. Returns an invalid Entity if the prefab cannot be loaded.
Despawn(entity)boolParks it. Returns false — and does nothing — for an entity that did not come from Spawn, or one already parked.
Prewarm(path, count)intBuilds instances up front so the first spawn costs what the thousandth does. Returns how many are parked for that prefab afterwards.
Clear()voidDestroys every parked instance. Live ones belong to the game and are left alone.
GetStats()StatsParked, Live, Spawns, Reuses. A pool whose Reuses stays at zero is not pooling anything.

A reused entity is the same entity

This is the part to design around. The pool does not rebuild anything, so a recycled instance keeps its UUID, its components and its script instance — including whatever the last life left in it. The pool restores only what it can honestly claim to own:

  • the world transform of the whole subtree,
  • the enabled state of the whole subtree,
  • linear and angular velocity of every body in it.

Everything else is yours, and ScriptableEntity grew two hooks for it:

class Arrow : public ScriptableEntity {
protected:
    void OnSpawn() override   { m_Stuck = false; m_Age = 0.0f; }
    void OnDespawn() override { /* still live here: drop loot, spawn an effect */ }
};
OnCreate no longer means "appeared". A pooled entity is created once and reused forever, so OnCreate runs on the first arrow and never again. Per-life setup belongs in OnSpawn, which runs every time — including that first one.

Disabled now really means disabled

Parking is built on EnabledComponent, written across the whole subtree. Several systems used not to consult it at all, so an entity with Enabled unticked went on colliding, animating, pathfinding and running its behaviour tree while being invisible. That is fixed, and it applies to the inspector checkbox as much as to the pool: physics (bodies leave the world rather than merely being skipped), animation, navigation agents, behaviour trees and builders now all stop.

The flag is not resolved up the hierarchy on every query. The pool writes it down the whole subtree once, when something is switched off — so a system's test is a single component lookup rather than a walk to the root.

Notes

Parked instances are skipped by world saves: a spare waiting off-stage is not something the player has seen, and restoring one would put a disabled ghost into the world. Pooled instances that are live save like anything else.

Destroying a parked instance with Scene::DestroyEntity is untidy rather than fatal — the pool validates every handle it takes off its free list and drops the dead ones.

Scene::Clear() empties the pool with the registry, so a scene change cannot leave it holding handles into a world that no longer exists.

EntityPool klasa w Thread

Ponowne użycie instancji prefabów. Despawn nie niszczy encji — wyłącza ją, wyjmuje jej ciała fizyczne ze świata i odkłada pod jej prefab; następny Spawn tego prefabu ją znajduje, przestawia i włącza z powrotem. Jedna pula na scenę, dostępna przez Scene::Pool().

Entity arrow = GetScene()->Pool().Spawn("assets/prefabs/arrow.prefab", muzzle, aim);
// …później
GetScene()->Pool().Despawn(arrow);

Po co

Wystrzelenie strzały oznaczało kiedyś odczyt pliku, parsowanie YAML, tworzenie encji, rozwiązanie każdego assetu wskazanego przez prefab i zbudowanie ciała Jolt — kształt, właściwości masy, miejsce w broadphase — a sekundę później wyrzucenie tego wszystkiego. Parsowania już nie ma (każde tworzenie po ścieżce idzie przez cache prefabów), ale reszta to praca przy każdym spawnie, którą pula usuwa w całości. Dla wszystkiego, co gra survivalowa robi w kółko — pociski, upuszczone przedmioty, odradzające się stworzenia, efekty trafień — to różnica między „za darmo” a przycięciem.

Metody

Spawn(path, position, eulerRotation)EntityPonownie użyta instancja, jeśli jakaś czeka, w przeciwnym razie nowa. Rotacja w radianach, jak TransformComponent::Rotation. Zwraca nieważną Entity, jeśli prefabu nie da się wczytać.
Despawn(entity)boolOdkłada ją. Zwraca false — i nic nie robi — dla encji, która nie pochodzi ze Spawn, albo już odłożonej.
Prewarm(path, count)intTworzy instancje z góry, żeby pierwszy spawn kosztował tyle co tysięczny. Zwraca, ile potem czeka dla tego prefabu.
Clear()voidNiszczy wszystkie odłożone instancje. Żywe należą do gry i zostają.
GetStats()StatsParked, Live, Spawns, Reuses. Pula, której Reuses stoi na zerze, niczego nie ponownie używa.

Ponownie użyta encja to ta sama encja

Wokół tego trzeba projektować. Pula niczego nie odbudowuje, więc odzyskana instancja zachowuje UUID, komponenty i instancję skryptu — razem z tym, co zostawiło w niej poprzednie życie. Pula przywraca tylko to, co uczciwie może uznać za swoje:

  • transformację w świecie całego poddrzewa,
  • stan włączenia całego poddrzewa,
  • prędkość liniową i kątową każdego ciała w nim.

Cała reszta należy do ciebie, a ScriptableEntity dostało do tego dwa zaczepy:

class Arrow : public ScriptableEntity {
protected:
    void OnSpawn() override   { m_Stuck = false; m_Age = 0.0f; }
    void OnDespawn() override { /* tu jeszcze żyje: upuść łup, odpal efekt */ }
};
OnCreate nie znaczy już „pojawiła się”. Encja z puli powstaje raz i jest używana w nieskończoność, więc OnCreate wykona się dla pierwszej strzały i nigdy więcej. Przygotowanie na każde życie należy do OnSpawn, które działa za każdym razem — także za pierwszym.

Wyłączona znaczy teraz naprawdę wyłączona

Odkładanie opiera się na EnabledComponent, zapisywanym w całym poddrzewie. Kilka systemów w ogóle go nie sprawdzało, więc encja z odznaczonym Enabled dalej kolidowała, animowała się, szukała ścieżek i wykonywała drzewo zachowań, będąc niewidoczną. To jest naprawione i dotyczy zarówno checkboxa w inspektorze, jak i puli: fizyka (ciała wychodzą ze świata, a nie są tylko pomijane), animacja, agenci nawigacji, drzewa zachowań i buildery teraz się zatrzymują.

Flaga nie jest rozwiązywana w górę hierarchii przy każdym zapytaniu. Pula zapisuje ją raz w całym poddrzewie, gdy coś jest wyłączane — więc test w systemie to jedno sprawdzenie komponentu, a nie wędrówka do korzenia.

Uwagi

Odłożone instancje są pomijane przez zapis świata: zapas czekający za kulisami to nie coś, co gracz widział, a jego przywrócenie wstawiłoby do świata wyłączonego ducha. Instancje z puli, które żyją, zapisują się jak wszystko inne.

Zniszczenie odłożonej instancji przez Scene::DestroyEntity to bałagan, a nie katastrofa — pula sprawdza każdy uchwyt zdejmowany z listy wolnych i odrzuca martwe.

Scene::Clear() opróżnia pulę razem z rejestrem, więc zmiana sceny nie zostawi w niej uchwytów do świata, który już nie istnieje.