Project Mammut Wiki
projectmammut.com
Project Mammut is currently in open beta. The UI is being updated a lot during this time, and you may run into bugs. If you'd like to help develop the engine or suggest features, come find us on Bluesky or Discord.

SceneManager

Written 18 Nov 2026 · Updated 19 Nov 2026 · Requires Mammut 0.9.22+

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 AttachScene aren'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 parentScene is the scene the element is in, or the innermost one if that scene is inside another. It's set before the copy's onEnter() runs, and it's null if 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 vars can be changed once it's attached, after its onStart() 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());
},