LiveGame

Returns the Storable instance

The same instance for the life of the LiveGame — newGame() and deserialize() rebuild the namespaces inside it, not the store itself, which is why a subscription made through Watching stored values survives both.

• return: Storable - Storable

Returns the Storable instance

const {game} = useGame();
const storable = game.getLiveGame().storable;

// is equivalent to
const storable = game.getLiveGame().getStorable();

• return: Storable - Storable

Starts a new game

• return this

Load a saved game

After calling this method, the current game state will be lost, and the stage will trigger force reset

**Note: **Even if you change just a single line of script, the saved game might not be compatible with the new version

Example:

const savedGame = {
    // ...saved game data
};

// use hook inside a component
const {game} = useGame();

// pass the saved game data to the game instance
game.getLiveGame().deserialize(savedGame);

• savedGame: SavedGame - SavedGame

Serialize the current game state

You can use this to save the game state to a file or a database

**Note: **Even if you change just a single line of script, the saved game might not be compatible with the new version

• return: SavedGame - See SavedGame`

Called when a character says something

• fc: (event: LiveGameEvent["event:character.prompt"]) => void - See LiveGameEvent
• Returns LiveGameEventToken - See LiveGameEventToken

const {game} = useGame();
const [texts, setTexts] = useState<string[]>([]);

useEffect(() => {
    const token = game.getLiveGame().onCharacterPrompt((event) => {
        setTexts((prevTexts) => [...prevTexts, event.text]);
    });

    return () => {
        token.cancel();
    };
}, []);

return (
    <div>
        {/* Your Text Log */}
    </div>
);

Called when a menu is completed

• fc: (event: LiveGameEvent["event:menu.choose"]) => void - See LiveGameEvent
• Returns LiveGameEventToken - See LiveGameEventToken

Capture the game screenshot, will only include the player element

Returns a PNG image base64-encoded data URL

**Note: **Image returned by this method is not compressed, and it is not affected by the screenshotQuality option

const {game} = useGame();

function handleButtonClick() {
    game.getLiveGame().capturePng().then((dataUrl) => {
        // do something with the dataUrl
    });
}

• Returns Promise<string>

Capture the game screenshot, will only include the player element

Returns compressed JPEG image data URL

• Returns Promise<string>

Capture the game screenshot, will only include the player element

Returns an SVG data URL

• Returns Promise<string>

Capture the game screenshot, will only include the player element

Returns a PNG image blob

• Returns Promise<Blob | null>

Request full screen on Chrome/Safari/Firefox/IE/Edge/Opera, the player element will be full screen

Note: this method should be called in response to a user gesture (for example, a click event)

Safari iOS and Webview iOS aren't supported, for more information, see MDN-requestFullscreen

• options?: FullscreenOptions | undefined
• Returns Promise<void> | void

Exit full screen

• Returns Promise<void> | void

Listen to the events of the player element

const {game} = useGame();

useEffect(() => {
    return game.getLiveGame().onPlayerEvent("click", (event) => {
        // do something
    }).cancel;
}, []);

• type: K - The event type
• listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any - The event listener
• options?: boolean | AddEventListenerOptions
• Returns LiveGameEventToken

Get the game history. This method is used to create backlog.

The backlog is every line read up to and including the one the game is on. Since save format v2 it is persisted, so this returns the full history immediately after deserialize — a loaded game no longer starts with an empty backlog.

After undo has stepped back, the lines beyond the play head are not here. They are a future the player can step into again, and getFuture returns those — a backlog listing them would be showing what has not happened yet.

import { useLiveGame, GameHistory } from "narraleaf-react";

const liveGame = useLiveGame();
const history = liveGame.getHistory();

function handleRestore(entry: GameHistory) {
    liveGame.restoreToHistory(entry.token);
}

return (
    <div>
        <h3>Backlog</h3>

        {history.map((item) => (
            <div
                key={item.token}
                onClick={() => handleRestore(item)}
            >
                {/* show the action text */}
                {/* text is available when the action is "say" or "menu" */}
                {item.element.text}
            </div>
        ))}
    </div>
);

An entry's token keeps naming its line across saves and rewinds, so a backlog UI can hold one and use it later.

• Returns GameHistory[] - The game history, see GameHistory

The lines ahead of the play head: read once, stepped back past with undo, and reachable again with redo.

Empty during ordinary play, and empty right after loading a save — a save written after stepping back carries the backlog up to that line and nothing beyond it, so loading it opens there with nothing to step forward into. That is what saving in the past means.

const liveGame = useLiveGame();

// The lines the player stepped back past, oldest first.
const future = liveGame.getFuture();

• Returns GameHistory[] - The lines ahead, see GameHistory

Whether there is a line before this one to step back to.

<button disabled={!liveGame.canUndo()} onClick={() => liveGame.undo()}>
    Back
</button>

• Returns boolean

Whether a line stepped back past is waiting ahead.

<button disabled={!liveGame.canRedo()} onClick={() => liveGame.redo()}>
    Forward
</button>

• Returns boolean

Step back one line.

liveGame.undo();

• Returns boolean - true if the game moved; false if this is already the first line, or that line carries no snapshot.

Backward and forward are one mechanism: every line records a self-contained snapshot of the game as it is reached, and moving in either direction restores the snapshot of the line being moved to.

Stepping back works after loading a save. Before 0.26.0, undo walked a stack of closures held in memory and nothing else. Closures cannot be written to a file, so loading a save left the player with a backlog they could not step back into — the button was there and did nothing. The live stack is still the preferred route while it can reach the line, precisely because it steps back without disturbing anything: the music keeps playing, running transitions are left alone, and the stage is not rebuilt. The snapshot takes over where the stack stops, so the boundary is no longer there.

Reading forward again keeps what is ahead. The line stepped back from is not discarded. Stepping back three lines and then reading forward retraces those same lines rather than overwriting them, so the rest of what had been read is still ahead. The future is dropped only when the story goes somewhere else — the other side of a choice — because that future no longer follows from where the story is.

Step forward one line, into a line stepped back past.

liveGame.redo();

• Returns boolean - true if the game moved; false if there is nothing ahead, or it carries no snapshot.

This only reaches lines the player has already read: it replays the recorded future rather than running the story on. To carry on past the end of the future, let the game advance normally.

Move the game to a recorded line, named by its token.

The same mechanism as undo and redo, and it reaches in either direction: a token from getHistory steps back, one from getFuture steps forward. Like both of them it works after loading a save, and it discards nothing — the lines past the one it moves to stay reachable.

const history = liveGame.getHistory();

// Jump to a line — including one restored from a loaded save.
liveGame.restoreToHistory(history[0].token);

• token: string - The token of the history item to move to, see GameHistory.
• Returns boolean - true if the line was restored; false if the token is unknown or the entry has no restore snapshot.

Create a notification.

The style of the notification is defined by Notification.

// notify for 3 seconds
game.notify("Save success", 3000);

// to control the notification, set the duration to `null` to make the notification stay forever
const token = game.notify("Fast forward", null);

// cancel the notification when the player releases the right key
window.addEventListener("keyup", (event) => {
    if (event.key === "ArrowRight") {
        token.cancel();
    }
});

• message: string - The message to notify
• duration?: number | null - The duration of the notification, default is 3000ms. Set to null to make the notification stay forever.
• Returns NotificationToken - See NotificationToken

Play a sound immediately and return its SoundToken.

const {game} = useGame();

game.getLiveGame()
    .playSound("https://example.com/voice.mp3")
    .then((token) => {
        token.once("ended", () => {
            console.log("Voice playback completed");
        });
    });

The clip starts at the volume its Sound was configured with — Sound.voice({src, volume: 0.4}) starts at 0.4, not at full volume. A source given as a string or URL becomes a default Sound, which is full volume; pass a Sound to say otherwise.

• sound: Sound | string | URL - The sound instance, sound source string, or URL
• Returns Promise<SoundToken> - See @NarraLeaf/Sound for more information about the soundToken instance

Wait for the router to exit.

This method is useful when you want to create a new game and wait for the router to exit.

const {game} = useGame();
const router = useRouter();
const liveGame = game.getLiveGame();

useEffect(() => {
    router.clear().cleanHistory();

    const token = liveGame
        .newGame()
        .waitForRouterExit()
    
    token
        .promise
        .then(() => {
            dispatchState({ isPlaying: true });
        });

    return () => {
        token.cancel();
    };
}, []);

• Returns { promise: Promise<void>; cancel: VoidFunction; }

Wait for the page to mount

const {game} = useGame();
const router = useRouter();
const liveGame = game.getLiveGame();

useEffect(() => {
    router.push("home");
    const token = liveGame.waitForPageMount();

    token.promise.then(() => {
        // do something
    });

    return () => {
        token.cancel();
    };
}, []);

• Returns { promise: Promise<void>; cancel: VoidFunction; }

Listen to the events of the window

const {game} = useGame();

useEffect(() => {
    return game.getLiveGame().onWindowEvent("resize", (event) => {
        // handle window resize
    }).cancel;
}, []);

• type: K - The event type
• listener: (this: Window, ev: WindowEventMap[K]) => any - The event listener
• options?: boolean | AddEventListenerOptions
• Returns LiveGameEventToken - See LiveGameEventToken

Reset the game state

Note: Calling this method will lose the current game state

const {game} = useGame();
const router = useRouter();

game.getLiveGame().reset();
router.clear().cleanHistory().push("home");

Skip the current dialog

game.getLiveGame().skipDialog();

Fast-forward playback to the next menu, to the end of the story, or to a specific action.

Every line in between is executed for real, so the backlog and its restore snapshots accumulate exactly as in normal play — only faster and silent. Audio is muted for the duration, and the timed pauses the run executes (Control.sleep, auto-forward) resolve at once. It stops as soon as a menu is waiting for a choice, so the choice itself is always left to the player. Because history accumulates the whole way, getHistory and restoreToHistory cover the fast-forwarded span just like normal play.

Skipping a line is a request broadcast to the renderer, not a synchronous state change, so it is re-issued until the line settles. A line that never answers ends the run with "stalled" rather than hanging — this method always settles.

// Jump ahead to the next decision point.
await game.getLiveGame().fastForward();

// Or run to the end of the story.
await game.getLiveGame().fastForward({ until: "end" });

// Or park the play head on a specific action, without running it.
const result = await game.getLiveGame().fastForward({ until: { actionId: "act-42" } });

if (result.reason === "action") {
    // parked on act-42, not yet executed
} else if (result.reachedTarget === false) {
    // a menu blocked the path, the stack drained, maxSteps was hit, or a line stalled
}

• options.until?: "menu" | "end" | { actionId: string } - "menu" (default) stops at the next menu; "end" runs until the story finishes; { actionId } runs until that action surfaces as the next thing to execute and stops just before running it, so the play head is left parked on that line. Only the root execution stack is scanned — an id buried inside an in-flight Control.all / Control.any or async branch is not a stop point. A menu that blocks the path stops an actionId run too, since the target cannot be reached until the player decides.
• options.maxSteps?: number - safety bound on the number of advance steps (defaults to the maxStackModelLoop config).
• options.stepTimeout?: number - how long, in milliseconds, a single suspended line is given to settle before the run reports "stalled". Default 10000. Raise it for a story that fast-forwards through long unskippable media.
• Returns Promise<{ reason: "menu" | "end" | "maxSteps" | "action" | "stalled"; reachedTarget?: boolean }> - why it stopped.
  • reason - "action" reached until.actionId; "menu" a menu is waiting for a choice; "end" the stack drained; "maxSteps" the step cap was hit; "stalled" a line refused to settle within stepTimeout.
  • reachedTarget - present only when until: { actionId } was requested, and true only for reason "action". A "menu" / "end" run keeps its plain { reason } shape.