NarraLeaf-React Core

Core is the main functionality of NarraLeaf-React. It provides the basic building blocks for creating a Visual Novel with React.

If you have not read the Quick Start yet, we recommend you to read it first. It will help you understand the basic concepts of NarraLeaf-React.

If you are looking for some components such as Player, GameProviders, or Top, you can find them in the Player section.

Core

Core is the main functionality of NarraLeaf-React. You can use its abstract classes to create a story. It has three parts:

Elements are the basic building blocks of NarraLeaf-React. They are used to create actions in the story.
Animation is used to create complex animations for the elements.
Game is the main class that represents the game's current state. For example, you can use LiveGame to save and load the game.

Core Concepts

Before we start, let's understand some core concepts of NarraLeaf-React.

NarraLeaf is based on the concept of Scenes, Elements, and Actions.

Scenes contain actions, and actions are generated by elements.

For example:

import {Scene, Character} from "narraleaf-react";
 
const scene1 = new Scene("scene-1-wake-up");
const character1 = new Character("John Smith");
const character2 = new Character("Alice");
 
scene1.action([
    character1
        .say("Hello, World!")
        .say("Good morning!"),
    character2
        .say("Hi, John!")
        .say("How are you?")
]);

In this example, we have a scene with two characters. The first character says "Hello, World!" and "Good morning!", and the second character says "Hi, John!" and "How are you?"

These two characters are elements, the scene is a scene, and the actions are the dialogues.

The code preceding will output actions like this:

Initialize the scene scene-1-wake-up.
Character John Smith says "Hello, World!"
Character John Smith says "Good morning!"
Character Alice says "Hi, John!"
Character Alice says "How are you?"

Scene

A Scene is a collection of Actions that are executed in order. You can use a Scene to create a conversation, a choice, or a cutscene.

For example, you can use a Scene to represent a conversation organized by background, time, or process.

A basic story may contain these Scenes:

scene-1-wake-up: The protagonist wakes up in the morning.
scene-2-go-to-school: The protagonist goes to school.
scene-3-meet-friend: The protagonist meets a friend.

A scene using multiple backgrounds is also possible.

Element

An Element is a basic unit of a story. It can be a character, an image, or a sound.

For example, you can use Character to represent a character in the story. It can show a dialog. Also, you can use Image to represent an image in the story. It can show characters.

Note: Character only shows the dialog, and Image only shows image. They're separated.

Here's a tree that shows the relationship:

Scene
- Sentence
- Word
Image
Sound
Menu
Script
Condition
Control
Text

Transform
Transition

As you can see, here are some basic elements in NarraLeaf-React.
We will use these elements to create a story in the next section.

Action

Action is the most important concept in NarraLeaf-React.

Every method you call on the elements is an Action. Action can do something, like show a dialog, play a sound, or change the background. NarraLeaf-React can only understand Actions.

For example, you can use character.say to show a dialog.

import {Character} from "narraleaf-react";
 
const character1 = new Character("John Smith");
character1.say("Hello, World!"); // This is an action

Some elements can receive actions, ex. Scene
Scene will execute actions in order.

import {Scene, Character} from "narraleaf-react";
 
const scene1 = new Scene("scene-1-wake-up");
const character1 = new Character("John Smith");
const character2 = new Character("Alice");
 
scene1.action([
    character1
        .say("Hello, World!")
        .say("Good morning!"),
    character2
        .say("Hi, John!")
        .say("How are you?")
]);

Finally, you can use a story to wrap the scenes.

import {Story} from "narraleaf-react";
 
/*
...your scenes
*/
 
const story = new Story();
story.entry(scene1);
 
export default story;

When you're placing the Player component in your React app, you can import the story and pass it to the Player component. We will talk about this later.

Create Story

Construct a Story

Story is the bigggest concept in NarraLeaf-React. You can define a story in a typescript file and export it.

import {Story,Scene} from "narraleaf-react";
 
const story = new Story("My First NarraLeaf Story"); // a human-readable name

After that, you can add an entry point to the story.

const scene1 = new Scene("scene1", {});
 
story.entry(scene1);

Finally, you can export the story and use it in your React app.

"use client";
 
import { GameProviders, Player } from "narraleaf-react";
import { story } from "./scene1"; // your story
 
export default function App() {
    return (
        <GameProviders>
 
            <Player 
                story={story} // your story
            />
 
        </GameProviders>
    );
}

Add Actions

To show something on the screen, you need to add actions to the story.

The basic action container is Scene. You can create a scene like this:

const scene1 = new Scene("Scene 1");

And then, you can add actions to the scene.

const character1 = new Character("Character 1");
 
scene1.action([
    character1
        .say("Hello World!")
        .say("Good morning!"),
]);

Your story will execute the actions in order. It will show the dialog "Hello World!" and "Good morning!" on the screen.

Read more about Element in the Elements section.

Example

Here is an example of a complete story.

import {
    Story,
    Scene,
    Character,
} from "narraleaf-react";
 
// Create a story
const story = new Story("My Story");
const scene1 = new Scene("Scene 1", {
    background: {
        url: "https://via.placeholder.com/1920x1080"
    },
});
 
// define your characters
const character1 = new Character("Character 1");
const character2 = new Character("Character 2");
 
// add actions to the scene
scene1.action([
    character1
        .say("Hello World!")
        .say("Welcome to NarraLeaf!")
        .say("This is a Visual Novel framework for React.")
        .say("I hope you enjoy it!"),
 
    character2
        .say("Start your story by editing this file.")
        .say("We have a lot of features for you."),
]);
 
// add the scene to the story
story.entry(scene1);
 
export { story };

Next Steps

Let's start creating complex stories with NarraLeaf-React. Read more about the Elements to learn how to create more complex actions.

Elements→

Voice Elements