场景

scene.local 是一个 Persistent 实例，仅限于场景内使用，用于存储仅在该场景中可用的临时数据

本地数据不需要注册或初始化，但在使用前是「未定义」的

当场景退出时，本地数据将被丢弃

scene.action([
    new Menu("你想喝哪种咖啡？")
        .choose("拿铁", [
            scene.local.set("coffee", "latte"),
        ])
        .choose("卡布奇诺", [
            scene.local.set("coffee", "cappuccino"),
        ]),
    character1.say`你选择了 ${scene.local.get("coffee")} 咖啡`,
]);

场景的背景 Image 实例

scene.background
    .char("background.png", new Dissolve({ duration: 1000, easing: "linear" }))

场景的背景层
该层包含场景的背景图像

scene.backgroundLayer.opacity(0.5, 1000, "linear")

场景的可显示层
该层包含所有不属于任何特定层的可显示对象

scene.displayableLayer.opacity(0.5, 1000, "linear")

• name: string - 场景名称
• config?: Partial<ISceneUserConfig> - ISceneUserConfig

向场景添加操作。不要多次调用此方法

重载 1 / 2

• actions: ActionStatements - 要执行的操作，参见 ActionStatements

重载 2 / 2

此重载允许传递一个函数，该函数接收场景实例并返回要执行的操作

在某些情况下，你可能希望为场景实例创建一个快捷方式

story.entry(
    new Scene("scene 1").action(scene => [
        scene
            .setBackground(background)
            .sleep(1000),
    ])
);

• actions: ((scene: Scene) => ActionStatements) - 要执行的操作，参见 ActionStatements
• 返回 this

手动注册图像源

用于预加载器无法自行预测的图像源 —— 最常见的是层叠图像中函数图层返回的源（对预加载器不透明），或是复杂到会触发「未预测的图像源」警告的外观变更

• src: string | string[] - 图像的 URL 或 URL 数组
• 返回 this

scene.background.char 的别名

设置场景的背景。如果提供了过渡效果，背景将通过该过渡效果切换

scene.action([
    scene.setBackground("background.png")

    // 等同于
    scene.background.char("background.png")
]);

• background: Color | ImageSrc - 参见 Color 以及 ImageSrc
• transition?: ImageTransition - 对于 ImageTransition，参见 Transition

跳转到另一个场景。如果提供了过渡效果，它会在两个场景切换期间跨整个舞台播放：立绘、文字以及其他所有层都参与其中，而不只是背景。参见 JumpConfig

注意：普通跳转会释放当前场景，它后面的动作永远不会执行。而带 returnable 的跳转是把当前场景挂起，目标场景的动作跑完就回来，所以跳转后面的动作会执行

• scene: Scene - 要跳转到的场景
• config: Partial<JumpConfig> | Transition - 跳转配置，或直接传过渡本身

// 单向：这个场景就此结束，跳转后面的一行都不会跑
scene.jumpTo(nextScene);

// 调用：这个场景被停在那儿，储藏室跑完之后跳转后面的那一行接着跑
scene.jumpTo(storeroom, {returnable: true});

设置场景的背景音乐

• sound: Sound - Sound 实例
• fade?: number - 如果设置，将对之前的音乐应用淡出、对当前音乐应用淡入，时长以毫秒计

创建 NVL（小说）模式块，用于堆叠显示多条对话。在 NVL 模式下，对话会逐条堆叠在屏幕上，而不是互相覆盖，类似传统视觉小说的旁白形式

重载 1：仅 actions

• actions: ActionStatements | ((nvl: NVLToken) => ActionStatements) - 在 NVL 模式下执行的操作，或接收 NVLToken 的回调，用于手动控制显示/隐藏/结束
• 返回 ChainableAction

scene.action([
    scene.nvl([
        character.say("第一行"),
        character.say("第二行"),
        character.say("第三行"),
    ]),
]);

重载 2：options + actions

• options: Partial<TransformDefinitions.CommonTransformProps> - NVL 层显示/隐藏时的过渡选项（如 { duration: 500 }）。参见 CommonTransformProps
• actions: ActionStatements | ((nvl: NVLToken) => ActionStatements) - 同重载 1
• 返回 ChainableAction

scene.action([
    scene.nvl({ duration: 300 }, [
        character.say("第一行"),
        character.say("第二行"),
    ]),
]);

使用 NVLToken 的回调形式

当传入回调 (nvl) => [...] 时，可使用 nvl.show()、nvl.hide() 和 nvl.end() 显式控制 NVL 层：

scene.action([
    scene.nvl(nvl => [
        character.say("第一行"),
        character.say("第二行"),
        nvl.hide({ duration: 500 }),
        Control.waitForClick(),
        nvl.show({ duration: 500 }),
        character.say("第三行"),
        nvl.end(),
    ]),
]);