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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-scenes-and-state技能说明
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