Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

melonjs-scenes-and-state

Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze.

melonjs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add melonjs/melonJS --skill melonjs-scenes-and-state

About this skill


name: melonjs-scenes-and-state description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze." license: MIT

Scenes, game state and timing

Stages and the state manager

A Stage is a screen. Register it against a state id, then change to it:

import { Stage, state } from "melonjs";

class PlayScreen extends Stage {
    onResetEvent(app) { /* build the scene */ }
    onDestroyEvent(app) { /* tear it down */ }
}

state.set(state.PLAY, new PlayScreen());   // register first
state.change(state.PLAY);                   // then switch

Built-in ids: state.LOADING, state.MENU, state.READY, state.PLAY, state.GAMEOVER (no underscore), state.GAME_END, state.SCORE, state.CREDITS, state.SETTINGS, state.DEFAULT. state.USER (100) is the base for your own ids — const CUTSCENE = state.USER + 1.

Build scene content in onResetEvent, not the constructor. onResetEvent runs on every entry to the state; the constructor runs once. Scene content created in the constructor exists once and is not rebuilt when you return.

onResetEvent(app) receives the Application — use that rather than importing the global game.

Extra arguments to state.change are forwarded:

state.change(state.PLAY, false, { level: 2 });   // → onResetEvent(app, { level: 2 })

The second argument is forceChange: pass true to switch immediately instead of on a deferred tick, which is what you want when changing state right after a preload completes. It is ignored when a transition is configured — a transition always drives the switch from its own completion callback.

onResetEvent runs when the switch is made. The first frame, STATE_CHANGE and a transition's reveal follow once the shaders the stage queued are ready, which is a few milliseconds once the browser has compiled them before, and at most 1.5s on a first visit. So build the stage in onResetEvent: an object a STATE_CHANGE listener adds is not waited for, and its first draw may still compile what it needs. That first frame steps the world once before drawing it, however short it is, so everything onResetEvent added is in it (the same goes for the frame after a level.load made while the game runs). Before 20.12 it was drawn unstepped, and showed the stage's background alone for one frame.

state.change throws Undefined Stage for state '<id>' if nothing was registered for that id, and state.set throws if the second argument is not a Stage instance. Neither fails quietly.

Always leave state.LOADING — it is transitional

loader.preload() switches to state.LOADING for you. Building your scene in the preload callback and then staying there looks like it works, and is one of the easiest mistakes to make:

// WRONG — the game now runs inside the loading stage, forever
loader.preload(assets, () => {
    app.world.addChild(new Player(...));
});

Nothing ever destroys that stage, so the built-in loading screen's logo and progress bar are never removed and sit on top of your game. (Eight of this repository's own examples did this before it was noticed, so it is not an obscure trap.)

Give the scene a stage of its own and switch to it:

class PlayScreen extends Stage {
    onResetEvent(app) {
        app.world.addChild(new Player(...));
    }
}

await loader.preload(assets);
state.set(state.PLAY, new PlayScreen());
state.change(state.PLAY);

The awaited form reads better here than the callback, because "load, then switch" is exactly what the code then says. If you genuinely want to keep using the loading stage as your scene, state.change(state.DEFAULT) at least gets you out of it — but a stage of your own is what you want.

Persistent objects across levels

if (typeof this.HUD === "undefined") {
    this.HUD = new Container();         // construct once (or UIBaseElement)
}
this.HUD.isPersistent = true;           // survives level changes
this.HUD.floating = true;               // screen coordinates, not world
app.world.addChild(this.HUD, 100);      // explicit z — see melonjs-renderables

Transitions and pausing

state.transition("fade", "#FFFFFF", 250);
state.transition("mask", "#000", 500, new Ellipse(0, 0, 1, 1));  // shape required
state.transition("pixelate", "#000", 300);  // blocks up to 32px; a 4th argument sets the size
state.pause();                               // freeze update, keep drawing
state.resume();
app.freeze(150);                             // brief hit-stop (proxies state.freeze)

state.transition is global and sticky — once set it applies to every later state.change. The "mask" form needs its fourth argument, an Ellipse or Polygon; without one it warns and falls back to a direct switch. The "pixelate" form breaks the screen up into blocks (its fourth argument is the largest block size in pixels). It is a shader effect, so on Canvas it does nothing and the state changes directly.

A state.change asked for while a transition covers the screen (Enter pressed twice on a menu, a timer firing as the player skips a screen) needs no guard: the transition already under way makes it, switching to the last state asked for with the last arguments, and a second cover never goes up. A change to a state with no transition of its own (state.setTransition(id, false)) is made at once, and the cover comes down with i

Read the complete source ↗