Lifecycle
Volver a la referencia

Lifecycle

What runs every frame, and what runs when a scene is taken down.

5 símbolos

useSceneUnmountfunctionhooknacatamalon

useSceneUnmount(cleanup: () => void) => void

Runs your code once, the moment the scene disappears: when it is stopped, when it changes to another scene, or when the whole game is destroyed. Pausing is not leaving, so a paused scene does not run it.

You need it for what the scene started outside the engine, because that keeps running on its own after the scene is gone: a setInterval, a keydown listener on the window, a request you want to abort. Everything the engine gave you (its sprites, its useUpdate, its loaded images) goes away with the scene and needs no cleaning.

Register as many as you like; if one of them throws, it is reported and the rest still run.

Parámetros

cleanup() => void

What to undo. It receives nothing and is called exactly once.

Ejemplo

export const Level: TSceneFn = () => {
    const onKey = (event: KeyboardEvent) => console.log(event.key);
    window.addEventListener('keydown', onKey);

    // Without this, the listener stays alive after the level ends and fires in the next scene.
    useSceneUnmount(() => window.removeEventListener('keydown', onKey));

    return createScene();
};
Ver el código · hooks/scene/use_scene_unmount.ts:34

useTimerfunctionhooknacatamalon

useTimer() => TTimer

Runs code later, in game time: once after a while, or again and again.

It is what setTimeout and setInterval would be if they knew about the game. The wait is counted in the same seconds as useUpdate's delta, so it stops while the scene is paused, follows timeScale, and is gone when the object that asked for it is: a cutscene that waits two seconds still waits two seconds after a pause, and a timer of a scene that ended never fires into the next one. A setTimeout does none of the three.

Call useTimer in the body, like any hook. What it returns can be used from anywhere after that, an update, a click or another timer, so a sequence is just calls that schedule the next step.

Several calls due in the same frame run in the order they were due, so a long frame cannot swap the steps of a sequence. One scheduled from inside another runs on a later frame at the soonest.

Ejemplo

export const Level: TSceneFn = () => {
    const timer = useTimer();
    const banner = createText({ text: 'READY', font, transform: { x: 160, y: 100 } });

    timer.after(1.5, () => { banner.text = 'GO!'; });
    timer.after(2.5, () => { banner.visible = false; });

    // A new enemy every three seconds, for as long as the level runs
    timer.every(3, () => { spawnEnemy(); });

    return createScene();
};
Ver el código · hooks/timer/use_timer.ts:66

useUpdatefunctionhooknacatamalon

useUpdate(callback: (delta: number, time: number) => void) => void

Runs your code once per frame, for as long as the scene is on screen.

The function you pass receives delta: how many seconds the last frame took, about 0.016 on a 60 Hz screen and about 0.008 on a 120 Hz one. Multiply by it whenever something moves or counts down, and the game runs at the same speed on every machine. Ignore it, and the same game is twice as fast on a better screen.

It also receives time: the seconds the scene has been running. It is what a sine wave, a blink or a pulse wants, so nothing needs its own counter. It is game time, like delta: it stops while the scene is paused, follows timeScale, and starts again from zero when the scene does. Every object in the scene reads the same clock, so two things that pulse together stay together, whenever each one was spawned.

Call it in the scene body, next to the sprites. It only registers the function, it does not run it: from then on the game loop calls it every frame, and stops when the scene does.

Parámetros

callback(delta: number, time: number) => void

What to run each frame. delta is the seconds since the previous frame, and time the seconds since the scene started.

Ejemplo

export const Level: TSceneFn = () => {
    const hero = createSprite({ key: 'hero', transform: { x: 40, y: 112 } });

    useUpdate((delta) => {
        // 100 pixels per second, whatever the screen does
        hero.transform.x += 100 * delta;
    });

    const coin = createSprite({ key: 'coin', transform: { x: 200, y: 100 } });
    useUpdate((delta, time) => {
        // bobs up and down once a second
        coin.transform.y = 100 + Math.sin(time * Math.PI * 2) * 4;
    });

    return createScene();
};
Ver el código · hooks/loop/use_update.ts:47

TTimerHandletypenacatamalon

One waiting call, handed back by after and every so it can be called off.

Propiedades

cancel
doneboolean

Whether it is over: an after that has run, or anything cancelled. An every is never done on its own.

Ver el código · hooks/timer/types/t_timer.ts:8