narraleaf-react 0.12.2 → 0.13.0

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

@@ -18,5 +18,6 @@ import { Layer } from "../elements/layer";
 import { Video } from "../elements/video";
 import { NVLToken } from "../elements/nvl";
 export { Character, Narrator, Condition, Control, Image, Lambda, Menu, NVLToken, Scene, Script, Sentence, Sound, Story, Transform, Word, Text, Pause, Persistent, Service, Layer, Video, };
+export type { LayeredDefinition, LayerGroupDefinition, LayerResolver, LayerSlot, LayerTagsOf, LayerVariants, } from "../elements/displayable/image";
 export type { SentenceMetadata } from "../elements/character/sentence";
 export type { CharacterPortraitConfig, DialogAvatar, DialogAvatarResolver, DialogAvatarResolverContext, DialogAvatarResolution, DialogAvatarSource, } from "../elements/character/avatar";

package/dist/game/nlcore/elements/built-in/DevTools.d.ts

@@ -2,9 +2,18 @@ import { ControlAction } from "../../action/actions/controlAction";
 import { Chained, Proxied } from "../../action/chain";
 import { GameState } from "../../common/game";
 import { LogicAction } from "../../game";
+import type { LiveGameEventToken } from "../../types";
 import { Layer } from "../layer";
 import { DynamicPersistent, Persistent } from "../persistent";
 import { Scene } from "../scene";
+/** Snapshot of the dialog line currently presented to the player (ADV or NVL). */
+export type DevToolsCurrentDialog = {
+    /** Id of the say action that produced the line (static id when assigned). */
+    actionId: string | null;
+    /** True once the line finished displaying and awaits advance. */
+    ended: boolean;
+    mode: "adv" | "nvl";
+};
 export declare class DevTools {
     static getActionId(action: LogicAction.Actions): string;
     static setActionId(action: LogicAction.Actions, id: string): LogicAction.Actions;
@@ -49,5 +58,17 @@ export declare class DevTools {
     static setDisplayableTransformProps(gameState: GameState, displayable: LogicAction.DisplayableElements, props: Record<string, unknown>, options?: {
         merge?: boolean;
     }): void;
+    /**
+     * Read the dialog line currently presented to the player, or null when no
+     * dialog is on screen. Covers both ADV (tracked via GameState.beginAdvDialog)
+     * and NVL (active entry + phase) presentation.
+     */
+    static getCurrentDialog(gameState: GameState): DevToolsCurrentDialog | null;
+    /**
+     * Subscribe to changes of the currently presented dialog line (creation,
+     * typing completion, advance/settle) across ADV and NVL modes. The listener
+     * carries no payload; call {@link getCurrentDialog} to read the new state.
+     */
+    static onDialogStateChange(gameState: GameState, listener: () => void): LiveGameEventToken;
     static DynamicPersistent: typeof DynamicPersistent;
 }

package/dist/game/nlcore/elements/displayable/image.d.ts

@@ -14,7 +14,7 @@ export type TagDefinitionObject<T extends TagGroupDefinition> = {
     resolve: TagSrcResolver<T>;
 };
 type ImageSrcType<T extends TagGroupDefinition | null = TagGroupDefinition | null> = T extends TagGroupDefinition ? TagDefinition<T> : (Color | ImageSrc);
-export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGroupDefinition | null> extends TransformDefinitions.ImageTransformProps {
+export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGroupDefinition | null, Layers extends LayerGroupDefinition = LayerGroupDefinition> extends TransformDefinitions.ImageTransformProps {
     /**
      * The name of the image, only for debugging purposes
      */
@@ -27,7 +27,7 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
     /**
      * Image Src, see [Image](https://react.narraleaf.com/documentation/core/elements/image) for more information
      */
-    src: ImageSrcType<Tag>;
+    src: ImageSrcType<Tag> | LayeredDefinition<Layers>;
     /**
      * Auto resize image's width to fit the screen
      * @default false
@@ -45,7 +45,40 @@ export interface IImageUserConfig<Tag extends TagGroupDefinition | null = TagGro
 }
 export type TagGroupDefinition = string[][];
 export type TagSrcResolver<T extends TagGroupDefinition> = (...tags: SelectElementFromEach<T>) => string;
-export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefinition | null> extends Displayable<ImageDataRaw, Image, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
+/**
+ * A set of mutually exclusive variants for one layer, keyed by tag.
+ *
+ * `null` means the layer draws nothing for that tag.
+ */
+export type LayerVariants = Record<string, string | null>;
+/**
+ * Derives a layer's src from the currently active tags. Declares no tags of its own.
+ */
+export type LayerResolver = (tags: ReadonlySet<string>) => string | null;
+/**
+ * One slot of a layered image, from bottom to top. Either a constant src, `null`,
+ * a {@link LayerVariants} map, or a {@link LayerResolver}.
+ */
+export type LayerSlot = string | null | LayerVariants | LayerResolver;
+export type LayerGroupDefinition = readonly LayerSlot[];
+/**
+ * The union of every tag declared by a layer stack.
+ */
+export type LayerTagsOf<L> = L extends readonly (infer E)[] ? (E extends LayerResolver ? never : E extends LayerVariants ? keyof E & string : never) : never;
+/**
+ * Layered image src, see [Image](https://react.narraleaf.com/documentation/core/elements/image).
+ */
+export type LayeredDefinition<L extends LayerGroupDefinition = LayerGroupDefinition> = {
+    /**
+     * The layer stack, from bottom to top. Array order is the stacking order.
+     */
+    layers: L;
+    /**
+     * One tag per variant layer, in any order.
+     */
+    defaults: readonly LayerTagsOf<L>[];
+};
+export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefinition | null, const Layers extends LayerGroupDefinition = LayerGroupDefinition> extends Displayable<ImageDataRaw, Image, TransformDefinitions.ImageTransformProps> implements EventfulDisplayable {
     /**
      * Construct an image element. The config can describe either static sources or tagged outfits, but not both.
      * @param config - Image metadata such as tags, source, layer, and wearables.
@@ -53,14 +86,17 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      * ```ts
      * const image = new Image({
      *   src: {
-     *     groups: [["happy", "sad"], ["top", "coat"]],
-     *     defaults: ["happy", "top"],
-     *     resolve: (emotion, top) => `https://img/${emotion}_${top}.png`
+     *     layers: [
+     *       "body.png",
+     *       {happy: "happy.png", sad: "sad.png"},
+     *       {shirt: "shirt.png", coat: "coat.png"},
+     *     ],
+     *     defaults: ["happy", "shirt"],
      *   }
      * });
      * ```
      */
-    constructor(config?: Partial<IImageUserConfig<Tags>>);
+    constructor(config?: Partial<IImageUserConfig<Tags, Layers>>);
     /**
      * Set the source of the image
      *
@@ -78,6 +114,7 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      */
     char(src: ImageSrc | Color, transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
     char(tags: SelectElementFromEach<Tags> | FlexibleTuple<SelectElementFromEach<Tags>>, transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
+    char(tags: LayerTagsOf<Layers>[], transition?: ImageTransition): Proxied<Image, Chained<LogicAction.Actions>>;
     /**
      * Set the darkness of the image
      * @param darkness - The darkness of the image, between 0 and 1

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

@@ -2,3 +2,20 @@ export type StorableData<K extends string = string> = {
     [key in K]: number | boolean | string | StorableData | StorableData[] | undefined | null | Date;
 };
 export type StorableType = BaseStorableType | Record<string, BaseStorableType> | Array<BaseStorableType>;
+/**
+ * A single stored value as it appears in a saved game. Values are tagged on the way out so
+ * that types JSON cannot express (currently `Date`) survive the round-trip.
+ *
+ * This is part of the on-disk save format rather than an implementation detail: it is what
+ * {@link SavedGame}'s `store` actually contains. Read it through `Namespace`, never by hand.
+ */
+export type WrappedStorableData<T extends StorableType = any> = {
+    type: BaseStorableTypeName;
+    data: T;
+};
+/**
+ * One namespace's contents in a saved game: every value wrapped by {@link WrappedStorableData}.
+ */
+export type SerializedNamespaceData = {
+    [key: string]: WrappedStorableData;
+};

package/dist/game/nlcore/elements/transition/transitions/image/fadeIn.d.ts

@@ -3,6 +3,17 @@ import { TransformDefinitions } from "../../../../elements/transform/type";
 import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
 import { GameState } from "../../../../../player/gameState";
 type AnimationType = [TransitionAnimationType.Number, TransitionAnimationType.Number, TransitionAnimationType.Number];
+/**
+ * A fade in, optionally travelling from a pixel offset to rest.
+ *
+ * The offset rides on the independent CSS `translate` property (not `transform`,
+ * and not `left`/`top`) for the same reason as {@link Push}: it composes additively
+ * with whatever base positioning the driven element already has, and it is the
+ * identity at offset `0`. Writing `transform` here instead would overwrite that
+ * base — a layered image's stack wrapper is positioned by `inset: 0` and carries
+ * no transform of its own, so a leftover `transform` from this transition would
+ * survive the crossfade and displace the settled stack.
+ */
 export declare class FadeIn extends ImageTransition<AnimationType> {
     private duration;
     private startPos;

package/dist/game/nlcore/elements/transition/transitions/image/imageTransition.d.ts

@@ -9,6 +9,20 @@ export declare abstract class ImageTransition<T extends TransitionAnimationType[
     /**@package */
     private _currentSrc;
     /**@package */
+    private _prevLayers;
+    /**@package */
+    private _targetLayers;
+    /**@package */
+    _setPrevLayers(layers: (string | null)[]): this;
+    /**@package */
+    _setTargetLayers(layers: (string | null)[]): this;
+    /**@package */
+    _getPrevLayers(): (string | null)[] | undefined;
+    /**@package */
+    _getTargetLayers(): (string | null)[] | undefined;
+    /**@package */
+    _isLayered(): boolean;
+    /**@package */
     _setPrevSrc(src: Color | ImageSrc | undefined): this;
     /**@package */
     _setTargetSrc(src: Color | ImageSrc | undefined): this;

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

@@ -1,6 +1,6 @@
 import { LogicAction } from "./action/logicAction";
 import { ContentNode, RawData } from "./action/tree/actionTree";
-import { StorableData } from "./elements/persistent/type";
+import { SerializedNamespaceData } from "./elements/persistent/type";
 import { ElementStateRaw } from "./elements/story";
 import { StringKeyOf } from "../../util/data";
 import { PlayerStateData } from "../player/gameState";
@@ -40,7 +40,7 @@ export interface SavedGame {
     meta: SavedGameMetaData;
     game: {
         store: {
-            [key: string]: StorableData;
+            [key: string]: SerializedNamespaceData;
         };
         elementStates: RawData<ElementStateRaw>[];
         stage: PlayerStateData;

package/dist/game/player/elements/image/Image.d.ts

@@ -1,3 +1,5 @@
+import React from "react";
 export type ImageEvents = {
     "event:image.onLoad": [];
 };
+export declare function stackStyle(darkness: number): React.CSSProperties;

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

@@ -37,6 +37,17 @@ export type NvlDialogEntry = {
     text: string;
 };
 export type NvlDialogPhase = "idle" | "typing" | "awaitAdvance";
+/**
+ * Transient tracking record for the currently displayed ADV dialog line.
+ * Rebuilt naturally on load/undo because the pending say action re-executes;
+ * never serialized.
+ */
+export type AdvDialogState = {
+    dialogId: string;
+    actionId: string | null;
+    /** True once the sentence finished displaying (typing done or skipped to full text). */
+    ended: boolean;
+};
 export type NvlState = {
     active: boolean;
     visible: boolean;
@@ -118,6 +129,7 @@ type GameStateEvents = {
     "event:state.end": [];
     "event:state.player.skip": [force?: boolean];
     "event:state.player.lineEnd": [];
+    "event:state.dialog.change": [];
     "event:state.player.requestFlush": [];
     "event:state.player.stageClick": [];
     "event:state.scene.mount": [scene: Scene];
@@ -165,6 +177,7 @@ export declare class GameState {
     pageRouter: null;
     private stageClickBuffer;
     private readonly nvlAdvanceWaiters;
+    private advDialogState;
     constructor(game: Game, stage: StageUtils);
     get deps(): number;
     addVideo(video: Video): this;
@@ -268,6 +281,20 @@ export declare class GameState {
     settleNvlDialog(dialogId: string): this;
     suppressNextNvlTyping(): this;
     consumeNvlTypingSuppression(): boolean;
+    /**
+     * Track the ADV dialog created by a say action. Emits `event:state.dialog.change`.
+     */
+    beginAdvDialog(dialogId: string, actionId: string | null): this;
+    /**
+     * Mark the tracked ADV dialog as fully displayed. No-op when the dialog id
+     * does not match the tracked one (e.g. DialogState reused outside ADV flow).
+     */
+    completeAdvDialogTyping(dialogId: string | undefined): this;
+    /**
+     * Clear the tracked ADV dialog when the line is advanced past or cancelled.
+     */
+    settleAdvDialog(dialogId: string): this;
+    getAdvDialogState(): AdvDialogState | null;
     recordStageClick(): this;
     consumeStageClick(maxAgeMs?: number): boolean;
     createDisplayable(displayable: LogicAction.DisplayableElements, scene?: Scene | null, layer?: Layer | null): this;