narraleaf-react 0.29.0 → 0.30.0

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

@@ -22,9 +22,10 @@ export declare const DisplayableActionTypes: {
     readonly applyTransform: "displayable:applyTransform";
     readonly applyTransition: "displayable:applyTransition";
     readonly init: "displayable:init";
+    readonly bringToFront: "displayable:bringToFront";
 };
 export type DisplayableActionContentType<TransitionType extends Transition = Transition> = {
-    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : any;
+    [K in typeof DisplayableActionTypes[keyof typeof DisplayableActionTypes]]: K extends "displayable:applyTransform" ? [Transform] : K extends "displayable:applyTransition" ? [TransitionType, ((transition: TransitionType) => TransitionType)?] : K extends "displayable:init" ? [scene: Scene | null, layer: Layer | null, isElement?: boolean] : K extends "displayable:bringToFront" ? [] : any;
 };
 export declare const CharacterActionTypes: {
     readonly say: "character:say";

package/dist/game/nlcore/action/actions/displayableAction.d.ts

@@ -17,10 +17,26 @@ export declare class DisplayableAction<T extends Values<typeof DisplayableAction
         readonly applyTransform: "displayable:applyTransform";
         readonly applyTransition: "displayable:applyTransition";
         readonly init: "displayable:init";
+        readonly bringToFront: "displayable:bringToFront";
     };
     executeAction(gameState: GameState, injection: ActionExecutionInjection): ExecutedActionResult;
     applyTransform(state: GameState, element: Displayable<any, any>, transform: Transform, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
     applyTransition(state: GameState, element: Displayable<any, any>, transition: TransitionType, injection: ActionExecutionInjection, onFinished?: () => void): Awaitable<CalledActionResult, CalledActionResult>;
     initDisplayable(state: GameState, scene: Scene | null, element: Displayable<any, any>, layer: Layer | null, isElement: boolean | undefined, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * Move the element to the end of the array its layer draws from.
+     *
+     * A layer renders its elements in array order, so the last entry is the one drawn on top; there
+     * is no per-element depth number to set. Reordering the array rather than introducing one is
+     * what keeps this saveable for free — {@link GameState.toData} writes each layer out as a list
+     * of ids in exactly this order, and loading rebuilds the array from it.
+     *
+     * Nothing is tweened, so the returned awaitable is settled before it is handed back.
+     */
+    bringToFront(state: GameState, element: Displayable<any, any>, injection: ActionExecutionInjection): Awaitable<CalledActionResult>;
+    /**
+     * The array of the scene's layer that currently holds this element, or null if none does.
+     */
+    private static getLayerElements;
     stringify(_story: Story, _seen: Set<LogicAction.Actions>, _strict: boolean): string;
 }

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

@@ -9,8 +9,9 @@ import { Darkness } from "../elements/transition/transitions/image/darkness";
 import { Exposure } from "../elements/transition/transitions/image/exposure";
 import { ThroughColor } from "../elements/transition/transitions/image/throughColor";
 import { Reveal } from "../elements/transition/transitions/image/reveal";
+import { RuleReveal } from "../elements/transition/transitions/image/ruleReveal";
 import { Mask } from "../elements/transition/transitions/image/mask";
-export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, Exposure, ThroughColor, Reveal, Mask, };
+export { Transition, ImageTransition, TextTransition, Dissolve, FadeIn, BlurDissolve, Push, Darkness, Exposure, ThroughColor, Reveal, RuleReveal, Mask, };
 export type { DissolveOptions } from "../elements/transition/transitions/image/dissolve";
 export type { FadeInOptions } from "../elements/transition/transitions/image/fadeIn";
 export type { BlurDissolveOptions } from "../elements/transition/transitions/image/blurDissolve";
@@ -19,5 +20,6 @@ export type { DarknessOptions } from "../elements/transition/transitions/image/d
 export type { ExposureOptions } from "../elements/transition/transitions/image/exposure";
 export type { ThroughColorOptions, ThroughColorUncover, } from "../elements/transition/transitions/image/throughColor";
 export type { RevealOptions } from "../elements/transition/transitions/image/reveal";
+export type { RuleRevealOptions } from "../elements/transition/transitions/image/ruleReveal";
 export type { MaskPattern, WipePatternOptions, BarnDoorPatternOptions, IrisPatternOptions, ClockPatternOptions, FanPatternOptions, BlindsPatternOptions, DotsPatternOptions, } from "../elements/transition/transitions/image/mask";
 export type { BlindsOrientation } from "../elements/transition/transitions/image/transitionMaskUtils";

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

@@ -82,4 +82,20 @@ export declare class Camera extends Displayable<CameraDataRaw, Camera, Transform
      * ```
      */
     resetCamera(duration?: number, easing?: TransformDefinitions.EasingDefinition): Proxied<Camera, Chained<LogicAction.Actions, Camera>>;
+    /**
+     * Not available on a camera: a camera has no front or back to be moved to.
+     *
+     * `bringToFront` reorders the list of elements a layer draws, and the camera is in no such list
+     * — it is the thing those lists are drawn *inside*. Every layer of every scene moves with it as
+     * one unit, which is the whole point of it, and there is therefore no sprite it could be put in
+     * front of. This is not a matter of the camera not being on stage yet, which is what the
+     * inherited error would have said: waiting changes nothing, because the camera never enters a
+     * layer at all.
+     *
+     * Reach for a transform instead — `zoom`, or {@link Camera.pan} — if the goal was to
+     * bring something into view.
+     *
+     * @throws RuntimeGameError - always
+     */
+    bringToFront(): never;
 }

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

@@ -179,6 +179,29 @@ export declare abstract class Displayable<StateData extends Record<string, any>,
      * ```
      */
     transform(transform: Transform<TransformType>): Proxied<Self, Chained<LogicAction.Actions, Self>>;
+    /**
+     * Bring the Displayable to the front of the layer it is on.
+     *
+     * Within one layer the order elements are shown in is the order they were added in, so the one
+     * added last is drawn over the others. This moves the element to the end of that order, and
+     * nothing else about it changes — it stays on the same layer, keeps its transform, and the move
+     * is instant.
+     *
+     * Depth *between* layers is a separate thing, decided by each layer's z-index; this cannot lift
+     * an element above one that sits on a higher layer.
+     *
+     * The new order is part of the saved game, so a save taken afterwards restores it.
+     *
+     * @chainable
+     * @example
+     * ```ts
+     * scene.action([
+     *     yukoSprite.bringToFront(),
+     *     yuko.say`It was me, all along.`,
+     * ]);
+     * ```
+     */
+    bringToFront(): Proxied<Self, Chained<LogicAction.Actions, Self>>;
     private registerEffectSrc;
     private static toCSSUrl;
     private static extractCSSUrls;

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

@@ -44,4 +44,15 @@ export declare class Layer extends Displayable<LayerDataRaw, Layer, TransformDef
      * @chainable
      */
     setZIndex(zIndex: number): Proxied<Layer, Chained<LogicAction.Actions>>;
+    /**
+     * Not available on a layer: depth between layers is the z-index.
+     *
+     * `bringToFront` moves an element to the end of the list its layer draws, and a layer is not
+     * in any such list — it *is* one. Accepting the call would mean accepting a story that reads as
+     * if it raised the layer and plays as if the line were not there, which is the failure the
+     * throw exists to prevent. Use {@link Layer.setZIndex} instead.
+     *
+     * @throws RuntimeGameError - always
+     */
+    bringToFront(): never;
 }

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

@@ -0,0 +1,102 @@
+import { AnimationController, AnimationTaskMapArray, TransitionAnimationType, TransitionTask } from "../../../../elements/transition/type";
+import { TransformDefinitions } from "../../../../elements/transform/type";
+import { ImageTransition } from "../../../../elements/transition/transitions/image/imageTransition";
+import { ImageSrc } from "../../../../types";
+type AnimationType = [TransitionAnimationType.Number];
+export type RuleRevealOptions = {
+    /** Duration in milliseconds. */
+    duration: number;
+    /**
+     * The rule image: a greyscale picture whose brightness at each point says *when* that point
+     * changes over. Dark changes first, bright last, so a rule painted as a spiral wipes as a
+     * spiral. Stretched to the frame, so paint it at the stage's aspect ratio.
+     */
+    rule: ImageSrc;
+    /**
+     * Width of the soft edge, as a fraction of the rule's brightness range. `0.12` puts roughly an
+     * eighth of the rule's tonal range in transition at any moment; smaller is a crisper edge.
+     * @default 0.12
+     */
+    feather?: number;
+    /** Change the bright areas over first instead of the dark ones. @default false */
+    inverted?: boolean;
+    easing?: TransformDefinitions.EasingDefinition;
+};
+/**
+ * The **rule-image** engine: the target is revealed over the previous frame in the order a
+ * greyscale picture dictates, rather than through a geometric pattern.
+ *
+ * This is the transition form commercial visual novels are authored against — a pack of rule
+ * images (spirals, shatters, brush strokes, drifting cloud fronts) and one engine that plays any of
+ * them. {@link Reveal} covers the geometric half of the same job with {@link Mask} patterns, which
+ * are CSS gradients and therefore limited to shapes that can be *described*; a rule image is
+ * per-pixel data and can be any shape at all, which is why it is its own engine rather than another
+ * `MaskPattern`.
+ *
+ * ```ts
+ * scene.jumpTo(next, new RuleReveal({duration: 1200, rule: "/rules/spiral.png"}))
+ * ```
+ *
+ * ### How it works, and the one thing worth knowing
+ *
+ * At progress `t` a point changes over once the sweep has passed its brightness:
+ *
+ * ```text
+ * alpha = clamp01((T - luminance) / feather),  T sweeping 0 .. 1 + feather
+ * ```
+ *
+ * That is computed by an SVG filter — `feImage` reads the rule, `feColorMatrix` turns its
+ * brightness into coverage, and one `feComposite` does the comparison — so the whole sweep is one
+ * GPU pass over the frame and costs the same as no filter at all in practice.
+ *
+ * The filter runs in **sRGB**, deliberately: filters default to linearRGB, under which a rule's
+ * mid-grey would land at 0.21 rather than half way, and every rule in a pack would play with its
+ * timing bent. Nothing about that failure looks like an error, so it is pinned here rather than
+ * left to a default.
+ */
+export declare class RuleReveal extends ImageTransition<AnimationType> {
+    private duration;
+    private rule;
+    private feather;
+    private inverted;
+    private easing?;
+    /**@package */
+    private filterId;
+    /**@package */
+    private host;
+    /**@package */
+    private cut;
+    constructor(options: RuleRevealOptions);
+    createTask(): TransitionTask<HTMLImageElement, AnimationType>;
+    /**
+     * Tear the scaffold down when the run ends, however it ends.
+     *
+     * Both drivers call this, and the controller they get back outlives the React element — a
+     * transition whose element unmounts mid-run still completes its value animation — so this is
+     * the one place that sees every ending. {@link styleAt} also drops it on the settled frame, so
+     * the normal path never waits for this.
+     * @package
+     */
+    requestAnimations(tasks: AnimationTaskMapArray<AnimationType>): AnimationController<AnimationType>;
+    copy(): RuleReveal;
+    /**
+     * The style for one frame — and the side of this class that has to stay honest about the DOM.
+     *
+     * The settled frame carries no filter at all rather than a filter wound to its end: a filter
+     * left on a scene root keeps that subtree rasterised as one layer, and the settled pose resets
+     * `filter` on the assumption that a finished transition owns nothing.
+     * @package
+     */
+    private styleAt;
+    /**
+     * Build the filter once, on first use, and hand back the id to point `filter` at.
+     *
+     * Not built in `createTask`: that method is documented as free of side effects, and it is
+     * called by callers that only want to read what a transition would write.
+     * @package
+     */
+    private ensureScaffold;
+    /**@package */
+    private dispose;
+}
+export {};