Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sanchedev/tiny-engine/llms.txt

Use this file to discover all available pages before exploring further.

Scene is a lightweight wrapper around a game’s root Node. It holds a factory function that returns (or resolves to) a Node, enabling both synchronous eager initialization and asynchronous lazy loading. The SceneManager tracks all registered scenes and controls which one is currently active.

​
Scene

​
Constructor

new Scene(render: () => Node | Promise<Node>)
​
render
() => Node | Promise<Node>
required
A function that returns the root Node for this scene, or a Promise that resolves to one. This function is not called until scene.load() is invoked — keeping asset imports deferred until the scene actually activates.

​
scene.load()

Calls render(), awaits the result, validates that the return value is a Node instance, and returns it. Throws InvalidSceneRootError if the resolved value is not a Node. 
const node = await scene.load()
You rarely need to call load() manually — SceneManager.addScene() (with autoLoad = true) and SceneManager.setScene() call it for you.

​
Eager scene (no lazy loading)

Pass a plain synchronous function when the scene’s assets are already available. The Node is constructed immediately when load() is called. 
import { Scene } from 'tiny-engine'
import { Node } from 'tiny-engine'

const menuScene = new Scene(() =>
  new Node({
    children: [titleNode, startButton],
  }),
)

​
Lazy scene (async import)

Wrap a dynamic import() inside an async function to defer loading the scene module — and any heavy assets it imports — until the scene is first activated. 
// In your bootstrap file
const gameScene = new Scene(
  async () => (await import('./scenes/game.js')).default,
)

// scenes/game.js
const game = new Node({
  children: [ /* ... */ ],
})

export default game
Lazy loading is especially valuable for large scenes with many textures or audio files. Only the scenes the player actually visits will ever be loaded, keeping initial startup fast.

​
SceneManager

SceneManager is available as the singleton Game.sceneManager. It maintains a map of named scenes and exposes methods to register, preload, and switch between them. See Game for how to access the instance.

​
sceneManager.addScene(name, scene, autoLoad?)

Registers a scene under a string key. If autoLoad is true, immediately calls setScene(name), loading the scene and making it the active node. 
await Game.sceneManager.addScene('menu', menuScene)
await Game.sceneManager.addScene('game', gameScene, true) // activate immediately
​
name
string
required
A unique string identifier for the scene. Used with setScene() and preloadScene() to reference the scene later.
​
scene
Scene
required
The Scene instance to register.
​
autoLoad
boolean
When true, the method awaits setScene(name) after registering the scene, making it the active scene immediately. Defaults to false.

​
sceneManager.setScene(name | null)

Destroys the current scene’s root node, clears internal state, loads the named scene, and sets it as the active node. Pass null to unload everything without activating a new scene. 
await Game.sceneManager.setScene('menu')
await Game.sceneManager.setScene(null) // unload current scene
​
name
string | null
required
The name of the scene to activate, or null to clear the active scene. Throws SceneNotFoundError if the name has not been registered.

​
sceneManager.preloadScene(name)

Loads the named scene in the background while the current scene keeps running. Returns a setter function; call that function when you want to make the preloaded scene active (e.g., after a transition animation finishes). 
const activateNext = await Game.sceneManager.preloadScene('level-2')

// ... later, when the transition is done
activateNext()
​
name
string
required
The registered name of the scene to preload. Throws SceneNotFoundError if not found.

​
sceneManager.currentNode

Read-only. Returns the root Node of the currently active scene, or null if no scene is active. 
const node = Game.sceneManager.currentNode

​
sceneManager.currentScene

Read-only. Returns the string name of the currently active scene, or null if no scene is active. 
console.log(Game.sceneManager.currentScene) // "menu"

​
Scene transition example

import { Game, Scene } from 'tiny-engine'

// Register all scenes up front (none loaded yet)
Game.sceneManager.addScene('menu', new Scene(
  async () => (await import('./scenes/menu.js')).default,
))
Game.sceneManager.addScene('level-1', new Scene(
  async () => (await import('./scenes/level1.js')).default,
))

// Activate the first scene
await Game.sceneManager.setScene('menu')

// Somewhere inside gameplay logic — switch to level 1
await Game.sceneManager.setScene('level-1')

Build docs developers (and LLMs) love

Get started for freeTalk to us