LiveGame

⚠️

此页面正在建设中

LiveGame 是代表游戏当前状态的主类。

公共属性

game

Game 实例

story

当前 Story 实例

公共方法

getStorable

返回 Storable 实例

return: Storable - Storable

get storable

返回 Storable 实例

const {game} = useGame();
const storable = game.getLiveGame().storable;
 
// 等价于
const storable = game.getLiveGame().getStorable();

return: Storable - Storable

newGame

开始新游戏

return this

deserialize

加载保存的游戏

调用此方法后，当前游戏状态将丢失，舞台将触发强制重置

**注意：**即使只更改一行脚本，保存的游戏也可能与新版本不兼容

示例：

const savedGame = {
    // ...保存的游戏数据
};
 
// 在组件中使用钩子
const {game} = useGame();
 
// 将保存的游戏数据传递给游戏实例
game.getLiveGame().deserialize(savedGame);

savedGame: SavedGame - SavedGame

serialize

序列化当前游戏状态

你可以使用此方法将游戏状态保存到文件或数据库中

**注意：**即使只更改一行脚本，保存的游戏也可能与新版本不兼容

return: SavedGame - 参见 SavedGame

onCharacterPrompt

角色说话时调用

fc: (event: LiveGameEvent["event:character.prompt"]) => void - 参见 LiveGameEvent
返回 LiveGameEventToken - 参见 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>
        {/* 你的文本日志 */}
    </div>
);

onMenuChoose

菜单完成时调用

fc: (event: LiveGameEvent["event:menu.choose"]) => void - 参见 LiveGameEvent
返回 LiveGameEventToken - 参见 LiveGameEventToken

capturePng

捕获游戏截图，仅包含玩家元素

返回 PNG 图像的 Base64 编码数据 URL

const {game} = useGame();
 
function handleButtonClick() {
    game.getLiveGame().capturePng().then((dataUrl) => {
        // 对 dataUrl 进行操作
    });
}

返回 Promise<string>

captureJpeg

捕获游戏截图，仅包含玩家元素

返回压缩后的 JPEG 图像数据 URL

返回 Promise<string>

captureSvg

捕获游戏截图，仅包含玩家元素

返回 SVG 数据 URL

返回 Promise<string>

capturePngBlob

捕获游戏截图，仅包含玩家元素

返回 PNG 图像的 Blob

返回 Promise<Blob | null>

requestFullScreen

在 Chrome/Safari/Firefox/IE/Edge/Opera 上请求全屏，玩家元素将进入全屏模式

注意：此方法应在用户手势（例如，点击事件）的响应中调用

Safari iOS 和 Webview iOS 不支持，更多信息请参见 MDN-requestFullscreen (opens in a new tab)

options?: FullscreenOptions | undefined
返回 Promise<void> | void

exitFullScreen

退出全屏

返回 Promise<void> | void

onPlayerEvent

监听玩家元素的事件

const {game} = useGame();
 
useEffect(() => {
    return game.getLiveGame().onPlayerEvent("click", (event) => {
        // 执行操作
    }).cancel;
}, []);

type: K - 事件类型
listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any - 事件监听器
options?: boolean | AddEventListenerOptions
返回 LiveGameEventToken

getHistory

获取游戏历史。这个方法用于创建回溯。

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

const game = useGame();
const history = game.getHistory();
 
function handleUndo(history: GameHistory) {
    game.undo(history.token);
}
 
return (
    <div>
        <h3>回溯</h3>
 
        {history.map((item) => (
            <div
                key={item.token}
                onClick={() => handleUndo(item)}
            >
                {/* show the action text */}
                {/* text is available when the action is "say" or "menu" */}
                {item.element.text}
            </div>
        ))}
    </div>
);

返回 GameHistory[] - 游戏历史，参见 GameHistory

undo

撤销游戏动作。

game.undo(history.token);

token?: string - 历史项的令牌，参见 GameHistory。如果未提供，则撤销最后一个动作。

notify

创建一个通知。

// 通知 3 秒
game.notify("Save success", 3000);

// 通知持续时间设置为 `null` 时，通知将一直显示
const token = game.notify("Fast forward", null);
 
// 当玩家释放箭头右键时，取消通知
window.addEventListener("keyup", (event) => {
    if (event.key === "ArrowRight") {
        token.cancel();
    }
});

message: string - 通知消息
duration?: number | null - 通知持续时间，默认是 3000ms。设置为 null 时，通知将一直显示。
返回 NotificationToken - 参见 NotificationToken

waitForRouterExit

等待路由退出。

此方法可以用于在创建新游戏时等待路由退出。

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();
    };
}, []);

返回 { promise: Promise<void>; cancel: VoidFunction; }

waitForPageMount

等待页面挂载

const {game} = useGame();
const router = useRouter();
const liveGame = game.getLiveGame();
 
useEffect(() => {
    router.push("home");
    const token = liveGame.waitForPageMount();
 
    token.promise.then(() => {
        // 执行操作
    });
 
    return () => {
        token.cancel();
    };
}, []);

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

onWindowEvent

监听窗口事件

const {game} = useGame();
 
useEffect(() => {
    return game.getLiveGame().onWindowEvent("resize", (event) => {
        // 处理窗口大小调整
    }).cancel;
}, []);

type: K - 事件类型
listener: (this: Window, ev: WindowEventMap[K]) => any - 事件监听器
options?: boolean | AddEventListenerOptions
返回 LiveGameEventToken

reset

重置游戏状态

**注意：**调用此方法将丢失当前游戏状态

const {game} = useGame();
const router = useRouter();
 
game.getLiveGame().reset();
router.clear().cleanHistory().push("home");

skipDialog

跳过当前对话

game.getLiveGame().skipDialog();

GameState Storable