t1k:cocos:playable:lifecycle

Field	Value
Module	`playable`
Version	`2.14.4`
Effort	`high`
Tools	—

Keywords: component, GameLifecycleManager, lifecycle

How to invoke

/t1k:cocos:playable:lifecycle

GameLifecycleManager — Non-Component Lifecycle System

Drives Tick/FixedTick/LateTick on plain TS classes that don’t extend Cocos Component. Add GameLifecycleManager as a component on a persistent scene node. See also: t1k-cocos-playable-signalbus, t1k-cocos-playable-async-utilities.

Import path:

db://assets/packages/@playablelabs/game-foundation/gameLifecycle — GameLifecycleManager, RegisterLifecycle, LifecycleRegistry, and the IInitializable / ITickable / IFixedTickable / ILateTickable / IDisposable interfaces

Interfaces

Interface	Method signature	Called when
`IInitializable`	`Initialize(): void`	Immediately on `Register()`
`ITickable`	`Tick(dt: number): void`	Every frame (via Cocos `update`)
`IFixedTickable`	`FixedTick(fixedDt: number): void`	Fixed timestep accumulator (default 0.02s / 50 FPS)
`ILateTickable`	`LateTick(dt: number): void`	After all Ticks (via Cocos `lateUpdate`)
`IDisposable`	`Dispose(): void`	On `Unregister()` or scene destroy

A class can implement any combination. Register() detects which interfaces are present via duck-typing (isType checks for method name existence).

@RegisterLifecycle() Decorator

Auto-instantiates and registers the class when GameLifecycleManager.onLoad() runs. No-arg constructor required.

import { RegisterLifecycle } from "db://assets/packages/@playablelabs/game-foundation/gameLifecycle";
import { IInitializable, ITickable, IDisposable } from "db://assets/packages/@playablelabs/game-foundation/gameLifecycle";

@RegisterLifecycle()
export class MySystem implements IInitializable, ITickable, IDisposable {
    Initialize(): void {
        // setup — called once at scene start
    }

    Tick(dt: number): void {
        // runs every frame
    }

    Dispose(): void {
        // cleanup on scene destroy
    }
}

Manual Registration

Use when you need constructor args or runtime control:

const system = new MySystem(someArg);
GameLifecycleManager.Instance.Register(system);

// Later, to stop ticking and call Dispose:
GameLifecycleManager.Instance.Unregister(system);

Fixed Timestep

The manager accumulates delta time and calls FixedTick at a fixed rate:

// Default: 0.02s (50 Hz). Change at runtime:
GameLifecycleManager.Instance.SetFixedTimeStep(1 / 30); // 30 Hz
GameLifecycleManager.Instance.GetFixedTimeStep();

FixedTick receives the configured fixedDeltaTime, not the accumulated surplus.

isType Pattern (Internal)

The manager uses duck-typing — not instanceof — to check interfaces:

// Internal implementation (for reference):
private isType<T>(obj: any, methodName: string): obj is T {
    return methodName in obj;
}

This means TypeScript interfaces are checked at runtime by method presence. Ensure method names match exactly (Tick, FixedTick, LateTick, Initialize, Dispose).

Debug Info

console.log(GameLifecycleManager.Instance.GetDebugInfo());
// Prints counts for each collection + fixedTimeStep

When to Use Lifecycle Manager vs Cocos Component update()

Scenario	Use
Pure logic / service class (no Node)	`@RegisterLifecycle()` + interfaces
Node-attached behaviour	Cocos `Component` with `update()`
Physics-like deterministic step	`IFixedTickable`
Camera follow / post-process	`ILateTickable`
One-time setup with no ticking	`IInitializable` only
Cross-system service needing frame updates	`ITickable` via lifecycle manager

Common Mistakes

Implementing tick() (lowercase) instead of Tick() — manager checks exact name; the method is silently ignored.
Using @RegisterLifecycle() on a class with constructor arguments — manager calls new ClassConstructor() with no args; use manual Register() instead.
Multiple GameLifecycleManager components in the scene — the second one self-destructs. Keep exactly one on a persistent node.
Forgetting IDisposable on systems holding signal subscriptions or timers — causes leaks on scene reload.

Gotchas

Cocos lifecycle order: onLoad → onEnable → start → update — this is the phase order WITHIN one component, not a guarantee between components. Wiring listeners in start instead of onEnable skips the first re-enable cycle.
Cross-component ordering is NOT guaranteed within a phase. Cocos guarantees every onLoad() in the scene finishes before any start() runs, and every start() finishes before the first scheduler tick — but it does not guarantee order between sibling components in the same phase: onLoad() of component A may run before or after onLoad() of component B, depending on scene tree order.
- Passing a value between two components → do it in onLoad() (the earlier-guaranteed phase). If you don’t know which side runs first, use a two-way handshake: both sides are singletons, and each tries to find the other in its own onLoad(); since onLoad() is single-threaded and non-interleaved, exactly one direction always succeeds.
- A side-effect depending on state built by another component’s start() → don’t assume start() order. Latch the desired value and flush once via scheduleOnce(fn, 0) — the first scheduler tick is guaranteed to run after every start().
- Anti-pattern: moving a data read from onLoad() to start() “to make sure the other side is ready” — this swaps an onLoad()-ordering trap for a start()-ordering trap, and if the other component throws when required data is missing in start(), it turns a silent bug into a crash.
onDisable fires on scene close before onDestroy — release resources in onDestroy, not onDisable, to survive scene navigation.
update is called even on disabled components in some Cocos versions — guard with this.enabled or migrate to lateUpdate.