6.7. fejezet: Időzítők és CallQueue

Bevezetés

A DayZ több mechanizmust biztosít a késleltetett és ismétlődő függvényhívásokhoz: ScriptCallQueue (az elsődleges rendszer), Timer, ScriptInvoker és WidgetFadeTimer. Ezek elengedhetetlenek a késleltetett logika ütemezéséhez, frissítési ciklusok létrehozásához és időzített események kezeléséhez a fő szál blokkolása nélkül. Ez a fejezet minden mechanizmust ismertet teljes API szignatúrákkal és használati mintákkal.

Hívási kategóriák

Minden időzítő és hívási sor rendszer egy hívási kategóriát igényel, amely meghatározza, hogy a késleltetett hívás mikor hajtódik végre a képkockán belül:

const int CALL_CATEGORY_SYSTEM   = 0;   // Rendszerszintű műveletek
const int CALL_CATEGORY_GUI      = 1;   // UI frissítések
const int CALL_CATEGORY_GAMEPLAY = 2;   // Játéklogika
const int CALL_CATEGORY_COUNT    = 3;   // Kategóriák összszáma

A sor elérése egy adott kategóriához:

ScriptCallQueue  queue   = GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY);
ScriptInvoker    updater = GetGame().GetUpdateQueue(CALL_CATEGORY_GAMEPLAY);
TimerQueue       timers  = GetGame().GetTimerQueue(CALL_CATEGORY_GAMEPLAY);

ScriptCallQueue

Fájl: 2_GameLib/tools.c

Az elsődleges mechanizmus késleltetett függvényhívásokhoz. Támogatja az egyszeri késleltetéseket, ismétlődő hívásokat és azonnali következő-képkockás végrehajtást.

CallLater

void CallLater(func fn, int delay = 0, bool repeat = false,
               void param1 = NULL, void param2 = NULL,
               void param3 = NULL, void param4 = NULL);

Paraméter	Leírás
`fn`	A meghívandó függvény (metódushivatkozás: `this.MyMethod`)
`delay`	Késleltetés milliszekundumban (0 = következő képkocka)
`repeat`	`true` = ismételt hívás `delay` időközönként; `false` = egyszeri hívás
`param1..4`	Opcionális paraméterek, amelyeket a függvénynek adunk át

Példa --- egyszeri késleltetés:

// MyFunction hívása egyszer 5 másodperc múlva
GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).CallLater(this.MyFunction, 5000, false);

Példa --- ismétlődő hívás:

// UpdateLoop hívása minden 1 másodpercben, ismétlődően
GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).CallLater(this.UpdateLoop, 1000, true);

Példa --- paraméterekkel:

void ShowMessage(string text, int color)
{
    Print(text);
}

// Hívás paraméterekkel 2 másodperc múlva
GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).CallLater(
    this.ShowMessage, 2000, false, "Hello!", ARGB(255, 255, 0, 0)
);

Call

void Call(func fn, void param1 = NULL, void param2 = NULL,
          void param3 = NULL, void param4 = NULL);

A függvényt a következő képkockán hajtja végre (delay = 0, nincs ismétlés). Rövidítés a CallLater(fn, 0, false) helyett.

Példa:

// Végrehajtás a következő képkockán
GetGame().GetCallQueue(CALL_CATEGORY_SYSTEM).Call(this.Initialize);

CallByName

void CallByName(Class obj, string fnName, Param params = NULL);

Metódus hívása a string neve alapján a következő képkockán. Hasznos, ha a metódushivatkozás nem érhető el közvetlenül. Késleltetett vagy ismétlődő név szerinti híváshoz használd helyette a CallLaterByName-t:

void CallLaterByName(Class obj, string fnName, int delay = 0, bool repeat = false,
                     Param params = NULL);

Példa:

GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).CallLaterByName(
    myObject, "OnTimerExpired", 3000, false
);

Remove

void Remove(func fn);

Egy ütemezett hívás eltávolítása. Elengedhetetlen az ismétlődő hívások leállításához és a megsemmisített objektumokon történő hívások megelőzéséhez.

Példa:

// Ismétlődő hívás leállítása
GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).Remove(this.UpdateLoop);

RemoveByName

void RemoveByName(Class obj, string fnName);

A CallByName-mel ütemezett hívás eltávolítása.

Tick

void Tick(float timeslice);

A motor minden képkockában belsőleg hívja. Soha nem szabad manuálisan meghívnod.

Timer

Fájl: 3_Game/tools/tools.c

Osztályalapú időzítő explicit start/stop életciklussal. Tisztább megoldás hosszú életű időzítőkhöz, amelyeket szüneteltetni vagy újraindítani kell.

Konstruktor

void Timer(int category = CALL_CATEGORY_SYSTEM);

Run

void Run(float duration, Managed obj, string fn_name, Param params = NULL, bool loop = false);

Paraméter	Leírás
`duration`	Idő másodpercben (nem milliszekundumban!)
`obj`	Az objektum, amelynek a metódusa meghívásra kerül
`fn_name`	Metódusnév stringként
`params`	Opcionális `Param` objektum paraméterekkel
`loop`	`true` = ismétlés minden időtartam után

Példa --- egyszeri időzítő:

ref Timer m_Timer;

void StartTimer()
{
    m_Timer = new Timer(CALL_CATEGORY_GAMEPLAY);
    m_Timer.Run(5.0, this, "OnTimerComplete", null, false);
}

void OnTimerComplete()
{
    Print("Időzítő befejeződött!");
}

Példa --- ismétlődő időzítő:

ref Timer m_UpdateTimer;

void StartUpdateLoop()
{
    m_UpdateTimer = new Timer(CALL_CATEGORY_GAMEPLAY);
    m_UpdateTimer.Run(1.0, this, "OnUpdate", null, true);  // Minden 1 másodpercben
}

void StopUpdateLoop()
{
    if (m_UpdateTimer && m_UpdateTimer.IsRunning())
        m_UpdateTimer.Stop();
}

Stop

void Stop();

Megállítja az időzítőt. Újraindítható egy újabb Run() hívással.

IsRunning

bool IsRunning();

true-t ad vissza, ha az időzítő jelenleg aktív.

Pause

void Pause();

Szünetelteti a futó időzítőt, megőrizve a hátralévő időt. Az időzítő a Continue()-val folytatható.

Continue

void Continue();

Folytatja a szüneteltetett időzítőt onnan, ahol megállt.

Példa --- szüneteltetés és folytatás:

A Timer-nek nincs IsPaused() metódusa. Mivel az IsRunning() csak akkor ad vissza true-t, amikor az időzítő aktív (és false-t, ha szünetel vagy leállt), használd ezt annak eldöntésére, hogy szüneteltetni vagy folytatni kell-e:

ref Timer m_Timer;

void StartTimer()
{
    m_Timer = new Timer(CALL_CATEGORY_GAMEPLAY);
    m_Timer.Run(10.0, this, "OnTimerComplete", null, false);
}

void TogglePause()
{
    if (m_Timer.IsRunning())
        m_Timer.Pause();
    else
        m_Timer.Continue();
}

GetRemaining

float GetRemaining();

A hátralévő időt adja vissza másodpercben.

GetDuration

float GetDuration();

A Run() által beállított teljes időtartamot adja vissza.

ScriptInvoker

Fájl: 2_GameLib/tools.c

Egy esemény/delegált rendszer. A ScriptInvoker visszahívási függvények listáját tartja, és mindegyiket meghívja, amikor az Invoke() hívásra kerül. Ez a DayZ megfelelője a C# eseményeknek vagy a megfigyelő mintának.

Insert

bool Insert(func fn, int flags = EScriptInvokerInsertFlags.IMMEDIATE);

Visszahívási függvény regisztrálása. Az opcionális flags argumentum elfogadja az EScriptInvokerInsertFlags.IMMEDIATE (alapértelmezett) vagy EScriptInvokerInsertFlags.UNIQUE értéket. Sikeres esetben true-t ad vissza.

Remove

bool Remove(func fn, int flags = EScriptInvokerRemoveFlags.ALL);

Visszahívási függvény regisztrációjának törlése. Az opcionális flags argumentum alapértelmezett értéke EScriptInvokerRemoveFlags.ALL. Sikeres esetben true-t ad vissza.

Invoke

void Invoke(void param1 = NULL, void param2 = NULL,
            void param3 = NULL, void param4 = NULL);

Az összes regisztrált függvény hívása a megadott paraméterekkel.

Count

int Count(func fn);

Azt adja vissza, hogy a megadott fn függvény hányszor van jelenleg regisztrálva az invokerben (nem az összes visszahívás teljes száma).

Clear

void Clear();

Az összes regisztrált visszahívás eltávolítása.

Példa --- egyéni eseményrendszer:

class MyModule
{
    ref ScriptInvoker m_OnMissionComplete = new ScriptInvoker();

    void CompleteMission()
    {
        // Befejezési logika végrehajtása...

        // Összes figyelő értesítése
        m_OnMissionComplete.Invoke("MissionAlpha", 1500);
    }
}

class MyUI
{
    void Init(MyModule module)
    {
        // Feliratkozás az eseményre
        module.m_OnMissionComplete.Insert(this.OnMissionComplete);
    }

    void OnMissionComplete(string name, int reward)
    {
        Print(string.Format("Misszió %1 befejezve! Jutalom: %2", name, reward));
    }

    void Cleanup(MyModule module)
    {
        // Mindig iratkozz le a lógó hivatkozások megelőzése érdekében
        module.m_OnMissionComplete.Remove(this.OnMissionComplete);
    }
}

Frissítési sor

A motor képkockánkénti ScriptInvoker sorokat biztosít:

ScriptInvoker updater = GetGame().GetUpdateQueue(CALL_CATEGORY_GAMEPLAY);
updater.Insert(this.OnFrame);

// Eltávolítás, ha kész
updater.Remove(this.OnFrame);

A frissítési sorba regisztrált függvények minden képkockában meghívódnak paraméterek nélkül. Ez hasznos képkockánkénti logikához az EntityEvent.FRAME használata nélkül.

WidgetFadeTimer

Fájl: 3_Game/tools/tools.c

Speciális időzítő widgetek be- és kihalványításához. A WidgetFadeTimer a TimerBase-ből származik, így örökli a Stop() és IsRunning() metódusokat.

class WidgetFadeTimer extends TimerBase
{
    void FadeIn(Widget w, float time, bool continue_ = false);
    void FadeOut(Widget w, float time, bool continue_ = false);
    // A Stop() és IsRunning() a TimerBase-ből öröklődik
}

Paraméter	Leírás
`w`	A halványítandó widget
`time`	A halványítás időtartama másodpercben
`continue_`	Ha `true`, az aktuális alfa értéktől indul; egyébként 0-ról (behalványítás) vagy 1-ről (kihalványítás)

Használd az örökölt IsRunning() metódust annak ellenőrzésére, hogy egy halványítás éppen folyamatban van-e.

Példa:

ref WidgetFadeTimer m_FadeTimer;
Widget m_NotificationPanel;

void ShowNotification()
{
    m_NotificationPanel.Show(true);
    m_FadeTimer = new WidgetFadeTimer;
    m_FadeTimer.FadeIn(m_NotificationPanel, 0.3);

    // Automatikus elrejtés 5 másodperc múlva
    GetGame().GetCallQueue(CALL_CATEGORY_GUI).CallLater(this.HideNotification, 5000, false);
}

void HideNotification()
{
    m_FadeTimer.FadeOut(m_NotificationPanel, 0.5);
}

GetRemainingTime (CallQueue)

A ScriptCallQueue lehetőséget biztosít arra is, hogy lekérdezd, mennyi idő van hátra (milliszekundumban) egy ütemezett hívásból. Két változata van --- az egyik függvényhivatkozással, a másik névvel kulcsozva:

int GetRemainingTime(func fn);
int GetRemainingTimeByName(Class obj, string fnName);

Példa:

// Mennyi idő van hátra egy név szerint ütemezett hívásból
int remaining = GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).GetRemainingTimeByName(this, "MyCallback");
if (remaining > 0)
    Print(string.Format("A visszahívás %1 ms múlva fut le", remaining));

Gyakori minták

Időzítő akkumulátor (lassított OnUpdate)

Amikor képkockánkénti visszahívásod van, de lassabb ütemben szeretnéd futtatni a logikát:

class MyModule
{
    protected float m_UpdateAccumulator;
    protected const float UPDATE_INTERVAL = 2.0;  // Minden 2 másodpercben

    void OnUpdate(float timeslice)
    {
        m_UpdateAccumulator += timeslice;
        if (m_UpdateAccumulator < UPDATE_INTERVAL)
            return;
        m_UpdateAccumulator = 0;

        // Lassított logika itt
        DoPeriodicWork();
    }
}

Takarítási minta

Mindig távolítsd el az ütemezett hívásokat, amikor az objektumod megsemmisül, hogy megelőzd az összeomlásokat:

class MyManager
{
    void MyManager()
    {
        GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).CallLater(this.Tick, 1000, true);
    }

    void ~MyManager()
    {
        GetGame().GetCallQueue(CALL_CATEGORY_GAMEPLAY).Remove(this.Tick);
    }

    void Tick()
    {
        // Periodikus munka
    }
}

Egyszeri késleltetett inicializálás

Gyakori minta rendszerek inicializálásához a világ teljes betöltése után:

void OnMissionStart()
{
    // Init késleltetése 1 másodperccel, hogy minden biztosan betöltődjön
    GetGame().GetCallQueue(CALL_CATEGORY_SYSTEM).CallLater(this.DelayedInit, 1000, false);
}

void DelayedInit()
{
    // Biztonságosan hozzáférhetünk a világ objektumaihoz
}

Összefoglalás

Mechanizmus	Felhasználás	Időegység
`CallLater`	Egyszeri vagy ismétlődő késleltetett hívások	Milliszekundum
`Call`	Végrehajtás a következő képkockán	N/A (azonnali)
`Timer`	Osztályalapú időzítő start/stop/hátralévő idővel	Másodperc
`ScriptInvoker`	Esemény/delegált (megfigyelő minta)	N/A (kézi hívás)
`WidgetFadeTimer`	Widget behalványítás/kihalványítás	Másodperc
`GetUpdateQueue()`	Képkockánkénti visszahívás regisztráció	N/A (minden képkocka)

Fogalom	Lényeg
Kategóriák	`CALL_CATEGORY_SYSTEM` (0), `GUI` (1), `GAMEPLAY` (2)
Hívások eltávolítása	Mindig `Remove()` a destruktorban a lógó hivatkozások megelőzéséhez
Timer vs CallLater	Timer másodperc + osztályalapú; CallLater milliszekundum + funkcionális
ScriptInvoker	Insert/Remove visszahívások, Invoke az összes kiváltásához

Legjobb gyakorlatok

Mindig hívd meg a Remove()-ot az ütemezett CallLater hívásokra a destruktorodban. Ha a tulajdonos objektum megsemmisül, miközben egy CallLater még függőben van, a motor egy törölt objektum metódusát hívja meg és összeomlik. Minden CallLater-nek kell egy megfelelő Remove() a destruktorban.
Használd a Timer-t (másodperc) hosszú életű időzítőkhöz szüneteltetéssel/folytatással, a CallLater-t (milliszekundum) tüzelj-és-felejtsd késleltetésekhez. A kettő keverése 1000-szeres időzítési hibákhoz vezet, mivel a Timer.Run() másodpercet, de a CallLater milliszekundumot használ.
Lassítsd az OnUpdate-et időzítő akkumulátorral az ismétlődő CallLater regisztrálása helyett. Az ismétlődő CallLater külön nyomon követett bejegyzést hoz létre a sorban, míg az akkumulátor minta (m_Acc += timeslice; if (m_Acc >= INTERVAL)) nulla terheléssel jár és könnyebben hangolható.
Iratkozz le a ScriptInvoker visszahívásokról, mielőtt a figyelő megsemmisül. A Remove() elfelejtése egy ScriptInvoker-en lógó függvényhivatkozást hagy hátra, ami összeomlást okoz, amikor az Invoke() kiváltódik.
Soha ne hívd meg manuálisan a Tick()-et a ScriptCallQueue-n. A motor automatikusan hívja minden képkockán. A manuális hívások duplán váltják ki az összes függőben lévő visszahívást.

Kompatibilitás és hatás

Mod kompatibilitás: Az időzítő rendszerek példányonkéntiák, így a modok ritkán ütköznek közvetlenül az időzítőkön. A kockázat a megosztott ScriptInvoker eseményeknél van, ahol több mod regisztrál visszahívásokat.

Betöltési sorrend: Az időzítő és CallQueue rendszerek betöltési sorrendtől függetlenek. Minden mod kezeli a saját időzítőit.
Modolt osztály ütközések: Nincs közvetlen ütközés, de ha két mod is felülírja az OnUpdate()-et ugyanazon az osztályon (pl. MissionServer) és az egyik elfelejti a super-t, a másik akkumulátor-alapú időzítői nem működnek.
Teljesítményhatás: Minden aktív CallLater repeat = true-val minden képkockán ellenőrzésre kerül. Több száz ismétlődő hívás rontja a szerver frissítési rátáját. Előnyben részesítsd a kevesebb időzítőt hosszabb időközökkel, vagy használd az akkumulátor mintát az OnUpdate-ben.
Szerver/Kliens: A CallLater és a Timer mindkét oldalon működik. Használd a CALL_CATEGORY_GAMEPLAY-t játéklogikához, a CALL_CATEGORY_GUI-t UI frissítésekhez (csak kliens), és a CALL_CATEGORY_SYSTEM-et alacsony szintű műveletekhez.

Valós modokban megfigyelt minták

Ezeket a mintákat professzionális DayZ modok forráskódjának tanulmányozásával igazoltuk.

Minta	Mod	Fájl/Hely
Destruktor `Remove()` takarítás minden `CallLater` regisztrációhoz	COT	Modulkezelő életciklus
`ScriptInvoker` eseménybusz modulok közötti értesítésekhez	Expansion	`ExpansionEventBus`
`Timer` `Pause()`/`Continue()` használattal kilépési visszaszámláláshoz	Vanilla	`MissionServer` kilépési rendszer
Akkumulátor minta `OnUpdate`-ben 5 másodperces periodikus ellenőrzésekhez	Dabs Framework	Modul frissítés ütemezés

<< Előző: Értesítések | Időzítők és CallQueue | Következő: Fájl I/O és JSON >>

6.7. fejezet: Időzítők és CallQueue ​

Bevezetés ​

Hívási kategóriák ​

ScriptCallQueue ​

CallLater ​

Call ​

CallByName ​

Remove ​

RemoveByName ​

Tick ​

Timer ​

Konstruktor ​

Run ​

Stop ​

IsRunning ​

Pause ​

Continue ​

GetRemaining ​

GetDuration ​

ScriptInvoker ​

Insert ​

Remove ​

Invoke ​

Count ​

Clear ​

Frissítési sor ​

WidgetFadeTimer ​

GetRemainingTime (CallQueue) ​

Gyakori minták ​

Időzítő akkumulátor (lassított OnUpdate) ​

Takarítási minta ​

Egyszeri késleltetett inicializálás ​

Összefoglalás ​

Legjobb gyakorlatok ​

Kompatibilitás és hatás ​

Valós modokban megfigyelt minták ​

6.7. fejezet: Időzítők és CallQueue

Bevezetés

Hívási kategóriák

ScriptCallQueue

CallLater

Call

CallByName

Remove

RemoveByName

Tick

Timer

Konstruktor

Run

Stop

IsRunning

Pause

Continue

GetRemaining

GetDuration

ScriptInvoker

Insert

Remove

Invoke

Count

Clear

Frissítési sor

WidgetFadeTimer

GetRemainingTime (CallQueue)

Gyakori minták

Időzítő akkumulátor (lassított OnUpdate)

Takarítási minta

Egyszeri késleltetett inicializálás

Összefoglalás

Legjobb gyakorlatok

Kompatibilitás és hatás

Valós modokban megfigyelt minták