narraleaf-react 0.41.1 → 0.42.0

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

@@ -11,7 +11,7 @@ import type { Script } from "../elements/script";
 import type { Sentence } from "../elements/character/sentence";
 import type { TransformDefinitions } from "../elements/transform/type";
 import type { Image, TagGroupDefinition } from "../elements/displayable/image";
-import type { FadeOptions } from "../elements/type";
+import type { FadeOptions, SoundPlayOptions } from "../elements/type";
 import type { Transition } from "../elements/transition/transition";
 import type { ImageTransition } from "../elements/transition/transitions/image/imageTransition";
 import type { Layer } from "../elements/layer";
@@ -107,7 +107,7 @@ export declare const SoundActionTypes: {
     readonly seek: "sound:seek";
 };
 export type SoundActionContentType = {
-    [K in typeof SoundActionTypes[keyof typeof SoundActionTypes]]: K extends "sound:play" ? [FadeOptions] : K extends "sound:stop" ? [FadeOptions] : K extends "sound:setVolume" ? [volume: number, duration: number] : K extends "sound:setRate" ? [number] : K extends "sound:pause" ? [FadeOptions] : K extends "sound:resume" ? [FadeOptions] : K extends "sound:mute" ? [boolean] : K extends "sound:seek" ? [time: number] : any;
+    [K in typeof SoundActionTypes[keyof typeof SoundActionTypes]]: K extends "sound:play" ? [SoundPlayOptions] : K extends "sound:stop" ? [FadeOptions] : K extends "sound:setVolume" ? [volume: number, duration: number] : K extends "sound:setRate" ? [number] : K extends "sound:pause" ? [FadeOptions] : K extends "sound:resume" ? [FadeOptions] : K extends "sound:mute" ? [boolean] : K extends "sound:seek" ? [time: number] : any;
 };
 export declare const ControlActionTypes: {
     readonly action: "control:action";

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

@@ -152,14 +152,20 @@ export declare class Sound extends Actionable<SoundDataRaw, Sound> {
      * It is *not* the same as {@link Scene.setBackgroundMusic}: a clip played here is not in the
      * scene's background-music slot, so leaving the scene will not stop it and no cross-fade is
      * arranged for it. That is true of every clip played this way, on any bus.
+     * The script carries on as soon as the clip is playing. A clip that is meant to hold the script
+     * until it finishes says so: `sound.play(0, {waitForEnd: true})`.
+     *
      * @param duration - Optional fade duration in milliseconds.
+     * @param options.waitForEnd - Hold the script until the clip finishes. Ignored for a looping clip.
      * @chainable
      * @example
      * ```ts
      * sound.play(1000);
      * ```
      */
-    play(duration?: number): ChainedSound;
+    play(duration?: number, options?: {
+        waitForEnd?: boolean;
+    }): ChainedSound;
     /**
      * Stop the sound and optionally fade out.
      * @param duration - Fade duration in milliseconds.

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

@@ -11,6 +11,18 @@ export type FadeOptions = {
     end: number;
     duration: number;
 };
+/**
+ * What {@link AudioManager.play} is asked for, on top of the fade.
+ *
+ * `waitForEnd` is what decides whether the action that started the clip holds the script until the
+ * clip finishes. A sound effect written between two lines is not a wait the author asked for - a
+ * seven-second chime stopped the script for seven seconds with nothing on screen saying why - so
+ * {@link Sound.play} leaves it off and a row that means "hold here" turns it on.
+ */
+export type SoundPlayOptions = FadeOptions & {
+    /** Resolve only once the clip has finished playing. Ignored for a looping clip. */
+    waitForEnd?: boolean;
+};
 export type ChainedActions = (Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>> | LogicAction.Actions)[];
 export type ActionStatements = ChainedActions | string[];
 export type { TransitionAnimationType, TransitionTask, };

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

@@ -185,6 +185,21 @@ export type GameConfig = {
      * @default true
      */
     waitForPreload: boolean;
+    /**
+     * How much of a scene has to be warm before the game is shown.
+     *
+     * `"firstFrame"` waits for the scene's opening background and nothing else, then keeps fetching
+     * the rest behind the game. `"scene"` waits for every image the scene registers anywhere in it,
+     * which is what this always did.
+     *
+     * The two differ by an order of magnitude on a real project: a chapter's registered set is
+     * every pose of every character it shows and every background it cuts to, while its first frame
+     * is one picture. Choose `"scene"` when a game would rather open late than risk an image
+     * arriving after the frame that wanted it.
+     *
+     * @default "firstFrame"
+     */
+    preloadGate: "firstFrame" | "scene";
     /**
      * Preload all possible images in the scene
      *

package/dist/game/player/elements/nvl/nvlAdvance.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One advance of an NVL line, decided and carried out.
+ *
+ * NVL differs from ADV in that the page owns the line: `requestNvlAdvance` is not a query but the
+ * move itself, and it settles a line that has finished revealing without the dialog hearing about
+ * it. Only when it answers `typing` is there anything left for this dialog to do - and what to do
+ * then is the same rule ADV follows, {@link resolveDialogAdvanceIntent}: an advance asks the line
+ * to complete, and only the skip mode forces.
+ *
+ * The skip key used to force here on every emission, tap included, which walked it past the pauses
+ * an author wrote. It is kept out of the hook so that a test can drive it against a real dialog
+ * state without a React tree.
+ *
+ * Comments in English per project convention.
+ */
+/** The page state, as this module needs it. */
+export type NvlAdvancePage = {
+    requestNvlAdvance(dialogId: string): "ignore" | "typing" | "advance";
+};
+/** The part of a dialog state an advance touches. Structural, as in `dialogAdvanceIntent`. */
+export type NvlAdvanceTarget = {
+    forceSkip(): void;
+    requestComplete(): void;
+};
+export type NvlAdvanceInput = {
+    dialogId: string;
+    /** Whether this dialog is the one holding the line. */
+    active: boolean;
+    /** Whether this is the skip mode rather than one advance. */
+    forced: boolean;
+};
+/**
+ * What one advance of an NVL line ended up doing.
+ *
+ * - `ignore` - not this dialog's to answer.
+ * - `pageHandled` - the page moved on its own; there was nothing left to reveal.
+ * - `requestComplete` / `forceSkip` - what was asked of the line still revealing.
+ */
+export type NvlAdvanceResult = "ignore" | "pageHandled" | "requestComplete" | "forceSkip";
+export declare function applyNvlAdvance(page: NvlAdvancePage, dialog: NvlAdvanceTarget, { dialogId, active, forced }: NvlAdvanceInput): NvlAdvanceResult;

package/dist/game/player/elements/preload/preloadPlan.d.ts

@@ -1,10 +1,22 @@
 import type { Scene } from "../../../nlcore/elements/scene";
 import type { Sound } from "../../../nlcore/elements/sound";
 export type ScenePreloadPlan = {
+    /**
+     * The image the scene's own first painted frame cannot do without: its opening background.
+     *
+     * Split out of {@link ScenePreloadPlan.critical} because those two answer different questions.
+     * "What does this scene use anywhere in it" is a whole chapter's artwork - every pose of every
+     * character it shows, every background it cuts to - and on a real project that is most of the
+     * library. "What is on screen when it opens" is one picture. A host that holds its loading
+     * screen up until the scene is warm was holding it for the first of those; this tier is the
+     * second, and it is what {@link GameConfig.preloadGate} lets a game wait on instead.
+     */
+    firstFrame: string[];
     /**
      * Image urls the scene that is about to paint registers directly: its own backgrounds and
-     * images, plus the immediate background of any scene it jumps to. This tier is on the path to
-     * the first painted frame, so it is fetched unpaced and nothing is revealed until it is warm.
+     * images, plus the immediate background of any scene it jumps to, minus anything already in
+     * {@link ScenePreloadPlan.firstFrame}. Fetched unpaced, because the player is a click away
+     * from needing it.
      */
     critical: string[];
     /**

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

@@ -1,6 +1,6 @@
 import { Sound as SoundElement, SoundBusId } from "../../nlcore/elements/sound";
 import { SoundToken } from "@narraleaf/sound";
-import { FadeOptions } from "../../nlcore/elements/type";
+import { FadeOptions, SoundPlayOptions } from "../../nlcore/elements/type";
 import { Awaitable } from "../../../util/data";
 import { GameState } from "../gameState";
 import { LogicAction } from "../../nlcore/action/logicAction";
@@ -139,7 +139,16 @@ export declare class AudioManager {
      * back to whatever the author first wrote down.
      */
     private static defaultFade;
-    play(sound: SoundElement, options?: FadeOptions): Awaitable<void>;
+    /**
+     * Start `sound`, and resolve when it is playing.
+     *
+     * `options.waitForEnd` moves the resolution to the end of the clip. It defaults to ON here and
+     * OFF at {@link Sound.play}, and the asymmetry is deliberate: the callers inside the engine - a
+     * voice line, a text-event effect - are tracking a clip's whole life and were written against
+     * that, while an authored sound-effect row is not asking the script to stop for the length of
+     * the file. A looping clip never ends, so it is always resolved once it is playing.
+     */
+    play(sound: SoundElement, options?: SoundPlayOptions): Awaitable<void>;
     /**
      * Start a clip and hand the token back once playback is under way.
      *

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

@@ -31,6 +31,15 @@ export declare class ImageCacheManager {
      */
     private decoded;
     constructor(game: Game);
+    /**
+     * Release the object URL an entry holds.
+     *
+     * Every path that drops an entry goes through this. An object URL pins its blob for the
+     * lifetime of the document, so a cache that forgets an entry without revoking leaks the whole
+     * image - which on a scene change is most of a scene's artwork.
+     */
+    private release;
+    private releaseAll;
     has(name: string): boolean;
     add(name: string, src: string): this;
     remove(name: string): this;
@@ -44,7 +53,7 @@ export declare class ImageCacheManager {
     size(): number;
     isPreloading(src: string): boolean;
     /**
-     * Fetch `url`, cache it as a data URL and decode it, resolving the returned token's
+     * Fetch `url`, cache it as an object URL and decode it, resolving the returned token's
      * `onFinished` only once the decode has settled.
      *
      * @param options.retainDecoded keep the decoded bitmap alive until this source leaves the