narraleaf-react 0.32.0 → 0.33.1

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

@@ -149,6 +149,7 @@ export type LayerActionContentType = {
 };
 export declare const VideoActionTypes: {
     readonly action: "video:action";
+    readonly preload: "video:preload";
     readonly show: "video:show";
     readonly hide: "video:hide";
     readonly play: "video:play";
@@ -158,10 +159,11 @@ 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: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:preload" | "video:show" | "video:hide" | "video:play" | "video:pause" | "video:stop" | "video:resume" ? [] : K extends "video:seek" ? [number] : any;
 };
 export declare const VfxActionTypes: {
     readonly action: "vfx:action";
+    readonly preload: "vfx:preload";
     readonly show: "vfx:show";
     readonly hide: "vfx:hide";
     readonly pause: "vfx:pause";
@@ -169,7 +171,7 @@ export declare const VfxActionTypes: {
     readonly setRate: "vfx:setRate";
 };
 export type VfxActionContentType = {
-    [K in typeof VfxActionTypes[keyof typeof VfxActionTypes]]: K extends "vfx:action" ? any : K extends "vfx:show" | "vfx:hide" ? [VfxFadeOptions?] : K extends "vfx:pause" | "vfx:resume" ? [] : K extends "vfx:setRate" ? [number] : any;
+    [K in typeof VfxActionTypes[keyof typeof VfxActionTypes]]: K extends "vfx:action" ? any : K extends "vfx:show" | "vfx:hide" ? [VfxFadeOptions?] : K extends "vfx:preload" | "vfx:pause" | "vfx:resume" ? [] : K extends "vfx:setRate" ? [number] : any;
 };
 export declare const PuppetActionTypes: {
     readonly action: "puppet:action";

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

@@ -10,6 +10,7 @@ import { Story } from "../../elements/story";
 export declare class VfxAction<T extends Values<typeof VfxActionTypes> = Values<typeof VfxActionTypes>> extends TypedAction<VfxActionContentType, T, Vfx> {
     static ActionTypes: {
         readonly action: "vfx:action";
+        readonly preload: "vfx:preload";
         readonly show: "vfx:show";
         readonly hide: "vfx:hide";
         readonly pause: "vfx:pause";

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

@@ -10,6 +10,7 @@ import { Story } from "../../elements/story";
 export declare class VideoAction<T extends Values<typeof VideoActionTypes> = Values<typeof VideoActionTypes>> extends TypedAction<VideoActionContentType, T, Video> {
     static ActionTypes: {
         readonly action: "video:action";
+        readonly preload: "video:preload";
         readonly show: "video:show";
         readonly hide: "video:hide";
         readonly play: "video:play";

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

@@ -26,6 +26,22 @@ export type VfxConfig = {
 export type VfxFadeOptions = {
     duration?: number;
     easing?: TransformDefinitions.EasingDefinition;
+    /**
+     * Opacity to fade in to, for this showing only. Defaults to `config.opacity`.
+     *
+     * The overlay's own opacity is a property of the material — how strong that rain IS — while this
+     * is a property of the moment: the same rain reading faintly behind a memory and at full strength
+     * in the storm. Read by `show` only; a `hide` always fades to zero.
+     */
+    opacity?: number;
+    /**
+     * Playback speed for this showing only. Defaults to `config.playbackRate`.
+     *
+     * Every `show` restates the speed, so an override lasts exactly as long as the showing that
+     * asked for it and the next `show` is back to the configured rate. Like
+     * {@link Vfx.setPlaybackRate}, it is not persisted: a loaded save plays at `config.playbackRate`.
+     */
+    rate?: number;
 };
 export type VfxState = {
     display: boolean;
@@ -58,15 +74,38 @@ export declare class Vfx extends Actionable<VfxStateRaw> {
         src: string;
     });
     /**
-     * Add the overlay to the stage, fade it in, and start looping playback.
+     * Put the overlay on the stage without showing it: the video element is created and starts
+     * buffering, at zero opacity and paused.
+     *
+     * This is what makes a later {@link show} instant. A video that is not in the document has not
+     * begun to load, let alone decode, so the first frame of an overlay shown from nothing arrives
+     * whenever the decoder gets there — and `show` waits for it rather than fading in an empty
+     * rectangle. Declaring the overlay early moves that wait somewhere the player is not looking.
+     *
+     * Resolves immediately: nothing is waited for, because the point is to stop the story from
+     * waiting later. Calling it on an overlay already on stage does nothing.
+     * @chainable
+     */
+    preload(): Proxied<Vfx, Chained<LogicAction.Actions>>;
+    /**
+     * Fade the overlay in and start looping playback, putting it on the stage first if
+     * {@link preload} has not already.
      *
      * The action waits for the fade-in to finish. Calling it while the overlay is
      * already shown is idempotent (the fade-in is re-applied).
+     *
+     * `options.opacity` and `options.rate` apply to this showing only; both fall back to the
+     * overlay's configured values, so a plain `show()` after an overridden one is back to normal.
      * @chainable
      */
     show(options?: VfxFadeOptions): Proxied<Vfx, Chained<LogicAction.Actions>>;
     /**
-     * Fade the overlay out, then stop playback and remove it from the stage.
+     * Fade the overlay out and stop playback. It stays on the stage, invisible and paused.
+     *
+     * 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.
      *
      * 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).
@@ -75,6 +114,11 @@ export declare class Vfx extends Actionable<VfxStateRaw> {
     hide(options?: VfxFadeOptions): Proxied<Vfx, Chained<LogicAction.Actions>>;
     /**
      * Freeze the overlay on its current frame.
+     *
+     * A freeze is explicit state, not a side effect of being invisible: it survives a
+     * {@link hide}/{@link show} pair, so an overlay paused and then hidden comes back still frozen
+     * and only {@link resume} starts it moving again. `hide` stops playback of its own accord and
+     * does not touch this.
      * @chainable
      */
     pause(): Proxied<Vfx, Chained<LogicAction.Actions>>;

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

@@ -21,6 +21,17 @@ export declare class Video extends Actionable<VideoStateRaw> {
      * ```
      */
     constructor(config: Partial<VideoConfig>);
+    /**
+     * Put the video element on the stage without showing it, so it can start buffering.
+     *
+     * A video that is not in the document has not begun to load. Declaring it ahead of the line
+     * that shows or plays it is what turns "the movie starts" into something immediate rather
+     * than a wait of unknown length on the player's connection.
+     *
+     * Resolves immediately, and does nothing to an element already on stage.
+     * @chainable
+     */
+    preload(): Proxied<Video, Chained<LogicAction.Actions>>;
     /**
      * Show the video element.
      * @chainable

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

@@ -282,6 +282,14 @@ export declare class GameState {
      */
     restoreNvlSnapshot(snapshot: NvlState): this;
     restorePresentationSnapshot(snapshot: PresentationSnapshot): this;
+    /**
+     * Resolve every element's loop anchor back to the transform the story holds.
+     *
+     * Idempotent and cheap - {@link Displayable._rebindLoop} returns at once for an element with no
+     * anchor or an already-resolved one - so it is safe after any restore. Running it after all of
+     * them is what keeps a half-resolved loop from ever reaching the player.
+     */
+    private rebindLoops;
     /**
      * Clear NVL dialogs
      */