narraleaf-react 0.38.0 → 0.39.1

package/dist/game/nlcore/action/actionTypes.d.ts

@@ -42,6 +42,9 @@ export declare const SceneActionTypes: {
     readonly init: "scene:init";
     readonly exit: "scene:exit";
     readonly jumpTo: "scene:jumpTo";
+    readonly callTo: "scene:callTo";
+    readonly preSuspend: "scene:preSuspend";
+    readonly resume: "scene:resume";
     readonly setBackgroundMusic: "scene:setBackgroundMusic";
     readonly preUnmount: "scene:preUnmount";
     readonly transitionToScene: "scene:transitionToScene";
@@ -55,7 +58,7 @@ export type NvlBlockOptions = {
     hideTransition?: Partial<TransformDefinitions.CommonTransformProps>;
 };
 export type SceneActionContentType = {
-    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [Transition, Scene] : K extends typeof SceneActionTypes["nvlBlock"] ? [LogicAction.Actions[], NvlBlockOptions] : K extends typeof SceneActionTypes["nvlShow"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlHide"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlEnd"] ? [NvlBlockOptions?] : any;
+    [K in typeof SceneActionTypes[keyof typeof SceneActionTypes]]: K extends typeof SceneActionTypes["action"] ? Scene : K extends typeof SceneActionTypes["init"] ? [Scene] : K extends typeof SceneActionTypes["exit"] ? [] : K extends typeof SceneActionTypes["jumpTo"] ? [Scene] : K extends typeof SceneActionTypes["callTo"] ? [Scene] : K extends typeof SceneActionTypes["preSuspend"] ? [Scene] : K extends typeof SceneActionTypes["resume"] ? [Scene] : K extends typeof SceneActionTypes["setBackgroundMusic"] ? [Sound | null, number?] : K extends typeof SceneActionTypes["preUnmount"] ? [] : K extends typeof SceneActionTypes["transitionToScene"] ? [Transition, Scene] : K extends typeof SceneActionTypes["nvlBlock"] ? [LogicAction.Actions[], NvlBlockOptions] : K extends typeof SceneActionTypes["nvlShow"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlHide"] ? [Partial<TransformDefinitions.CommonTransformProps>?] : K extends typeof SceneActionTypes["nvlEnd"] ? [NvlBlockOptions?] : any;
 };
 export declare const StoryActionTypes: {
     readonly action: "story:action";

package/dist/game/nlcore/action/actions/sceneAction.d.ts

@@ -25,6 +25,9 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
         readonly init: "scene:init";
         readonly exit: "scene:exit";
         readonly jumpTo: "scene:jumpTo";
+        readonly callTo: "scene:callTo";
+        readonly preSuspend: "scene:preSuspend";
+        readonly resume: "scene:resume";
         readonly setBackgroundMusic: "scene:setBackgroundMusic";
         readonly preUnmount: "scene:preUnmount";
         readonly transitionToScene: "scene:transitionToScene";
@@ -42,8 +45,15 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
      * Initialize background music for the target scene.
      * Waits until the previous BGM has completely faded out (if any) before
      * resolving, ensuring seamless audio transition when jumping between scenes.
+     *
+     * A **suspended** scene starts nothing. This is the one place every path that starts a scene's
+     * music passes through, and it has to be the guard, because the call that reaches it is not
+     * always the one that asked: `getExposedStateAsync` waits on a component that is not mounted
+     * yet, and a stage remount - which is what loading a save performs - fires those waiting
+     * callbacks all over again. A caller parked behind a scene call therefore came back from a save
+     * with its music playing over the scene it had called.
      */
-    static initBackgroundMusic(scene: Scene, exposed: ExposedState[ExposedStateType.scene]): Promise<void>;
+    static initBackgroundMusic(scene: Scene, exposed: ExposedState[ExposedStateType.scene], state?: GameState): Promise<void>;
     static createSceneSnapshot(scene: Scene, state: GameState): SceneSnapshot;
     static restoreSceneSnapshot(snapshot: SceneSnapshot, state: GameState): void;
     /**
@@ -54,6 +64,25 @@ export declare class SceneAction<T extends typeof SceneActionTypes[keyof typeof
      * subtrees rather than swapping one image's source underneath them.
      */
     applyStageTransition(gameState: GameState, transition: Transition, target: Scene, injection: ActionExecutionInjection): Awaitable<CalledActionResult, CalledActionResult>;
+    /**
+     * Take a scene off the stage: the same three steps `scene:exit` performs, for the two paths
+     * that unload a scene the exit action never runs for - a call returning, and a plain jump
+     * giving up the callers parked behind it.
+     */
+    static unloadScene(scene: Scene, state: GameState): void;
+    /**
+     * Give up every scene parked by a returnable jump, innermost first.
+     *
+     * A plain jump clears the execution stack, and the frames it clears are the only things that
+     * could ever have returned to those scenes. Leaving them mounted would leave the stage carrying
+     * scenes no player can reach, each still holding its layers and its local variables.
+     *
+     * The snapshots come back so the jump can put them all back if it is undone - the same
+     * bargain `scene:exit` strikes with its own single scene.
+     */
+    static unwindCallStack(state: GameState): [scene: Scene, snapshot: SceneSnapshot][];
+    /** Put back what {@link SceneAction.unwindCallStack} took away, in the order it took it. */
+    static rewindCallStack(unwound: [scene: Scene, snapshot: SceneSnapshot][], state: GameState): void;
     exit(state: GameState): void;
     applyNvlVisibility(gameState: GameState, visible: boolean, options: Partial<TransformDefinitions.CommonTransformProps> | undefined, injection: ActionExecutionInjection): CalledActionResult | Awaitable<CalledActionResult, CalledActionResult>;
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;

package/dist/game/nlcore/action/stackModel.d.ts

@@ -195,5 +195,19 @@ export declare class StackModel {
     reset(): void;
     deserialize(data: StackModelRawData, actionMap: Map<string, LogicAction.Actions>): this;
     isEmpty(): boolean;
+    /**
+     * Drop everything above the innermost scene-call return address, or the whole stack if there
+     * is none.
+     *
+     * This is what moving the play head has to do instead of clearing outright once a scene can be
+     * called. A `scene:resume` item on the stack is a promise to come back to the scene that made
+     * the call, and it sits below everything the called scene has queued - so clearing to it moves
+     * the head within the called scene and leaves the promise intact, while clearing past it would
+     * strand a suspended scene on the stage with nothing able to return to it.
+     *
+     * With no call open the stack has no such item and this is exactly {@link reset}, which is what
+     * an in-scene jump has always done.
+     */
+    clearAboveCallFrame(): this;
     push(...items: (CalledActionResult | Awaitable<CalledActionResult>)[]): this;
 }

package/dist/game/nlcore/elements/scene.d.ts

@@ -43,6 +43,27 @@ export type JumpConfig = {
      * expected to be gone by the time a scene ends.
      */
     transition: Transition;
+    /**
+     * Come back here when the target scene runs out of actions, instead of leaving for good.
+     *
+     * Defaults to `false`, which is the plain jump this method has always performed: the calling
+     * scene is unloaded and everything after the jump is unreachable.
+     *
+     * With `true` the calling scene is **suspended** rather than unloaded. It keeps its stage, its
+     * sprites, its layers and its scene-local variables, its background music is paused, and it
+     * stops painting while the target scene is on screen. When the target scene runs out of
+     * actions the call returns: the target is unloaded, the calling scene paints again, its music
+     * resumes from where it was paused, and the action after the jump runs.
+     *
+     * Only the scene's own background music is suspended. Everything else a sound plays through
+     * belongs to the story rather than to one scene, and plays on across a call exactly as it
+     * plays on across a plain jump.
+     *
+     * A scene cannot be called while it is already on the call stack: one `Scene` owns one place
+     * on the stage and one set of local variables, so it cannot be in two of them at once. Calling
+     * one that is already there throws.
+     */
+    returnable: boolean;
 };
 type ChainableAction = Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>> | LogicAction.Actions;
 type ChainedScene = Proxied<Scene, Chained<LogicAction.Actions>>;
@@ -71,9 +92,11 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      */
     setBackground(background: Color | ImageSrc, transition?: ImageTransition): ChainedScene;
     /**
-     * Jump to another scene and discard the current one.
+     * Jump to another scene, either for good or for the length of that scene.
      *
-     * After the jump the calling scene is unloaded and any actions that follow are ignored.
+     * By default the calling scene is unloaded and any actions that follow the jump are ignored.
+     * Pass `returnable: true` to suspend the calling scene instead and come back to the action
+     * after the jump once the target scene runs out of actions; see {@link JumpConfig.returnable}.
      *
      * A `transition` plays across the whole stage rather than across the background alone; see
      * {@link JumpConfig.transition}.
@@ -86,6 +109,14 @@ export declare class Scene extends Constructable<LogicAction.Actions, Scene> {
      *     scene.jumpTo(nextScene, new FadeIn({duration: 800}))
      * ]);
      * ```
+     * @example
+     * ```ts
+     * // Play the title card, then carry on with the line after the jump.
+     * scene.action([
+     *     scene.jumpTo(titleCard, {returnable: true}),
+     *     character.say("...and we were back."),
+     * ]);
+     * ```
      */
     jumpTo(scene: Scene, config?: Partial<JumpConfig> | JumpConfig["transition"]): ChainableAction;
     /**

package/dist/game/nlcore/gameTypes.d.ts

@@ -433,6 +433,18 @@ export type GameConfig = {
      * @default 100
      */
     maxActionHistory: number;
+    /**
+     * How many scenes a chain of returnable jumps may keep suspended at once.
+     *
+     * A returnable jump keeps the scene it left mounted, so a chain of them holds every scene in
+     * the chain on the stage together with its layers and sprites. This is the ceiling on that
+     * chain; the story throws when a call would cross it.
+     *
+     * It is not a recursion guard - recursion is impossible either way, because a scene that is
+     * already on the call stack cannot be called again.
+     * @default 8
+     */
+    maxSceneCallDepth: number;
 };
 export type GameSettings = {
     volume: number;

package/dist/game/player/gameState.d.ts

@@ -91,6 +91,13 @@ export type PlayerStateElement = {
     layers: Map<Layer, LogicAction.DisplayableElements[]>;
     texts: Clickable<TextElement>[];
     menus: Clickable<MenuElement, Chosen>[];
+    /**
+     * Set while this scene is a caller waiting for a returnable jump to come back
+     * ({@link JumpConfig.returnable}). A suspended scene keeps everything it has - its layers, its
+     * sprites, its local variables - but stops painting, stops being the scene new dialog and
+     * menus attach to, and has its background music paused.
+     */
+    suspended?: boolean;
 };
 export type NvlStateData = {
     active: boolean;
@@ -112,6 +119,11 @@ export type NvlDialogEntryData = {
 export type PlayerStateData = {
     scenes: {
         sceneId: string;
+        /**
+         * Whether this scene is a suspended caller waiting for a returnable jump to return.
+         * Absent in saves written before scene calls existed; readers must read it as `false`.
+         */
+        suspended?: boolean;
         elements: {
             /**@deprecated */
             displayable?: string[];
@@ -134,6 +146,14 @@ export type PresentationSnapshot = {
 export type PlayerStateElementSnapshot = {
     scene: Scene;
     layers: Map<Layer, [LogicAction.DisplayableElements, Record<string, any>][]>;
+    /**
+     * Whether this scene was a caller parked behind a returnable jump when the snapshot was taken.
+     *
+     * A snapshot is restored by rebuilding the element, so anything the element carries and the
+     * snapshot does not is silently dropped on the way back. This one is the difference between a
+     * scene that is on the stage and one that is on the stage waiting for a call to return.
+     */
+    suspended?: boolean;
 };
 export type PlayerAction = CalledActionResult;
 interface StageUtils {
@@ -219,6 +239,17 @@ export declare class GameState {
     popScene(): this;
     removeScene(scene: Scene): this;
     getSceneElements(): PlayerStateElement[];
+    /**
+     * The scene the story is currently running in.
+     *
+     * Walks from the end of the list past any **suspended** scene. A suspended scene is a caller
+     * parked mid-jump: it is still mounted and still holds its stage, but it is not where the next
+     * line of dialogue belongs. Without this skip a called scene's dialogue would attach to the
+     * scene that called it, which still renders its own dialog box.
+     *
+     * With nothing suspended - which is every story that never makes a returnable jump, and every
+     * moment of one that does not have a call open - this is byte for byte what it always was.
+     */
     getLastScene(): Scene | null;
     getCurrentScene(): Scene | null;
     findCurrentPortraitForCharacter(character: Character): NormalizedCharacterPortraitConfig | null;

package/dist/game/player/lib/AudioManager.d.ts

@@ -8,6 +8,20 @@ import { AudioBusState } from "../../nlcore/game/audioBus";
 export type AudioDataRaw = {
     isPlaying: boolean;
     position: number;
+    /**
+     * The clip is paused rather than stopped: it is off, and it is expected to be picked up again
+     * from `position`.
+     *
+     * On the record rather than left to the sound element's own state, because a sound only reaches
+     * a save through the element table when something has marked it dirty AND its state differs
+     * from what the script authored - and a scene's background music is not any action's callee, so
+     * it is routinely absent from that table. This record is written for every clip the manager is
+     * holding, so it is the one place that can speak for a paused one.
+     *
+     * Absent in saves written before scene calls existed, where it reads as the element's own state
+     * exactly as it did then.
+     */
+    paused?: boolean;
 };
 export type AudioManagerDataRaw = {
     sounds: [string, AudioDataRaw][];
@@ -140,6 +154,18 @@ export declare class AudioManager {
     stop(sound: SoundElement, duration?: number): Awaitable<void>;
     setVolume(sound: SoundElement, volume: number, duration?: number): Awaitable<void>;
     mute(sound: SoundElement, muted?: boolean): Awaitable<void>;
+    /**
+     * Arm a transport change that will only act once a fade has finished, and hand back the test
+     * for whether it is still wanted by then.
+     *
+     * `FadeToken.finished` resolves when the fade is **cancelled** as well as when it runs out, and
+     * every later transport call on the same token cancels it - `resume` writes a volume, which is
+     * what cancels a pause's fade-out. Without this test, a scene call that returned while the
+     * caller's pause fade was still in flight landed the pause *after* the resume, with nothing
+     * left to undo it: the caller's music stayed silent for the rest of the scene while
+     * `sound.state.paused` said it was playing, so the next save recorded a stopped clip.
+     */
+    private arm;
     pause(sound: SoundElement, duration?: number): Awaitable<void>;
     resume(sound: SoundElement, duration?: number): Awaitable<void>;
     /**