Scene Systems
Scene systems are the place to put logic that:
- Operates on many entities at once (instead of one entity per ScriptableEntity instance).
- Should run for every scene automatically, not opt-in per entity.
- Has a clear "tick" cadence — once per frame during play.
Examples shipped with the engine: AutoRotateSystem (rotates
entities with AutoRotateComponent), CameraControllerSystem
(WASD camera movement based on a component), animation system, UI system.
Anatomy of a system
A scene system is a subclass of SceneSystem with a single
override:
Example: a system that bobs entities up and down
// BobSystem.h — a SceneSystem in your project's assets/scripts folder
#pragma once
#include "scene/SceneSystem.h"
#include "scene/Components.h"
namespace Thread {
struct BobComponent {
float Frequency = 1.0f;
float Amplitude = 0.5f;
float Phase = 0.0f;
};
class BobSystem : public SceneSystem {
public:
void OnUpdate(Scene* scene, float dt) override {
auto& reg = scene->GetRegistry();
auto view = reg.view<BobComponent, TransformComponent>();
for (auto e : view) {
auto& bob = view.get<BobComponent>(e);
auto& tc = view.get<TransformComponent>(e);
bob.Phase += dt * bob.Frequency * 6.2831853f;
tc.Translation.y += std::sin(bob.Phase) * bob.Amplitude * dt;
}
}
};
}
Registering the system
Nothing to write. Create it with Content Browser ▸ Code ▸ New System and the
editor generates the registration alongside every other script in the folder — it reads
SceneSystem as the base class and emits REGISTER_SYSTEM rather than
REGISTER_SCRIPT. Press F6 and the type is live.
A system written by hand registers itself the same way the engine's own do, with the macro directly in the header:
#include "systems/SystemRegistry.h"
namespace Thread {
class BobSystem : public SceneSystem { /* ... */ };
REGISTER_SYSTEM(BobSystem); // the generator sees this and leaves the class alone
}
Parameters from a .system asset
New System also writes a .system YAML asset. It is DATA — packed
into assets.pak and shipped — so a designer can retune a system without touching C++:
# BobSystem.system
System: BobSystem
Amplitude: 0.75
void DeserializeFromAsset(const YAML::Node& node) override {
if (node["Amplitude"]) m_Amplitude = node["Amplitude"].as<float>(m_Amplitude);
}
The scene then calls each registered system's OnUpdate in order,
every runtime tick.
System vs ScriptableEntity
| Use a System when… | Use a ScriptableEntity when… |
|---|---|
| Logic applies to many entities sharing a tag-component. | Logic is unique to one entity (one-off behaviour script). |
| You want the behaviour to be data-driven via a small component struct. | You want full OO state per entity, including private fields. |
| You need batched iteration (renderer, physics-sync, AI swarm). | The work is sequential and entity-specific. |
System ordering
Systems run in registration order. Critical ordering rules:
- Physics integration (built-in) runs after custom systems — your AddForce calls from a system land in the same frame.
- Audio listener update runs after physics — sources hear from the post-step camera position.
- Rendering runs last, so any transform mutation from a system / script / physics tick is reflected in the same frame.
Lifecycle hooks
OnInit(scene) and OnDestroy(scene) bracket the system's life, so a
system owning GPU/AL/Jolt resources has a place to take and release them that is not the
constructor.
See also
Systemy sceny
Systemy sceny to miejsce na logikę, która:
- Działa na wielu encjach naraz (zamiast na jednej encji na instancję ScriptableEntity).
- Ma działać w każdej scenie automatycznie, a nie po włączeniu na encji.
- Ma wyraźny rytm „ticku” — raz na klatkę w trakcie gry.
Przykłady dostarczane z silnikiem: AutoRotateSystem (obraca encje z
AutoRotateComponent), CameraControllerSystem (ruch kamery WASD na podstawie
komponentu), system animacji, system UI.
Budowa systemu
System sceny to podklasa SceneSystem z jednym wymaganym nadpisaniem:
Przykład: system, który podrzuca encje w górę i w dół
// BobSystem.h — SceneSystem w folderze assets/scripts projektu
#pragma once
#include "scene/SceneSystem.h"
#include "scene/Components.h"
namespace Thread {
struct BobComponent {
float Frequency = 1.0f;
float Amplitude = 0.5f;
float Phase = 0.0f;
};
class BobSystem : public SceneSystem {
public:
void OnUpdate(Scene* scene, float dt) override {
auto& reg = scene->GetRegistry();
auto view = reg.view<BobComponent, TransformComponent>();
for (auto e : view) {
auto& bob = view.get<BobComponent>(e);
auto& tc = view.get<TransformComponent>(e);
bob.Phase += dt * bob.Frequency * 6.2831853f;
tc.Translation.y += std::sin(bob.Phase) * bob.Amplitude * dt;
}
}
};
}
Rejestracja systemu
Nic do pisania. Utwórz go przez Content Browser ▸ Code ▸ New System, a edytor
wygeneruje rejestrację razem z każdym innym skryptem w folderze — rozpozna SceneSystem jako
klasę bazową i użyje REGISTER_SYSTEM zamiast REGISTER_SCRIPT. Naciśnij
F6 i typ działa.
System pisany ręcznie rejestruje się tak samo jak systemy silnika — makrem bezpośrednio w nagłówku:
#include "systems/SystemRegistry.h"
namespace Thread {
class BobSystem : public SceneSystem { /* ... */ };
REGISTER_SYSTEM(BobSystem); // generator to widzi i zostawia klasę w spokoju
}
Parametry z assetu .system
New System zapisuje też asset YAML .system. To DANE — pakowane do
assets.pak i wysyłane — więc projektant może dostroić system bez dotykania C++:
# BobSystem.system
System: BobSystem
Amplitude: 0.75
void DeserializeFromAsset(const YAML::Node& node) override {
if (node["Amplitude"]) m_Amplitude = node["Amplitude"].as<float>(m_Amplitude);
}
Scena wywołuje potem OnUpdate każdego zarejestrowanego systemu po kolei, w każdym ticku
gry.
System czy ScriptableEntity
| Użyj systemu, gdy… | Użyj ScriptableEntity, gdy… |
|---|---|
| Logika dotyczy wielu encji z wspólnym komponentem-znacznikiem. | Logika jest unikalna dla jednej encji (jednorazowy skrypt zachowania). |
| Chcesz, żeby zachowanie było sterowane danymi przez małą strukturę komponentu. | Chcesz pełnego stanu obiektowego per encja, z prywatnymi polami. |
| Potrzebujesz iteracji wsadowej (renderer, synchronizacja fizyki, rój AI). | Praca jest sekwencyjna i specyficzna dla encji. |
Kolejność systemów
Systemy działają w kolejności rejestracji. Najważniejsze reguły:
- Integracja fizyki (wbudowana) działa po własnych systemach — wywołania AddForce z systemu trafiają w tę samą klatkę.
- Aktualizacja słuchacza audio działa po fizyce — źródła słyszą z pozycji kamery po kroku.
- Renderowanie jest ostatnie, więc każda zmiana transformu z systemu / skryptu / fizyki widać w tej samej klatce.
Zaczepy cyklu życia
OnInit(scene) i OnDestroy(scene) obejmują życie systemu, więc system
posiadający zasoby GPU/AL/Jolt ma miejsce, by je wziąć i zwolnić, inne niż konstruktor.