narraleaf-react 0.17.1 → 0.19.0

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

@@ -3,8 +3,9 @@ import { GameState } from "../../player/gameState";
 import { Storable, Namespace } from "../elements/persistent/storable";
 import { LiveGame } from "../game/liveGame";
 import { Preference } from "../game/preference";
+import type { StorableChange, StorableRestore } from "../elements/persistent/storable";
 import type { SavedGame } from "../gameTypes";
 import type { StackSnapshot, StackFrameSnapshot } from "../action/stackModel";
 import { KeyMap } from "../game/keyMap";
 export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, };
-export type { SavedGame, StackSnapshot, StackFrameSnapshot, };
+export type { SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };

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

@@ -3,6 +3,7 @@ import { Chained, Proxied } from "../../action/chain";
 import { GameState } from "../../common/game";
 import { LogicAction } from "../../game";
 import type { LiveGameEventToken } from "../../types";
+import { Image } from "../displayable/image";
 import { Layer } from "../layer";
 import { DynamicPersistent, Persistent } from "../persistent";
 import { Scene } from "../scene";
@@ -23,6 +24,15 @@ export declare class DevTools {
     static wrapAction(action: LogicAction.Actions[] | Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>>): ControlAction;
     static getNamespaceName(persistent: Persistent<any>): string;
     static getCurrentScene(gameState: GameState): Scene | null;
+    /**
+     * The src of each of a layered image's layers, bottom to top, for the given tags (the image's
+     * current ones when omitted). `null` entries are layers that draw nothing; a non-layered image
+     * yields an empty array.
+     *
+     * A layered image has no single src to read — it is a stack — so an editor host that renders
+     * its own thumbnail of an on-stage element has to composite these itself, in order.
+     */
+    static getLayerSrcs(image: Image, tags?: string[]): (string | null)[];
     /**
      * Register a displayable into a scene's render tree without emitting a `displayable:init`
      * action. The element renders immediately at its constructor-config transform state

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

@@ -49,10 +49,21 @@ export type TagSrcResolver<T extends TagGroupDefinition> = (...tags: SelectEleme
  * A set of mutually exclusive variants for one layer, keyed by tag.
  *
  * `null` means the layer draws nothing for that tag.
+ *
+ * The tag set is the group's identity: every layer offering the *same* set of tags is driven by
+ * one group, which is how a single `char(["angry"])` moves the brows, the eyes and the mouth at
+ * once. To follow a group, repeat its whole tag set on the layer and use `null` for the tags
+ * where that layer draws nothing. Offering only part of a set instead declares a *different*
+ * group, and the shared tags then collide.
  */
 export type LayerVariants = Record<string, string | null>;
 /**
  * Derives a layer's src from the currently active tags. Declares no tags of its own.
+ *
+ * A resolver is opaque, so the srcs it can return are invisible to the preloader and are fetched
+ * on first use. Prefer {@link LayerVariants} — including for a layer that follows another layer's
+ * group, which no longer needs a resolver — and keep resolvers for sources that genuinely cannot
+ * be enumerated.
  */
 export type LayerResolver = (tags: ReadonlySet<string>) => string | null;
 /**
@@ -74,7 +85,8 @@ export type LayeredDefinition<L extends LayerGroupDefinition = LayerGroupDefinit
      */
     layers: L;
     /**
-     * One tag per variant layer, in any order.
+     * One tag per group, in any order. Layers that offer the same tag set share a group and so
+     * share that one default.
      */
     defaults: readonly LayerTagsOf<L>[];
 };
@@ -88,10 +100,14 @@ export declare class Image<Tags extends TagGroupDefinition | null = TagGroupDefi
      *   src: {
      *     layers: [
      *       "body.png",
-     *       {happy: "happy.png", sad: "sad.png"},
      *       {shirt: "shirt.png", coat: "coat.png"},
+     *       // Both layers offer {happy, sad}, so one group drives them together.
+     *       {happy: "brows_happy.png", sad: "brows_sad.png"},
+     *       {happy: "mouth_happy.png", sad: "mouth_sad.png"},
+     *       // Follows the same group, and draws nothing while happy.
+     *       {happy: null, sad: "tears.png"},
      *     ],
-     *     defaults: ["happy", "shirt"],
+     *     defaults: ["shirt", "happy"],
      *   }
      * });
      * ```

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

@@ -1,4 +1,31 @@
-import { NameSpaceContent } from "../../elements/persistent/type";
+import { NameSpaceContent, StorableType } from "../../elements/persistent/type";
+import { EventDispatcher, EventToken } from "../../../../util/data";
+/**
+ * One stored value changing. Reported by {@link Storable.onChange} after the new value is
+ * already readable through `getNamespace(namespace).get(key)`.
+ */
+export type StorableChange<T extends StorableType = any> = {
+    /**
+     * The key the namespace is registered under in the {@link Storable} — the same string
+     * {@link Storable.getNamespace} takes, and the one a save file carries. For a namespace
+     * declared with `new Persistent("player", ...)` this is `"persistent:player"`.
+     */
+    namespace: string;
+    key: string;
+    /** The value that was there. `undefined` if the key had never been written. */
+    previous: T | undefined;
+    /** The value that is there now. `undefined` if the key was dropped (see {@link Namespace.reset}). */
+    next: T | undefined;
+};
+/**
+ * A bulk value application — a save being loaded, or a namespace being rewound to a
+ * snapshot. Reported by {@link Storable.onRestore} *instead of* per-key changes; see the
+ * note on {@link Namespace.deserialize}.
+ */
+export type StorableRestore = {
+    /** The namespace keys whose contents were replaced. */
+    namespaces: string[];
+};
 export declare class Namespace<T extends NameSpaceContent<keyof T>> {
     static isSerializable(value: any): boolean;
     name: string;
@@ -11,10 +38,25 @@ export declare class Namespace<T extends NameSpaceContent<keyof T>> {
     keys(): (keyof T)[];
     values(): T[keyof T][];
     entries(): [keyof T, T[keyof T]][];
+    /**
+     * Restore the author's defaults.
+     *
+     * Reports one change per key that actually moved. A key written after construction is
+     * not in the defaults, so it is dropped and reported as changing to `undefined`.
+     */
     reset(): this;
 }
 export declare class Storable {
+    static EventTypes: {
+        readonly "event:storable.change": "event:storable.change";
+        readonly "event:storable.restore": "event:storable.restore";
+    };
     static createNamespace<T extends NameSpaceContent<keyof T>>(name: string, initContent: T, key?: string): Namespace<T>;
+    /**
+     * Changes to any value in any registered namespace. Prefer {@link Storable.onChange},
+     * which filters by namespace and key.
+     */
+    readonly events: EventDispatcher<StorableEvents>;
     addNamespace<T extends NameSpaceContent<keyof T>>(namespace: Namespace<T>): this | undefined;
     getNamespace<T extends NameSpaceContent<keyof T> = any>(key: string): Namespace<T>;
     setNamespace<T extends NameSpaceContent<keyof T> = any>(key: string, namespace: Namespace<T>): this;
@@ -26,4 +68,45 @@ export declare class Storable {
     keys(): string[];
     values(): Namespace<any>[];
     entries(): [string, Namespace<any>][];
+    /**
+     * Listen for a stored value changing.
+     *
+     * The listener runs after the new value is readable, and only when the value actually
+     * moved — writing a value equal to the one already there reports nothing, so a line that
+     * re-asserts a flag every time it runs does not wake anything up. Equality is structural,
+     * so rebuilding an object with the same contents is also a no-op.
+     *
+     * Loading a save does not report changes; see {@link Storable.onRestore}.
+     *
+     * Subscriptions outlive the namespaces they watch: `newGame()` and loading a save both
+     * rebuild every namespace from scratch, and a listener registered here survives that.
+     *
+     * @example
+     * ```ts
+     * // every change, anywhere
+     * liveGame.getStorable().onChange(({namespace, key, previous, next}) => {...});
+     *
+     * // one namespace
+     * liveGame.getStorable().onChange("persistent:player", ({key, next}) => {...});
+     *
+     * // one key
+     * liveGame.getStorable().onChange("persistent:player", "gold", ({next}) => {
+     *     if (next === 100) {...}
+     * });
+     * ```
+     * @returns a token whose `cancel()` removes the listener
+     */
+    onChange(listener: (change: StorableChange) => void): EventToken;
+    onChange(namespace: string, listener: (change: StorableChange) => void): EventToken;
+    onChange(namespace: string, key: string, listener: (change: StorableChange) => void): EventToken;
+    /**
+     * Listen for the store being replaced wholesale — loading a save, or rewinding a
+     * namespace to a snapshot. Fires once per bulk application, naming the namespaces
+     * involved, instead of the changes it implies.
+     *
+     * Re-read whatever you derive from the store when this fires.
+     *
+     * @returns a token whose `cancel()` removes the listener
+     */
+    onRestore(listener: (restore: StorableRestore) => void): EventToken;
 }