NarraLeaf

Game

The Game class, covering preference, audio bus, and key map properties, plugin registration, configuration, and lifecycle events.

Game is the main class that represents the game itself. It contains all the game's configuration and LiveGames

A Game belongs to the GameProvider that owns it — a provider constructs one, and separate providers own separate games. Reach the one you are inside with the useGame() hook.

Public Properties

preference

the Preference instance

game.preference.setPreference("autoForward", true);

audioBuses

The audio bus mixer: the tree declared in GameConfig.audioBuses, and what the player has done to it. Available at any point after new Game(...) — before the audio context has unlocked and before the player has mounted.

game.audioBuses.setVolume("alice", 0.5);
localStorage.setItem("mixer", JSON.stringify(game.audioBuses.getVolumes()));

keyMap

Key binding manager of the game

game.keyMap.setKeyBinding(KeyBindingType.skipAction, "Control");

Public Methods

getLiveGame

  • return: LiveGame - the LiveGame instance

configure

Assign a new configuration to the game

Note: This method is designed to be used before the game is initialized.

Calling this method after the game is initialized will not take effect or not taking effect immediately. Settings in the Preference will take effect immediately.

const game = useGame();

useEffect(() => {
    game.configure({
        ratioUpdateInterval: 0, // update the player size immediately

        /* cursor */
        cursor: "cursor.jpeg",
        cursorHeight: 60,
        cursorWidth: 60,
    });
}, []);

use

Register a plugin to the game.

Note: Plugins with the same name will not be registered.

A name consists of namespace and name is recommended.
Ex: "@Namespace/PluginName", "@Author/PluginName", "PluginName"

game.use({
    ... /** plugin register config */
});
  • plugin: IGamePluginRegistry - The plugin registry config, see Plugin

dispose

Dispose the game and release all the resources.

Note: This action is irreversible.

game.dispose();

configureAndFreeze

Configure the game and freeze specific fields to prevent further modifications.

Warning: This method is not recommended to be used without using NarraLeaf Engine or Plugin Environment.

game.configureAndFreeze({
    ratioUpdateInterval: 0,
    cursor: "cursor.jpeg"
});
  • config: DeepPartial<GameConfig> - The game configuration to apply and freeze

freeze

Freeze specific configuration fields to prevent further modifications.

Warning: This method is not recommended to be used without using NarraLeaf Engine or Plugin Environment.

game.freeze(["ratioUpdateInterval", "cursor"]);
  • fields: (StringKeyOf<GameConfig>)[] - Array of configuration field names to freeze

Lifecycle Events

Two points in a game's start-up can be listened for. Each fires at most once per game lifecycle, and every listener receives the same context object: {game, gameState, liveGame, storable, scene}, where scene may be null.

preloadComplete moved in 0.17.0. It now fires before the game is entered, while a menu may still be on screen — not after newGame() has mounted a scene. Use it to gate a loading step; use firstSceneReady for "the game has content on screen". See Preloading.

onPreloadComplete

Listen for the initial preload pass completing. Since 0.17.0 this is before the game is entered.

const token = game.onPreloadComplete(({scene}) => {
    setLoadingBarDone(true);
});

token.cancel();

oncePreloadComplete

Same, removed after the first call.

whenPreloadComplete

Resolve when the initial preload pass has completed. Resolves immediately if it already has, so this is the safe form when the listener may be registered late.

const {scene} = await game.whenPreloadComplete();
  • return: Promise<GameLifecycleEventContext>

isPreloadComplete

Whether the initial preload pass has completed.

  • return: boolean

onFirstSceneReady

Listen for the first scene being fully ready: the preload pass has finished, the first scene component has mounted, and the browser has had a frame to render it. This is the most direct signal that the game is visually ready for the player.

const token = game.onFirstSceneReady(() => hideLoadingOverlay());

token.cancel();

onceFirstSceneReady

Same, removed after the first call.

whenFirstSceneReady

Resolve when the first scene is fully ready. Resolves immediately if it already is.

await game.whenFirstSceneReady();
  • return: Promise<GameLifecycleEventContext>

isFirstSceneReady

Whether the first scene is fully ready.

  • return: boolean

On this page