narraleaf-react 0.46.0 → 0.47.0

package/dist/game/nlcore/preload/types.d.ts

@@ -1,6 +1,7 @@
 import type { Scene } from "../elements/scene";
 import type { Sound } from "../elements/sound";
 import type { Story } from "../elements/story";
+import type { Video } from "../elements/video";
 /**
  * The preload seam: what the player warms, when it warms it, and where the bytes come from.
  *
@@ -28,7 +29,16 @@ import type { Story } from "../elements/story";
  * A game that supplies no strategy gets the built-in one, which reproduces the walk and the tiers
  * exactly as they were, driven by the same `preload*` fields of `GameConfig`.
  */
-/** What kind of thing a plan entry names. Audio is not one of these - see {@link PreloadPlan.audio}. */
+/**
+ * What kind of thing a preload resource names.
+ *
+ * Only images are named this way in a plan's {@link PreloadPlan.entries}: they are the resources
+ * the player fetches, caches and decodes, so a url is the whole of what it needs to know. Audio and
+ * video are named by element instead ({@link PreloadPlan.audio}, {@link PreloadPlan.video}),
+ * because what warming them means is a property of the element and not of the url. `video` survives
+ * here for {@link PreloadStrategy.onMissing} and {@link PreloadStrategy.acquire}, which speak about
+ * a resource rather than about a plan.
+ */
 export type PreloadResourceType = "image" | "video";
 /** One thing a plan can ask for, named by the url the stage will show. */
 export type PreloadResource = {
@@ -53,7 +63,17 @@ export type PreloadResource = {
  *   abandoned without ceremony when the moment is superseded.
  */
 export type PreloadBand = "gate" | "soon" | "idle";
-export type PreloadEntry = PreloadResource & {
+export type PreloadEntry = {
+    /**
+     * Always an image.
+     *
+     * Video used to be nameable here, and warming it meant reading the bytes once and dropping
+     * them, in the hope that whatever served them kept a copy. That hope is unfounded on the hosts
+     * that matter - a game serving assets through its own protocol has no cache to warm - so it
+     * reported warming that had not happened. {@link PreloadPlan.video} is the answer that works.
+     */
+    type: "image";
+    src: string;
     band: PreloadBand;
     /**
      * Whether to decode the image off-screen before anything shows it, and hold the bitmap.
@@ -88,6 +108,25 @@ export type PreloadPlan = {
      * so a loading screen that waited for a clip could wait for ever.
      */
     readonly audio?: readonly Sound[];
+    /**
+     * Clips this moment wants buffering, nearest first, and only these.
+     *
+     * Named by element for the same reason audio is, only more so: warming a video means putting
+     * its element in the document and letting the browser buffer into it, and the element that
+     * buffered has to be the one that plays or nothing was gained. There is no video cache in the
+     * player, and there is no url-shaped way to fill one.
+     *
+     * The order is a statement of what is coming first. The player admits the clips one at a time
+     * and starts the next when the current one reports it can play, so how many are really being
+     * fetched at once follows the connection rather than the length of this list - which is why
+     * there is no setting for it and no number for a host to choose. A clip the story has already
+     * declared is left alone: it is on the stage on the author's own instruction.
+     *
+     * Never gated on. A clip can take arbitrarily long to buffer, and a loading screen that waited
+     * for one would be a download bar wearing a story's clothes. Omit the field to leave the warm
+     * set as it is; an empty array releases it.
+     */
+    readonly video?: readonly Video[];
     /**
      * Every url the image cache may keep, which is normally the plan's own entries.
      *

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

@@ -26,6 +26,7 @@ import { Vfx, VfxStateRaw } from "../nlcore/elements/vfx";
 import { Timelines } from "./Tasks";
 import { Notification, NotificationManager } from "./lib/notification";
 import type { ImageCacheManager } from "./lib/ImageCacheManager";
+import type { PreloadResource } from "../nlcore/preload/types";
 import { ActionHistoryManager } from "../../game/nlcore/action/actionHistory";
 import { GameHistoryManager } from "../../game/nlcore/action/gameHistory";
 import type { Character } from "../nlcore/elements/character";
@@ -204,6 +205,14 @@ export declare class GameState {
     preloadingScene: Scene | null;
     flushDep: number;
     rollLock: Lock;
+    /**
+     * Clips held on the stage, hidden, because a plan said they are coming - never part of a save.
+     * See {@link VideoWarmQueue}.
+     */
+    private readonly videoWarmQueue;
+    private videoMissingReporter;
+    /** Sources already reported as unwarmed, so one clip in a loop does not report every pass. */
+    private readonly reportedUnwarmedVideos;
     readonly notificationMgr: NotificationManager;
     readonly events: EventDispatcher<GameStateEvents>;
     readonly logger: Logger;
@@ -222,8 +231,50 @@ export declare class GameState {
     get deps(): number;
     addVideo(video: Video): this;
     removeVideo(video: Video): this;
+    /**
+     * Whether the STORY has put this clip on the stage - a declaration row, a show, a play.
+     *
+     * Deliberately not "is it in the document": a clip the warm queue is holding is mounted and
+     * buffering but nothing has shown it, and the two answers are wanted in different places. What
+     * a save records, what an undo takes back and what a second declaration skips are all this one;
+     * whether an action may talk to the element is {@link GameState.isVideoOnStage}.
+     */
     isVideoAdded(video: Video): boolean;
+    /** Whether the clip is in the document at all, warmed or shown - so whether it has a state to talk to. */
+    isVideoOnStage(video: Video): boolean;
+    /**
+     * Every clip the stage renders: the story's own, then whatever the warm queue is holding.
+     *
+     * The two lists are kept apart rather than merged on insert because only the first is state.
+     * A save is a list of what the story put on the stage; a warmed clip is a performance detail of
+     * this run of it, and writing it into a save would make a story edit able to invalidate a save
+     * that has nothing to do with the change (`fromData` throws on a video id it cannot find).
+     */
     getVideos(): Video[];
+    /**
+     * Hold exactly these clips buffering ahead of the story, in this order of preference.
+     *
+     * What a {@link PreloadPlan.video} asks for. The queue starts them one at a time and waits for
+     * each to become playable before starting the next, so how many are really being fetched at
+     * once follows the connection rather than the plan; see {@link VideoWarmQueue}.
+     */
+    retainWarmVideos(videos: readonly Video[]): this;
+    /**
+     * Where to report a clip the story played that no plan named, or null for nowhere.
+     *
+     * The image half of this lives on the cache manager, which is the thing that would have fetched
+     * the image; a video is never fetched by the player, so the report has to come from the action
+     * that starts it.
+     */
+    useVideoMissingReporter(reporter: ((resource: PreloadResource) => void) | null): this;
+    /**
+     * Note that a clip is about to be shown or played with nothing having warmed it.
+     *
+     * Once per source, and only when no plan named it and nothing has it on the stage: a clip the
+     * author declared a few rows earlier is warm by authorship, and reporting that would be
+     * reporting the feature working.
+     */
+    reportUnwarmedVideo(video: Video): this;
     addVfx(vfx: Vfx): this;
     removeVfx(vfx: Vfx): this;
     isVfxAdded(vfx: Vfx): boolean;

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

@@ -0,0 +1,78 @@
+import type { Video } from "../../nlcore/elements/video";
+export type VideoWarmQueueOptions = {
+    /**
+     * Whether the story itself has put this clip on the stage.
+     *
+     * Declared clips are the author's own instruction (`/video`, or a `Video.preload()` call) and
+     * are never queued: they are already buffering, they are not subject to the ceiling, and
+     * releasing one would take away something the story asked for.
+     */
+    isDeclared(video: Video): boolean;
+    /** Ask the player to re-render the stage, because what is mounted has changed. */
+    onChange(): void;
+};
+/**
+ * Which clips are held on the stage buffering, and in what order they are started.
+ *
+ * ## Why a queue and not a number
+ *
+ * Warming a video is not warming an image. An image is bytes plus a decode, and the player can hold
+ * both in a cache under a budget it can measure. A video is a `<video>` element that is in the
+ * document: the browser buffers into it, the buffer belongs to that element, and the element that
+ * buffered has to be the element that plays or the buffering bought nothing. So "warm this clip"
+ * means "mount it hidden, early", and the only questions left are how many and in what order.
+ *
+ * Both are answered here rather than by whoever wrote the story or configured the game. The host's
+ * plan says which clips are coming and in what order (nearest first); this admits them one at a
+ * time and starts the next when the current one reports it can play. On a fast local disk that
+ * empties the queue almost at once; on a slow connection it keeps a single read running instead of
+ * five that finish together and too late. Nobody has to know what number to write, which is the
+ * point - it is not a number an author could be expected to get right, and the browser is telling
+ * us the answer anyway.
+ */
+export declare class VideoWarmQueue {
+    private readonly options;
+    /** Everything the current plan named, declared clips included - what {@link isPlanned} answers. */
+    private planned;
+    /** What this queue may mount, in plan order, minus anything the story declared itself. */
+    private desired;
+    /** Mounted by this queue, hidden and buffering. A subset of {@link desired}, in admission order. */
+    private admitted;
+    /** The clip whose "can play" the queue is waiting for before it starts another. */
+    private pending;
+    private pendingTimer;
+    constructor(options: VideoWarmQueueOptions);
+    /**
+     * Take a plan's clips as the complete set this moment wants warm.
+     *
+     * Total replacement, like every other part of a plan: a clip the new plan does not name is
+     * released as soon as this returns, because the scene that wanted it is behind the reader. What
+     * the story declared is untouched - releasing that is the story's business, not the plan's.
+     */
+    retain(next: readonly Video[]): void;
+    /**
+     * A clip is playable, or has failed trying - either way the queue stops waiting for it.
+     *
+     * Fed from the player's exposed-state mount, which the video component performs on `canplay`
+     * and, for a source that will not load, on `error`. Anything that is not the clip being waited
+     * for is ignored, so this can be wired to every state mount there is.
+     */
+    noteReady(video: unknown): void;
+    /**
+     * Stop holding a clip the story has taken over.
+     *
+     * Called when a row declares, shows or plays something this queue had mounted. The element does
+     * not move and does not reload - it is the same element, now on the stage for a better reason -
+     * so this only stops counting it against the ceiling and frees the queue to start another.
+     */
+    forget(video: Video): void;
+    /** Clips this queue is holding on the stage, hidden. */
+    getAdmitted(): readonly Video[];
+    /** Whether the current plan named this clip at all, declared or not. */
+    isPlanned(video: Video): boolean;
+    /** Drop everything, for a player being torn down or reset. */
+    clear(): void;
+    /** Start the next clip if there is room and nothing is being waited on. Reports whether it did. */
+    private admit;
+    private clearPending;
+}