Player

The Player component's props, including story, sizing, lifecycle callbacks such as onReady and onPreloadComplete, and the active flag.

Player component is used to play the story.

If you are creating a story using abstract classes, please check the Core documentation.

Example

This is a basic example of how to use the Player component:

"use client";

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

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

Props

story

The story object that you want to play.

onReady

A callback function that is called when the player is ready. It returns the ScriptCtx object.

This is where newGame() belongs. It is not a preload or a first-render guarantee — see onPreloadComplete and onFirstSceneReady below.

onPreloadComplete

Called once the initial preload pass has actually completed.

Since 0.17.0 this fires before the game is entered, while a menu may still be on screen and no scene is mounted — the entry scene is warmed as soon as the story is loaded. If you were reading this as "the game has content on screen", use onFirstSceneReady instead. See Preloading.

Receives {game, gameState, liveGame, storable, scene}, where scene may be the preloading scene rather than a mounted one. Called at most once per game lifecycle.

<Player story={story} onPreloadComplete={() => setLoadingBarDone(true)} />

onFirstSceneReady

Called once the preload pass has finished, the first scene 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.

Receives the same context object as onPreloadComplete, and is called at most once per game lifecycle.

<Player story={story} onFirstSceneReady={() => setLoadingOverlay(false)} />

onPreloadedReady

Use onPreloadComplete instead.

onEnd

Called when the player ends.

This callback is called when the story ends.

onError

Called when the game encounters an error.

This callback is only called once per lifecycle and receives two parameters: error and errorInfo.

children

The children of the player.

You can pass the children to the player.

For example, you can use PageRouter API to create your own quick menu.

active

Whether to show the player

Even the active is false, the pages will be rendered

const [active, setActive] = useState(false);

return <Player active={active}/>