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:

// SceneSystem — the base class you override class SceneSystem { public: virtual ~SceneSystem() = default; virtual void OnInit(Scene* scene) {} virtual void OnUpdate(Scene* scene, float ts) = 0; // the only required one virtual void OnDestroy(Scene* scene) {} virtual void DeserializeFromAsset(const YAML::Node& node) {} // params from the .system asset virtual const char* GetName() const = 0; };

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

ECS Model · Native Scripting · Scripts & IDE workflow

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:

// SceneSystem — klasa bazowa, którą nadpisujesz class SceneSystem { public: virtual ~SceneSystem() = default; virtual void OnInit(Scene* scene) {} virtual void OnUpdate(Scene* scene, float ts) = 0; // jedyne wymagane virtual void OnDestroy(Scene* scene) {} virtual void DeserializeFromAsset(const YAML::Node& node) {} // parametry z assetu .system virtual const char* GetName() const = 0; };

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.

Zobacz też

Model ECS · Skrypty natywne · Skrypty i IDE