narraleaf-react 0.17.1 → 0.18.0

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"],
      *   }
      * });
      * ```