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

package/lib/web/types/src/render/GameView.d.ts

@@ -0,0 +1,94 @@
+import { type Camera, type Light, type RenderSource } from '../types';
+import type { Color } from '../world/types';
+import { type ViewStyle } from './host';
+import { type RenderQuality, type RenderQualitySetting } from './quality';
+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).
+     * Step your simulation here, e.g. `world.update(dt)`, then read input, spawn, move the camera.
+     */
+    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, linear 0..1 RGB (alpha ignored). Also the fog color. Default dark navy. */
+    background?: Color;
+    /** 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. Step it yourself
+     * (`overlay.update(dt)` in `onUpdate`).
+     */
+    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;

package/lib/web/types/src/render/camera.d.ts

@@ -0,0 +1,5 @@
+import type { Camera, RenderSource } from '../types';
+/** `camera.follow`: ease the target toward the entity (where it was last drawn) and keep the eye at the offset. */
+export declare function follow(camera: Camera, source: RenderSource, out: [number, number, number], dt: number): void;
+/** `camera.shake`: a jittered copy of the camera; the strength fades by itself. */
+export declare function shake(camera: Camera, out: Camera, dt: number): Camera;

package/lib/web/types/src/render/host.d.ts

@@ -0,0 +1,15 @@
+import { type CSSProperties } from 'react';
+import { createTouchResponder } from './touch';
+export { createTouchResponder };
+export type ViewStyle = CSSProperties;
+export declare const pixelRatio: () => number;
+export declare function useActive(): boolean;
+interface SurfaceProps {
+    surfaceId: number;
+    style?: CSSProperties;
+    onSize: (width: number, height: number) => void;
+    onError: (error: Error) => void;
+    touch?: ReturnType<typeof createTouchResponder>;
+    onPrimaryAction?: () => void;
+}
+export declare function Surface({ surfaceId, style, onSize, onError, touch, onPrimaryAction }: SurfaceProps): import("react").JSX.Element;

package/lib/web/types/src/render/meshes.d.ts

@@ -0,0 +1,44 @@
+export declare const VERTEX_FLOATS = 11;
+type V3 = readonly [number, number, number];
+export declare class Builder {
+    vertices: number[];
+    indices: number[];
+    /** Adds a vertex, returns its index. */
+    vertex(p: V3, n: V3, u: number, v: number): number;
+    /** Two triangles, counter-clockwise a b c d as seen from the front. */
+    quad(a: number, b: number, c: number, d: number): void;
+    /**
+     * A (rows + 1) x (cols + 1) vertex grid; `at(u, v)` gives position and normal. u runs along a row and
+     * v down the rows; the grid faces the side from which u goes right and v goes down.
+     */
+    grid(rows: number, cols: number, at: (u: number, v: number) => [V3, V3]): void;
+    /** A flat disc at height y facing up (+1) or down (-1). */
+    disc(y: number, radius: number, facing: 1 | -1, segments: number): void;
+}
+/** Render-ready geometry: VERTEX_FLOATS floats per vertex, u32 triangle indices. */
+export type MeshGeometry = {
+    vertices: Float32Array;
+    indices: Uint32Array;
+};
+/** What the renderer draws for a mesh id: geometry, and a texture id (see `loadTexture`) if any. */
+/** `shine` 0..1: how glossy (sun highlight and sky reflection), 0 = matte. */
+export type MeshInfo = {
+    geometry: MeshGeometry;
+    texture?: number;
+    shine?: number;
+};
+/** Registers what a mesh id draws (loaded models, glyphs, textured variants). */
+export declare function registerMesh(mesh: number, info: MeshInfo, uploadGeometry?: boolean): void;
+/** One past the highest mesh id in use: per-frame scans of a source's ranges stop here. */
+export declare const getMeshIdLimit: () => number;
+/** Generates the built-in shapes in the Rust core and registers them with the native renderer (once). */
+export declare function uploadBuiltInMeshes(): void;
+/**
+ * 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>;
+/** What to draw for a mesh id, or undefined ("none", or unknown). Built-in shapes use native geometry. */
+export declare function meshInfo(mesh: number): MeshInfo | undefined;
+export {};

package/lib/web/types/src/render/quality.d.ts

@@ -0,0 +1,45 @@
+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';
+export type QualityLevel = {
+    /** Most device pixels drawn per point (the screen's own ratio when lower). */
+    maxPixelRatio: number;
+    /** MSAA samples: 4 or 1 (off). */
+    samples: 1 | 4;
+    /** Shadow map width and height in texels. */
+    shadowSize: number;
+    /** 3x3 filtered (soft) shadow edges, or a single tap (hard). */
+    softShadows: boolean;
+};
+/** From best looking to cheapest; "auto" walks down this list only as far as it must. */
+export declare const QUALITIES: readonly RenderQuality[];
+export declare const QUALITY_LEVELS: Record<RenderQuality, QualityLevel>;
+/** One second of frames, as the frame loop measured it. */
+export type FrameReport = {
+    /** The typical (median) time between frames, in ms: hiccups (garbage collection, a busy JS frame) don't move it. */
+    frameMs: number;
+    /** The typical (median) time spent drawing a frame, in ms (including any wait for the screen). */
+    renderMs: number;
+};
+/**
+ * Picks the level for "auto": starts at the best, steps down one level after `SLOW_SECONDS`
+ * consecutive seconds whose typical frame misses ~50 fps while drawing took most of it, and steps
+ * back up after `FAST_SECONDS` smooth seconds. A level that fails again soon after being restored
+ * becomes the ceiling, so it never bounces.
+ */
+export declare class AutoQuality {
+    private index;
+    /** The best level it may return to (raised past a level that keeps failing). */
+    private ceiling;
+    private started;
+    private changed;
+    private raisedAt;
+    private slow;
+    private fast;
+    get quality(): RenderQuality;
+    /** Feeds one second of frames; returns true when the level changed. */
+    report(now: number, frames: FrameReport): boolean;
+    private moved;
+}
+/** The middle value of `values` (sorted in place). */
+export declare function median(values: number[]): number;

package/lib/web/types/src/render/responder.d.ts

@@ -0,0 +1,39 @@
+import type { PointerEvent as ReactPointerEvent } from 'react';
+type Touch = {
+    pageX: number;
+    pageY: number;
+};
+interface Event {
+    nativeEvent: Touch & {
+        locationX: number;
+        locationY: number;
+        touches: Touch[];
+    };
+}
+interface Gesture {
+    dx: number;
+    dy: number;
+}
+interface Callbacks {
+    onStartShouldSetPanResponder: () => boolean;
+    onMoveShouldSetPanResponder: () => boolean;
+    onPanResponderGrant: (event: Event) => void;
+    onPanResponderMove: (event: Event, gesture: Gesture) => void;
+    onPanResponderRelease: (event: Event, gesture: Gesture) => void;
+    onPanResponderTerminate: (event: Event, gesture: Gesture) => void;
+}
+export interface PanResponderInstance {
+    panHandlers: {
+        onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onPointerCancel: (event: ReactPointerEvent<HTMLDivElement>) => void;
+        onLostPointerCapture: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    };
+    cancel: () => void;
+}
+/** Adapt DOM pointer capture to the gesture recognizer used on mobile. Coordinates stay in CSS pixels. */
+export declare const PanResponder: {
+    create(callbacks: Callbacks): PanResponderInstance;
+};
+export {};

package/lib/web/types/src/render/touch.d.ts

@@ -0,0 +1,25 @@
+import type { DragEvent, OverlayTouchPhase, PinchEvent, SwipeDirection } from './GameView';
+import { type PanResponderInstance } from './responder';
+declare const TAP_SLOP = 10;
+declare const TAP_TIME = 300;
+declare const SWIPE_DISTANCE = 30;
+declare const SWIPE_SPEED = 0.3;
+declare const LONG_PRESS_TIME = 500;
+type Handlers = {
+    onTap?: (x: number, y: number) => void;
+    onSwipe?: (direction: SwipeDirection) => void;
+    onDrag?: (drag: DragEvent) => void;
+    onLongPress?: (x: number, y: number) => void;
+    onPinch?: (pinch: PinchEvent) => void;
+    onOverlayTouch?: (phase: OverlayTouchPhase, x: number, y: number) => boolean | void;
+};
+/**
+ * Creates a PanResponder that recognizes taps, swipes, drags, long presses and pinches.
+ * `getHandlers` is called on each event so the caller can swap handlers without recreating the responder.
+ */
+export declare function createTouchResponder(getHandlers: () => Handlers): {
+    responder: PanResponderInstance;
+    dispose: () => void;
+    cancel: () => void;
+};
+export { TAP_SLOP, TAP_TIME, SWIPE_DISTANCE, SWIPE_SPEED, LONG_PRESS_TIME };

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

@@ -0,0 +1,71 @@
+import type { Color, Entity } from './world/types';
+export type Vec3 = readonly [number, number, number];
+/** Number of mesh ids: built-in shapes (0..15), then loaded models, glyphs and textured variants. */
+export declare const MAX_MESHES = 4096;
+/** What the renderer draws. `World` implements it; so can any custom simulation. */
+export interface RenderSource {
+    /** Native world id, when this source supports skeletal characters. */
+    readonly nativeWorld?: number;
+    /** Column-major mat4 per instance (16 floats), grouped by mesh. Only the first `count` are valid. */
+    readonly matrices: Float32Array;
+    /** RGBA per instance (4 floats), same order as `matrices`. Alpha below 1 draws see-through. */
+    readonly colors: Float32Array;
+    /** Texture region per instance (u0 v0 u1 v1), same order. Optional: the whole texture by default. */
+    readonly regions?: Float32Array;
+    /**
+     * `[first, count]` per mesh id, in instances: opaque instances at `ranges[2 * mesh]`, transparent ones
+     * at `ranges[2 * (MAX_MESHES + mesh)]`. Shorter arrays just have no transparent part.
+     */
+    readonly ranges: Uint32Array;
+    /** Total number of valid instances. */
+    readonly count: number;
+    /** Maximum number of instances (sizes the GPU buffers). */
+    readonly capacity: number;
+    /** Called by GameView after each frame with the camera it drew with (for picking and `toScreen`). */
+    setView?(viewProj: Float32Array, width: number, height: number): void;
+}
+/**
+ * Built-in shapes, each 1 unit across before scaling. "none" isn't drawn (groups, pivots, trigger zones).
+ * "puff" is a soft, round sprite that always faces the camera and is always see-through: overlapping
+ * puffs blend into smoke, dust, steam and clouds. "flame" is the same sprite drawn additively: it adds
+ * light to what's behind it, so overlapping flames build up to a hot white core and stay bright over
+ * smoke (fire, sparks, explosions, magic, glows). Use them as a burst's `mesh`.
+ */
+export type Shape = 'cube' | 'sphere' | 'plane' | 'cylinder' | 'cone' | 'capsule' | 'torus' | 'roundedBox' | 'puff' | 'flame' | 'none';
+/** Mesh ids of the built-in shapes, as the core and renderer know them. */
+export declare const SHAPE_MESH: Record<Shape, number>;
+export type Camera = {
+    eye: [number, number, number];
+    target: [number, number, number];
+    /** Vertical field of view in radians (ignored when `ortho` is set). */
+    fov: number;
+    /** Orthographic: half the visible height in world units. Board and puzzle games look flat and tidy. */
+    ortho?: number;
+    /**
+     * Chase an entity: each frame the target moves toward it and the eye keeps `offset` from the target.
+     * `smoothing` is roughly the seconds it takes to catch up (0 = rigid, default 0.15).
+     */
+    follow?: {
+        target: Entity;
+        offset: Vec3;
+        smoothing?: number;
+    } | null;
+    /** Shake strength in world units (e.g. 0.3 for a hit). Fades out by itself. */
+    shake?: number;
+};
+export type Light = {
+    /** Direction *towards* the light. Need not be normalized. */
+    direction: [number, number, number];
+    /** 0..1 ambient term. */
+    ambient: number;
+    /** Cast shadows (one directional shadow map centred on the camera target). Default true. */
+    shadows?: boolean;
+    /** Half-size in world units of the shadowed area around the camera target. Default 30. */
+    shadowExtent?: number;
+    /**
+     * Color and brightness of the light, multiplying both sun and ambient: e.g. [0.35, 0.38, 0.6] for
+     * moonlight. Glowing colors (channels above 1) aren't affected. Alpha, if given, is ignored.
+     * Default [1, 1, 1].
+     */
+    color?: Color;
+};

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

@@ -0,0 +1,64 @@
+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.
+ *
+ * ```ts
+ * world.scoreboard.handlers = { onScore: setScore, onSecond: setTime, onTimeUp: () => end(true) };
+ * world.scoreboard.reset(3);
+ * world.scoreboard.startCountdown(60);
+ * world.scoreboard.add(10);
+ * ```
+ */
+export declare class Scoreboard {
+    private readonly world;
+    handlers: ScoreboardHandlers;
+    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;
+    /** @internal Runs handlers for what changed since the last call. */
+    dispatch(): void;
+}

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()`. Flush before reading
+ * positions, animating, or stepping the world. 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,198 @@
+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;
+    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 after `update()`, then `flush()` once before the frame is drawn.
+     */
+    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;
+    /** 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, refreshes what GameView draws. */
+    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;
+}