NarraLeaf

Play a Story

Create a Story and set its entry scene.

story.ts
import { Character, Scene, Story } from "narraleaf-react";

const alice = new Character("Alice");
const opening = new Scene("opening", {
    background: "/backgrounds/room.webp",
}).action([
    alice.say("Good morning."),
]);

export const story = new Story("My Story").entry(opening);

Render the story inside GameProviders, then start it from Player.onReady.

Game.tsx
"use client";

import { GameProviders, Player } from "narraleaf-react";
import { story } from "./story";

export default function Game() {
    return (
        <GameProviders>
            <Player
                story={story}
                width="100%"
                height="100%"
                onReady={({ liveGame }) => liveGame.newGame()}
            />
        </GameProviders>
    );
}

GameProviders supplies the game, router, scaling, and preload contexts. Hooks such as useGame, useLiveGame, and useRouter must run below this provider.

Start after the first frame is ready

onReady means the Player instance is initialized. If an outer loading screen must stay visible until the first scene has rendered, use onFirstSceneReady for that UI state. Starting the story still belongs in onReady.

<Player
    story={story}
    onReady={({ liveGame }) => liveGame.newGame()}
    onFirstSceneReady={() => setLoading(false)}
/>

Note that onPreloadComplete is a different point: since 0.17.0 the entry scene is warmed as soon as the story is loaded, so that callback fires before the game is entered, while a menu may still be on screen. See Preloading.

To share a configured game instance with the provider, create it once and pass it through game:

import { Game, GameProviders, Player } from "narraleaf-react";

const game = new Game({ waitForPreload: true });

<GameProviders game={game}>
    <Player story={story} onReady={({ liveGame }) => liveGame.newGame()} />
</GameProviders>

On this page

Start after the first frame is ready