hayao 0.1.0 → 0.2.0

package/dist/scene/floatingText.d.ts

@@ -0,0 +1,51 @@
+import type { Transform, Vec2 } from '../core/math';
+import type { DrawCommand, TextAlign } from '../render/commands';
+import { Node, type NodeConfig } from './node';
+export interface FloatStyle {
+    /** Text colour. */
+    color: string;
+    /** Font size in px. */
+    size?: number;
+    font?: string;
+    weight?: number;
+    align?: TextAlign;
+    /** Upward speed in px/s (screen +y is down, so this is negated internally). */
+    rise?: number;
+    /** Gravity pulling the rise back down (px/s²) — arcs the pop. */
+    gravity?: number;
+    /** Lifetime in seconds. */
+    life?: number;
+    /** Random horizontal spread of the launch (px/s). */
+    jitter?: number;
+    /** Fraction of life spent fading out at the end (0..1, default 0.4). */
+    fade?: number;
+}
+/**
+ * A pooled floating-text emitter. Call `pop(text, at, style)` from game code in
+ * response to feel events. Always cosmetic; add it wherever the numbers should
+ * live in the tree (usually the world layer, so pops ride the camera).
+ */
+export declare class FloatingText extends Node {
+    readonly type: string;
+    private pool;
+    private rng;
+    /** Cap on live popups (oldest recycled first). */
+    maxPopups: number;
+    constructor(config?: NodeConfig & {
+        seed?: number;
+        maxPopups?: number;
+    });
+    /** Spawn one popup at `at` (in this node's local space). */
+    pop(text: string, at: Vec2, style: FloatStyle): void;
+    private gravity;
+    protected onProcess(dt: number): void;
+    protected draw(out: DrawCommand[], world: Transform): void;
+    get liveCount(): number;
+}
+/** Ready-made popup looks for the common combat moments. */
+export declare const FLOAT_PRESETS: {
+    readonly damage: (color?: string) => FloatStyle;
+    readonly crit: (color?: string) => FloatStyle;
+    readonly heal: (color?: string) => FloatStyle;
+    readonly label: (color?: string) => FloatStyle;
+};

package/dist/scene/particles.d.ts

@@ -53,6 +53,70 @@ export declare const PARTICLE_PRESETS: {
     readonly hit: (colors?: string[]) => ParticleStyle;
     readonly sparkle: (colors?: string[]) => ParticleStyle;
 };
+export interface AmbientStyle {
+    /** Colors drawn from at random per particle. */
+    colors: string[];
+    /** Particle radius range (px). */
+    sizeMin: number;
+    sizeMax: number;
+    /** Steady horizontal wind (px/s). */
+    windX?: number;
+    /** Fall speed (px/s, +y down). Snow ≈ 40, rain ≈ 600. */
+    fallY: number;
+    /** Horizontal sway amplitude (px) and frequency (Hz) — gives snow its wobble. */
+    swayAmp?: number;
+    swayFreq?: number;
+    /** Draw vertical streaks instead of dots (rain). */
+    streak?: boolean;
+    /** Streak length (px) in streak mode. Default = fallY * 0.03. */
+    streakLen?: number;
+}
+/** A single weather keyframe: `intensity` (0..1) reached at sim `time` (s). */
+export interface WeatherKey {
+    time: number;
+    intensity: number;
+}
+/**
+ * Smoothstep-interpolated weather intensity at sim time `t` over an ordered list
+ * of keyframes. Before the first / after the last key it holds that key's value.
+ * Pure — drive it with `world.time`, never wall-clock.
+ */
+export declare function weatherEnvelope(t: number, keys: readonly WeatherKey[]): number;
+/**
+ * A screen-wrapping ambient field for snow, rain, dust, or ash. Seed once with a
+ * region size; it fills itself and drifts forever. Set `.envelope` to fade the
+ * weather in/out over sim time. Always cosmetic.
+ */
+export declare class AmbientField extends Node {
+    readonly type: string;
+    private rng;
+    private field;
+    private time;
+    private style;
+    /** Field region (px). Particles wrap within [0,width] × [0,height]. */
+    width: number;
+    height: number;
+    /** Optional weather intensity schedule; scales count/opacity. */
+    envelope?: WeatherKey[];
+    constructor(config: NodeConfig & {
+        seed?: number;
+        count?: number;
+        width: number;
+        height: number;
+        style: AmbientStyle;
+        envelope?: WeatherKey[];
+    });
+    private intensity;
+    protected onProcess(dt: number): void;
+    protected draw(out: DrawCommand[], world: Transform): void;
+    get liveCount(): number;
+}
+/** Ready-made ambient weather styles (pair with `AmbientField`). */
+export declare const AMBIENT_PRESETS: {
+    readonly snow: (colors?: string[]) => AmbientStyle;
+    readonly rain: (colors?: string[]) => AmbientStyle;
+    readonly ash: (colors?: string[]) => AmbientStyle;
+};
 /**
  * Screen shake as a cosmetic camera offset with its own Rng and exponential
  * decay. Attach to whatever node the camera follows and read `offset` into the

package/dist/scene/pool.d.ts

@@ -0,0 +1,16 @@
+import type { Node } from './node';
+export declare class NodePool<T extends Node = Node> {
+    private parent;
+    private make;
+    private items;
+    private used;
+    constructor(parent: Node, make: () => T);
+    /** Start a frame: every pooled node is up for reuse. */
+    begin(): void;
+    /** Claim the next node (created and parented on first use), made visible. */
+    get(): T;
+    /** End a frame: hide every node not claimed since begin(). */
+    end(): void;
+    /** Nodes claimed this frame (call after the get() loop). */
+    get liveCount(): number;
+}

package/dist/scene/tween.d.ts

@@ -1,5 +1,31 @@
 import { Node } from './node';
 export type Easing = (t: number) => number;
+/**
+ * Exponentially damp `current` toward `target`, framerate-independent.
+ * `lambda` is the decay rate (1/s): larger = snappier. Reaches ~63% of the way
+ * to the target after 1/lambda seconds regardless of how dt is subdivided.
+ */
+export declare const lerpDamp: (current: number, target: number, lambda: number, dt: number) => number;
+/** A critically-damped spring value: rides toward a target with no overshoot. */
+export interface SpringState {
+    value: number;
+    vel: number;
+}
+/** Make a spring at rest on `value`. */
+export declare const spring: (value?: number) => SpringState;
+/**
+ * Advance a critically-damped spring one fixed step toward `target`. `omega` is
+ * the angular frequency (rad/s) — higher snaps faster. Critical damping means it
+ * settles as fast as possible without oscillating. Mutates and returns the state.
+ * Uses the closed-form solution so it is stable at any dt (no stiffness blow-up).
+ */
+export declare function springStep(s: SpringState, target: number, omega: number, dt: number): SpringState;
+/**
+ * One-liner critically-damped follow that owns its own velocity in a closure —
+ * for camera/value chase where you don't want to thread a SpringState around.
+ * `settle` is the approximate time (s) to arrive. Returns a `(target, dt) → value`.
+ */
+export declare function makeReach(start?: number, settle?: number): (target: number, dt: number) => number;
 export declare const EASINGS: Record<string, Easing>;
 /** A node that runs one or more property tweens and reports when they finish. */
 export declare class AnimationPlayer extends Node {

package/dist/ui/transition.d.ts

@@ -0,0 +1,107 @@
+import { type Rect, type Transform } from '../core/math';
+import type { DrawCommand } from '../render/commands';
+import { Node, type NodeConfig } from '../scene/node';
+export type WipeKind = 'fade' | 'circle' | 'dither';
+export interface WipeOptions {
+    /** Seconds to cover the screen (default 0.4). */
+    cover?: number;
+    /** Seconds to hold fully covered before revealing (default 0). */
+    hold?: number;
+    /** Seconds to reveal the scene again (default = cover). */
+    reveal?: number;
+    /** Fired at full cover — swap the level/scene here. */
+    onMidpoint?: () => void;
+    /** Fired once the reveal finishes. */
+    onDone?: () => void;
+}
+export interface TransitionConfig extends NodeConfig {
+    kind?: WipeKind;
+    /** Overlay colour. */
+    color?: string;
+    /** Screen size in px (pass world.width / world.height). */
+    width?: number;
+    height?: number;
+    /** Dither cell size in px (default 28). */
+    cell?: number;
+}
+/**
+ * A full-screen wipe overlay. Add it to the tree (cosmetic), then drive it with
+ * `cover()` / `reveal()` / `wipe()`. `coverage` runs 0 (clear) → 1 (opaque).
+ */
+export declare class ScreenTransition extends Node {
+    readonly type: string;
+    kind: WipeKind;
+    color: string;
+    screenW: number;
+    screenH: number;
+    cell: number;
+    /** 0 = fully clear, 1 = fully covering. */
+    coverage: number;
+    private queue;
+    constructor(config?: TransitionConfig);
+    /** True while a wipe is animating. */
+    get busy(): boolean;
+    private enqueue;
+    /** Animate the overlay to fully covering over `dur` seconds. */
+    cover(dur?: number, onEnd?: () => void): this;
+    /** Animate the overlay back to fully clear over `dur` seconds. */
+    reveal(dur?: number, onEnd?: () => void): this;
+    /** Hold the current coverage for `dur` seconds (chains after cover/reveal). */
+    hold(dur: number, onEnd?: () => void): this;
+    /** The classic cover → onMidpoint → reveal sequence. Returns this for chaining. */
+    wipe(opts?: WipeOptions): this;
+    /** Signal emitted at full cover (the midpoint). */
+    get covered(): import("..").Signal<void>;
+    /** Signal emitted when a wipe fully finishes revealing. */
+    get done(): import("..").Signal<void>;
+    protected onProcess(dt: number): void;
+    protected draw(out: DrawCommand[], _world: Transform): void;
+}
+export interface CinematicStep {
+    /** Optional label (handy for debugging/skip logic). */
+    name?: string;
+    /** Runs once when the step begins — aim the camera, set text, mutate state. */
+    enter?: () => void;
+    /** Minimum seconds to hold on this step before advancing (default 0). */
+    duration?: number;
+    /** Gate: advance only once this returns true (e.g. `() => !transition.busy`). */
+    until?: () => boolean;
+}
+/**
+ * Runs a list of pure-data cinematic steps on the fixed clock. Each step's
+ * `enter` fires once, then the player waits for both its `duration` and its
+ * `until` gate before moving on — the fade-gate pattern for scripted intros.
+ * Cosmetic: it only orchestrates view/state changes, holds no hashed state.
+ */
+export declare class CinematicPlayer extends Node {
+    readonly type: string;
+    private steps;
+    private index;
+    private elapsed;
+    private running;
+    private onFinish?;
+    constructor(config?: NodeConfig);
+    /** Load and start a sequence. `onDone` fires after the last step advances. */
+    play(steps: CinematicStep[], onDone?: () => void): this;
+    /** True while a sequence is playing. */
+    get active(): boolean;
+    /** Index of the step currently on screen (−1 before play / after finish). */
+    get step(): number;
+    /** Signal emitted when the whole sequence finishes. */
+    get finished(): import("..").Signal<void>;
+    private advance;
+    /** Abort the sequence immediately (no further enters, no finish callback). */
+    stop(): void;
+    protected onProcess(dt: number): void;
+}
+/**
+ * Convenience: make a Transition sized to a world and add it to a parent (the
+ * scene root by default, so it paints over everything). Returns the node.
+ */
+export declare function addTransition(parent: Node, config?: TransitionConfig): ScreenTransition;
+/** A cinematic step that fires a wipe and gates advancement on its completion. */
+export declare function wipeStep(transition: ScreenTransition, opts?: WipeOptions & {
+    name?: string;
+}): CinematicStep;
+/** Screen rect helper for wiring a Transition into other 9-slice/UI code. */
+export declare const screenRect: (w: number, h: number) => Rect;

package/dist/verify/layout.d.ts

@@ -0,0 +1,39 @@
+import type { DrawCommand, TextCommand } from '../render/commands';
+import type { InputMap } from '../input/actions';
+import type { World } from '../world';
+export interface TextBox {
+    cmd: TextCommand;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Approximate a text command's on-screen box (serif ≈ 0.56em per char). */
+export declare function textBox(cmd: TextCommand): TextBox;
+/** Conservative bounds of a non-text command (local shape + translation). */
+export declare function shapeBox(cmd: DrawCommand): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+export interface LayoutOptions {
+    /** Shapes at or below this z are background lattice (tiles/felt) and may sit under text. */
+    backgroundZ?: number;
+    /** Extra pixels of breathing room demanded around text (default 0 = touch is allowed, overlap is not). */
+    margin?: number;
+}
+/**
+ * Lint a display list for text readability. Returns human-readable issues
+ * (empty = clean). Checks: text-vs-shape partial overlaps (rule 1) and
+ * text-vs-text overlaps.
+ */
+export declare function layoutIssues(commands: DrawCommand[], opts?: LayoutOptions): string[];
+/** Friendly names a hint text may use to reference a key code. */
+export declare function keyMentions(code: string): string[];
+/**
+ * First-contact check: which actions does no on-screen text explain? An
+ * action passes if any text mentions its name or one of its keys' friendly
+ * names. 'restart' is exempt (universal convention).
+ */
+export declare function missingControlHints(world: World, inputMap: InputMap): string[];