narraleaf-react 1.0.1 → 1.1.0

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

@@ -21,6 +21,17 @@ export declare class VideoAction<T extends Values<typeof VideoActionTypes> = Val
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
     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/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>;