Public API reference

import { GameView, useWorld, type Entity, type EntityOptions } from "@nayan-ui/engine";

const ball: EntityOptions = { mesh: "sphere", color: "#33B3FF", physics: "dynamic" };

export function Ball() {
  let handle: Entity | null = null;
  const world = useWorld(16, (w) => { handle = w.spawn(ball); });
  return world && <GameView source={world} onTap={() => handle !== null && world.impulse(handle, [0, 4, 0])} />;
}

/** 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;
    constructor(capacity: number);
    /** 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;
    /** 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>;
    /** 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;
    /**
     * 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;
    /** 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;
}

/** 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;
};

/** 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
];

/** 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
];

/**
 * 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 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 {
    /** The game's own handlers. `listen` adds more without replacing these. */
    handlers: ScoreboardHandlers;
    /** @internal */
    constructor(world: number);
    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;
}

/** Opaque entity handle. Handles of despawned entities are safely ignored. */
export type Entity = number & {
    readonly __entity: unique symbol;
};

export type Color = readonly [
    number,
    number,
    number
] | readonly [
    number,
    number,
    number,
    number
];

export type Quat = readonly [
    number,
    number,
    number,
    number
];

/** Playback for one entity using a skeletal animation embedded in a loaded model. */
export interface ClipOptions {
    /** Repeat the clip. Default true. */
    loop?: boolean;
    /** Playback rate; zero holds a pose. Default 1. */
    speed?: number;
    /** Crossfade from the current pose, in seconds. Default 0.15. */
    fade?: number;
    /** Seek to this time in seconds. Omit to retain playback when reselecting a clip. */
    time?: number;
}

/** Plane used by screenToWorld; defaults to the ground through the origin. */
export interface ScreenPlane {
    point?: Vec3;
    normal?: Vec3;
}

/**
 * - `dynamic`: moved by physics (gravity, collisions, impulses).
 * - `kinematic`: moved by you; pushes dynamic bodies out of the way.
 * - `fixed`: never moves (floors, walls).
 */
export type BodyType = 'dynamic' | 'kinematic' | 'fixed';

export type PhysicsOptions = {
    type: BodyType;
    /** Default: matches the mesh (spheres get a ball, cylinders a cylinder, ...; anything else a box). */
    shape?: 'ball' | 'box' | 'cylinder' | 'capsule' | 'cone';
    /** Ball, cylinder, capsule or cone radius. Default: from the entity's size. */
    radius?: number;
    /** Cylinder, capsule or cone height (total). Default: from the entity's size. */
    height?: number;
    /** Box size (full width, height, depth). Default: the entity's size. */
    size?: Vec3;
    /** Layer bits this collider is on. Default 1. */
    layer?: number;
    /** Layers it interacts with. Either side's mask is enough. Default: all. */
    mask?: number;
    /** Reports touches but doesn't push: pickups, trigger zones. */
    sensor?: boolean;
    /** How grippy, default 0.5. */
    friction?: number;
    /** Bounciness 0..1, default 0. */
    bounce?: number;
    /** Mass per volume, default 1. */
    density?: number;
    /** Slows movement over time (air resistance), default 0. */
    drag?: number;
    /** Slows spinning over time, default 0.05. */
    angularDrag?: number;
    /** Multiplier on world gravity, default 1. */
    gravityScale?: number;
    /** Stays upright: never tumbles. */
    upright?: boolean;
    /** Stops fast, small bodies passing through walls. */
    ccd?: boolean;
    /** 2D games: stays in its XY plane (moves in x/y, spins only around z). Keep the camera looking down -z. */
    planar?: boolean;
};

/** Sound/haptic the core plays by itself when the entity hits something solid. */
export type ImpactFeedback = {
    /** A loaded sound, e.g. `sfx.get("bump")`. Omit for haptics only. */
    sound?: Sound;
    /** Slower impacts are silent. Default 1. */
    minSpeed?: number;
    /** Full volume and strength at this speed. Default 10. */
    maxSpeed?: number;
    /** Volume at full strength, 0..2. Default 1. */
    volume?: number;
    /** Vibration at full strength, 0..1. Default 0 (none). */
    haptic?: number;
};

/**
 * Everything about an entity. `spawn` and `set` take the same options; in `set`, only what you
 * pass changes, and `null` removes something (physics, parent, follow, bob, lifetime, impact).
 */
export type EntityOptions = {
    /** A built-in shape or a model from `loadModel`. Default "cube". */
    mesh?: Shape | Model;
    /** An image from `loadTexture`, drawn on the mesh (`null` = none). In `set`, pass `mesh` with it. */
    texture?: Texture | null;
    /** Part of the texture to show, [u0, v0, u1, v1] from 0..1 (sprite sheets, card atlases). */
    textureRegion?: readonly [
        number,
        number,
        number,
        number
    ];
    /** 3D text instead of a mesh (needs `font`). Letters are 1 unit tall at scale 1. */
    text?: string;
    /** A font from `loadFont`, for `text`. */
    font?: Font;
    /** Text alignment around `position`. Default "center". */
    align?: TextAlign;
    /** Extra space between letters, in ems. Default 0. */
    letterSpacing?: number;
    /** Digits all as wide as the widest, so changing scores and timers don't shift. Default false. */
    tabular?: boolean;
    /** Relative to the parent when attached. */
    position?: Vec3;
    rotation?: Quat;
    /** A number scales uniformly. Children scale with their parent. Visual only after the body exists. */
    scale?: Vec3 | number;
    /**
     * A CSS color (`'#FF4757'`, `'rgba(…)'`) or a 0..1 tuple. Alpha below 1 makes it see-through. Tuple
     * channels above 1 glow: at 2 it's self-lit, ignoring light and shadow (fire, lamps).
     */
    color?: ColorInput;
    /** Units per second. */
    velocity?: Vec3;
    /** Sets horizontal speed [x, z] and keeps the vertical one: steer a body and it still falls. */
    groundVelocity?: readonly [
        number,
        number
    ];
    /** Units per second², for entities without a dynamic body (falling debris, thrown items). */
    acceleration?: Vec3;
    /** Radians per second around each axis. */
    spin?: Vec3;
    /** Visual bob: the drawn position moves by amplitude * sin(phase), phase advancing at `speed`. */
    bob?: {
        amplitude: Vec3;
        speed: number;
        phase?: number;
    } | null;
    /** Chase `target` along the ground at `speed`. */
    follow?: {
        target: Entity;
        speed: number;
    } | null;
    /** Seconds until it shrinks away and is despawned. */
    lifetime?: number | null;
    /** Attach to another entity: it moves, turns and scales with the parent and is despawned with it. Visual only. */
    parent?: Entity | null;
    physics?: BodyType | PhysicsOptions | null;
    impact?: ImpactFeedback | null;
    /** Whether `pick` can hit it. Default true. */
    pickable?: boolean;
};

export type Easing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'back' | 'bounce' | 'elastic';

/** What `animate` changes. Anything left out stays as it is (and keeps any animation it already has). */
export type AnimateTarget = {
    position?: Vec3;
    rotation?: Quat;
    scale?: Vec3 | number;
    /** A CSS color or a 0..1 tuple. */
    color?: ColorInput;
    /** Move by this offset from where the animation starts (instead of to a `position`). */
    moveBy?: Vec3;
    /** Turn by these angles (radians around x, y, z) from the starting rotation. 2π spins once; more spins more. */
    turn?: Vec3;
    /** Shake by up to this distance, fading out. Only the drawn position shakes (hits, wrong moves). */
    shake?: number;
};

/** A step of a keyframed animation: values to pass through, and when (0..1 of the duration; default evenly spaced). */
export type Keyframe = AnimateTarget & {
    at?: number;
};

export type SpringOptions = {
    /** How strongly it pulls toward the target. Default 170. */
    stiffness?: number;
    /** How quickly it calms down. Lower bounces more. Default 26 (no overshoot). */
    damping?: number;
    /** Heavier moves slower and swings further. Default 1. */
    mass?: number;
};

export type AnimateOptions = {
    /** Seconds (ignored by springs). Default 0.3. */
    duration?: number;
    /** Seconds before it starts. Default 0. */
    delay?: number;
    /** Default "easeOut". "back" overshoots, "bounce" bounces, "elastic" springs. */
    easing?: Easing;
    /** Extra runs after the first, or "forever". Default 0. */
    repeat?: number | 'forever';
    /** Every other run plays backwards (pulses, ping-pong). */
    yoyo?: boolean;
    /** With several entities: extra delay for each next one, in seconds (waves, board reveals). */
    stagger?: number;
    /** "smooth" moves along a curve through the keyframes (arcs, hops) instead of straight lines. */
    path?: 'linear' | 'smooth';
    /**
     * Physically simulated motion instead of a fixed duration: true (smooth), "bouncy", or your own
     * settings. Interrupting a spring with another keeps its speed, so it never jerks.
     */
    spring?: boolean | 'bouncy' | SpringOptions;
};

export type BurstOptions = {
    position: Vec3;
    /** How many particles. Default 16. */
    count?: number;
    /** Main direction. Default up. */
    direction?: Vec3;
    /** Half-angle of the cone around `direction`, in radians. Default π (every direction). */
    spread?: number;
    /** Default "cube". */
    mesh?: Shape | Model;
    /** Particle size. Default 0.15. */
    size?: number;
    /** Top speed. Default 5. */
    speed?: number;
    /** Seconds. Default 0.8. */
    lifetime?: number;
    /** Vertical acceleration. Default -9.81 (falls); 0 floats. */
    gravity?: number;
    /** One color (CSS string or tuple), or up to 4 to pick from at random. Default white. */
    color?: ColorInput | readonly ColorInput[];
    /** Size at the end of each particle's life, as a multiple of its start size: above 1 grows (smoke), below shrinks (embers). Default 1. */
    endSize?: number;
    /** Color every particle shifts to over its life, e.g. flame to dark red; an alpha below 1 fades it out. Default: keeps its color. */
    endColor?: ColorInput;
};

export type CollisionInfo = {
    /** True when the touch started; false when it ended. */
    started: boolean;
    /** A sensor was involved. */
    sensor: boolean;
    /** Impact speed (0 when a touch ends). */
    speed: number;
};

export type RaycastHit = {
    entity: Entity;
    distance: number;
    normal: [
        number,
        number,
        number
    ];
    point: [
        number,
        number,
        number
    ];
};

export type PickHit = {
    entity: Entity;
    /** Where the tap ray hit the entity's bounding box, in world space. */
    point: [
        number,
        number,
        number
    ];
    distance: number;
};

export type Bounds = readonly [
    minX: number,
    minZ: number,
    maxX: number,
    maxZ: number
];

/**
 * Runs `fn` right after the next frame a GameView hands to the screen, on the same display clock
 * (the native one where the platform has it): the time a frame leaves is the best moment for
 * background work, such as loading in slices. With no GameView running it falls back to
 * requestAnimationFrame. Returns a function that cancels it.
 *
 * ```ts
 * const cancel = afterNextFrame(() => buildNextChunk());
 * ```
 */
export declare function afterNextFrame(fn: () => void): () => void;

export type GameViewStats = {
    fps: number;
    /** Mean time spent in `onUpdate` per frame, in milliseconds. */
    updateMs: number;
    /** Average milliseconds per frame spent drawing (CPU side, including waiting on the GPU). */
    renderMs: number;
    /** The quality level drawn with (with `quality="auto"`, the one it settled on so far). */
    quality: RenderQuality;
    /** The graphics API drawing: "vulkan", "gl" (OpenGL ES) or "metal". */
    backend: string;
};

export type SwipeDirection = 'left' | 'right' | 'up' | 'down';

export type OverlayTouchPhase = 'start' | 'move' | 'end' | 'cancel';

export type DragEvent = {
    phase: 'start' | 'move' | 'end';
    /** Finger position in the view, in points. */
    x: number;
    y: number;
    /** Distance moved since the drag started, in points. */
    dx: number;
    dy: number;
    /** On "end": the drag was interrupted (a second finger started a pinch, or the system took the touch). Put a held piece back. */
    cancelled?: boolean;
};

export type PinchEvent = {
    phase: 'start' | 'move' | 'end';
    /** Finger spread relative to the start: 2 = twice as far apart (zoom in). */
    scale: number;
    /** Radians the two fingers turned since the start, clockwise on screen. */
    rotation: number;
    /** Midpoint between the fingers in the view, in points. */
    x: number;
    y: number;
};

export type GameViewProps = {
    /** What to draw (usually a `World`). Changing it restarts the view; never pass a disposed world. */
    source: RenderSource;
    /**
     * Your game loop, called once per frame before drawing, with the elapsed seconds (capped at 0.1;
     * 0 until the first frame is on screen, so nothing plays out unseen): read input, spawn, move the
     * camera. The world (and `overlay`) is stepped for you right after; call `world.update(dt)` here
     * yourself only to step it at a different point or with a different `dt`.
     */
    onUpdate?: (dt: number) => void;
    /** Mutate this object (e.g. `camera.eye`) from `onUpdate`; it is read every frame. */
    camera?: Camera;
    light?: Light;
    /** Sky / clear color: a CSS color or linear 0..1 RGB (alpha ignored). Also the fog color. Default dark navy. */
    background?: ColorInput;
    /** Distance fog density towards `background` (e.g. 0.02). Default 0 (off). */
    fog?: number;
    /**
     * Resolution, anti-aliasing and shadow quality. "auto" (default) starts at "high", steps down only
     * while the GPU really can't keep up (shadow detail first, then anti-aliasing, resolution last) and
     * steps back up once frames are smooth again, so every phone gets the best look it can hold.
     */
    quality?: RenderQualitySetting;
    /** Suspend updates and drawing while keeping the native surface mounted. */
    paused?: boolean;
    style?: ViewStyle;
    /** A quick tap, at `x, y` points in the view. `world.pick(x, y)` finds what was tapped. */
    onTap?: (x: number, y: number) => void;
    /** A quick flick in one direction (2048, runners, sliding puzzles). */
    onSwipe?: (direction: SwipeDirection) => void;
    /** Finger down, moving and up (aiming, dragging pieces, slicing). */
    onDrag?: (drag: DragEvent) => void;
    /** A finger held still for half a second (pick up, show moves). No tap follows. */
    onLongPress?: (x: number, y: number) => void;
    /** Two fingers spreading, pinching or turning (zoom and rotate a board). Ends any drag in progress. */
    onPinch?: (pinch: PinchEvent) => void;
    /** Host primary action for keyboard input, such as Start/Stop or Play Again. */
    onPrimaryAction?: () => void;
    /**
     * A screen-space layer drawn over the scene by the renderer (scoreboards, buttons): usually a second
     * `World`, in points from the view's top-left with y up (so on screen y <= 0) and z toward the viewer
     * within -100..100. Unlit (flat faces show their exact color) and always in front. Stepped each
     * frame like `source`.
     */
    overlay?: RenderSource;
    /**
     * Touches for the overlay, in points in the view. Return true from "start" to claim the touch (a
     * button was hit): its moves and end come here, and the game gets no drag, tap or swipe for it.
     * "cancel" when the system takes the touch.
     */
    onOverlayTouch?: (phase: OverlayTouchPhase, x: number, y: number) => boolean | void;
    /** Called once a second. */
    onStats?: (stats: GameViewStats) => void;
    /** GPU setup failures and rendering errors. Defaults to console.error. */
    onError?: (error: Error) => void;
};

export declare function GameView(props: GameViewProps): import("react").JSX.Element;

/** What `useWorld`'s setup may return: a cleanup, run just before the world is disposed. */
export type WorldSetup = (world: World) => void | (() => void);

/**
 * A `World` owned by a component: the engine is warmed up (needed on the web, cheap on mobile), the
 * world is created with `capacity` entity slots and handed to `setup` to fill, and it is disposed on
 * unmount. A change in `deps` replaces it with a fresh one. Returns null until it's ready (one frame),
 * and while the engine is unavailable (Expo Go) or failed to start (`onError`, console by default).
 *
 * ```tsx
 * const world = useWorld(100, (w) => {
 *   w.spawn({ mesh: 'plane', scale: [20, 1, 20], color: '#4C9A4C', physics: 'fixed' });
 *   w.spawn({ mesh: 'sphere', position: [0, 4, 0], color: '#3399FF', physics: 'dynamic' });
 * });
 * return world && <GameView source={world} style={{ flex: 1 }} />;
 * ```
 */
export declare function useWorld(capacity: number, setup?: WorldSetup, deps?: DependencyList, onError?: (error: Error) => void): World | null;

/**
 * A light for flat, front-facing scenes (boards, puzzles, 2D games looking down -z): surfaces facing
 * the camera (+z) are lit at exactly 1, so flat panels show their color unchanged, while rounded
 * shapes keep their shading (lighter toward the light, darker away). Shadows are off.
 *
 * ```tsx
 * <GameView source={world} light={frontLight([-0.45, 0.6, 1], 0.5)} />
 * ```
 */
export declare function frontLight(direction: [
    number,
    number,
    number
], ambient: number): Light;

type V3 = readonly [
    number,
    number,
    number
];

/** One past the highest mesh id in use: per-frame scans of a source's ranges stop here. */
export declare const getMeshIdLimit: () => number;

/**
 * Initializes the shared core and built-in meshes. Await before using the engine on the web.
 * Mobile initialization remains synchronous and also warms the GPU on a background thread.
 * Repeat calls reuse initialization and mesh registration.
 */
export declare function warmUpEngine(): Promise<void>;

export type TransformOptions = Pick<EntityOptions, 'position' | 'rotation' | 'scale' | 'color'>;

/**
 * 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 {
    constructor(commit: (data: Float64Array, count: number) => number);
    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;
    flush(): number;
    clear(): void;
}

export type RenderQuality = 'high' | 'medium' | 'low' | 'lowest';

/** `"auto"` starts at "high" and steps down only while the device really can't keep up. */
export type RenderQualitySetting = RenderQuality | 'auto';

/** Browser assets use URLs (including URLs emitted by Vite/webpack imports). */
export type AssetSource = number | string;

export type ModelOptions = {
    /** Move the model's bounding box center to the origin, so `position` is its middle. Default true. */
    center?: boolean;
    /** Scale it so its largest side is this long (e.g. 1 to match the built-in shapes). Default: keep its size. */
    fit?: number;
    /**
     * How glossy, 0..1: a sharp sun highlight and a reflection of the sky that grows at grazing angles.
     * 0 is matte; around 0.8 reads as car paint or glass. Default 0.
     */
    shine?: number;
};

/** A loaded model: pass it as an entity's `mesh`. Colliders sized from the mesh fit its bounding box. */
export type Model = {
    /** Bounding box size [x, y, z] at scale 1 (after `fit`). */
    readonly size: Vec3;
    /** Mesh id in the core. */
    readonly id: number;
};

/** An animation embedded in a loaded GLB. */
export type ModelClip = {
    readonly name: string;
    readonly duration: number;
};

export type LoadedModel = Model & {
    readonly animations: readonly ModelClip[];
    readonly jointCount: number;
};

/**
 * Initializes the engine automatically. Loads a glTF model once; pass it as an entity's `mesh`. Meshes, node transforms, material colors
 * and the base color texture are kept (one texture per model); skeletal animation clips are available through `animations` and `World.playClip`.
 * Every entity using the model is drawn in one instanced draw call.
 *
 * ```ts
 * const tree = await loadModel(require("./assets/tree.glb"), { fit: 2 });
 * world.spawn({ mesh: tree, position: [0, 1, 0], physics: "fixed" });
 * ```
 */
export declare function loadModel(source: AssetSource, options?: ModelOptions): Promise<LoadedModel>;

/**
 * Explicitly removes the engine's saved geometry and original model/texture/font/audio files.
 * Also clears temporary download bytes. Existing worlds and loaded handles remain usable;
 * registrations are session resources and will be rebuilt/reloaded on a future app launch.
 * Custom ProceduralStorage adapters belong to their host and are not cleared by this function.
 * Rejects if storage cannot be cleared, allowing a settings screen to report the failure.
 */
export declare function clearAssetCache(): Promise<void>;

/** Optional storage override. The engine selects a best-effort platform cache by default. */
export interface ProceduralStorage {
    read(key: string): Uint8Array | null;
    write(key: string, bytes: Uint8Array): void | Promise<void>;
    /**
     * The store itself verifies every record's integrity (the engine's own Rust store checksums each
     * one with SHA-256), so the cache needn't checksum and scan them again in JS. Geometry is still
     * validated by the core when it's registered.
     */
    readonly verified?: boolean;
}

/**
 * Persists the output of a deterministic model factory, including nested model arrays/objects.
 * Hits register saved vertices directly: no procedural tessellation, painting or optimization.
 * Imported/skinned/textured models are intentionally excluded; their own loaders retain their rigs.
 */
export declare class ProceduralCache {
    readonly revision: string;
    constructor(revision: string, storage?: ProceduralStorage | undefined);
    get stats(): {
        hits: number;
        builds: number;
        invalid: number;
        failures: number;
        pendingWrites: number;
    };
    flush(): Promise<void>;
    /**
     * A value already cached (in memory, or saved by an earlier launch), without building anything:
     * undefined when there is none yet. Lets work that's spread over many frames (a level generated
     * step by step) skip itself entirely when a saved result exists, then save with `get`.
     */
    peek<T>(key: string): T | undefined;
    get<T>(key: string, build: () => T): T;
}

/** A loaded image. Pass it as an entity's `texture`. */
export type Texture = {
    readonly id: number;
    readonly width: number;
    readonly height: number;
};

/**
 * Initializes the engine automatically. Loads a PNG or JPEG once (up to 4096 x 4096). Use it on any entity: `{ mesh: "cube", texture }`.
 * The entity's `color` tints it; `textureRegion` shows part of it (sprite sheets, card atlases).
 *
 * ```ts
 * const crate = await loadTexture(require("./assets/crate.png"));
 * world.spawn({ mesh: "cube", texture: crate });
 * ```
 */
export declare function loadTexture(source: AssetSource): Promise<Texture>;

type Node = {
    readonly kind: 'sphere';
    readonly radius: number;
} | {
    readonly kind: 'ellipsoid';
    readonly radii: Vec3;
} | {
    readonly kind: 'box';
    readonly size: Vec3;
    readonly radius: number;
} | {
    readonly kind: 'capsule';
    readonly start: Vec3;
    readonly end: Vec3;
    readonly radius: number;
} | {
    readonly kind: 'cylinder';
    readonly radius: number;
    readonly height: number;
} | {
    readonly kind: 'torus';
    readonly radius: number;
    readonly tube: number;
} | {
    readonly kind: 'union';
    readonly a: Node;
    readonly b: Node;
    readonly blend: number;
} | {
    readonly kind: 'subtract' | 'intersect';
    readonly a: Node;
    readonly b: Node;
} | {
    readonly kind: 'transform';
    readonly child: Node;
    readonly position: Vec3;
    readonly rotation: Quat;
    readonly scale: Vec3;
} | {
    readonly kind: 'paint';
    readonly child: Node;
    readonly color: Color;
} | {
    readonly kind: 'shell';
    readonly child: Node;
    readonly thickness: number;
} | {
    readonly kind: 'displace';
    readonly child: Node;
    readonly amplitude: number;
    readonly frequency: number;
    readonly seed: number;
    readonly octaves: number;
};

/**
 * An immutable, code-authored solid. Join primitives into a single surface, blend organic forms,
 * drill holes, hollow shells and add reproducible rock/terrain detail before tessellating once.
 * Distances use world units; primitives are centered at the origin, cylinders/tori use the Y axis.
 *
 * const torso = Solid.ellipsoid([0.5, 0.7, 0.3]).paint([0.5, 0.1, 0.9]);
 * const neck = Solid.capsule([0, 0.5, 0], [0, 0.9, 0], 0.15);
 * const geometry = solidGeometry(torso.blend(neck, 0.15), { resolution: 48 });
 */
export declare class Solid {
    static sphere(radius?: number): Solid;
    static ellipsoid(radii: Vec3): Solid;
    /** Full width/height/depth. Rounding stays inside these dimensions. */
    static box(size: Vec3, radius?: number): Solid;
    static capsule(start: Vec3, end: Vec3, radius: number): Solid;
    static cylinder(radius: number, height: number): Solid;
    /** Major radius to the tube center; minor radius of the tube itself. */
    static torus(radius: number, tube: number): Solid;
    /** Balanced union for many parts; avoids building a deeply nested operation chain. */
    static union(...solids: readonly Solid[]): Solid;
    union(other: Solid): Solid;
    /** Smoothly weld overlapping forms; blend controls the transition width in world units. */
    blend(other: Solid, blend: number): Solid;
    subtract(other: Solid): Solid;
    intersect(other: Solid): Solid;
    translate(position: Vec3): Solid;
    rotate(rotation: Quat): Solid;
    scale(scale: number | Vec3): Solid;
    /** Vertex colors blend with the surface at smooth joins. Apply after subtract() to color cut walls. */
    paint(color: Color): Solid;
    /** A shell centered on the original surface; thickness is its full wall thickness. */
    shell(thickness: number): Solid;
    /** Seeded fractal value noise. Use a resolution fine enough to sample its smallest features. */
    displace(options: DisplacementOptions): Solid;
    /** Serializable recipe for caching or inspecting a generated asset. */
    toJSON(): Node;
}

export interface DisplacementOptions {
    amplitude: number;
    frequency?: number;
    seed?: number;
    /** 1..6 octaves. Default 3. */
    octaves?: number;
}

export interface SolidOptions {
    /** Cells across the longest dimension, 8..128. Default 48. Higher costs cubic sampling work. */
    resolution?: number;
    /** Planar UV projection. Use parametricSurface/loft for explicitly authored UVs. Default xy. */
    uv?: 'xy' | 'xz' | 'yz';
}

/** Tessellates into editable, unregistered geometry. Prefer createSolid() for automatic model reuse. */
export declare function solidGeometry(solid: Solid, options?: SolidOptions): Geometry;

/**
 * Tessellates, cleans and registers a solid once, then returns its cached model on later calls
 * with the same recipe/options. White vertex colors can be tinted per spawned entity. Temporary
 * intermediate meshes consume no IDs. Prepared solids persist automatically when platform storage
 * is available; storage failure falls back to building. Call after warmUpEngine(), before spawning a run.
 */
export declare function createSolid(solid: Solid, options?: SolidOptions & ShapeOptions): Model;

export interface OptimizeOptions {
    /** Target triangle fraction in (0,1]. Default 1: lossless cleanup, welding and GPU cache ordering. */
    ratio?: number;
    /** Maximum relative error, 0..1, against the largest dimension, with attribute error included. Default 0.001. */
    error?: number;
    /** Keep open borders fixed, useful for separately generated terrain chunks. Default true. */
    lockBorders?: boolean;
}

/**
 * Returns new geometry, preserving the input and its normal/color/UV seams. Removes degenerate
 * triangles and unused/identical vertices, simplifies within the error bound, then orders buffers
 * for GPU reuse. The error bound may prevent reaching the requested ratio. Opaque static meshes only:
 * do not use on skinning buffers or meshes whose vertex indices are used by external code.
 */
export declare function optimizeGeometry(geometry: Geometry, options?: OptimizeOptions): Geometry;

/**
 * Independently simplifies the original at each requested ratio, avoiding accumulated error.
 * Cache/register the results once. The caller selects a level when camera distance changes.
 */
export declare function createGeometryLods(geometry: Geometry, ratios?: readonly number[], options?: Omit<OptimizeOptions, 'ratio'>): Geometry[];

export interface GeometryStats {
    vertices: number;
    triangles: number;
    /** CPU geometry bytes, excluding registration/driver copies. */
    bytes: number;
    bounds: {
        min: Vec3;
        max: Vec3;
        size: Vec3;
    } | null;
}

/** Cheap counts and bounds without registering a mesh. */
export declare function getGeometryStats(geometry: Geometry): GeometryStats;

/** Copies/sculpts one smooth surface and updates its normals. Deform hard-edged parts separately. */
export declare function deformGeometry(geometry: Geometry, deform: (position: Vec3, uv: readonly [
    number,
    number
]) => Vec3): Geometry;