narraleaf-react 1.1.0 → 1.2.0

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

@@ -18,6 +18,15 @@ export declare class VfxAction<T extends Values<typeof VfxActionTypes> = Values<
         readonly setRate: "vfx:setRate";
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * A pause, a resume or a rate change aimed at an overlay that is no longer on the stage.
+     *
+     * An overlay leaves the stage with the scene that started it, so a handle kept in script and used
+     * after that scene is gone has nothing to talk to. It does nothing and says so - what `hide` on an
+     * overlay that is not shown has always done, and what a clip's transport does - rather than
+     * stopping the story.
+     */
+    private skipOffStage;
     private changeStateBase;
     private changeState;
     private changeStateAsync;

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

@@ -20,6 +20,16 @@ export declare class VideoAction<T extends Values<typeof VideoActionTypes> = Val
         readonly seek: "video:seek";
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * A transport row - pause, resume, seek, stop - aimed at a clip that is no longer on the stage.
+     *
+     * There is nothing to talk to, and nothing it could have done: a clip that has left has stopped,
+     * and the next show puts it back from the start. Which side of the clip leaving such a row lands
+     * on is not always the author's to decide - a clip played without waiting for it leaves when it
+     * ends, at a moment set by how fast the player reads - so a row that would have worked a click
+     * earlier must not stop the story a click later. The same answer `hide` gives.
+     */
+    private skipOffStage;
     private changeStateBase;
     /**
      * {@link changeStateBase} for a fade, which the player can walk away from halfway.

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

@@ -54,8 +54,13 @@ export type VfxStateRaw = {
  * A full-screen looping video overlay for particle and ambience effects
  * (falling petals, light dust, rain, snow, fog, light flares).
  *
- * The effect is a pre-rendered video that plays above the scenes and videos of the
- * stage; camera transforms apply to it like any other stage content.
+ * The effect is a pre-rendered video that plays over the scene that shows it, above that scene's
+ * sprites and videos; camera transforms apply to it like any other stage content.
+ *
+ * Like everything else on the stage, an overlay belongs to the scene that shows it: rain started in
+ * one scene stops when the story jumps to another, waits hidden and paused while its scene has
+ * called another, and comes back when the call returns. A scene that wants the rain to go on shows
+ * it itself.
  */
 export declare class Vfx extends Actionable<VfxStateRaw> {
     /**
@@ -104,8 +109,8 @@ export declare class Vfx extends Actionable<VfxStateRaw> {
      *
      * A paused video decodes nothing, so a hidden overlay costs no frame time — and keeping the
      * element means the next {@link show} has a decoder already holding the clip instead of starting
-     * over. Both halves of the same decision: stop the work, keep the warmth. Only a new game or a
-     * load clears the stage.
+     * over. Both halves of the same decision: stop the work, keep the warmth. The overlay leaves the
+     * stage when its scene does.
      *
      * The action waits for the fade-out to finish. Calling it while the overlay is
      * not shown is a no-op (a weak warning is logged).

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

@@ -133,6 +133,22 @@ export type PlayerStateData = {
              * { [layerName]: [displayableId][] }
              */
             layers: Record<string, string[]>;
+            /**
+             * The ids of the clips this scene put on the stage. Their state is in
+             * {@link PlayerStateData.videos}; this says which scene each one leaves with.
+             *
+             * Written only when the scene has any. Absent in saves written before clips belonged to
+             * scenes, and a clip no scene names is given to the scene the story is running in.
+             */
+            videos?: string[];
+            /**
+             * The ids of the overlays this scene put on the stage, the same way
+             * {@link videos} names its clips. Their state is in {@link PlayerStateData.vfx}.
+             *
+             * Written only when the scene has any. Absent in saves written before overlays belonged
+             * to scenes, and an overlay no scene names is given to the scene the story is running in.
+             */
+            vfx?: string[];
         };
     }[];
     audio: AudioManagerDataRaw;
@@ -156,6 +172,20 @@ export type PlayerStateElementSnapshot = {
      * scene that is on the stage and one that is on the stage waiting for a call to return.
      */
     suspended?: boolean;
+    /**
+     * The clips this scene had on the stage, each with its state, in stage order.
+     *
+     * A clip is drawn over the scene rather than inside one of its layers, but it belongs to the
+     * scene that put it there all the same, and leaves with it. Absent in snapshots taken before
+     * clips belonged to scenes; read as none.
+     */
+    videos?: [Video, VideoStateRaw][];
+    /**
+     * The overlays this scene had on the stage, each with its state, in stage order - for the same
+     * reason as {@link videos}. Absent in snapshots taken before overlays belonged to scenes; read as
+     * none.
+     */
+    vfx?: [Vfx, VfxStateRaw][];
 };
 export type PlayerAction = CalledActionResult;
 interface StageUtils {
@@ -210,6 +240,22 @@ export declare class GameState {
      * See {@link VideoWarmQueue}.
      */
     private readonly videoWarmQueue;
+    /**
+     * Which scene each of the story's clips belongs to: the one running when the clip went on.
+     *
+     * A clip is not on one of the scene's layers - it is a sibling of the scene's root, so that a clip
+     * the preloader warmed can be taken over without being remounted - so nothing about where it sits
+     * says whose it is. And it has to be somebody's, because a scene takes everything it put on the
+     * stage with it when it leaves. Kept beside {@link PlayerState.videos} rather than in it, because
+     * the stage order of clips is not grouped by scene.
+     */
+    private videoOwners;
+    /**
+     * Which scene each overlay on the stage belongs to: the one running when it went on. An overlay
+     * is a stage object like any other - rain started in a scene stops when the scene is left - and
+     * it is drawn beside its scene's root for the reason a clip is (see {@link videoOwners}).
+     */
+    private vfxOwners;
     private videoMissingReporter;
     /** Sources already reported as unwarmed, so one clip in a loop does not report every pass. */
     private readonly reportedUnwarmedVideos;
@@ -547,6 +593,26 @@ export declare class GameState {
      * excluded explicitly rather than by trusting that route to stay closed.
      */
     private resetLayers;
+    /**
+     * The clip half of leaving a scene: every clip the scene put on the stage leaves with it, and
+     * goes back to its authored state, exactly as the sprites on its layers do in
+     * {@link resetLayers}.
+     *
+     * Without this a clip outlived its scene, and since a clip paints over its scene's sprites, one
+     * that stopped on its last frame covered the whole of the next scene - where nothing could take it
+     * down, because a host that names stage objects per scene cannot even name it.
+     *
+     * Every path that takes a scene off the stage comes through here - a plain jump's exit, a call
+     * returning, a jump giving up the callers parked behind it, stepping back over a scene's entrance
+     * - and each of them snapshots the scene first (see {@link createElementSnapshot}), so the clips
+     * come back with it when the step is undone.
+     */
+    private releaseVideosOf;
+    /**
+     * The overlay half of leaving a scene, the same as {@link releaseVideosOf}: rain the scene started
+     * stops when the scene is left, and the overlay goes back to its authored state.
+     */
+    private releaseVfxOf;
     private syncNvlDerivedState;
     private emitNvlStateChange;
     private resolveNvlAdvance;

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

@@ -0,0 +1 @@
+export {};