@nayan-ui/engine 1.0.0-beta.3 → 1.0.0-beta.4

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

@@ -5,6 +5,6 @@ export declare class AssetLoader<T> {
     private readonly name;
     private readonly loads;
     constructor(name: string);
-    load(source: AssetSource, decode: (native: EngineBridge, bytes: ArrayBuffer) => T, variant?: readonly (string | number | boolean)[]): Promise<T>;
+    load(source: AssetSource, decode: (native: EngineBridge, bytes: ArrayBuffer) => T | Promise<T>, variant?: readonly (string | number | boolean)[]): Promise<T>;
     private error;
 }

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

@@ -2,6 +2,12 @@
 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.
@@ -26,6 +32,12 @@ export declare class ProceduralCache {
         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;
     private encode;
     private restore;

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

@@ -1,3 +1,4 @@
+import { type MeshGeometry } from '../render/meshes';
 import type { Vec3 } from '../types';
 import type { AssetSource } from './source';
 export type ModelOptions = {
@@ -32,6 +33,15 @@ export declare function nativeGeometry(mesh: number): {
     vertices: Float32Array<ArrayBuffer>;
     indices: Uint32Array<ArrayBuffer>;
 };
+/**
+ * Registers a mesh the core already holds (a created, cached or loaded model, a glyph, an alias):
+ * the renderer copies it inside Rust, and JS reads its geometry only if something asks for it
+ * (merging, caching). Apps built before `renderModel` upload it through JS as before.
+ */
+export declare function registerCoreMesh(mesh: number, info?: {
+    texture?: number;
+    shine?: number;
+}, geometry?: () => MeshGeometry): void;
 /** Independent materials share core geometry without overwriting an existing model's appearance. */
 export declare function registerModelMesh(mesh: number, shine: number): number;
 /**

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

@@ -1,9 +1,12 @@
 export { World, isEngineAvailable } from './world/World';
 export { quat, type MutableQuat } from './world/quat';
+export { toColor, type ColorInput } from './world/color';
 export { effects, type DustOptions, type EffectOptions, type FlashOptions, type PopOptions } from './world/effects';
 export { Scoreboard, type ScoreboardHandlers } from './world/Scoreboard';
 export type { AnimateOptions, AnimateTarget, BodyType, Bounds, BurstOptions, CollisionInfo, ClipOptions, ScreenPlane, Color, Easing, Entity, EntityOptions, ImpactFeedback, Keyframe, PhysicsOptions, PickHit, Quat, RaycastHit, SpringOptions } from './world/types';
-export { GameView } from './render/GameView';
+export { afterNextFrame, GameView } from './render/GameView';
+export { useWorld, type WorldSetup } from './render/useWorld';
+export { frontLight } from './render/light';
 export { warmUpEngine, getMeshIdLimit } from './render/meshes';
 export type { TransformBatch, TransformOptions } from './world/TransformBatch';
 export type { DragEvent, GameViewProps, GameViewStats, OverlayTouchPhase, PinchEvent, SwipeDirection } from './render/GameView';

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

@@ -4,11 +4,13 @@ export interface NativeGeometry {
     vertices: ArrayBuffer;
     indices: ArrayBuffer;
 }
-type BufferValue<T, Buffer> = T extends readonly number[] ? T : T extends object ? Buffer : T;
+type BufferValue<T, Buffer> = T extends readonly number[] ? T : T extends Promise<unknown> ? T : T extends (...args: never[]) => unknown ? T : T extends object ? Buffer : T;
 type BufferMethod<T> = T extends (...args: infer A) => infer R ? (...args: {
     [K in keyof A]: BufferValue<A[K], ArrayBufferLike>;
 }) => BufferValue<R, ArrayBuffer> : T;
-type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize'>;
+/** Native-only (a display clock and a render thread): absent on the web core and on older app builds. */
+type NativeFrames = 'publishFrame' | 'renderStats' | 'hasFrameClock' | 'startFrames' | 'stopFrames';
+type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize' | NativeFrames>;
 /** The same runtime ABI on JSI and WASM, with precise TypeScript buffer and tuple contracts. */
 export type EngineBridge = {
     [K in keyof BinarySpec]: BufferMethod<BinarySpec[K]>;
@@ -17,5 +19,7 @@ export type EngineBridge = {
     geometryOptimize(vertices: ArrayBufferLike, indices: ArrayBufferLike, ratio: number, error: number, lockBorders: boolean): NativeGeometry;
     modelSize(mesh: number): [x: number, y: number, z: number];
     textureSize(texture: number): [width: number, height: number];
+} & {
+    [K in NativeFrames]?: BufferMethod<Spec[K]>;
 };
 export {};

package/lib/web/types/src/native/spec/NativeNayanEngine.d.ts

@@ -90,6 +90,8 @@ export interface Spec extends TurboModule {
     shapePrepare(vertices: Object, indices: Object, options: string): number;
     solidPrepare(recipe: string, options: string): number;
     modelLoad(data: Object, center: boolean, fit: number): number;
+    /** `modelLoad` on a background native thread (the data is copied first): resolves to the mesh id, or -1. */
+    modelLoadAsync(data: Object, center: boolean, fit: number): Promise<number>;
     /** 11 floats per vertex (position, normal, color, uv); aliases native memory. */
     modelVertices(mesh: number): Object;
     /** u32 triangle indices; aliases native memory. */
@@ -102,6 +104,11 @@ export interface Spec extends TurboModule {
     meshAlias(base: number): number;
     /** Registers geometry (copied): 11 floats per vertex, u32 triangle indices. Returns the mesh id, or -1. */
     meshCreate(vertices: Object, indices: Object): number;
+    /**
+     * Hands a core model's own geometry (from `meshCreate`, `modelLoad`, a font) to the renderer, in
+     * Rust: nothing is copied through JS. `texture` -1 for none. False if the mesh is unknown.
+     */
+    renderModel(mesh: number, texture: number, shine: number): boolean;
     /**
      * Fills 2D contours ([x, y] f32 pairs, `counts[k]` points per contour) by the non-zero or even-odd
      * rule and extrudes them `depth` deep. Returns an ArrayBuffer of 11 floats per vertex (unindexed).
@@ -122,12 +129,16 @@ export interface Spec extends TurboModule {
     geometryPlace(vertices: Object, indices: Object, placement: Array<number>, first: number, outVertices: Object, vertexOffset: number, outIndices: Object, indexOffset: number): void;
     /** Decodes a PNG/JPEG ArrayBuffer. Returns the texture id, or -1. */
     textureLoad(data: Object): number;
+    /** `textureLoad` on a background native thread: resolves to the texture id, or -1. */
+    textureLoadAsync(data: Object): Promise<number>;
     /** RGBA8 pixels, top row first; aliases native memory. */
     texturePixels(texture: number): Object;
     /** [width, height]. */
     textureSize(texture: number): Array<number>;
     /** Builds extruded glyph meshes for `chars`. Returns the font id, or -1. */
     fontLoad(data: Object, depth: number, chars: string, weight: number): number;
+    /** `fontLoad` (outlines and glyph meshes) on a background native thread: resolves to the font id, or -1. */
+    fontLoadAsync(data: Object, depth: number, chars: string, weight: number): Promise<number>;
     /** [codepoint, mesh (-1 = nothing drawn), advance, ...] followed by the cap height. */
     fontGlyphs(font: number): Array<number>;
     /** Why the last model / texture / font / alias load failed ("" after a success). */
@@ -151,6 +162,22 @@ export interface Spec extends TurboModule {
      * Returns 1 (drawn), 0 (surface not ready yet / frame skipped) or -1 (see `renderError`).
      */
     renderFrame(surface: number, frame: Object, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, viewProj: Object, world: number): number;
+    /**
+     * `renderFrame`'s arguments, but the frame is copied and drawn on the native render thread: returns
+     * at once, with `viewProj` written. 1 once the surface has presented a frame, 0 before, -1 if the
+     * last frame failed (see `renderError`).
+     */
+    publishFrame(surface: number, frame: Object, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, viewProj: Object, world: number): number;
+    /** [frames presented, smoothed render milliseconds] for a surface drawn by the render thread. */
+    renderStats(surface: number): Array<number>;
+    /** True where the platform drives frames from its display clock (`startFrames`); else use requestAnimationFrame. */
+    hasFrameClock(): boolean;
+    /**
+     * Calls `onFrame` on the JS thread once per display refresh while the surface is attached and
+     * visible, with the frame time in milliseconds. A frame JS hasn't started yet isn't queued again.
+     */
+    startFrames(surface: number, onFrame: (timeMs: number) => void): void;
+    stopFrames(surface: number): void;
     /**
      * The screen-space overlay drawn over surface `surface` from its next frame on, copied from a world's
      * buffers. In points: x right and y up from the view's top-left (on screen y <= 0), z toward the
@@ -167,6 +194,8 @@ export interface Spec extends TurboModule {
     drawingDestroy(document: number): void;
     /** Decodes a WAV ArrayBuffer. Returns a sound id, or -1. */
     audioLoad(data: Object): number;
+    /** `audioLoad` on a background native thread: resolves to the sound id, or -1. */
+    audioLoadAsync(data: Object): Promise<number>;
     /** Returns a voice id (> 0), or 0 if nothing played. */
     audioPlay(sound: number, volume: number, pan: number, pitch: number, loop: boolean): number;
     audioStop(voice: number): void;

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

@@ -1,7 +1,18 @@
 import { type Camera, type Light, type RenderSource } from '../types';
-import type { Color } from '../world/types';
+import { type ColorInput } from '../world/color';
 import { type ViewStyle } from './host';
 import { type RenderQuality, type RenderQualitySetting } from './quality';
+/**
+ * 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. */
@@ -41,15 +52,16 @@ export type GameViewProps = {
     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.
+     * 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, linear 0..1 RGB (alpha ignored). Also the fog color. Default dark navy. */
-    background?: Color;
+    /** 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;
     /**
@@ -76,8 +88,8 @@ export type GameViewProps = {
     /**
      * 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`).
+     * within -100..100. Unlit (flat faces show their exact color) and always in front. Stepped each
+     * frame like `source`.
      */
     overlay?: RenderSource;
     /**

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

@@ -0,0 +1,11 @@
+import type { Light } from '../types';
+/**
+ * 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;

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

@@ -23,8 +23,9 @@ export type FrameReport = {
 };
 /**
  * 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
+ * consecutive seconds whose typical frame misses ~50 fps while drawing took most of it (after a
+ * single second when it misses ~33 fps, so a struggling phone recovers in seconds rather than
+ * stuttering through every level), 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 {
@@ -35,6 +36,7 @@ export declare class AutoQuality {
     private changed;
     private raisedAt;
     private slow;
+    private verySlow;
     private fast;
     get quality(): RenderQuality;
     /** Feeds one second of frames; returns true when the level changed. */

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

@@ -0,0 +1,19 @@
+import { type DependencyList } from 'react';
+import { World } from '../world/World';
+/** 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;

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

@@ -1,4 +1,5 @@
-import type { Color, Entity } from './world/types';
+import type { ColorInput } from './world/color';
+import type { 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;
@@ -23,6 +24,14 @@ export interface RenderSource {
     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;
+    /**
+     * Steps the source. When present, GameView calls it once a frame after `onUpdate`, unless
+     * `onUpdate` already did (`updateCount` changed) or the source is disposed.
+     */
+    update?(dt: number): void;
+    /** How many times `update` has run. */
+    readonly updateCount?: number;
+    readonly isDisposed?: boolean;
 }
 /**
  * Built-in shapes, each 1 unit across before scaling. "none" isn't drawn (groups, pivots, trigger zones).
@@ -64,8 +73,8 @@ export type Light = {
     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].
+     * moonlight, or a CSS color. Glowing colors (channels above 1) aren't affected. Alpha, if given, is
+     * ignored. Default [1, 1, 1].
      */
-    color?: Color;
+    color?: ColorInput;
 };

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

@@ -12,10 +12,12 @@ export type ScoreboardHandlers = {
 /**
  * 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.
+ * 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 = { onScore: setScore, onSecond: setTime, onTimeUp: () => end(true) };
+ * 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);
@@ -23,7 +25,9 @@ export type ScoreboardHandlers = {
  */
 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);
@@ -59,6 +63,12 @@ export declare class Scoreboard {
      * 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

@@ -2,8 +2,8 @@ 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
+ * 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.

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

@@ -44,6 +44,7 @@ export declare class World implements RenderSource {
     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
@@ -61,7 +62,8 @@ export declare class World implements RenderSource {
     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.
+     * 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. */
@@ -131,6 +133,8 @@ export declare class World implements RenderSource {
     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. */
@@ -183,7 +187,11 @@ export declare class World implements RenderSource {
     /** 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. */
+    /**
+     * 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:

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/effects.d.ts

@@ -1,11 +1,12 @@
 import type { Vec3 } from '../types';
-import type { BurstOptions, Color, Entity } 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, or several to pick from at random. */
-    colors: Color | readonly Color[];
+    /** One color (CSS string or tuple), or several to pick from at random. */
+    colors: ColorInput | readonly ColorInput[];
     /** Typical particle size. */
     size: number;
     /** Top speed. */
@@ -27,7 +28,7 @@ export type EffectOptions = {
 export type DustOptions = {
     position: Vec3;
     /** Start color (alpha is how thick it looks), or several to pick from. */
-    color: Color | readonly Color[];
+    color: ColorInput | readonly ColorInput[];
     /** Puff size at the start. */
     size: number;
     /** Top speed. */
@@ -44,7 +45,7 @@ export type DustOptions = {
     /** 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?: Color;
+    endColor?: ColorInput;
     /** Default "puff" (blended); "flame" adds light instead. */
     mesh?: BurstOptions['mesh'];
 };
@@ -52,14 +53,14 @@ export type DustOptions = {
 export type FlashOptions = {
     position: Vec3;
     /** Use channels above 1 to glow (see `effects.hot`). */
-    color: Color;
+    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?: Color;
+    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. */
@@ -72,7 +73,7 @@ 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?: Color;
+    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. */
@@ -82,9 +83,9 @@ export type PopOptions = {
 };
 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(c: Color, peak?: number, alpha?: number): Rgba;
+declare function hot(input: ColorInput, peak?: number, alpha?: number): Rgba;
 /** Part way (`t`, 0..1) to white, with `alpha`. */
-declare function pale(c: Color, t: number, alpha?: number): Rgba;
+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. */
@@ -110,8 +111,8 @@ declare function sparks(world: World, e: EffectOptions): void;
  */
 declare function explosion(world: World, e: Omit<EffectOptions, 'colors'> & {
     colors?: EffectOptions['colors'];
-    debris?: readonly Color[];
-    smoke?: Color;
+    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>;

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

@@ -3,6 +3,7 @@ import type { Model } from '../assets/model';
 import type { Texture } from '../assets/texture';
 import type { Sound } from '../media/audio';
 import type { Vec3 } from '../types';
+import type { ColorInput } from './color';
 /** Opaque entity handle. Handles of despawned entities are safely ignored. */
 export type Entity = number & {
     readonly __entity: unique symbol;
@@ -105,8 +106,11 @@ export type EntityOptions = {
     rotation?: Quat;
     /** A number scales uniformly. Children scale with their parent. Visual only after the body exists. */
     scale?: Vec3 | number;
-    /** Alpha below 1 makes it see-through. Channels above 1 glow: at 2 it's self-lit, ignoring light and shadow (fire, lamps). */
-    color?: Color;
+    /**
+     * 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. */
@@ -141,7 +145,8 @@ export type AnimateTarget = {
     position?: Vec3;
     rotation?: Quat;
     scale?: Vec3 | number;
-    color?: Color;
+    /** 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. */
@@ -200,12 +205,12 @@ export type BurstOptions = {
     lifetime?: number;
     /** Vertical acceleration. Default -9.81 (falls); 0 floats. */
     gravity?: number;
-    /** One color, or up to 4 to pick from at random. Default white. */
-    color?: Color | readonly Color[];
+    /** 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?: Color;
+    endColor?: ColorInput;
 };
 export type CollisionInfo = {
     /** True when the touch started; false when it ended. */