NarraLeaf-React 核心

NarraLeaf-React 的元素、动画与 Game 类，及场景与动作如何组成故事

核心是 NarraLeaf-React 的主体，提供了用 React 创作视觉小说的基本构建块

如果你还没读过快速开始，建议先读一遍，它会帮你理解 NarraLeaf-React 的基本概念

如果你要找的是 Player、GameProviders 或 Stage 这类组件，它们在播放器部分

核心

核心是 NarraLeaf-React 的主要功能，你可以用它的抽象类来编写剧本，它由三部分组成：

元素是 NarraLeaf-React 的基本构建块，用于在故事中产生动作动画用于为元素制作复杂动画游戏是代表游戏当前状态的主类。例如，可以用 LiveGame 保存和读取游戏

核心概念

动手之前，先了解 NarraLeaf-React 的几个核心概念

NarraLeaf 基于场景、元素和动作三个概念

场景包含动作，动作由元素产生

例如：

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?")
]);

这个例子中有一个场景和两个角色。第一个角色说「Hello, World!」和「Good morning!」，第二个角色说「Hi, John!」和「How are you?」

两个角色都是元素，场景就是场景，这些台词则对应各自的动作

上面的代码会产生如下动作：

初始化场景 scene-1-wake-up
角色 John Smith 说「Hello, World!」
角色 John Smith 说「Good morning!」
角色 Alice 说「Hi, John!」
角色 Alice 说「How are you?」

场景

场景是按顺序执行的动作集合。可以用场景组织对话、选项或过场动画

例如，可以把按背景、时间或流程划分的对话放进不同的场景

一个简单的故事可能包含这些场景：

scene-1-wake-up：主角早上醒来
scene-2-go-to-school：主角去上学
scene-3-meet-friend：主角遇见朋友

一个场景也可以使用多个背景

元素

元素是故事的基本单元，可以是一个角色、一张图片或一段声音

例如，用 Character 表示故事中的角色，它可以显示台词；用 Image 表示故事中的图像，它可以显示角色

注意： Character 只显示台词，Image 只显示图像，两者相互独立

下图展示了 NarraLeaf-React 中的基本元素

Scene（场景）

Sentence（句子）

Word（单词）

Image（图片）

Sound（声音）

Menu（选项）

Script（脚本）

Condition（条件）

Control（控制）

Text（文本）

Transform（变换）

Transition（过渡）

如你所见，这些就是 NarraLeaf-React 的基本元素，下一节我们会用它们写一段剧本

动作

动作是 NarraLeaf-React 中最重要的概念

你在元素上调用的每个方法都会产生一个动作。动作负责执行显示台词、播放声音、更换背景等操作。NarraLeaf-React 只会执行这些动作

例如，用 character.say 显示台词：

import {Character} from "narraleaf-react";

const character1 = new Character("约翰-史密斯");
character1.say("你好，世界！"); // 这是一个动作

有些元素可以接收动作，比如 Scene，场景会按顺序执行动作

import {Scene, Character} from "narraleaf-react";

const scene1 = new Scene("scene-1-wake-up");
const character1 = new Character("约翰-史密斯");
const character2 = new Character("爱丽丝");

scene1.action([
    character1
        .say("你好，世界！")
        .say("早上好！"),
    character2
        .say("嗨，约翰！")
        .say("你过得怎么样？")
]);

最后，用故事把场景包装起来：

import {Story} from "narraleaf-react";

/*
...你的场景
*/

const story = new Story();
story.entry(scene1);

export default story;

把 Player 组件放进 React 应用时，导入故事并传给 Player 即可，我们稍后会讲到这一步

创建故事

构建故事

故事是 NarraLeaf-React 中最重要的概念。你可以在一个 TypeScript 文件里定义故事并导出

import {Story,Scene} from "narraleaf-react";

const story = new Story("我的第一个NarraLeaf故事"); // 人类可读的名称

然后为故事添加入口点：

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

story.entry(scene1);

最后，导出故事并在 React 应用中使用：

"use client";

import { GameProviders, Player } from "narraleaf-react";
import { story } from "./scene1"; // 你的故事

export default function App() {
    return (
        <GameProviders>

            <Player 
                story={story} // 你的故事
            />

        </GameProviders>
    );
}

添加动作

要在屏幕上显示内容，你需要向故事添加动作

最基本的动作容器是 场景，可以这样创建：

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

然后向场景添加动作：

const character1 = new Character("Character 1");

scene1.action([
    character1
        .say("你好，世界！")
        .say("早上好！"),
]);

故事会按顺序执行动作，在屏幕上依次显示「你好，世界！」和「早上好！」两句台词

更多关于 元素 的内容见元素部分

完整示例

这里是一个完整故事的示例

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

// 创建一个故事
const story = new Story("My Story");
const scene1 = new Scene("Scene 1", {
    background: {
        url: "https://via.placeholder.com/1920x1080"
    },
});

// 定义你的角色
const character1 = new Character("Character 1");
const character2 = new Character("Character 2");

// 为场景添加动作
scene1.action([
    character1
        .say("你好，世界！")
        .say("欢迎来到 NarraLeaf!")
        .say("这是一个为了React开发者而设计的视觉小说框架。")
        .say("我希望你喜欢它。"),

    character2
        .say("编辑这个文件以开始你的视觉小说之旅")
        .say("我们为你准备了很多功能"),
]);

// 将场景添加到故事中
story.entry(scene1);

export { story };

"use client";

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

export default function App() {
    return (
        <GameProviders game={game}>
            <Player 
                // 传入故事到 Player 组件
                story={story} 
                onReady={({game}) => {
                    // 当故事准备好时，开始新游戏
                    game.getLiveGame().newGame();
                }} 
                height={"100vh"} 
            />
        </GameProviders>
    );
}

下一步

用 NarraLeaf-React 创作复杂的故事吧。阅读元素部分，学习如何构建更复杂的动作

元素

学习如何用 NarraLeaf-React 构建更复杂的动作

NarraLeaf-React 核心

元素

本页目录