SceneManager switches between full-screen scenes, loads scenes ahead of time, adds scenes on top of the current one, and finds the scenes that are showing. See Scene Manager for what happens during a switch, step by step.
Scenes are named by their file name, in lower case with spaces turned into underscores, so Main Menu.mmsc is "main_menu". Every method that takes a scene also takes a scene picked in a File variable (an AssetRef), so SceneManager.AttachScene(this.vars.menu, this.dom.overlay) works without looking up its name.
| Member | Description |
|---|---|
SwitchScene() |
Fades to another full-screen scene |
GetCurrentScene() |
The name of the full-screen scene |
GetScene() |
The newest showing copy of a scene |
GetScenes() |
Every showing copy of a scene |
AttachScene() |
Shows a scene inside an element |
DetachScene() |
Removes an attached scene |
GetAttachedScenes() |
The names of the attached scenes |
Preload() |
Loads a scene and its images and audio |
LoadScene() |
Loads a scene's file |
ShowNextStartScene() |
Moves on from a splash screen |
Switching scenes
SwitchScene
SceneManager.SwitchScene(name: SceneName, fadeDuration = 1, fadeHold = 1): Promise<void>
Fades the screen to black, removes the current full-screen scene, and fades in a fresh copy of another.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
SceneName |
The scene to switch to | |
fadeDuration |
number |
1 |
Seconds to fade out, and again to fade in. 0 switches straight away |
fadeHold |
number |
1 |
Seconds to stay black between the two |
Returns a promise that resolves once the new scene has been added and its onEnter() and onStart() have been called. It doesn't wait for the fade back in.
How it works
- The new scene starts loading as soon as you call it, so loading overlaps the fade.
- The old scene's
onExit()runs once the screen is black and the hold has passed. - Switching to the scene that's already showing starts it again from scratch.
- Scenes added with
AttachScenearen't affected. - If the scene doesn't exist, a "Scene missing" message is shown in its place.
Example
onPlayPressed() {
SceneManager.SwitchScene("level_1");
},
onDied() {
SceneManager.SwitchScene("game_over", 0.3, 0); // a quick cut, with no pause on black
},
GetCurrentScene
SceneManager.GetCurrentScene(): SceneName
Returns the name of the full-screen scene. It changes as soon as a switch reaches the black screen.
Example
onOpenSettings() {
Store.Set("returnTo", SceneManager.GetCurrentScene()); // remember where to come back to
SceneManager.SwitchScene("settings");
},
onCloseSettings() {
SceneManager.SwitchScene(Store.Get("returnTo", "main_menu"));
},
Finding scenes
Every scene that's showing can be found by name, whether it's full screen, attached, or inside a Scene node. To reach a sub-scene inside your own scene, use this.dom.<id>.scene instead (see Scene Script (this)).
GetScene
SceneManager.GetScene(name: SceneName): SceneObject | undefined
Returns the newest showing copy of a scene, or undefined if none is showing.
How it works
The result isn't typed from the scene's script, so its methods don't autocomplete. Check a method exists before calling it.
Example
onCoinCollected() {
SceneManager.GetScene("hud")?.addCoins?.(1); // the hud scene has an addCoins method
},
GetScenes
SceneManager.GetScenes(name: SceneName): SceneObject[]
Returns every showing copy of a scene, oldest first, or an empty array.
Example
onMagnetPickedUp() {
for (const coin of SceneManager.GetScenes("coin")) {
coin.flyToPlayer?.();
}
},
Attaching scenes
An attached scene is shown inside an element, on top of or alongside the full-screen scene, for things like a pause menu, a HUD, coins or characters. You can attach as many copies of the same scene as you like. Each one stays until you detach it, or until the scene whose element it's in exits. One attached to an element outside every scene, such as document.body, stays when the full-screen scene changes.
AttachScene
SceneManager.AttachScene(name: SceneName | AssetRef<"scene">, target: Element | string): Promise<SceneObject>
Loads a scene, with its images and audio, and adds a fresh copy of it inside an element.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
SceneName | AssetRef<"scene"> |
The scene to show, by name or from a File variable | |
target |
Element | string |
The element to put it in, or a CSS selector that finds it anywhere on the page |
Returns a promise of the copy it attached, resolved once the scene has been added and its onEnter() and onStart() have run. It's rejected if the selector finds nothing or the scene can't be loaded.
How it works
- Each call adds another copy, with its own script and variables. Keep the copy it returns if you want to remove just that one later.
- To attach something only once, such as a menu, check
GetAttachedScenes()first (see its example). - The copy isn't typed from the scene's script, so its methods don't autocomplete. Check a method exists before calling it.
- Its
parentSceneis the scene the element is in, or the innermost one if that scene is inside another. It's set before the copy'sonEnter()runs, and it'snullif the element isn't inside any scene. - When that scene exits, the attached copy is detached too, and its
onExit()runs after the parent's. You don't need to detach it yourself. - You can't give it starting variables. Its
varscan be changed once it's attached, after itsonStart()has run.
Example
async onPausePressed() {
Revealer.Pause();
// pause_menu's parentScene is this scene, because overlay is one of its elements
const menu = await SceneManager.AttachScene("pause_menu", this.dom.overlay);
menu.focusFirstButton?.(); // the pause_menu scene has a focusFirstButton method
},
// Scatters five coins across the field. Each is its own copy of the coin scene.
async onStart() {
for (let i = 0; i < 5; i++) {
const coin = await SceneManager.AttachScene("coin", this.dom.field);
coin.root.style.position = "absolute"; // so left moves the whole coin
coin.root.style.left = `${100 + i * 150}px`;
}
},
DetachScene
SceneManager.DetachScene(target: SceneName | AssetRef<"scene"> | SceneObject): void
Removes copies added with AttachScene. Their onExit() runs and their elements are removed.
| Parameter | Type | Default | Description |
|---|---|---|---|
target |
SceneName | AssetRef<"scene"> | SceneObject |
One copy, such as the one AttachScene returned or this inside it, or a scene's name to remove every attached copy of it |
How it works
- Does nothing for a copy that isn't attached, or a name with no attached copies.
- A copy can remove itself with
SceneManager.DetachScene(this), for example from its own close button. - It doesn't work for scenes in Scene nodes. Hide those with
this.root.hide()from inside the sub-scene instead.
Example
// In the coin scene's own script: removes just this coin
onCollected() {
this.parentScene?.addScore?.(1); // tell the scene the coin is in
SceneManager.DetachScene(this);
},
// In the level's script: clears every coin that's left
onLevelReset() {
SceneManager.DetachScene("coin");
},
GetAttachedScenes
SceneManager.GetAttachedScenes(): SceneName[]
Returns the names of the scenes added with AttachScene that haven't been detached, each name once however many copies there are. Use GetScenes(name) to get the copies themselves.
Example
onEscapePressed() {
if (SceneManager.GetAttachedScenes().includes("pause_menu")) SceneManager.DetachScene("pause_menu");
else SceneManager.AttachScene("pause_menu", this.dom.overlay);
},
Loading
Preload
SceneManager.Preload(name: SceneName): Promise<void>
Loads a scene's file, the images and audio it uses, and those of the scenes inside it, without showing it. Switching to it later then has nothing to wait for.
Returns a promise that resolves when everything has loaded, or after 10 seconds, whichever comes first. It's never rejected. Files that fail to load are skipped with a warning.
Example
onStart() {
SceneManager.Preload("level_1"); // loads in the background while the player reads the menu
},
LoadScene
SceneManager.LoadScene(name: SceneName): Promise<void>
Loads only a scene's file, not its images or audio. SwitchScene, AttachScene and Preload do this for you, so it's rarely needed.
Returns a promise that resolves when the scene is ready to show. It's rejected if the file can't be loaded, and calling it again tries again.
Example
async onStart() {
try {
await SceneManager.LoadScene("bonus_level");
} catch {
this.dom.bonus_button.hide(); // the bonus scene isn't in this build
}
},
ShowNextStartScene
SceneManager.ShowNextStartScene(): void
Moves on to the next splash screen, or to the project's start scene after the last one. Splash screens without an auto-advance time call this themselves, usually when clicked. See Making a Splash Screen.
How it works
Reaching the start scene this way also clears the autosaves (see SaveManager).
Example
onStart() {
this.root.addEventListener("click", () => SceneManager.ShowNextStartScene());
},