服务 | NarraLeaf-React

用于构建跨场景共享自定义逻辑的 `Service` 抽象类，涵盖动作、序列化与异步处理

Service 是一个抽象类，用于创建自定义操作与行为，或在多个场景之间共享自定义逻辑

使用时需要继承它，并实现全部抽象方法

import {Service} from "narraleaf-react";

示例

以下是一个实现简单画廊服务的自定义服务示例

type GalleryActions = {
    "add": [name: string]
};

class Gallery extends Service<GalleryActions> {
    // 自定义数据
    unlocked: string[] = [];

    constructor() {
        super();

        // 注册操作处理程序
        this.on("add", (ctx: ServiceHandlerCtx, name: string) => {
            console.log("添加", name);
            this.unlocked.push(name);
        })
    }

    /* 实现 serialize 和 deserialize 方法 */
    serialize(): Record<string, any> | null {
        return {
            unlocked: this.unlocked
        };
    }
    deserialize(data: Record<string, any>): void {
        this.unlocked = data.unlocked;
    }

    /* 自定义服务逻辑 */
    add(name: string) {
        // 触发操作
        return this.trigger("add", name);
    }
}

在游戏中使用该服务：

const gallery = new Gallery();

myScene.action([
    gallery
        .add("image1")
        .add("image2")
        .add("image3"),
]);

创建自定义服务

实现服务

要实现服务，请继承 Service 类并实现抽象方法：

class MyCustomService extends Service {
    /**
     * 将服务序列化为数据
     *
     * **注意**：数据必须是 JSON 可序列化的，如果不需要保存则返回 null
     */
    serialize(): Record<string, any> | null {
        return null;
    }

    /**
     * 将数据加载到服务中
     * @param data 从 toData 导出的数据
     */
    deserialize(data: Record<string, any>): void {
    }
}

注册操作

要注册操作，请使用 on 方法，所有注册都在构造函数中完成：

class MyCustomService extends Service {
    constructor() {
        super();

        this.on("myAction", (ctx: ServiceHandlerCtx, ...args: any[]) => {
            // 自定义逻辑
        });
    }
}

关于 ServiceHandlerCtx 的详细说明见 ServiceHandlerCtx

要启用类型检查，可以定义操作类型：

type MyCustomActions = {
    "myAction": [arg0: string, arg1: number]
};

class MyCustomService extends Service<MyCustomActions> {
    constructor() {
        super();

        this.on("myAction", (ctx: ServiceHandlerCtx, arg0: string, arg1: number) => {
            // 自定义逻辑
        });
    }
}

异步操作

异步操作可以返回一个 promise，同时建议让操作支持中止，以便撤销时能够及时清理：

当玩家在该服务仍在执行时执行撤销（undo）操作，游戏引擎会自动调用当前 Action 上注册的所有 onAbort 回调。脚本有义务中止任何正在进行的任务（网络请求、定时器、动画等）并清理已产生的副作用，以确保再次执行相同操作时能够得到完全一致的结果

this.on("myAction", (ctx: ServiceHandlerCtx, ...args: any[]) => {
    const abortController = new AbortController();
    const { signal } = abortController;
    const promise = fetch("https://example.com", { signal }); // 一些异步操作

    ctx.onAbort(() => {
        abortController.abort(); // 中止异步操作
    });

    return promise; // 返回 promise 时，游戏会等待其解析
});

触发操作

要触发操作，请使用 trigger 方法：

const service = new MyCustomService();

scene.action([
    service.trigger("myAction", "foo", 123)
]);

也可以把操作包装进自定义方法：

class MyCustomService extends Service<MyCustomActions> {
    myAction(arg0: string, arg1: number) {
        return this.trigger("myAction", arg0, arg1);
    }
}

const service = new MyCustomService();

scene.action([
    service.myAction("foo", 123),

    service
        .myAction("foo", 123)  // 操作被包装并可链式调用
        .myAction("bar", 456), // 游戏将自动管理链式行为
]);

访问服务

创建服务后，要在游戏中注册它：

const story = new Story(/* ... */);
story.registerService("gallery", gallery);

之后就可以通过 ctx 访问服务：

// 例如，在组件中
const game = useGame();
const liveGame = game.getLiveGame();

const gallery = liveGame.story?.getService<Gallery>("gallery");

return (
    {gallery && gallery.unlocked.map((name) => (
        <div key={name}>{name}</div>
    ))}
);

公共方法

on<K extends StringKeyOf<Content>>

注册一个操作处理程序

type MyCustomActions = {
    "myAction": [arg0: string, arg1: number]
};

class MyCustomService extends Service<MyCustomActions> {
    constructor() {
        super();

        this.on<"myAction">("myAction", (ctx: ServiceHandlerCtx, arg0: string, arg1: number) => {
            // 自定义逻辑
        });
    }
}

key: K - 操作键
handler: ServiceHandler<Content[K]> - 详细说明参见 ServiceHandlerCtx
返回 this

可链式方法

trigger<K extends StringKeyOf<Content>>

触发一个操作

const service = new MyCustomService();

scene.action([
    service.trigger<"myAction">("myAction", "foo", 123)
]);

key: K - 操作键
...args: Content[K] - 操作参数

服务

本页目录