@nayan-ui/engine 0.0.0-stage → 1.0.0-beta.4

package/lib/web/types/src/world/Scoreboard.d.ts

@@ -0,0 +1,74 @@
+export type ScoreboardHandlers = {
+    /** The score changed (points, time-based points, reset). */
+    onScore?: (score: number) => void;
+    onLives?: (lives: number) => void;
+    /** The whole seconds shown changed: time left for a countdown, elapsed otherwise. */
+    onSecond?: (seconds: number) => void;
+    /** A countdown reached 0 (the clock stops). */
+    onTimeUp?: () => void;
+    /** Lives went from above 0 to 0. */
+    onLivesOut?: () => void;
+};
+/**
+ * Score, lives and the game clock, kept and advanced in Rust by `world.update`: countdowns, elapsed
+ * time and time-based points (survival, distance) cost no JS per frame. Handlers run from `update`
+ * only when something they show changed. Set `handlers` for the game's own rules, and `listen` for
+ * anything else that follows along (a UI showing the score), so neither replaces the other.
+ *
+ * ```ts
+ * world.scoreboard.handlers = { onTimeUp: () => end(true) };
+ * const stop = world.scoreboard.listen({ onScore: setScore, onSecond: setTime });
+ * world.scoreboard.reset(3);
+ * world.scoreboard.startCountdown(60);
+ * world.scoreboard.add(10);
+ * ```
+ */
+export declare class Scoreboard {
+    private readonly world;
+    /** The game's own handlers. `listen` adds more without replacing these. */
+    handlers: ScoreboardHandlers;
+    private readonly listeners;
+    private readonly state;
+    /** @internal */
+    constructor(world: number);
+    private op;
+    get score(): number;
+    get best(): number;
+    get lives(): number;
+    /** Seconds left (countdown) or elapsed, fractional. */
+    get seconds(): number;
+    /** Whole seconds as shown: rounded up while counting down, down while counting up. */
+    get shownSeconds(): number;
+    get running(): boolean;
+    /** Adds points (negative to take away). Returns the score. */
+    add(points: number): number;
+    set(score: number): number;
+    addLives(n: number): number;
+    setLives(n: number): void;
+    /** Counts `seconds` down to 0 (then `onTimeUp`), earning `pointsPerSecond` meanwhile. */
+    startCountdown(seconds: number, pointsPerSecond?: number): void;
+    /** Counts up from 0, earning `pointsPerSecond` (survival and distance scores). */
+    startClock(pointsPerSecond?: number): void;
+    stop(): void;
+    resume(): void;
+    /** Time bonus (or penalty) on the clock. */
+    addTime(seconds: number): void;
+    /**
+     * Adds `pointsPerSecond` for each whole second saved: the seconds left on a countdown, or
+     * `expectedSeconds` minus the seconds elapsed on a clock counting up. Returns the score.
+     */
+    awardTimeBonus(pointsPerSecond: number, expectedSeconds?: number): number;
+    /**
+     * A new run: score 0, `lives`, clock stopped at 0. With `countdownSeconds`, the stopped clock shows
+     * that countdown in full (a ready screen); `resume()` starts it.
+     */
+    reset(lives?: number, countdownSeconds?: number): void;
+    /**
+     * Adds handlers alongside `handlers` (and other listeners); they run after them, in order of
+     * listening. Returns a function that removes them.
+     */
+    listen(handlers: ScoreboardHandlers): () => void;
+    /** @internal Runs handlers for what changed since the last call. */
+    dispatch(): void;
+    private run;
+}

package/lib/web/types/src/world/TransformBatch.d.ts

@@ -0,0 +1,38 @@
+import type { Entity, EntityOptions } from './types';
+export type TransformOptions = Pick<EntityOptions, 'position' | 'rotation' | 'scale' | 'color'>;
+export declare const TRANSFORM_STRIDE = 16;
+/**
+ * Explicit draw-only updates, applied in one native call by `flush()`. `world.update` flushes
+ * `world.transforms` before stepping; flush yourself before reading positions or animating. Records and scratch storage are reused; values are
+ * copied when queued, never retained by reference. The scalar methods (`position`, `rotation`,
+ * `scale`, `color`, `transform`) allocate nothing; consecutive calls for the same entity share one
+ * record.
+ *
+ * ```ts
+ * const batch = world.transforms;
+ * for (const p of pieces) batch.transform(p.entity, p.x, 0, p.z, 0, p.qy, 0, p.qw);
+ * batch.flush();
+ * ```
+ */
+export declare class TransformBatch {
+    private readonly commit;
+    private data;
+    private count;
+    constructor(commit: (data: Float64Array, count: number) => number);
+    private record;
+    position(entity: Entity, x: number, y: number, z: number): void;
+    /** Rotation quaternion [x, y, z, w]. */
+    rotation(entity: Entity, x: number, y: number, z: number, w: number): void;
+    /** Uniform scale, or per axis. */
+    scale(entity: Entity, x: number, y?: number, z?: number): void;
+    /** RGBA color; alpha defaults to 1. */
+    color(entity: Entity, r: number, g: number, b: number, a?: number): void;
+    /** Position and rotation together (the common per-frame update for a moving piece). */
+    transform(entity: Entity, x: number, y: number, z: number, qx: number, qy: number, qz: number, qw: number): void;
+    /** Queued records (merged per entity). */
+    get size(): number;
+    set(entity: Entity, options: TransformOptions): void;
+    private writeColor;
+    flush(): number;
+    clear(): void;
+}

package/lib/web/types/src/world/World.d.ts

@@ -0,0 +1,206 @@
+import { type RenderSource, type Vec3 } from '../types';
+import { Scoreboard } from './Scoreboard';
+import { TransformBatch } from './TransformBatch';
+import type { AnimateOptions, AnimateTarget, Bounds, BurstOptions, ClipOptions, CollisionInfo, Entity, EntityOptions, Keyframe, PickHit, RaycastHit, ScreenPlane } from './types';
+/** True when the engine's native code is linked into this build (it is not in Expo Go). */
+export declare const isEngineAvailable: boolean;
+/**
+ * A game world, simulated by the Rust core: entities, motion, Rapier physics, collisions,
+ * animations and raycasts at a fixed 60 Hz, with rendering smoothed between steps. Pass it to `<GameView>`.
+ *
+ * ```ts
+ * const world = new World(500);
+ * const ball = world.spawn({ mesh: "sphere", position: [0, 5, 0], physics: "dynamic" });
+ * world.set(ball, { color: [1, 0, 0] });
+ * ```
+ */
+export declare class World implements RenderSource {
+    readonly capacity: number;
+    readonly matrices: Float32Array;
+    readonly colors: Float32Array;
+    readonly regions: Float32Array;
+    readonly ranges: Uint32Array;
+    private readonly events;
+    private readonly eventFloats;
+    private readonly finished;
+    private readonly scratch;
+    private readonly desc;
+    private anim;
+    private readonly burstDesc;
+    private readonly info;
+    /** Promise resolvers of running animations, by animation id. */
+    private readonly pending;
+    /** Callbacks of pending `after` timers, by timer id (the core counts the time). */
+    private readonly timers;
+    /** Timers for a native core built before `after` existed: [fire time, callback], on `clock`. */
+    private fallbackTimers;
+    private fallbackTimerId;
+    private transformsValue;
+    private clock;
+    private scoreboardValue;
+    private readonly texts;
+    private readonly id;
+    private disposed;
+    private gravityValue;
+    private boundsValue;
+    private listenerValue;
+    private updates;
+    constructor(capacity: number);
+    private get native();
+    /** True once `dispose()` has run. Cleanup calls (despawn, set, has, queries, stopping animations
+     * and timers) are safe no-ops afterwards, so late animation promises and timers need no guard.
+     */
+    get isDisposed(): boolean;
+    /** Live entities (text letters count too). */
+    get count(): number;
+    /** Adds an entity (one native call; text adds one per letter). Throws if the world is full or an option is invalid. */
+    spawn(options?: EntityOptions): Entity;
+    /**
+     * Changes an entity (one native call). Only the options you pass change; `null` removes.
+     * Returns false if the entity is gone, the world is disposed, or an option was rejected (the others still apply).
+     */
+    set(e: Entity, options: EntityOptions): boolean;
+    /**
+     * This world's shared draw-only transform batch (created on first use). Queue per-frame moves with
+     * its allocation-free methods; the next `update()` applies them first (or `flush()` them yourself
+     * before reading positions or animating).
+     */
+    get transforms(): TransformBatch;
+    /** Reusable draw-only transforms; use set() for text entities and flush before animations/queries. */
+    createTransformBatch(): TransformBatch;
+    /** Removes an entity and anything attached to it. Returns false if it was already gone. */
+    despawn(e: Entity): boolean;
+    /** A one-off push: jump, explosion, knockback (dynamic bodies only). */
+    impulse(e: Entity, impulse: Vec3): void;
+    private resolveMesh;
+    private encodeColor;
+    /** Updates a text entity's letters in place, growing or shrinking only when needed. */
+    private buildText;
+    /** Native world backing this render source; bone palettes stay in Rust. */
+    get nativeWorld(): number;
+    /** Play a named GLB clip. Re-selecting it changes speed without restarting; `time` explicitly seeks.
+     * `fade` crossfades from the current pose (seconds). A speed of zero holds a pose for a ready screen.
+     */
+    playClip(entity: Entity, clip: string, options?: ClipOptions): boolean;
+    /** Hold the current GLB pose, or return to its bind pose with `reset`. */
+    stopClip(entity: Entity, reset?: boolean): boolean;
+    /** Sample selected animated vertices in model space for foot contact and attachments.
+     * Reuse both arrays. `after` previews the interpolated pose following the next update.
+     */
+    sampleSkinnedVertices(entity: Entity, vertices: Uint32Array, output: Float32Array, after?: number): boolean;
+    /**
+     * Animates in Rust, with no per-frame JS: from where things are to `to`, or through keyframes.
+     * Each property (position, rotation, scale, color, shake) runs on its own, so a piece can move
+     * while it pulses; animating a property again replaces only that property. Pass several entities
+     * to animate them together (with `stagger` for waves). Resolves when every part has finished, been
+     * replaced or stopped, or its entity was despawned.
+     *
+     * ```ts
+     * await world.animate(piece, { position: [2, 0, 3] }, { duration: 0.25, easing: "back" });
+     * world.animate(coin, { scale: 1.2 }, { repeat: "forever", yoyo: true }); // pulse
+     * world.animate(piece, [{ moveBy: [1, 1.5, 0] }, { moveBy: [2, 0, 0] }], { path: "smooth" }); // hop
+     * world.animate(card, { turn: [0, Math.PI, 0] }); // flip
+     * world.animate(tiles, { scale: 1 }, { stagger: 0.03, easing: "back" }); // reveal a board
+     * world.animate(cursor, { position: [x, 0, z] }, { spring: true }); // follows the finger smoothly
+     * world.animate(wrongTile, { shake: 0.15 }, { duration: 0.4 });
+     * ```
+     */
+    animate(targets: Entity | readonly Entity[], to: AnimateTarget | readonly Keyframe[], options?: AnimateOptions): Promise<void>;
+    private encodeKeyframe;
+    /** Stops every animation on the entity where it is (their promises resolve). */
+    stopAnimation(e: Entity): void;
+    /**
+     * Particles: many small, short-lived pieces flying out of a point (explosions, sparks, dust,
+     * confetti). One native call; they fall, spin, shrink away and clean themselves up. `endSize` and
+     * `endColor` grow / shrink and recolor them over their life (fire cooling, smoke thinning out).
+     * Returns how many were spawned (fewer if the world is nearly full).
+     */
+    burst(options: BurstOptions): number;
+    /**
+     * Runs `fn` after `seconds` of `update` time (game time: it pauses when updates stop). The clock is
+     * kept in Rust, so there's no JS timer list to scan every frame. Due callbacks run inside `update`,
+     * earliest first. Returns the timer's id for `cancelTimer`; `cancelTimers()` drops every pending one.
+     * After `dispose()` it does nothing and returns 0.
+     *
+     * ```ts
+     * world.after(0.3, () => checkMatches());
+     * ```
+     */
+    after(seconds: number, fn: () => void): number;
+    /** Drops one pending `after` timer so its callback never runs. Returns false if it already ran or was dropped. */
+    cancelTimer(id: number): boolean;
+    /** Drops every pending `after` timer: their callbacks never run (a new round, a reset). */
+    cancelTimers(): void;
+    /** Score, lives and the game clock, kept in Rust (created on first use). */
+    get scoreboard(): Scoreboard;
+    /** How many times `update` has run. GameView reads it to step the world only when `onUpdate` didn't. */
+    get updateCount(): number;
+    /** Timers waiting to fire. */
+    get timerCount(): number;
+    /** Resolves the promises of animations the core reports as ended, then runs due timers. */
+    private resolveFinished;
+    private runFallbackTimers;
+    /**
+     * Current simulated position (relative to the parent when attached), or null if the entity is gone.
+     * Pass `out` to avoid allocating every frame.
+     */
+    position(e: Entity, out?: [number, number, number]): [number, number, number] | null;
+    /** Where the entity was last drawn, in world space (parents and smoothing included), or null if it's gone. */
+    worldPosition(e: Entity, out?: [number, number, number]): [number, number, number] | null;
+    /** Current velocity, or null if the entity is gone. Pass `out` to avoid allocating every frame. */
+    velocity(e: Entity, out?: [number, number, number]): [number, number, number] | null;
+    /** True while the entity exists (false after `dispose()`). */
+    has(e: Entity): boolean;
+    /**
+     * First solid (non-sensor) collider along the ray whose layer is in `mask`, as of the last update.
+     * Pass `out` to reuse a hit object every frame.
+     */
+    raycast(origin: Vec3, direction: Vec3, maxDistance: number, mask?: number, out?: RaycastHit): RaycastHit | null;
+    /**
+     * The entity under a point of the GameView (e.g. a tap's `x, y`), tested against what was last
+     * drawn. Needs no physics. Returns null if nothing pickable is there. Pass `out` to reuse a hit object.
+     */
+    pick(x: number, y: number, out?: PickHit): PickHit | null;
+    /**
+     * Where a world position appears in the GameView, in points from its top-left, or null if it's behind
+     * the camera (or nothing has been drawn yet). Place React Native views over 3D objects with it.
+     * Pass `out` to avoid allocating every frame.
+     */
+    toScreen(position: Vec3, out?: [number, number]): [number, number] | null;
+    /**
+     * Where a GameView point (a finger's `x, y`) lands on a plane, or null if the plane is behind the
+     * camera or edge-on. Defaults to the ground (y = 0). Drag a piece across a board with it:
+     * `world.screenToWorld(x, y, { point: [0, pieceHeight, 0] })`. 2D games looking down -z use
+     * `{ normal: [0, 0, 1] }`. Like `toScreen`, it needs a drawn frame (null before the first one).
+     * Pass `out` to avoid allocating every frame.
+     */
+    screenToWorld(x: number, y: number, plane?: ScreenPlane, out?: [number, number, number]): [number, number, number] | null;
+    /** Called by GameView after drawing a frame, with the camera matrix and the view size in points. */
+    setView(viewProj: Float32Array, width: number, height: number): void;
+    private copyScratch;
+    /** Default [0, -9.81, 0]. */
+    get gravity(): Vec3;
+    set gravity(g: Vec3);
+    /** Keeps moving non-physics entities inside [minX, minZ, maxX, maxZ]. Physics bodies need walls. */
+    get bounds(): Bounds | null;
+    set bounds(b: Bounds | null);
+    /** Impact sounds pan and fade relative to this entity (usually the player). */
+    get listener(): Entity | null;
+    set listener(e: Entity | null);
+    /**
+     * Advances the simulation (fixed 60 Hz steps), resolves finished animations, runs due timers and
+     * scoreboard handlers, and refreshes what GameView draws. `GameView` calls it for you each frame;
+     * call it yourself from `onUpdate` only to step with a different `dt` (it is then not stepped twice).
+     */
+    update(dt: number): void;
+    /**
+     * Calls `fn` for each touch that started or ended during the last `update`. `info` is reused:
+     * copy what you need. Either entity may already be despawned by an earlier callback.
+     */
+    forEachCollision(fn: (a: Entity, b: Entity, info: CollisionInfo) => void): void;
+    /**
+     * Frees the native world. Pending animation promises resolve and timers are dropped. Later cleanup
+     * calls and queries are no-ops (see `isDisposed`); `spawn` and `update` throw.
+     */
+    dispose(): void;
+}

package/lib/web/types/src/world/color.d.ts

@@ -0,0 +1,17 @@
+import type { Color } from './types';
+/** A color as an option takes it: `[r, g, b]` / `[r, g, b, a]` (0..1, channels above 1 glow) or a CSS string. */
+export type ColorInput = Color | string;
+/**
+ * Any color input as an `[r, g, b, a]` tuple (0..1), with its alpha multiplied by `alpha`. Use it when
+ * you need the numbers (to brighten, mix or fade a theme color); options take strings directly.
+ *
+ * ```ts
+ * toColor('#FF4757'); // [1, 0.278, 0.341, 1]
+ * toColor('#FF4757', 0.5); // half see-through
+ * ```
+ */
+export declare function toColor(color: ColorInput, alpha?: number): [number, number, number, number];
+/** A color input as a tuple, without copying tuples (the hot path of `spawn`, `set` and `animate`). */
+export declare function resolveColor(color: ColorInput): Color;
+/** One color input, or a list to pick from, as tuples. */
+export declare function resolveColors(colors: ColorInput | readonly ColorInput[]): readonly Color[];

package/lib/web/types/src/world/desc.d.ts

@@ -0,0 +1,16 @@
+import type { EntityOptions } from './types';
+export declare const DESC_LEN = 64;
+/** Writes `options` into `d`, with the mesh id already resolved. Only the fields present are flagged. */
+export declare function encode(d: Float64Array, o: EntityOptions, mesh: number | undefined): void;
+export declare const ANIM_HEADER = 12;
+export declare const ANIM_KEY_LEN = 23;
+export declare const BURST_LEN = 36;
+export declare const EASING: {
+    readonly linear: 0;
+    readonly easeIn: 1;
+    readonly easeOut: 2;
+    readonly easeInOut: 3;
+    readonly back: 4;
+    readonly bounce: 5;
+    readonly elastic: 6;
+};

package/lib/web/types/src/world/effects.d.ts

@@ -0,0 +1,156 @@
+import type { Vec3 } from '../types';
+import { type ColorInput } from './color';
+import type { BurstOptions, Entity } from './types';
+import type { World } from './World';
+/** Shared options of the layered effects (confetti, sparkle, shatter, splash, sparks, explosion). */
+export type EffectOptions = {
+    position: Vec3;
+    /** One color (CSS string or tuple), or several to pick from at random. */
+    colors: ColorInput | readonly ColorInput[];
+    /** Typical particle size. */
+    size: number;
+    /** Top speed. */
+    speed: number;
+    /** About how many particles (a few extra go to the flash and puffs). */
+    count: number;
+    /** Seconds. */
+    lifetime: number;
+    /** Vertical acceleration (negative falls). Default 0. */
+    gravity?: number;
+    /** Main direction. Default up. */
+    direction?: Vec3;
+    /** Half-angle of the cone around `direction`. Default π (every direction). */
+    spread?: number;
+    /** A brief glow at the source. Default true. */
+    flash?: boolean;
+};
+/** A soft cloud of puffs that swell and fade: landing dust, kicked-up sand, sawdust, steam, muzzle smoke. */
+export type DustOptions = {
+    position: Vec3;
+    /** Start color (alpha is how thick it looks), or several to pick from. */
+    color: ColorInput | readonly ColorInput[];
+    /** Puff size at the start. */
+    size: number;
+    /** Top speed. */
+    speed: number;
+    count: number;
+    /** Seconds. */
+    lifetime: number;
+    /** Default up. */
+    direction?: Vec3;
+    /** Half-angle around `direction`. Default π. */
+    spread?: number;
+    /** Default 0 (dust hangs; positive rises like smoke). */
+    gravity?: number;
+    /** How much each puff grows by the end. Default 2. */
+    endSize?: number;
+    /** Color at the end. Default: a single `color` faded to transparent; several colors keep theirs. */
+    endColor?: ColorInput;
+    /** Default "puff" (blended); "flame" adds light instead. */
+    mesh?: BurstOptions['mesh'];
+};
+/** One glow that swells and fades at a point: a hit, a strike, a muzzle flash. */
+export type FlashOptions = {
+    position: Vec3;
+    /** Use channels above 1 to glow (see `effects.hot`). */
+    color: ColorInput;
+    size: number;
+    /** Seconds. Default 0.22. */
+    lifetime?: number;
+    /** How much it grows by the end. Default 2.2. */
+    endSize?: number;
+    /** Default: `color` faded to transparent. */
+    endColor?: ColorInput;
+    /** Default "flame" (adds light); "sphere" or "puff" for a solid or soft flash. */
+    mesh?: BurstOptions['mesh'];
+    /** Glows drawn at once (slightly scattered when `speed` > 0). Default 1. */
+    count?: number;
+    /** Default 0. */
+    speed?: number;
+};
+/** The cleared-piece pop: swell, flash white, settle, shrink away. */
+export type PopOptions = {
+    /** Its scale at rest (what it has now): one number, or per axis. */
+    scale: number | Vec3;
+    /** Its color at rest, to return to after the white flash. Omit to flash `flash` only (or nothing). */
+    color?: ColorInput;
+    /** Parts to flash white as well (a group's visible children, whose rest color is white). */
+    flash?: readonly Entity[];
+    /** Seconds before it starts. Default 0. */
+    delay?: number;
+    /** Seconds it takes. Default `effects.POP_TIME`. */
+    duration?: number;
+};
+type Rgba = [number, number, number, number];
+/** The same hue, self-lit: its brightest channel lifted to `peak` (above 1 glows, through light, shadow and fog). */
+declare function hot(input: ColorInput, peak?: number, alpha?: number): Rgba;
+/** Part way (`t`, 0..1) to white, with `alpha`. */
+declare function pale(input: ColorInput, t: number, alpha?: number): Rgba;
+declare function flash(world: World, o: FlashOptions): number;
+declare function dust(world: World, o: DustOptions): number;
+/** Celebration confetti: tumbling paper in two layers, a few glinting sparkles, and a pop of light. */
+declare function confetti(world: World, e: EffectOptions): void;
+/** Glitter for a reward: solid bright beads (seen on any background) with additive glints around them. */
+declare function sparkle(world: World, e: EffectOptions): void;
+/**
+ * Something breaking apart: big slow chunks, small fast crumbs, a glow at the break and a puff of
+ * its dust. `mesh` is the chunks' shape.
+ */
+declare function shatter(world: World, e: EffectOptions & {
+    mesh?: BurstOptions['mesh'];
+    dust?: boolean;
+}): void;
+/** Liquid: droplets in two sizes thrown out of a fine mist of the same color. */
+declare function splash(world: World, e: EffectOptions): void;
+/** Hot metal sparks: additive streaks that burn out, with a few solid beads and a flash where they strike. */
+declare function sparks(world: World, e: EffectOptions): void;
+/**
+ * A fiery blast: a white-hot flash, a fireball that cools into smoke, embers thrown out and, given
+ * `debris` colors, chunks of whatever blew up. `size` is the fireball's puff size; `colors` its fire.
+ * The fire and smoke swell every way; `direction`, `spread` and `gravity` aim the embers and debris.
+ */
+declare function explosion(world: World, e: Omit<EffectOptions, 'colors'> & {
+    colors?: EffectOptions['colors'];
+    debris?: readonly ColorInput[];
+    smoke?: ColorInput;
+}): void;
+/** The piece swells, flashes white, settles and shrinks away. Resolves when it's gone (despawning it is the caller's). */
+declare function pop(world: World, entity: Entity, o: PopOptions): Promise<void>;
+/**
+ * Ready-made effects. Each is one call; particles then live, fall, shrink and recolor in Rust.
+ *
+ * ```ts
+ * effects.confetti(world, { position, colors: [RED, GOLD], size: 0.12, speed: 6, count: 40, lifetime: 1.2, gravity: -6 });
+ * effects.dust(world, { position: feet, color: [0.8, 0.75, 0.65, 0.6], size: 0.3, speed: 1.5, count: 6, lifetime: 0.5 });
+ * effects.flash(world, { position: hit, color: effects.hot(ORANGE), size: 0.8 });
+ * await effects.pop(world, candy, { scale: 1, color: RED });
+ * world.despawn(candy);
+ * ```
+ */
+export declare const effects: {
+    /** Celebration: tumbling paper, glints and a pop of light (wins, level-ups). */
+    confetti: typeof confetti;
+    /** Reward glitter: bright beads and glints (pickups, perfect moves). */
+    sparkle: typeof sparkle;
+    /** Breaking apart: chunks, crumbs, a glow and dust (bricks, crates, glass). `mesh` shapes the chunks. */
+    shatter: typeof shatter;
+    /** Liquid: droplets and mist (water, juice, paint). */
+    splash: typeof splash;
+    /** Hot metal: additive streaks and beads (scrapes, strikes, electricity). */
+    sparks: typeof sparks;
+    /** Fiery blast: flash, fireball cooling to smoke, embers and optional debris. */
+    explosion: typeof explosion;
+    /** Soft swelling puffs: dust, sand, sawdust, steam, smoke. */
+    dust: typeof dust;
+    /** One swelling glow: hits, strikes, muzzle flashes. */
+    flash: typeof flash;
+    /** The cleared-piece animation: swell, flash white, settle, shrink to nothing. */
+    pop: typeof pop;
+    /** Default `pop` duration in seconds. */
+    POP_TIME: number;
+    /** The same hue made self-lit (brightest channel lifted to `peak`), for glows. */
+    hot: typeof hot;
+    /** Part way (`t`, 0..1) to white. */
+    pale: typeof pale;
+};
+export {};

package/lib/web/types/src/world/quat.d.ts

@@ -0,0 +1,30 @@
+import type { Quat } from './types';
+/** A writable quaternion; pass one as `out` to reuse it instead of allocating. */
+export type MutableQuat = [number, number, number, number];
+/**
+ * Quaternion helpers for `rotation` options, keyframes and geometry parts ([x, y, z, w]). Every
+ * function takes an optional `out` so per-frame code can reuse one array instead of allocating.
+ *
+ * ```ts
+ * world.set(car, { rotation: quat.y(heading) });
+ * const spin = quat.multiply(quat.y(yaw), quat.x(pitch), scratch); // pitch first, then yaw
+ * ```
+ */
+export declare const quat: {
+    /** No rotation. */
+    identity: Quat;
+    /** Rotation by `angle` radians around the unit axis (x, y, z). */
+    axisAngle(x: number, y: number, z: number, angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the x axis (pitch). */
+    x(angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the y axis (yaw, heading). */
+    y(angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the z axis (roll; spin for 2D games looking down -z). */
+    z(angle: number, out?: MutableQuat): MutableQuat;
+    /** `a` after `b`: `b` turns first. `out` may be `a` or `b`. */
+    multiply(a: Quat, b: Quat, out?: MutableQuat): MutableQuat;
+    /** Turns around x, then y, then z (radians): the same as `multiply(z(z), multiply(y(y), x(x)))`. */
+    fromEuler(x: number, y: number, z: number, out?: MutableQuat): MutableQuat;
+    /** Shortest-path interpolation from `a` (t = 0) to `b` (t = 1). */
+    slerp(a: Quat, b: Quat, t: number, out?: MutableQuat): MutableQuat;
+};