narraleaf-react 1.0.1 → 1.1.1

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

@@ -16,6 +16,7 @@ import type { Transition } from "../elements/transition/transition";
 import type { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import type { Layer } from "../elements/layer";
 import type { VfxFadeOptions } from "../elements/vfx";
+import type { VideoFadeOptions } from "../elements/video";
 import type { PuppetCommandOptions } from "../elements/displayable/puppet";
 export declare const DisplayableActionTypes: {
     readonly action: "displayable:action";
@@ -162,7 +163,7 @@ export declare const VideoActionTypes: {
     readonly seek: "video:seek";
 };
 export type VideoActionContentType = {
-    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:preload" | "video:show" | "video:hide" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
+    [K in typeof VideoActionTypes[keyof typeof VideoActionTypes]]: K extends "video:action" ? any : K extends "video:show" | "video:hide" ? [VideoFadeOptions?] : K extends "video:preload" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
 };
 export declare const VfxActionTypes: {
     readonly action: "vfx:action";

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

@@ -20,7 +20,28 @@ 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.
+     *
+     * Aborting the action - stepping back, loading a save, starting a new game - abandons the fade
+     * where it stands, and the element goes back to showing what `video.state.display` says: the undo
+     * that follows the abort then decides what that is. The handler is told through `signal`, so the
+     * part of it that records the change never runs for a change that did not happen.
+     */
+    private changeStateFading;
+    /** Whether a show or hide was asked to fade, rather than to happen at once. */
+    private static fades;
     private changeState;
     private changeStateAsync;
     stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;

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

@@ -23,6 +23,7 @@ import { Puppet } from "../elements/displayable/puppet";
 import { NVLToken } from "../elements/nvl";
 export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, TextEvent, Persistent, Service, Layer, Camera, Video, Vfx, Puppet, };
 export type { VfxConfig, VfxBlendMode, VfxFadeOptions } from "../elements/vfx";
+export type { VideoFadeOptions } from "../elements/video";
 export type { IPuppetUserConfig, PuppetConfig, PuppetCommandOptions, } from "../elements/displayable/puppet";
 export type { PuppetBackend, PuppetDescription, PuppetInstance, PuppetMountContext, PuppetSize, PuppetState, PuppetStatus, } from "../game/puppet/puppetBackend";
 export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot, LayerTagsOf, LayerVariants, } from "../elements/displayable/image";

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

@@ -1,10 +1,27 @@
 import { Actionable } from "../action/actionable";
 import { Chained, Proxied } from "../action/chain";
 import { LogicAction } from "../game";
+import type { TransformDefinitions } from "../elements/transform/type";
 export type VideoConfig = {
     src: string;
     muted: boolean;
 };
+/**
+ * How {@link Video.show} or {@link Video.hide} fades the clip in or out.
+ *
+ * Omitted, or with no positive `duration`, the clip appears or disappears at once - which is what
+ * `show()` and `hide()` have always done.
+ */
+export type VideoFadeOptions = {
+    /** How long the fade takes, in milliseconds. */
+    duration?: number;
+    /**
+     * The curve of the fade: a named easing (`"linear"`, `"easeIn"`, `"easeOut"`, `"easeInOut"`) or a
+     * cubic-bezier as four numbers. Linear when omitted. A named easing with no CSS equivalent falls
+     * back to `"ease"`, as it does for a `Vfx` fade.
+     */
+    easing?: TransformDefinitions.EasingDefinition;
+};
 export type VideoState = {
     display: boolean;
 };
@@ -33,15 +50,38 @@ export declare class Video extends Actionable<VideoStateRaw> {
      */
     preload(): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
-     * Show the video element.
+     * Show the video element, putting it on the stage first if it is not there yet.
+     *
+     * With `options.duration`, the clip fades in over that many milliseconds and the action waits for
+     * the fade to finish; it starts once the clip can present a frame, so what fades in is the picture
+     * and not an empty rectangle. Without it the clip appears at once.
      * @chainable
+     * @example
+     * ```ts
+     * video.show({duration: 500});
+     * ```
      */
-    show(): Proxied<Video, Chained<LogicAction.Actions>>;
+    show(options?: VideoFadeOptions): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
-     * Hide the video element.
+     * Hide the video element and take it off the stage.
+     *
+     * With `options.duration`, the clip fades out over that many milliseconds - holding whatever frame
+     * it is on, which after {@link play} is its last - and leaves the stage once the fade is over; the
+     * action waits for that. Without it the clip disappears at once.
+     *
+     * A clip that is not on the stage has nothing to hide, and the call does nothing.
      * @chainable
+     * @example
+     * ```ts
+     * // A cutscene that clears itself away when it ends
+     * scene.action([
+     *     video.show(),
+     *     video.play(),
+     *     video.hide({duration: 600}),
+     * ]);
+     * ```
      */
-    hide(): Proxied<Video, Chained<LogicAction.Actions>>;
+    hide(options?: VideoFadeOptions): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
      * Play the video and wait until it finishes.
      * @chainable

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

@@ -133,6 +133,14 @@ 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[];
         };
     }[];
     audio: AudioManagerDataRaw;
@@ -156,6 +164,14 @@ 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][];
 };
 export type PlayerAction = CalledActionResult;
 interface StageUtils {
@@ -210,6 +226,16 @@ 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;
     private videoMissingReporter;
     /** Sources already reported as unwarmed, so one clip in a loop does not report every pass. */
     private readonly reportedUnwarmedVideos;
@@ -547,6 +573,21 @@ 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;
     private syncNvlDerivedState;
     private emitNvlStateChange;
     private resolveNvlAdvance;

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

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

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

@@ -11,7 +11,7 @@ import { Text } from "../nlcore/elements/displayable/text";
 import { Displayable } from "../nlcore/elements/displayable/displayable";
 import { Scene } from "../nlcore/elements/scene";
 import { Sound } from "../nlcore/elements/sound";
-import { Video } from "../nlcore/elements/video";
+import { Video, VideoFadeOptions } from "../nlcore/elements/video";
 import { Vfx, VfxFadeOptions } from "../nlcore/elements/vfx";
 import { Puppet } from "../nlcore/elements/displayable/puppet";
 import { Timeline } from "./Tasks";
@@ -80,8 +80,12 @@ export type ExposedState = {
         setBackgroundMusic: (music: Sound | null, fade: number) => Promise<void>;
     };
     [ExposedStateType.video]: {
-        show: () => void;
-        hide: () => void;
+        /** Resolves once the clip is showing: at once, or when a fade in ends, is skipped or is abandoned. */
+        show: (options?: VideoFadeOptions) => Promise<void>;
+        /** Resolves once the clip is hidden: at once, or when a fade out ends, is skipped or is abandoned. */
+        hide: (options?: VideoFadeOptions) => Promise<void>;
+        /** Abandon a fade in flight and show the clip as `video.state.display` says. */
+        cancelFade: () => void;
         play: () => Promise<void>;
         pause: () => void;
         resume: () => Promise<void>;