littlejsengine 1.20.0 → 1.22.0

package/dist/littlejs.d.ts

@@ -7,6 +7,10 @@ declare module "littlejsengine" {
      * - Called after the engine starts, can be async
      */
     export type GameInitCallback = () => void | Promise<void>;
+    /**
+     * - Draws the loading screen on mainContext, each frame while the game loads
+     */
+    export type LoadingScreenCallback = (progress: number) => any;
     /**
      * - Update or render function for the game
      */
@@ -76,6 +80,10 @@ declare module "littlejsengine" {
          */
         object?: any;
     };
+    /**
+     * - Called once when a SpriteAnimation's play ends
+     */
+    export type SpriteAnimationEndCallback = () => void;
     /**
      * - Function called when sound is loaded
      */
@@ -88,6 +96,104 @@ declare module "littlejsengine" {
      * - Decides whether a particle stops at a tile, it is a filter rather than a notice
      */
     export type ParticleCollideCallback = (particle: Particle, tileData: number, pos: Vector2) => boolean;
+    /**
+     * A scene, any object with the hooks it needs, each optional and called as a method so this is the scene
+     */
+    export type Scene = {
+        /**
+         * - Called when the scene starts, after the old one left and the objects were destroyed
+         */
+        enter?: () => void;
+        /**
+         * - Called before the next scene starts, while the scene is current and its objects are still there
+         */
+        leave?: () => void;
+        /**
+         * - Called each update after gameUpdate, not while paused or at time scale 0
+         */
+        update?: () => void;
+        /**
+         * - Called before gameRender, to draw under the objects
+         */
+        render?: () => void;
+        /**
+         * - Called after gameRenderPost, to draw over the game, while paused too; plugins made after the first setScene draw over it
+         */
+        renderPost?: () => void;
+    };
+    /**
+     * The draw state's values, behind render3D's accessors, and the rgb emissiveMapColor had when it was set
+     */
+    export type Render3DDrawState = {
+        blend: boolean;
+        additive: boolean;
+        depthTest: boolean;
+        depthWrite: boolean;
+        cullBackFaces: boolean;
+        mirrored: boolean;
+        lighting: boolean;
+        emissive: number;
+        receiveShadow: boolean;
+        specular: number;
+        pixelated: boolean;
+        shader: Shader | undefined;
+        normalMap: TextureInfo | undefined;
+        normalScale: number;
+        shininess: number;
+        reflectivity: number;
+        emissiveMap: TextureInfo | undefined;
+        emissiveMapColor: Color;
+        emissiveR: number;
+        emissiveG: number;
+        emissiveB: number;
+    };
+    /**
+     * A particle as a ParticleEmitter3D's callbacks see it: one object the emitter reuses, set from the particle for each
+     * call and written back after it, so copy what you keep
+     */
+    export type Particle3D = {
+        /**
+         * - The emitter it is in
+         */
+        emitter: ParticleEmitter3D;
+        /**
+         * - Where it is, change it to move it
+         */
+        pos: Vector3;
+        /**
+         * - How far it moves each frame
+         */
+        velocity: Vector3;
+        /**
+         * - Seconds it has lived
+         */
+        age: number;
+        /**
+         * - Seconds it lives
+         */
+        lifeTime: number;
+        /**
+         * - How much the emitter grows its effect, from its scale3D and its parents', as the 2D
+         * particle's scale
+         */
+        scale: number;
+        /**
+         * - Set by destroy
+         */
+        destroyed: boolean;
+        /**
+         * - End it this update, the destroy callback gets it
+         */
+        destroy: () => void;
+    };
+    /**
+     * - A function a ParticleEmitter3D calls with one of its particles
+     */
+    export type Particle3DCallback = (particle: Particle3D) => any;
+    /**
+     * - Decides whether a particle stops where it hits the level, a filter as in 2D
+     */
+    export type Particle3DCollideCallback = (particle: Particle3D, level: EngineObject3D, pos: Vector3) => boolean | void;
     /**
      * What VoxelMap.raycast finds: how far along the ray, the block's cell and type, and the normal of the face it comes in
      * through
@@ -146,11 +252,12 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Engine */
     export const frameRate: number;
-    /** How many seconds each frame lasts, engine uses a fixed time step
+    /** How many seconds the update covers: 1/60 with the fixed time step, or with engineVariableStep the time of the
+     *  display frame it runs on, times timeScale; while paused it keeps the last update's
      *  @type {number}
      *  @default 1/60
      *  @memberof Engine */
-    export const timeDelta: number;
+    export let timeDelta: number;
     /** Array containing all engine objects
      *  @type {Array<EngineObject>}
      *  @memberof Engine */
@@ -189,6 +296,11 @@ declare module "littlejsengine" {
      * @return {void|Promise<void>}
      * @memberof Engine
      */
+    /**
+     * @callback LoadingScreenCallback - Draws the loading screen on mainContext, each frame while the game loads
+     * @param {number} progress - The part of the loads done, 0 to 1
+     * @memberof Engine
+     */
     /**
      * @callback GameCallback - Update or render function for the game
      * @memberof Engine
@@ -284,6 +396,15 @@ declare module "littlejsengine" {
      *  @param {PluginCallback} [preRender] - Called after the canvas is cleared and before gameRender
      *  @memberof Engine */
     export function engineAddPlugin(update?: PluginCallback, render?: PluginCallback, glContextLost?: PluginCallback, glContextRestored?: PluginCallback, preRender?: PluginCallback): void;
+    /** Add something the game loads to what startup waits for: while engineInit and gameInit run, the game loop starts
+     *  once it is done, and the loading screen counts it; images from loadTexture and sounds from files are added on
+     *  their own, and a load that fails counts as done; after startup it does nothing
+     *  @param {Promise<any>} promise
+     *  @return {Promise<any>} - The same promise
+     *  @example
+     *  async function gameInit() { level = await engineAddLoad(fetchJSON('level.json')); }
+     *  @memberof Engine */
+    export function engineAddLoad(promise: Promise<any>): Promise<any>;
     /**
      * LittleJS Debug System
      * - Press Esc to toggle debug overlay with object picking
@@ -532,6 +653,12 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let showSplashScreen: boolean;
+    /** The loading screen, drawn after the splash while the images, gameInit and what they load are loading, once that
+     *  takes more than half a second: a function given the part done, 0 to 1, or undefined for none, which leaves the
+     *  screen blank; the default says Loading over a bar
+     *  @type {LoadingScreenCallback|undefined}
+     *  @memberof Settings */
+    export let loadingScreen: LoadingScreenCallback | undefined;
     /** Disables all rendering, audio, and input for servers, must be set before engineInit
      *  @type {boolean}
      *  @default
@@ -543,6 +670,14 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let engineManualStep: boolean;
+    /** Run one update per display frame with timeDelta the time it covers, in place of fixed updates at frameRate
+     *  - Per-frame values are not scaled: velocity, gravity, damping and particle speeds act once per update, so a
+     *    game that turns this on scales its own movement by timeDelta
+     *  - Values in seconds follow real time as they are: time, timers, particle emit rate and life, animation, Box2D
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let engineVariableStep: boolean;
     /** Default size of tiles in pixels
      *  @type {Vector2}
      *  @default Vector2(16,16)
@@ -854,6 +989,10 @@ declare module "littlejsengine" {
      *  @param {boolean} show
      *  @memberof Settings */
     export function setShowSplashScreen(show: boolean): void;
+    /** Set the loading screen, drawn after the splash while the game loads, once that takes more than half a second
+     *  @param {LoadingScreenCallback} [callback] - Draws on mainContext given the part done, 0 to 1; undefined for none
+     *  @memberof Settings */
+    export function setLoadingScreen(callback?: LoadingScreenCallback): void;
     /** Set to disable rendering, audio, and input for servers, must be set before engineInit
      *  @param {boolean} headless
      *  @memberof Settings */
@@ -864,6 +1003,11 @@ declare module "littlejsengine" {
      *  @param {boolean} [enable]
      *  @memberof Settings */
     export function setEngineManualStep(enable?: boolean): void;
+    /** Set if the engine runs one update per display frame with timeDelta the time it covers
+     *  Can be set before engineInit or while running; turned off it goes back to fixed updates at frameRate
+     *  @param {boolean} [enable]
+     *  @memberof Settings */
+    export function setEngineVariableStep(enable?: boolean): void;
     /** Set if WebGL rendering is enabled
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -1973,8 +2117,9 @@ declare module "littlejsengine" {
          * @param {boolean} [useWebGL] - Should use WebGL if available?
          * @param {boolean|Array<number>} [wrap] - Should the texture wrap (REPEAT) or clamp (CLAMP_TO_EDGE)? Or the WebGL
          *   modes across and down, like [gl.CLAMP_TO_EDGE, gl.MIRRORED_REPEAT], as a glTF sampler gives them
+         * @param {boolean} [pixelated] - Hard edged or smooth for this texture alone, undefined follows tilesPixelated
          */
-        constructor(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, useWebGL?: boolean, wrap?: boolean | Array<number>);
+        constructor(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, useWebGL?: boolean, wrap?: boolean | Array<number>, pixelated?: boolean);
         /** @property {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} - image source */
         image: OffscreenCanvas | ImageBitmap | HTMLCanvasElement | HTMLImageElement;
         /** @property {Vector2} - size of the image */
@@ -1988,6 +2133,10 @@ declare module "littlejsengine" {
          *  across and down
          *  @type {boolean|Array<number>} */
         wrap: boolean | Array<number>;
+        /** @property {boolean|undefined} - Hard edged or smooth for this texture alone, a soft glow in a pixel art
+         *  game or pixel art in a smooth one; undefined follows tilesPixelated
+         *  @type {boolean|undefined} */
+        pixelated: boolean | undefined;
         /** Creates the WebGL texture, updates if already created */
         createWebGLTexture(): void;
         /** Destroys the WebGL texture */
@@ -1999,6 +2148,10 @@ declare module "littlejsengine" {
          *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across
          *    and down */
         setWrap(wrap?: boolean | Array<number>): void;
+        /** Make this texture hard edged or smooth on its own, whatever tilesPixelated says for the rest; it is made again
+         *  with the new filtering
+         *  @param {boolean} [pixelated] - undefined follows tilesPixelated again */
+        setPixelated(pixelated?: boolean): void;
     }
     /** Load a texture at a specific index after engineInit, the images passed to engineInit load this way
      *  @param {number} textureIndex - Index to store the texture at, an unused one
@@ -2006,12 +2159,19 @@ declare module "littlejsengine" {
      *  @return {Promise<TextureInfo>} Resolves to the texture info once the image loads, or fails to with a warning
      *  @memberof Draw */
     export function loadTexture(textureIndex: number, src?: string): Promise<TextureInfo>;
+    /**
+     * @callback SpriteAnimationEndCallback - Called once when a SpriteAnimation's play ends
+     * @return {void}
+     * @memberof Draw
+     */
     /**
      * SpriteAnimation - Steps a tile through its frames over time: looping, once, or there and back
      * - Driven by the engine time like a Timer, so it pauses with the game and needs no update call
      * - Read tileInfo each frame for the frame to draw, from an object's update or before a drawTile
      * - loop, play and pingPong each start over from the first frame; stop holds the current one
+     * - play(onEnd) calls onEnd once the play ends, on the first read after it, since there is no update to call it
      * - Frames follow each other along the row, as tileInfo.frame counts them
+     * - SpriteAnimator switches between a character's animations by name
      * @example
      * const walk = new SpriteAnimation(tile(0, 16), 4, .1); // four frames, a tenth of a second each
      * const attack = new SpriteAnimation(tile(4, 16), 3, .05).play(); // once, then holds the last frame
@@ -2039,19 +2199,23 @@ declare module "littlejsengine" {
         /** @property {number|undefined} - The frame held by stop, undefined while running
          *  @type {number|undefined} */
         heldFrame: number | undefined;
+        /** @property {SpriteAnimationEndCallback|undefined} - Called once when a play ends, on the first read after it
+         *  @type {SpriteAnimationEndCallback|undefined} */
+        onEnd: SpriteAnimationEndCallback | undefined;
         /** Start over from the first frame and repeat forever
          *  @return {SpriteAnimation} */
         loop(): SpriteAnimation;
         /** Start over from the first frame, run through once and hold the last frame, last to first at a negative speed
+         *  @param {function():void} [onEnd] - Called once when it ends, on the first read of it after that
          *  @return {SpriteAnimation} */
-        play(): SpriteAnimation;
+        play(onEnd?: () => void): SpriteAnimation;
         /** Start over from the first frame and run there and back forever
          *  @return {SpriteAnimation} */
         pingPong(): SpriteAnimation;
         /** Hold the current frame
          *  @return {SpriteAnimation} */
         stop(): SpriteAnimation;
-        /** Start over from the first frame in a mode
+        /** Start over from the first frame in a mode, with no end callback
          *  @param {string} [mode] - 'loop', 'once' or 'pingPong', the current mode when left out
          *  @return {SpriteAnimation} */
         restart(mode?: string): SpriteAnimation;
@@ -2064,7 +2228,52 @@ declare module "littlejsengine" {
         /** The tile of the frame showing now
          *  @return {TileInfo} */
         get tileInfo(): TileInfo;
-        /** True once a play has shown its last frame for its time
+        /** True once a play has shown its last frame for its time, the first read after that calls onEnd
+         *  @return {boolean} */
+        get isDone(): boolean;
+    }
+    /**
+     * SpriteAnimator - A character's animations by name, like idle, walk and attack, and the one showing now
+     * - Each clip is a SpriteAnimation and keeps its own mode, loop, play or pingPong
+     * - set starts a clip over only when it changes or a play of it has ended, so it can be called every update
+     * - Read tileInfo each frame for the frame to draw, as with a SpriteAnimation
+     * @example
+     * const hero = new SpriteAnimator({
+     *     idle:   new SpriteAnimation(tile(0, 16), 2, .4),
+     *     walk:   new SpriteAnimation(tile(2, 16), 4, .1),
+     *     attack: new SpriteAnimation(tile(6, 16), 3, .05).play(),
+     * });
+     * hero.set('attack', ()=> hero.set('idle')); // back to idle when the attack ends
+     * // in update: this.tileInfo = hero.tileInfo;
+     * @memberof Draw
+     */
+    export class SpriteAnimator {
+        /** Create an animator from its clips, showing the first one
+         *  @param {Object<string, SpriteAnimation>} clips - The clips by name */
+        constructor(clips: {
+            [x: string]: SpriteAnimation;
+        });
+        /** @property {Object<string, SpriteAnimation>} - The clips by name */
+        clips: {
+            [x: string]: SpriteAnimation;
+        };
+        /** @property {string} - The name of the clip showing now */
+        name: string;
+        /** Show a clip, starting it over in its own mode unless it is showing and has not ended
+         *  @param {string} name - The clip's name
+         *  @param {function():void} [onEnd] - Called once when a play clip ends, as with SpriteAnimation.play
+         *  @return {SpriteAnimator} */
+        set(name: string, onEnd?: () => void): SpriteAnimator;
+        /** The clip showing now
+         *  @return {SpriteAnimation} */
+        get clip(): SpriteAnimation;
+        /** The tile of the frame showing now
+         *  @return {TileInfo} */
+        get tileInfo(): TileInfo;
+        /** The frame of the clip showing now
+         *  @return {number} */
+        get frame(): number;
+        /** True once the clip showing now is a play that has ended
          *  @return {boolean} */
         get isDone(): boolean;
     }
@@ -2590,9 +2799,10 @@ declare module "littlejsengine" {
      *  Restores the active texture when done
      *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} [image]
      *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across and down
+     *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
      *  @return {WebGLTexture}
      *  @memberof WebGL */
-    export function glCreateTexture(image?: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, wrap?: boolean | Array<number>): WebGLTexture;
+    export function glCreateTexture(image?: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, wrap?: boolean | Array<number>, pixelated?: boolean): WebGLTexture;
     /** Deletes a WebGL texture
      *  @param {WebGLTexture} [texture]
      *  @memberof WebGL */
@@ -2600,8 +2810,9 @@ declare module "littlejsengine" {
     /** Set WebGL texture data from an image, restores the active texture when done
      *  @param {WebGLTexture} texture
      *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image
+     *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
      *  @memberof WebGL */
-    export function glSetTextureData(texture: WebGLTexture, image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap): void;
+    export function glSetTextureData(texture: WebGLTexture, image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, pixelated?: boolean): void;
     /** Draw all sprites and clear out the buffer, called automatically by the system whenever necessary
      *  @memberof WebGL */
     export function glFlush(): void;
@@ -2614,6 +2825,17 @@ declare module "littlejsengine" {
      *  @param {boolean} [antialias]
      *  @memberof WebGL */
     export function glSetAntialias(antialias?: boolean): void;
+    /** The largest texture this device makes, in pixels across, 0 until WebGL starts; at least 2048 with WebGL2
+     *  @type {number}
+     *  @memberof WebGL */
+    export let glMaxTextureSize: number;
+    /** A texture size this device can make: the size asked for, or the largest it supports when that is smaller
+     *  - The engine sizes the textures it makes itself through this, the shadow maps and the like, so a size a device
+     *    does not have falls back instead of failing
+     *  @param {number} size - Pixels across
+     *  @return {number}
+     *  @memberof WebGL */
+    export function glClampTextureSize(size: number): number;
     /** Add a sprite to the gl draw list, used by all gl draw functions
      *  @param {number} x
      *  @param {number} y
@@ -2983,6 +3205,9 @@ declare module "littlejsengine" {
         constructor(asset?: string | URL | any[], randomness?: number, range?: number, taper?: number, onloadCallback?: SoundLoadCallback);
         /** @property {number} - World space max range of sound */
         range: number;
+        /** @property {boolean} - No range was given, so it got soundDefaultRange; played in 3D such a sound is heard
+         *  to render3D.soundDefaultRange instead, which is further */
+        rangeIsDefault: boolean;
         /** @property {number} - At what percentage of range should it start tapering */
         taper: number;
         /** @property {number} - How much to randomize frequency each time sound plays
@@ -3266,9 +3491,9 @@ declare module "littlejsengine" {
      *  @param {number}  [decay] - Decay time, how long to reach sustain after attack (seconds)
      *  @param {number}  [tremolo] - Trembling effect, rate controlled by repeat time (percent)
      *  @param {number}  [filter] - Filter cutoff frequency, positive for HPF, negative for LPF (Hz)
-     *  @return {Array} - Array of audio samples
+     *  @return {Float32Array} - The audio samples
      *  @memberof Audio */
-    export function zzfxG(volume?: number, randomness?: number, frequency?: number, attack?: number, sustain?: number, release?: number, shape?: number, shapeCurve?: number, slide?: number, deltaSlide?: number, pitchJump?: number, pitchJumpTime?: number, repeatTime?: number, noise?: number, modulation?: number, bitCrush?: number, delay?: number, sustainVolume?: number, decay?: number, tremolo?: number, filter?: number): any[];
+    export function zzfxG(volume?: number, randomness?: number, frequency?: number, attack?: number, sustain?: number, release?: number, shape?: number, shapeCurve?: number, slide?: number, deltaSlide?: number, pitchJump?: number, pitchJumpTime?: number, repeatTime?: number, noise?: number, modulation?: number, bitCrush?: number, delay?: number, sustainVolume?: number, decay?: number, tremolo?: number, filter?: number): Float32Array;
     /**
      * LittleJS Object System
      * - EngineObject is the base class for all game objects
@@ -3950,6 +4175,13 @@ declare module "littlejsengine" {
         localSpace: boolean;
         /** @property {number} - If non zero the particle is drawn as a trail, stretched in the direction of velocity */
         trailScale: number;
+        /** @property {number} - Grows the whole effect as each particle is born: the spawn area, the particles' sizes,
+         *  speed and fall, so it looks the same only bigger; 1 is as made, and a particle keeps the scale it was born
+         *  with, so a change never moves the ones already out */
+        scale: number;
+        /** @property {number} - The effect's own fall, added to each particle's velocity y every frame, on top of the
+         *  world's gravity times gravityScale; an effect that sets its own looks the same in any game */
+        gravity: number;
         /** @property {ParticleCallback|undefined} - Callback when particle is created
          *  @type {ParticleCallback|undefined} */
         particleCreateCallback: ParticleCallback | undefined;
@@ -4000,6 +4232,8 @@ declare module "littlejsengine" {
         constructor(emitter: ParticleEmitter, pos: Vector2, angle: number, colorStart: Color, colorEnd: Color, lifeTime: number, sizeStart: number, sizeEnd: number, velocity?: Vector2, angleVelocity?: number);
         /** @property {ParticleEmitter} - The emitter this particle came from */
         emitter: ParticleEmitter;
+        /** @property {number} - The emitter's scale when it was made, which grows its fall */
+        scale: number;
         /** @property {Vector2} - Position, world space or local to the emitter when localSpace is set */
         pos: Vector2;
         /** @property {number} - Angle in radians */
@@ -4318,6 +4552,8 @@ declare module "littlejsengine" {
         *  new PostProcessPlugin(shaderCode);
         */
         constructor(shaderCode?: string, includeMainCanvas?: boolean, feedbackTexture?: boolean);
+        /** @property {string} - The shadertoy style mainImage code it shades with, see setShaderCode */
+        shaderCode: string;
         /** @property {WebGLProgram|undefined} - Shader for post processing
          *  @type {WebGLProgram|undefined} */
         shader: WebGLProgram | undefined;
@@ -4330,6 +4566,10 @@ declare module "littlejsengine" {
         /** @property {WebGLVertexArrayObject|undefined} - Vertex array object
          *  @type {WebGLVertexArrayObject|undefined} */
         vao: WebGLVertexArrayObject | undefined;
+        /** Shade with new code from the next frame on, to switch effects while the game runs; the shader is made again
+         *  @param {string} [shaderCode] - Shadertoy style mainImage code, postProcessEffects builds it; none passes the
+         *  frame through */
+        setShaderCode(shaderCode?: string): void;
     }
     /**
      * Set up post processing with a bloom effect, so bright colors and lights glow
@@ -4354,6 +4594,98 @@ declare module "littlejsengine" {
      * @memberof PostProcess
      */
     export function postProcessBloomShader(threshold?: number, strength?: number, size?: number): string;
+    /**
+     * Join effects into one post process shader, in the order given, for PostProcessPlugin or setShaderCode
+     * - Each effect is a piece of shader code on c, the pixel's color, and uv, where it is on the screen from 0 to 1;
+     *   your own code is a piece too, a line of GLSL or many, dropped in where you put it
+     * - Put the ones that bend the picture or sample it first: postProcessCurve, postProcessChromatic, postProcessGlow
+     * @param {...string} effects - The pieces, from the effect functions or your own code
+     * @return {string} - Shadertoy style mainImage code
+     * @example
+     * new PostProcessPlugin(postProcessEffects(
+     *     postProcessScanlines(.5), postProcessVignette(), 'c.rgb *= vec3(1, .9, .8);'));
+     * @memberof PostProcess
+     */
+    export function postProcessEffects(...effects: string[]): string;
+    /**
+     * Bright parts glow, the bloom as an effect to join with others; postProcessBloom sets up bloom on its own
+     * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+     * @param {number} [strength] - How much glow to add
+     * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessGlow(threshold?: number, strength?: number, size?: number): string;
+    /**
+     * Scan lines across the screen, like an old TV
+     * @param {number} [strength] - How dark the lines are, and how bright between them
+     * @param {number} [spacing] - Pixels from one line to the next
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessScanlines(strength?: number, spacing?: number): string;
+    /**
+     * Static noise over the picture, changing every frame
+     * @param {number} [strength] - How bright the static is
+     * @param {number} [size] - Size of a speck in pixels
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessNoise(strength?: number, size?: number): string;
+    /**
+     * Darken toward the edges and corners
+     * @param {number} [strength] - How dark the corners get, 1 is black
+     * @param {number} [falloff] - How far in it reaches, low darkens most of the screen, high only the corners
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessVignette(strength?: number, falloff?: number): string;
+    /**
+     * Bend the picture like the bulged glass of an old TV, black past the corners; put it first
+     * @param {number} [strength] - How much it bends
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessCurve(strength?: number): string;
+    /**
+     * Split red and blue apart toward the edges, like a cheap lens; put it before what shades the picture
+     * @param {number} [strength] - How far apart at the edge, as a part of the screen
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessChromatic(strength?: number): string;
+    /**
+     * Draw lines where the 3D depth jumps, around objects and along their creases; needs render3D.depthTexture on
+     * @param {Color} [color] - The lines' color, its alpha how strong they are
+     * @param {number} [thickness] - How wide the lines are in pixels
+     * @param {number} [threshold] - How big a jump makes a line, as a part of the distance, lower draws more
+     * @return {string}
+     * @memberof PostProcess
+     */
+    export function postProcessOutline(color?: Color, thickness?: number, threshold?: number): string;
+    /**
+     * The look of an old TV, as one effect to use alone or join with others: static noise, scan lines, a soft glow and
+     * a vignette, and a bulged screen when curve is set; any setting at 0 leaves that part out
+     * @param {Object} [settings]
+     * @param {number} [settings.noise] - Static noise strength
+     * @param {number} [settings.scanlines] - Scan line strength
+     * @param {number} [settings.scanlineSpacing] - Pixels from one scan line to the next
+     * @param {number} [settings.glow] - Soft glow strength
+     * @param {number} [settings.vignette] - Vignette strength
+     * @param {number} [settings.curve] - How much the screen bulges, 0 by default for flat
+     * @return {string}
+     * @example
+     * new PostProcessPlugin(postProcessEffects(postProcessTV({scanlines: .4, curve: .1})));
+     * @memberof PostProcess
+     */
+    export function postProcessTV({ noise, scanlines, scanlineSpacing, glow, vignette, curve }?: {
+        noise?: number;
+        scanlines?: number;
+        scanlineSpacing?: number;
+        glow?: number;
+        vignette?: number;
+        curve?: number;
+    }): string;
     /**
      * LittleJS Light System Plugin
      * - Adds 2D dynamic lighting to the scene
@@ -4376,6 +4708,8 @@ declare module "littlejsengine" {
      *   shadow map through renderShadow(), which calls render() by default; obj.castShadow = false keeps it
      *   out (a floor TileLayer, a background), a draw's alpha sets how much light it blocks, and
      *   setShadowTransparent lets its color tint the light
+     * - Set light.glow for a soft hazy glow over a light, like a lamp at night; it is added over the lit scene after the
+     *   lightmap, so it shows in the dark and sits in front of everything there
      * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
      * @namespace LightSystem
      */
@@ -4473,6 +4807,9 @@ declare module "littlejsengine" {
         shadowMapWorldSize: number;
         shadowMapSizeAllocated: number;
         shadowTextureSizeAllocated: number;
+        /** Bring the sizes of the textures it makes down to what the device can make: shadowMapSize, shadowTextureSize
+         *  and a textureSize given by hand; called before they are made, so a size too big falls back instead of failing */
+        clampTextureSizes(): void;
         /** Draw a single Light's falloff blob into the currently bound lightmap.
          *  Called by Light.renderLight() during the plugin's render pass.
          *  @param {Light} light */
@@ -4520,6 +4857,17 @@ declare module "littlejsengine" {
          *  or torch that holds it, or the player carrying it, does not block it; it has to reach past that object's
          *  corners, about half its diagonal and a little more, or dark rays run out from them */
         shadowCore: number;
+        /** @property {number} - Size across of a soft hazy glow drawn over the light, like a lamp at night, 0 for
+         *  none; it is added over the lit scene, in front of everything there */
+        glow: number;
+        /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
+         *  bright core */
+        glowFalloff: number;
+        /** @type {TileInfo|undefined} */
+        glowTileInfo: TileInfo | undefined;
+        /** Draw this light's glow, soft and round, its glow size across and in its color, added over the lit scene;
+         *  called by LightSystemPlugin after the lightmap is applied */
+        renderGlow(): void;
     }
     /**
      * LittleJS ZzFXM Plugin
@@ -6788,6 +7136,16 @@ declare module "littlejsengine" {
         function PIECEWISE(...fns: ((arg0: number) => number)[]): (arg0: number) => number;
         function BEZIER(x1: number, y1: number, x2: number, y2: number): (arg0: number) => number;
     }
+    /** Leave the current scene, destroy every object that is not persistent, and enter the next scene
+     *  - Setting the current scene again restarts it, and no scene leaves the game with none
+     *  - The switch happens at once, it can be called from anywhere but a scene's leave
+     *  @param {Scene} [scene] - The scene to enter
+     *  @memberof SceneSystem */
+    export function setScene(scene?: Scene): void;
+    /** Get the current scene
+     *  @return {Scene|undefined}
+     *  @memberof SceneSystem */
+    export function getScene(): Scene | undefined;
     /** Grid pathfinder using A* with two optional smoothing passes.
      *  @memberof PathFinding
      *  @example
@@ -7363,24 +7721,27 @@ declare module "littlejsengine" {
      */
     export function buildMatrix(pos?: Vector3, rotation?: Vector3, scale?: Vector3, matrix?: Matrix4): Matrix4;
     /**
-     * Check if a point is inside an axis aligned box, boundary is inclusive
+     * Check if a point is inside a box, boundary is inclusive
      * @param {Vector3} point
      * @param {Vector3} pos - Center of the box
      * @param {Vector3} size - Full size of the box
+     * @param {Vector3} [rotation] - How the box is turned, upright when left out
      * @return {boolean}
      * @memberof Math3D
      */
-    export function isPointInBox3D(point: Vector3, pos: Vector3, size: Vector3): boolean;
+    export function isPointInBox3D(point: Vector3, pos: Vector3, size: Vector3, rotation?: Vector3): boolean;
     /**
-     * Check if two axis aligned boxes are overlapping, touching edges do not overlap
+     * Check if two boxes are overlapping, touching edges do not overlap
      * @param {Vector3} posA
      * @param {Vector3} sizeA - Full size of box A
      * @param {Vector3} posB
      * @param {Vector3} [sizeB] - Full size of box B, zero for a point
+     * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+     * @param {Vector3} [rotationB] - How box B is turned
      * @return {boolean}
      * @memberof Math3D
      */
-    export function isOverlapping3D(posA: Vector3, sizeA: Vector3, posB: Vector3, sizeB?: Vector3): boolean;
+    export function isOverlapping3D(posA: Vector3, sizeA: Vector3, posB: Vector3, sizeB?: Vector3, rotationA?: Vector3, rotationB?: Vector3): boolean;
     /**
      * Returns the vector to move sphere A by so it no longer overlaps sphere B, or undefined
      * @param {Vector3} posA
@@ -7392,15 +7753,16 @@ declare module "littlejsengine" {
      */
     export function collideSphereSphere(posA: Vector3, radiusA: number, posB: Vector3, radiusB: number): Vector3 | undefined;
     /**
-     * Returns the vector to move a sphere out of an axis aligned box, or undefined
+     * Returns the vector to move a sphere out of a box, or undefined
      * @param {Vector3} pos - Sphere center
      * @param {number} radius
      * @param {Vector3} boxPos
      * @param {Vector3} boxSize - Full size of the box
+     * @param {Vector3} [boxRotation] - How the box is turned, upright when left out
      * @return {Vector3|undefined}
      * @memberof Math3D
      */
-    export function collideSphereBox(pos: Vector3, radius: number, boxPos: Vector3, boxSize: Vector3): Vector3 | undefined;
+    export function collideSphereBox(pos: Vector3, radius: number, boxPos: Vector3, boxSize: Vector3, boxRotation?: Vector3): Vector3 | undefined;
     /**
      * Returns the vector to move a sphere back inside an axis aligned box, or undefined when it is all inside
      * - The inside out twin of collideSphereBox, for keeping things in a room or an arena
@@ -7427,14 +7789,17 @@ declare module "littlejsengine" {
     /**
      * Returns the vector to move box A by so it no longer overlaps box B, the shortest way out, or undefined
      * - The 3D twin of collideBoxBox
+     * - Turned boxes are tested by the separating axis test, the push is along the direction they overlap least on
      * @param {Vector3} posA
      * @param {Vector3} sizeA - Full size of box A
      * @param {Vector3} posB
      * @param {Vector3} sizeB - Full size of box B
+     * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+     * @param {Vector3} [rotationB] - How box B is turned
      * @return {Vector3|undefined}
      * @memberof Math3D
      */
-    export function collideBoxBox3D(posA: Vector3, sizeA: Vector3, posB: Vector3, sizeB: Vector3): Vector3 | undefined;
+    export function collideBoxBox3D(posA: Vector3, sizeA: Vector3, posB: Vector3, sizeB: Vector3, rotationA?: Vector3, rotationB?: Vector3): Vector3 | undefined;
     /**
      * Returns the distance along the ray to the first intersection with a sphere, or undefined
      * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
@@ -7457,16 +7822,17 @@ declare module "littlejsengine" {
      */
     export function raycastPlane(ray: Ray3D, planePos: Vector3, planeNormal: Vector3): number | undefined;
     /**
-     * Returns the distance along the ray to the first intersection with an axis aligned box, or undefined
+     * Returns the distance along the ray to the first intersection with a box, or undefined
      * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
      * - A ray starting inside the box is already there, so it gets back 0
      * @param {Ray3D} ray
      * @param {Vector3} pos - Center of the box
      * @param {Vector3} size - Full size of the box
+     * @param {Vector3} [rotation] - How the box is turned, upright when left out
      * @return {number|undefined}
      * @memberof Math3D
      */
-    export function raycastBox(ray: Ray3D, pos: Vector3, size: Vector3): number | undefined;
+    export function raycastBox(ray: Ray3D, pos: Vector3, size: Vector3, rotation?: Vector3): number | undefined;
     /**
      * LittleJS 3D Rendering Plugin
      * - Adds a 3D scene that draws into the same WebGL canvas as the 2D game
@@ -7499,6 +7865,10 @@ declare module "littlejsengine" {
      * new EngineObject3D(vec3(), buildBox());
      */
     export class Render3DPlugin {
+        /** @type {Render3DDrawState} */
+        drawState: Render3DDrawState;
+        /** @property {number} - Goes up when a draw state field changes, so a batch sees at a glance that none did */
+        stateVersion: number;
         /** @property {Camera3D} - The camera */
         camera: Camera3D;
         /** @property {Vector3} - Direction toward the sun, where its light comes from, like a directional Light3D;
@@ -7531,10 +7901,22 @@ declare module "littlejsengine" {
         /** @property {boolean} - Default for every builder's smooth argument: true for smooth vertex normals, false for
          *  flat faces */
         smoothShading: boolean;
+        /** @property {boolean} - Draw the camera's depth into a texture each frame for post processing:
+         *  PostProcessPlugin hands it to its shader as iChannel2, read with sceneDepth(uv); off by default and free
+         *  when off, on it draws the solid objects of the default layer once more, depth only */
+        depthTexture: boolean;
         /** @property {boolean} - Cast real shadows from the sun, off by default and free when off */
         shadows: boolean;
+        /** @property {number} - How far a sound played with playSound is heard when it was made with no range of
+         *  its own, in world units; further than the 2D soundDefaultRange, a 3D world is bigger */
+        soundDefaultRange: number;
         /** @property {number} - Size of the shadow map in pixels, bigger is sharper and slower */
         shadowMapSize: number;
+        /** @property {Light3D|undefined} - A spotlight, a Light3D with a coneAngle, to cast the shadows in place
+         *  of the sun, a flashlight in the dark: the shadow map looks down its cone, as far as its radius, and the
+         *  sun still lights the scene but casts none; undefined for the sun, as is a light that is off or has no cone
+         *  @type {Light3D|undefined} */
+        shadowLight: Light3D | undefined;
         /** @property {number} - World size the shadow map covers around shadowCenter, smaller is sharper; it is a
          *  square facing the light, so it turns as the light does, and about 1.5 times an area's width covers it from
          *  any angle */
@@ -7546,31 +7928,6 @@ declare module "littlejsengine" {
         shadowBias: number;
         /** @property {number} - How much to blur the shadow edges */
         shadowSoftness: number;
-        /** @property {boolean} - Apply lighting, when false draws plain vertex color times texture and casts no shadow;
-         *  off for billboards, lines, ribbons and soft discs, an object sets emissive instead */
-        lighting: boolean;
-        /** @property {number} - How much a surface lights itself, set per object by its emissive */
-        emissive: number;
-        /** @property {boolean} - Additive blending instead of alpha, in the transparent stage */
-        additive: boolean;
-        /** @property {boolean} - Test against the depth buffer, reset to true before each object and callback; a draw
-         *  with it off goes over what was drawn before it and under what is drawn after, by render order, which
-         *  ends the batch of meshes before it, so one per object costs a draw per object */
-        depthTest: boolean;
-        /** @property {boolean} - Write to the depth buffer, owned by the stages: on for opaque, off for transparent */
-        depthWrite: boolean;
-        cullBackFaces: boolean;
-        mirrored: boolean;
-        /** @property {number} - Strength of the highlight where the sun and the Light3D objects reflect, 0 is none and
-         *  1 adds a light's full color at its brightest; its size is fixed */
-        specular: number;
-        /** @property {Shader|undefined} - Custom Shader for the next draws, set from each object's shader; undefined
-         *  draws with the plugin's own
-         *  @type {Shader|undefined} */
-        shader: Shader | undefined;
-        /** @property {boolean} - Darken by the shadow map when shadows are on, turn it off for things that should stay
-         *  lit inside a shadow */
-        receiveShadow: boolean;
         /** @property {Function|undefined} - Draw solid world here, it runs again for shadows so only draw in it
          *  @type {Function|undefined} */
         onRenderOpaque: Function | undefined;
@@ -7592,9 +7949,6 @@ declare module "littlejsengine" {
         /** @property {boolean} - Sample textures through mipmaps so they do not shimmer in the distance, false uses
          *  each texture's own filtering like 2D */
         mipmaps: boolean;
-        /** @property {boolean} - Draw state: keep texture pixels hard edged, no mipmaps and no blending between them,
-         *  set per object by pixelated */
-        pixelated: boolean;
         /** @property {number} - Anisotropic filtering for textures seen at an angle, 1 to 16, 1 is off; needs mipmaps */
         anisotropy: number;
         /** @property {Mesh} - A box of size 1 that drawBox uses, for any object that is a box; set the object's scale3D
@@ -7629,7 +7983,6 @@ declare module "littlejsengine" {
         /** @property {Vector3} - Camera forward axis this frame */
         cameraForward: Vector3;
         cameraBack: Vector3;
-        blend: boolean;
         /** @type {Array<Array<number>>} */
         frustumPlanes: Array<Array<number>>;
         /** @type {Array<Array<number>>} */
@@ -7654,6 +8007,13 @@ declare module "littlejsengine" {
         /** @type {WebGLFramebuffer|undefined} */
         shadowFramebuffer: WebGLFramebuffer | undefined;
         shadowTextureSize: number;
+        /** @type {WebGLTexture|undefined} */
+        cameraDepthTexture: WebGLTexture | undefined;
+        /** @type {WebGLFramebuffer|undefined} */
+        cameraDepthFramebuffer: WebGLFramebuffer | undefined;
+        cameraDepthWidth: number;
+        cameraDepthHeight: number;
+        depthPass: boolean;
         contextGeneration: number;
         uniforms: Map<any, any>;
         /** @type {Object<string, Array<number>>} */
@@ -7664,6 +8024,9 @@ declare module "littlejsengine" {
         passIsDefault: boolean;
         lightPositions: Float32Array;
         lightColors: Float32Array;
+        lightCones: Float32Array;
+        shadowLightIndex: number;
+        shadowDepthBias: number;
         /** @type {WebGLBuffer|undefined} */
         streamBuffer: WebGLBuffer | undefined;
         /** @type {Array<WebGLBuffer>} */
@@ -7688,6 +8051,89 @@ declare module "littlejsengine" {
             state: any;
             draw: () => void;
         }> | undefined;
+        set lighting(arg: boolean);
+        /** Apply lighting, when false draws plain vertex color times texture and casts no shadow;
+         *  off for billboards, lines, ribbons and soft discs, an object sets emissive instead
+         *  @return {boolean} */
+        get lighting(): boolean;
+        set emissive(arg: number);
+        /** How much a surface lights itself, set per object by its emissive
+         *  @return {number} */
+        get emissive(): number;
+        set additive(arg: boolean);
+        /** Additive blending instead of alpha, in the transparent stage
+         *  @return {boolean} */
+        get additive(): boolean;
+        set depthTest(arg: boolean);
+        /** Test against the depth buffer, reset to true before each object and callback; a draw
+         *  with it off goes over what was drawn before it and under what is drawn after, by render order, which
+         *  ends the batch of meshes before it, so one per object costs a draw per object
+         *  @return {boolean} */
+        get depthTest(): boolean;
+        set depthWrite(arg: boolean);
+        /** Write to the depth buffer, owned by the stages: on for opaque, off for transparent
+         *  @return {boolean} */
+        get depthWrite(): boolean;
+        set cullBackFaces(arg: boolean);
+        /** Skip back faces, set by drawMesh from each mesh: off for strips so they show from
+         *  both sides
+         *  @return {boolean} */
+        get cullBackFaces(): boolean;
+        set mirrored(arg: boolean);
+        /** The transform mirrors the draw, so the other winding is the front, set by drawMesh
+         *  from each transform
+         *  @return {boolean} */
+        get mirrored(): boolean;
+        set specular(arg: number);
+        /** Strength of the highlight where the sun and the Light3D objects reflect, 0 is none and
+         *  1 adds a light's full color at its brightest; shininess sets its size
+         *  @return {number} */
+        get specular(): number;
+        set shininess(arg: number);
+        /** The highlight's exponent, how small and sharp it is: 4 is broad like rubber, 100 sharp
+         *  like polished metal; set from each object's shininess
+         *  @return {number} */
+        get shininess(): number;
+        set normalMap(arg: TextureInfo);
+        /** Normal map for the next draws, set from each object's normalMap
+         *  @return {TextureInfo|undefined} */
+        get normalMap(): TextureInfo;
+        set normalScale(arg: number);
+        /** How strongly the normal map bends the surface, set from each object's normalScale
+         *  @return {number} */
+        get normalScale(): number;
+        set reflectivity(arg: number);
+        /** How much the surface reflects the sky, 0 to 1, set from each object's reflectivity
+         *  @return {number} */
+        get reflectivity(): number;
+        set emissiveMap(arg: TextureInfo);
+        /** Emissive map for the next draws, set from each object's emissiveMap
+         *  @return {TextureInfo|undefined} */
+        get emissiveMap(): TextureInfo;
+        set emissiveMapColor(arg: Color);
+        /** Multiplies the emissive map, set from each object's emissiveMapColor; compared by its rgb, so a Color
+         *  changed in place is seen when it is set again, and undefined is white
+         *  @return {Color} */
+        get emissiveMapColor(): Color;
+        set shader(arg: Shader);
+        /** Custom Shader for the next draws, set from each object's shader; undefined draws
+         *  with the plugin's own
+         *  @return {Shader|undefined} */
+        get shader(): Shader;
+        set receiveShadow(arg: boolean);
+        /** Darken by the shadow map when shadows are on, turn it off for things that should
+         *  stay lit inside a shadow
+         *  @return {boolean} */
+        get receiveShadow(): boolean;
+        set pixelated(arg: boolean);
+        /** Keep texture pixels hard edged, no mipmaps and no blending between them, set per
+         *  object by pixelated
+         *  @return {boolean} */
+        get pixelated(): boolean;
+        set blend(arg: boolean);
+        /** Blending on, set by the stages
+         *  @return {boolean} */
+        get blend(): boolean;
         /** Rebuild the view and projection matrices from the camera, called automatically each frame
          *  @param {number} [aspect] - Width over height, defaults to the main canvas */
         updateMatrices(aspect?: number): void;
@@ -7728,7 +8174,8 @@ declare module "littlejsengine" {
             distance: number;
         } | undefined;
         /** Play a sound at a 3D position, quieter with distance from the camera and panned by its side, like Sound.play
-         *  with a 2D position
+         *  with a 2D position; a sound made with no range of its own is heard to soundDefaultRange, 100, and one given
+         *  a range keeps it
          *  @param {Sound} sound
          *  @param {Vector3} pos3D
          *  @param {number} [volume]
@@ -7953,17 +8400,17 @@ declare module "littlejsengine" {
      * EngineObject3D - An EngineObject with a 3D transform and a mesh
      * - Set pos3D, rotation3D and scale3D instead of the 2D pos, size and angle
      * - Gets update, children, timers, destroy and renderOrder from EngineObject
-     * - velocity3D is added to pos3D each frame, along with render3D.gravity and damping once it has a mass
+     * - velocity3D is added to pos3D each frame, slowed by damping, and render3D.gravity pulls it once it has a mass
      * - Objects face -Z, the same way the camera does, so lookAt turns them to face a point
      * - The 2D pos and velocity are still there but nothing draws them
-     * - These inherited fields are 2D only and do nothing here: angle, angleVelocity, angleDamping,
-     *   additiveColor, drawSize, mirror, clampSpeed, friction and groundObject
+     * - These inherited fields are 2D only and do nothing here: angle, angleVelocity, additiveColor, drawSize and mirror;
+     *   damping, angleDamping, clampSpeed, friction and groundObject work as in 2D, on velocity3D and angleVelocity3D
      * - The inherited shader works here as in 2D, and with emissive at 1 its snippet does its own lighting
      * - Set sync2D for a 2D game with 3D looks, pos and angle then drive pos3D and rotation3D,
      *   which is the one way those 2D fields reach a 3D object
      * - setCollision takes the same flags as in 2D, but the solid collision happens in 3D against size3D
-     * - The solid box is axis aligned in the world, rotation3D is ignored like angle is in 2D, so give a turned wall a
-     *   size3D along the world axes
+     * - The solid box turns with rotation3D, so a turned wall or a ramp collides as it looks; resting on one no steeper
+     *   than groundAngle stands there
      * - Its tile and raycast halves are 2D only so they default off here, and a child sits solid collision out
      * - A sync2D object collides in 2D instead, which needs the 2D size set as well as size3D
      * - setMesh swaps the mesh and frees the old one, for text and terrain that get built again
@@ -7997,7 +8444,7 @@ declare module "littlejsengine" {
         /** @property {Vector3} - Added to pos3D each frame by the engine before update, like the 2D velocity, no super
          *  call needed; damping and render3D.gravity act on it once the object has a mass */
         velocity3D: Vector3;
-        /** @property {Vector3} - Added to rotation3D each frame by the engine before update, angleDamping is 2D only */
+        /** @property {Vector3} - Added to rotation3D each frame by the engine before update, slowed by angleDamping */
         angleVelocity3D: Vector3;
         /** @property {Mesh|undefined} - Mesh to draw
          *  @type {Mesh|undefined} */
@@ -8019,11 +8466,33 @@ declare module "littlejsengine" {
         /** @property {boolean} - Additive blending, in the transparent stage */
         additive: boolean;
         /** @property {number} - Strength of the highlight where the sun and the Light3D objects reflect, 0 is none and
-         *  1 adds a light's full color at its brightest; its size is fixed */
+         *  1 adds a light's full color at its brightest; shininess sets its size */
         specular: number;
+        /** @property {number} - The highlight's exponent, how small and sharp it is: 4 is broad like rubber, 16 the
+         *  default, 100 sharp like polished metal; shows only with specular above 0 */
+        shininess: number;
+        /** @property {TextureInfo|undefined} - A normal map that bends the surface at each texel so it catches the
+         *  light like bumps and grooves, green pointing up the image as OpenGL and glTF have it; read at the color
+         *  texture's coordinates, see normalMapFromHeight to make one in code
+         *  @type {TextureInfo|undefined} */
+        normalMap: TextureInfo | undefined;
+        /** @property {number} - How strongly the normal map bends the surface, 0 turns it off, as glTF's scale */
+        normalScale: number;
+        /** @property {number} - How much it reflects the sky, 0 none and 1 a mirror of it; the edges seen at a
+         *  glancing angle reflect more either way, as water and glass do */
+        reflectivity: number;
+        /** @property {TextureInfo|undefined} - A texture of where it glows, added on top of the lit surface so it
+         *  shows in the dark, like lit windows; read at the color texture's coordinates
+         *  @type {TextureInfo|undefined} */
+        emissiveMap: TextureInfo | undefined;
+        /** @property {Color} - Multiplies the emissive map, as glTF's emissiveFactor */
+        emissiveMapColor: Color;
         /** @property {boolean} - Collide as the sphere that fits size3D instead of as the size3D box, so it rolls
          *  around corners */
         collideAsSphere3D: boolean;
+        /** @property {number} - The steepest slope it stands on, in radians from level, PI/4 by default: resting on
+         *  a solid within this of flat sets groundObject and holds it still, steeper it slides down */
+        groundAngle: number;
         /** @property {boolean} - Darkened by the shadow map when render3D.shadows is on */
         receiveShadow: boolean;
         /** @property {boolean|undefined} - Draw this object over the 2D scene, undefined uses render3D.renderAfter2D
@@ -8297,20 +8766,24 @@ declare module "littlejsengine" {
      * InstancedMesh3D - Many copies of one mesh drawn as one call, with their transforms kept on the GPU
      * - For big sets that mostly stay put: an instance costs nothing per frame until it changes, so a hundred thousand
      *   trees cost what one tree does; objects and drawMesh batch by themselves too, but rebuild their batch every frame
-     * - setMatrixAt and setColorAt change one instance, and only the changed range uploads before the next draw
+     * - setTransformAt, setMatrixAt and setColorAt change one instance, and only the changed range uploads before the
+     *   next draw; the matrices and the colors are kept apart, so moving instances uploads 64 bytes each
+     * - For many instances moving every frame, setTransforms places a run of them from arrays of positions, rotations
+     *   and scales in one loop, the fastest way; or write matrixData directly and call markDirtyRange
      * - The instances are in world space; the object's own pos3D, rotation3D and scale3D do not move them
-     * - The whole set is culled by one bounding sphere around the origin, and casts and receives shadows like any object
+     * - The whole set is culled by one bounding sphere around the origin, worked out when culling reads it, or set by hand
+     *   with radius; it casts and receives shadows like any object
      * - The object's flags cover the whole set, one emissive, one tileInfo, one shader; only the colors are per instance
      * - A mirrored instance, one with a negative scale, shows its inside unless the mesh is doubleSided
      * - A transparent set draws in one go in the transparent stage, its instances are not sorted against each other;
      *   the set sorts against other transparent draws by the object's position, so put pos3D at its middle
-     * - pick, the raycast and the collect helpers do not see the instances, test them yourself from instanceData
+     * - pick, the raycast and the collect helpers do not see the instances, test them yourself from matrixData
      * @extends EngineObject3D
      * @memberof Render3D
      * @example
      * const forest = new InstancedMesh3D(treeMesh, 1000);
      * for (let i = 0; i < 1000; ++i)
-     *     forest.setMatrixAt(i, buildMatrix(randomGroundPos(), vec3(0, rand(2*PI), 0)));
+     *     forest.setTransformAt(i, randomGroundPos(), vec3(0, rand(2*PI), 0));
      */
     export class InstancedMesh3D extends EngineObject3D {
         /** Create a set of instances of a mesh, each at the origin in the object's color until it is set
@@ -8323,21 +8796,53 @@ declare module "littlejsengine" {
         count: number;
         /** @property {number} - How many instances it was made with */
         maxCount: number;
-        /** @property {Float32Array} - The per instance values the shader reads, 24 floats each: the matrix, the color
-         *  and the uv rect; edit it directly and call markDirty for the instances changed */
-        instanceData: Float32Array;
-        /** @property {number} - Radius of the sphere around the origin that holds every instance set so far, for
-         *  culling; from the farthest instance and the largest scale, and the mesh's size when it draws */
-        radius: number;
-        reach: number;
-        maxScale: number;
-        /** @property {number} - First instance to upload before the next draw */
+        /** @property {Float32Array} - Each instance's matrix, 16 floats, what moving them uploads; edit it directly and
+         *  call markDirty for the instances changed */
+        matrixData: Float32Array;
+        /** @property {Float32Array} - Each instance's color and uv rect, 8 floats, uploaded only when they change; edit
+         *  it directly and call markColorDirty for the instances changed */
+        colorData: Float32Array;
+        /** @property {number} - First instance whose matrix uploads before the next draw */
         dirtyStart: number;
-        /** @property {number} - One past the last instance to upload, so nothing uploads when it is not past dirtyStart */
+        /** @property {number} - One past the last instance whose matrix uploads, nothing when it is not past dirtyStart */
         dirtyEnd: number;
+        /** @property {number} - First instance whose color uploads before the next draw */
+        colorDirtyStart: number;
+        /** @property {number} - One past the last instance whose color uploads */
+        colorDirtyEnd: number;
+        reachSquared: number;
+        scaleSquared: number;
+        boundsStart: number;
+        boundsEnd: number;
+        /** @type {number|undefined} */
+        fixedRadius: number | undefined;
         buffer: WebGLBuffer;
+        /** @type {WebGLBuffer|undefined} */
+        colorBuffer: WebGLBuffer | undefined;
         bufferGeneration: number;
         uvTileInfo: TileInfo | TextureInfo;
+        /** Place an instance by its position, rotation and scale, what buildMatrix takes, written straight in with no
+         *  matrix made; in world space
+         *  @param {number} i
+         *  @param {Vector3} [pos]
+         *  @param {Vector3} [rotation] - Euler angles in radians
+         *  @param {Vector3} [scale] */
+        setTransformAt(i: number, pos?: Vector3, rotation?: Vector3, scale?: Vector3): void;
+        /** Place a run of instances from arrays indexed by instance, plain or typed, as a game keeps them: each is placed
+         *  as setTransformAt places it, all in one loop with nothing made, the fastest way to move many every frame;
+         *  in world space
+         *  @param {number} start - First instance
+         *  @param {number} count - How many
+         *  @param {ArrayLike<number>} x - Positions
+         *  @param {ArrayLike<number>} y
+         *  @param {ArrayLike<number>} z
+         *  @param {ArrayLike<number>} [rx] - Euler angles in radians, all three or none for upright
+         *  @param {ArrayLike<number>} [ry]
+         *  @param {ArrayLike<number>} [rz]
+         *  @param {ArrayLike<number>} [sx] - Scales, all three or none for 1
+         *  @param {ArrayLike<number>} [sy]
+         *  @param {ArrayLike<number>} [sz] */
+        setTransforms(start: number, count: number, x: ArrayLike<number>, y: ArrayLike<number>, z: ArrayLike<number>, rx?: ArrayLike<number>, ry?: ArrayLike<number>, rz?: ArrayLike<number>, sx?: ArrayLike<number>, sy?: ArrayLike<number>, sz?: ArrayLike<number>): void;
         /** Place an instance, in world space
          *  @param {number} i
          *  @param {Matrix4} matrix */
@@ -8350,10 +8855,26 @@ declare module "littlejsengine" {
          *  @param {number} i
          *  @param {Color} color */
         setColorAt(i: number, color: Color): void;
-        /** Note that an instance changed, so it uploads before the next draw and the bounds hold it; setMatrixAt and
-         *  setColorAt call this, and so must an edit made straight to instanceData
+        /** Note that an instance's matrix changed, so it uploads before the next draw and the bounds take it in when
+         *  they are read; setTransformAt and setMatrixAt call this, and so must an edit made straight to matrixData
          *  @param {number} i */
         markDirty(i: number): void;
+        /** Note that a run of instances' matrices changed, for code that writes matrixData directly, the lowest level
+         *  way to move many: they upload before the next draw and the bounds take them in when they are read
+         *  @param {number} start - First instance
+         *  @param {number} end - One past the last */
+        markDirtyRange(start: number, end: number): void;
+        /** Note that an instance's color changed, so it uploads before the next draw; setColorAt calls this, and so must
+         *  an edit made straight to colorData
+         *  @param {number} i */
+        markColorDirty(i: number): void;
+        set radius(arg: number);
+        /** Radius of the sphere around the origin that holds every instance set so far, for culling: the farthest
+         *  instance, and the mesh's size at the largest scale; it only grows, and takes in the instances set since it
+         *  was last read, so with frustum culling off it is never worked out. Set it to fix the sphere, which a big set
+         *  that is culled can use to skip that work, and set it to undefined to go back to the bounds
+         *  @return {number} */
+        get radius(): number;
     }
     /**
      * Spin a flat outline around the Y axis to make a round shape, like a vase or a wheel
@@ -8499,6 +9020,15 @@ declare module "littlejsengine" {
      * @memberof Render3D
      */
     export function buildSky(topColor?: Color, horizonColor?: Color, bottomColor?: Color, sides?: number, rings?: number): Mesh;
+    /** Make a normal map from a height at each pixel, for bumps and grooves with no image file: the slope at each pixel
+     *  from its neighbors' heights, taken around the edges so the map tiles; set it as an object's normalMap
+     *  @param {Vector2} size - In pixels
+     *  @param {function(number, number): number} heightFunction - The height 0 to 1 at a pixel, x across and y down
+     *  @param {number} [strength] - How steep the slopes are: a height change of 1 over one pixel leans the normal
+     *  by strength
+     *  @return {TextureInfo} - Wraps; headless it has no image
+     *  @memberof Render3D */
+    export function normalMapFromHeight(size: Vector2, heightFunction: (arg0: number, arg1: number) => number, strength?: number): TextureInfo;
     /**
      * Turn a sprite into a 3D block model by giving its pixels thickness
      * - A pixel counts as solid when it is more than half opaque
@@ -8607,6 +9137,16 @@ declare module "littlejsengine" {
          *  @return {number|undefined}
          *  @ignore */
         levelRaycast3D(ray: Ray3D): number | undefined;
+        /** Where a short move goes under the surface, for a particle's move in one frame: the part of the move made
+         *  before it, 0 to 1, and the surface normal there; undefined when it stays above, starts under, or is off the map
+         *  @param {Vector3} from
+         *  @param {Vector3} to
+         *  @return {{distance: number, normal: Vector3}|undefined}
+         *  @ignore */
+        levelSegment3D(from: Vector3, to: Vector3): {
+            distance: number;
+            normal: Vector3;
+        };
         /** Keep an object above the ground, called by the engine for each object with collideLevel
          *  @param {EngineObject3D} o
          *  @param {Vector3} oldPos - Where it was before it moved
@@ -8752,6 +9292,16 @@ declare module "littlejsengine" {
          *  @return {number|undefined}
          *  @ignore */
         levelRaycast3D(ray: Ray3D): number | undefined;
+        /** Where a short move goes into a block, for a particle's move in one frame: the part of the move made before it,
+         *  0 to 1, and the normal of the face it comes in through; undefined when it hits none, or starts inside one
+         *  @param {Vector3} from
+         *  @param {Vector3} to
+         *  @return {{distance: number, normal: Vector3}|undefined}
+         *  @ignore */
+        levelSegment3D(from: Vector3, to: Vector3): {
+            distance: number;
+            normal: Vector3;
+        } | undefined;
         /** Draw the chunks, each at its center, with the whole texture so each face shows its own tile
          *  @param {boolean} transparent
          *  @ignore */
@@ -8760,7 +9310,10 @@ declare module "littlejsengine" {
     /**
      * Light3D - A light that is an EngineObject3D, so it can move, follow a parent or be destroyed like anything else
      * - A point light: it lights what is near it and fades out by its radius, DirectionalLight3D shines from far away
-     * - Only the sun, render3D.sunDirection, casts shadows; these light and make highlights without one
+     * - A coneAngle makes it a spotlight: it shines along its own forward, turned by rotation3D or by what it is
+     *   attached to, inside the cone, fading over the part of it coneSoftness says
+     * - The sun, render3D.sunDirection, casts the shadows; a spotlight can cast them in its place, see
+     *   render3D.shadowLight; the other lights light and make highlights without one
      * - Only the 8 lights nearest the camera are used each frame
      * - radius is where the light fades out, and it fades fast, so a small radius wants a higher intensity
      * - intensity multiplies the color, above 1 for a light brighter than white
@@ -8786,6 +9339,18 @@ declare module "littlejsengine" {
         /** @property {boolean} - Shine from far away, from its position toward the origin, instead of out from its
          *  position with a falloff; DirectionalLight3D sets it */
         directional: boolean;
+        /** @property {number} - Makes it a spotlight: the angle in radians from its forward out to the edge of its
+         *  cone, so the beam is twice this across; 0 for a light that shines every way */
+        coneAngle: number;
+        /** @property {number} - How much of the cone is its fading edge: 0 a hard edge, .2 by default, the outer
+         *  fifth, 1 fading all the way from the middle of the beam */
+        coneSoftness: number;
+        /** @property {number} - Size of a soft hazy glow drawn over the light, like a lamp at night, 0 for none; it
+         *  is added onto what is behind it, and what is in front of the light hides it */
+        glow: number;
+        /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
+         *  bright core */
+        glowFalloff: number;
     }
     /**
      * DirectionalLight3D - A Light3D that shines from far away with no falloff, like sunlight
@@ -8881,13 +9446,41 @@ declare module "littlejsengine" {
         /** @property {boolean} - Capture the mouse on a click, so looking needs no button held */
         lockPointer: boolean;
         /** @property {number} - Speed of a jump in world units a frame, 0 for none; Space or gamepad button 0 jumps
-         *  while it stands on something, a height map or voxel map it collides with, see collideLevel */
+         *  while it stands on something, a height map, a voxel map or a solid, see groundObject */
         jumpSpeed: number;
         /** @property {number} - How far above its position the eye is, in its own space, so with a size3D the eye can
          *  sit toward the top of the body instead of its middle; keep it under half the body's height, or the eye is
          *  outside the body and sees through a ceiling it stands under */
         eyeHeight: number;
     }
+    /**
+     * A particle as a ParticleEmitter3D's callbacks see it: one object the emitter reuses, set from the particle for each
+     * call and written back after it, so copy what you keep
+     * @typedef {Object} Particle3D
+     * @property {ParticleEmitter3D} emitter - The emitter it is in
+     * @property {Vector3} pos - Where it is, change it to move it
+     * @property {Vector3} velocity - How far it moves each frame
+     * @property {number} age - Seconds it has lived
+     * @property {number} lifeTime - Seconds it lives
+     * @property {number} scale - How much the emitter grows its effect, from its scale3D and its parents', as the 2D
+     *   particle's scale
+     * @property {boolean} destroyed - Set by destroy
+     * @property {function(): void} destroy - End it this update, the destroy callback gets it
+     * @memberof Render3D
+     */
+    /**
+     * @callback Particle3DCallback - A function a ParticleEmitter3D calls with one of its particles
+     * @param {Particle3D} particle
+     * @memberof Render3D
+     */
+    /**
+     * @callback Particle3DCollideCallback - Decides whether a particle stops where it hits the level, a filter as in 2D
+     * @param {Particle3D} particle
+     * @param {EngineObject3D} level - The HeightMap or VoxelMap it hit
+     * @param {Vector3} pos - Where it hit
+     * @return {boolean|void} - true to stop it there; a callback that returns nothing lets it pass through
+     * @memberof Render3D
+     */
     /**
      * ParticleEmitter3D - Spawns camera facing particles, the 3D twin of ParticleEmitter
      * - Each particle is a flat square facing the camera, with a soft round dot when no tile is given
@@ -8897,9 +9490,14 @@ declare module "littlejsengine" {
      * - emitConeAngle spreads them, PI sprays in every direction
      * - Speeds are per frame and sizes are world units, the same as the 2D emitter
      * - scale3D, its own or a parent's, grows the whole effect: the spawn area, the sizes, the speed and the fall
-     * - gravity here is its own number added to velocity y each frame: it is neither the engine's 2D
-     *   gravity nor render3D.gravity, so an effect keeps its own fall wherever it is used
+     * - gravity here is its own number added to velocity y each frame, so an effect keeps its own fall wherever it is
+     *   used, the same as the 2D emitter's gravity; gravityScale adds a share of render3D.gravity on top, as the 2D
+     *   emitter's gravityScale adds the engine's gravity
      * - An emitter with an emitTime destroys itself once its last particle is gone, like the 2D emitter
+     * - Callbacks as the 2D emitter's: particleCreateCallback, particleUpdateCallback, particleCollideCallback and
+     *   particleDestroyCallback, each given a Particle3D, one object the emitter reuses for every particle and call
+     * - collideLevel, off by default, has particles hit the height maps and voxel maps, bouncing by restitution and
+     *   sliding by friction
      * @extends EngineObject3D
      * @memberof Render3D
      * @example
@@ -8923,14 +9521,17 @@ declare module "littlejsengine" {
          *  @param {number} [sizeEnd] - Particle size at end of life
          *  @param {number} [speed] - Spawn speed in world units per frame
          *  @param {number} [damping] - Per frame velocity multiplier, 1 is none
-         *  @param {number} [gravity] - Per frame change to velocity y, negative pulls down; its own number,
-         *    not render3D.gravity, so the 2D emitter's gravityScale has no equivalent here
+         *  @param {number} [gravity] - Per frame change to velocity y, negative pulls down; its own number, and
+         *    gravityScale adds a share of render3D.gravity on top
          *  @param {number} [fadeRate] - Fraction of life spent fading, half in and half out
          *  @param {number} [randomness] - Extra randomness applied to speed, size and life
          *  @param {boolean} [additive] - Additive blending */
         constructor(pos3D?: Vector3, emitSize?: number | Vector3, emitTime?: number, emitRate?: number, emitConeAngle?: number, tileInfo?: TileInfo | TextureInfo, colorStartA?: Color, colorStartB?: Color, colorEndA?: Color, colorEndB?: Color, particleTime?: number, sizeStart?: number, sizeEnd?: number, speed?: number, damping?: number, gravity?: number, fadeRate?: number, randomness?: number, additive?: boolean);
         /** @property {number|Vector3} - Spawn area, a number for a sphere diameter or a vec3 for a box */
         emitSize: number | Vector3;
+        /** @property {boolean} - Flatten the spawn area across the way it emits, its own up: a sphere becomes a disc
+         *  and a box a flat rectangle, for rain from a sheet of sky or flames from a patch of ground */
+        emitFlat: boolean;
         /** @property {number} - How long to keep emitting, 0 is forever */
         emitTime: number;
         /** @property {number} - Particles per second, 0 does not emit */
@@ -8959,7 +9560,8 @@ declare module "littlejsengine" {
         fadeRate: number;
         /** @property {number} - Extra randomness applied to speed, size and life */
         randomness: number;
-        /** @property {number} - Seconds of each particle's path to draw as a ribbon behind it, 0 draws billboards */
+        /** @property {number} - Seconds of each particle's path to draw as a ribbon behind it, 0 draws billboards;
+         *  with engineVariableStep it keeps trailTime * frameRate updates of path */
         trailTime: number;
         /** @property {number} - Radians per frame each particle turns in the camera plane, either way; 0 is no spin */
         angleSpeed: number;
@@ -8973,12 +9575,30 @@ declare module "littlejsengine" {
         trailData: Float32Array | undefined;
         /** @property {number} - Trail points kept per particle, from trailTime */
         trailMax: number;
+        /** @property {Particle3DCallback|undefined} - Called with each particle as it is made
+         *  @type {Particle3DCallback|undefined} */
+        particleCreateCallback: Particle3DCallback | undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle each update, after it moves
+         *  @type {Particle3DCallback|undefined} */
+        particleUpdateCallback: Particle3DCallback | undefined;
+        /** @property {Particle3DCollideCallback|undefined} - Decides if a particle stops where it hits the level,
+         *  with collideLevel on; a callback that returns nothing lets it through
+         *  @type {Particle3DCollideCallback|undefined} */
+        particleCollideCallback: Particle3DCollideCallback | undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle as it goes, its life over or destroyed
+         *  @type {Particle3DCallback|undefined} */
+        particleDestroyCallback: Particle3DCallback | undefined;
+        /** @property {Particle3D} - The particle the callbacks get, one object for every particle and call
+         *  @type {Particle3D} */
+        particleView: Particle3D;
         /** @property {Vector3|undefined} - Where the emitter was at its last update, for when its parent is destroyed
          *  @type {Vector3|undefined} */
         worldPos3D: Vector3 | undefined;
         emitTimeBuffer: number;
         /** Spawn one particle now */
         emitParticle(): void;
+        particleCall(callback: any, k: any, level: any, pos: any): any;
+        particleCollide(k: any, x: any, y: any, z: any): void;
     }
     /**
      * Trail3D - A ribbon through where the object has been, thinning and fading with age
@@ -9023,10 +9643,95 @@ declare module "littlejsengine" {
         clear(): void;
         worldPos3D: Vector3;
     }
+    /**
+     * LensFlare3D - The sun's lens flare, the old kind: a glow at the sun and a row of discs and rings of different
+     * sizes along the line from the sun through the middle of the screen
+     * - Make one and it shows, over the 3D scene and under what the game draws after, a HUD; destroy it to take it away
+     * - It follows render3D.sunDirection, and fades out as the sun leaves the screen or goes behind something
+     * - flareSize, count, intensity and saturation set its look, seed picks another arrangement, and its color tints it,
+     *   with the sun's own color; or give it elements of your own
+     * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read
+     * - What hides the sun is found with a ray from the camera, against the level and every object that is not see
+     *   through, each as the box around its mesh, see render3D.pick; turn it off with occlusion
+     * - It needs WebGL, and it draws nothing in the shadow of renderAfter2D
+     * @extends EngineObject3D
+     * @memberof Render3D
+     * @example
+     * new LensFlare3D;                // the sun flares
+     * new LensFlare3D(1.5, 10, .7, 0); // bigger, 10 ghosts, dimmer, all one color
+     */
+    export class LensFlare3D extends EngineObject3D {
+        /** Create the sun's lens flare
+         *  @param {number} [size] - Scales every part of it, 1 by default
+         *  @param {number} [count] - How many ghosts there are along the line, besides the glow at the sun
+         *  @param {number} [intensity] - How bright it is
+         *  @param {number} [saturation] - How colorful the ghosts are, 0 for all the flare's own color, 1 a rainbow
+         *  @param {Color} [color] - Tints the whole flare, with the sun's color */
+        constructor(size?: number, count?: number, intensity?: number, saturation?: number, color?: Color);
+        /** @property {number} - Scales every part of the flare */
+        flareSize: number;
+        /** @property {number} - How many ghosts there are along the line, besides the glow at the sun */
+        count: number;
+        /** @property {number} - How bright it is */
+        intensity: number;
+        /** @property {number} - How colorful the ghosts are, 0 for all the flare's own color, 1 a rainbow */
+        saturation: number;
+        /** @property {number} - Picks the arrangement of the ghosts, another seed is another flare */
+        seed: number;
+        /** @property {Array<{at: number, size: number, color: Color, shape: string}>|undefined} - The parts of the
+         *  flare, to set your own in place of the ones made from count, seed and saturation: at is where along the
+         *  line, 0 the sun, 1 the middle of the screen, 2 as far past it; size is across, as a part of the screen's
+         *  height; shape is glow, disc or ring
+         *  @type {Array<{at: number, size: number, color: Color, shape: string}>|undefined} */
+        elements: {
+            at: number;
+            size: number;
+            color: Color;
+            shape: string;
+        }[];
+        /** @property {boolean} - Fade out when something is between the camera and the sun */
+        occlusion: boolean;
+        /** @property {number} - Seconds the flare takes to fade out or in when the sun is hidden or shows again */
+        fadeTime: number;
+        /** @property {number} - How much of the sun shows, 0 hidden or behind the camera to 1 in plain view, eased */
+        visible: number;
+        madeKey: string;
+        /** @type {Array<{at: number, size: number, color: Color, shape: string}>} */
+        made: {
+            at: number;
+            size: number;
+            color: Color;
+            shape: string;
+        }[];
+        /** The parts of the flare: the elements set by hand, or the ones made from count, seed and saturation, a glow
+         *  and a core at the sun and the ghosts, made again when one of those changes
+         *  @return {Array<{at: number, size: number, color: Color, shape: string}>} */
+        getElements(): Array<{
+            at: number;
+            size: number;
+            color: Color;
+            shape: string;
+        }>;
+        /** Where the sun is on the screen, in pixels like mousePosScreen, undefined when it is behind the camera
+         *  @return {Vector2|undefined} */
+        getSunScreenPos(): Vector2 | undefined;
+        /** The parts of the flare as they are drawn now: each one's place on the screen, its size in pixels and its
+         *  color, dimmed by how much of the sun shows; empty when there is nothing to draw
+         *  @return {Array<{pos: Vector2, size: number, color: Color, shape: string}>} */
+        getScreenElements(): Array<{
+            pos: Vector2;
+            size: number;
+            color: Color;
+            shape: string;
+        }>;
+        /** Is something between the camera and the sun: the level, or an object that is not see through
+         *  @return {boolean} */
+        isSunHidden(): boolean;
+    }
     /**
      * Collect the EngineObject3D objects whose boxes overlap a sphere or a box, the 3D twin of engineObjectsCollect
-     * - Boxes are axis aligned around the world position, rotation3D is ignored; lights, emitters and trails have no size
-     *   and are never collected
+     * - Each object is its size3D box at its world position, turned as it is turned; lights, emitters and trails have no
+     *   size and are never collected
      * @param {Vector3} pos - Center of the area
      * @param {Vector3|number} size - Diameter of a sphere if a number, 0 for a point, full size of a box if a Vector3
      * @param {Array<EngineObject>} [objects] - Defaults to every object
@@ -9154,6 +9859,8 @@ declare module "littlejsengine" {
      *   GLTFObject that createObject makes; a skinned character's walk is not read
      * - Materials give a base color and texture and whether they blend; glass made with KHR_materials_transmission blends too,
      *   and a KHR_materials_unlit material comes in emissive, its own color with no shading
+     * - A material's normal map and emissive map load too, with its normal scale and emissive factor, read at the base
+     *   color texture's uvs; roughness, metalness and occlusion maps are not loaded
      * - The base color texture reads the uv set its texCoord names, moved by KHR_texture_transform as gltfpack and
      *   Blender write it
      * - An OPAQUE material, the default, ignores its texture's alpha as the format says: a texture only such materials
@@ -9196,6 +9903,17 @@ declare module "littlejsengine" {
         /** @property {boolean} - The material is unlit (KHR_materials_unlit), its own color with no shading; the object
          *  createObject makes draws it with emissive 1 */
         unlit: boolean;
+        /** @property {TextureInfo|undefined} - The material's normal map, drawn with the base color texture's uvs
+         *  @type {TextureInfo|undefined} */
+        normalMap: TextureInfo | undefined;
+        /** @property {number} - The normal map's strength, its scale in the file */
+        normalScale: number;
+        /** @property {TextureInfo|undefined} - The material's emissive map, or a white texture when it has an
+         *  emissiveFactor and no texture, so it glows all over
+         *  @type {TextureInfo|undefined} */
+        emissiveMap: TextureInfo | undefined;
+        /** @property {Color} - The emissiveFactor, which multiplies the emissive map */
+        emissiveMapColor: Color;
     }
     /**
      * GLTFObject - A model as an object with a child per part, which plays the model's animations
@@ -9301,6 +10019,69 @@ declare module "littlejsengine" {
      *  @param {number} [size] - Length of the cross
      *  @memberof Render3D */
     export function debugPoint3D(pos: Vector3, color?: Color, time?: number, size?: number): void;
+    /** Add a type of object, so level3DLoad makes one wherever a level has an object of that type
+     *  - The name is a string because minified builds rename classes
+     *  - A class, or any function with a prototype, is made with new make(pos3D, properties); an arrow function is
+     *    called as make(pos3D, properties), for what is not an object, like a player start
+     *  - properties is the defaults with the object's own values over them, and each of the type's own is also set on
+     *    what was made; a property the type has no default for is in properties and is not set
+     *  - Give a class a constructor of its own that takes the position: one that hands every argument on to
+     *    EngineObject3D would hand it the properties as its mesh
+     *  - An EngineObject3D then gets the object's rotation, and its scale times the scale it was made with
+     *  - Adding a name again replaces it, Box, Sphere, Cylinder and Light too
+     *  @param {string} name - The type the objects have in the level
+     *  @param {Function} make - A class made at each object's position, or a function called with it
+     *  @param {Object} [defaults] - Properties of each one made, the level editor shows inputs for them
+     *  @param {TileInfo} [tileInfo] - An icon for the level editor
+     *  @memberof Level3D
+     *  @example
+     *  level3DAddType('Crate', Crate, {health: 3});
+     *  level3DAddType('PlayerStart', (pos)=> playerStart = pos); */
+    export function level3DAddType(name: string, make: Function, defaults?: any, tileInfo?: TileInfo): void;
+    /** Add a type that is a mesh and nothing more, a static prop with no class to write, for a built mesh or a model
+     *  - Each object has a color and a solid property, solid collides as the box around the mesh
+     *  @param {string} name - The type the objects have in the level
+     *  @param {Mesh} mesh - Shared by every object of the type
+     *  @param {TileInfo} [tileInfo] - Its texture
+     *  @param {Color} [color] - Its color, an object's own color property goes over it
+     *  @memberof Level3D
+     *  @example
+     *  level3DAddMesh('Tree', treeMesh, tile(4)); */
+    export function level3DAddMesh(name: string, mesh: Mesh, tileInfo?: TileInfo, color?: Color): void;
+    /** Make the objects of a level, each from the type added for its name
+     *  - The level is an object: {littlejs3D: 1, objects: [{id, type, pos: [x, y, z]}, ...]}, and {} is a new one
+     *  - rotation is pitch, yaw and roll in degrees, scale is a number for each axis, both left out when they are
+     *    the default, and properties holds what differs from the type's defaults
+     *  - A Color property is a #rrggbb or #rrggbbaa string, a Vector2 or Vector3 an array, as the default says
+     *  - An object whose type was not added is skipped, with a warning in debug builds
+     *  - What a file written by hand gets wrong uses the default: a value that is not of its default's type
+     *  - An object its type can not make is skipped with an error in debug builds, where asserts throw, and the rest
+     *    of the level is made
+     *  - A level may hold a map of blocks, in a voxels block: pos, its corner, size, its cells along x, y and z, and
+     *    blocks, runs of a count and a type along x, then y, then z; it is made a VoxelMap, the first of what is
+     *    returned, see level3DVoxelSetup for its sheet
+     *  - A level may hold a terrain, in a terrain block: pos, its center, size, its size in the world along x and z,
+     *    height, how tall a full height is, color, and heights, rows of 0 to 1 from -z to +z, each from -x to +x; it
+     *    is made a HeightMap, returned with what else was made
+     *  - A level may set the scene too, in a scene block beside its objects: sky, three colors for straight up, the
+     *    horizon and straight down, ambient, how much of them lights the scene, .5 when not given, sunDirection and
+     *    sunColor, fog, its start and end, fogColor, the horizon color when not given, and shadows; what the block
+     *    leaves out stays as the game set it, and a level with no block changes nothing
+     *  @param {Object} level - The level, the level editor edits this same object
+     *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
+     *  @memberof Level3D */
+    export function level3DLoad(level: any): Array<any>;
+    /** How a level's block map is made: the sheet its blocks show tiles of, and a function to set it up
+     *  - A level's voxels block makes a VoxelMap when the level loads, with texture 0 and the default tile size unless
+     *    a sheet is given here; a block's type shows that tile of the sheet on every face
+     *  - setup is called with each map a level makes, to give block types their own faces or make them see-through
+     *  - Call it before level3DLoad; with no arguments the defaults are back
+     *  @param {TileInfo} [tileInfo] - The sheet's first tile, as for a VoxelMap
+     *  @param {function(VoxelMap): void} [setup]
+     *  @example
+     *  level3DVoxelSetup(tile(0, 16, 1), (map)=> map.setBlockType(1, {top: 0, side: 1, bottom: 2})); // grass
+     *  @memberof Level3D */
+    export function level3DVoxelSetup(tileInfo?: TileInfo, setup?: (arg0: VoxelMap) => void): void;
     /**
      * LittleJS Three.js Plugin
      * - Renders a three.js scene on a canvas behind the LittleJS canvases
@@ -9501,6 +10282,177 @@ declare module "littlejsengine" {
      *  }
      *  @memberof TextureSheets */
     export function spritesReady(): Promise<any>;
+    /**
+     * LittleJS Particle Effects Plugin
+     * - Ready made particle effects in one line, particleEffect('fire', pos), and particleEffect3D for 3D
+     * - Every built-in effect is tuned around a one unit emitter; options.scale grows it to fit, options.hue and
+     *   options.saturation recolor it
+     * - Effects are plain data, {name, settings, behaviors}, the format the particle designer saves: load a library the
+     *   designer saved with particleEffectsLoad and play its effects by name
+     * - The built-in effects draw with a sheet of shapes the plugin draws itself, so they need no image
+     * @namespace ParticleEffects
+     */
+    /** The groups the settings are in, in order
+     *  @type {Array<string>}
+     *  @memberof ParticleEffects */
+    export const particleEffectGroups: Array<string>;
+    /** Every setting an effect has: its name, kind (number, checkbox, color or shape), default, the range the designer's
+     *  slider covers (min, max, step), the hard limits a typed value is clamped to, and whether it is set after the
+     *  emitter is made rather than passed to its constructor (extra)
+     *  @type {Array<{group:string, name:string, kind:string, value:any, min:number, max:number, step:number,
+     *  description:string, hardMin:number, hardMax:number, extra:boolean}>}
+     *  @memberof ParticleEffects */
+    export const particleEffectSettings: Array<{
+        group: string;
+        name: string;
+        kind: string;
+        value: any;
+        min: number;
+        max: number;
+        step: number;
+        description: string;
+        hardMin: number;
+        hardMax: number;
+        extra: boolean;
+    }>;
+    /** The behaviors an effect can use, each a push applied to every particle every update, with a 2D and a 3D version
+     *  @type {Array<{name:string, update:(Function|undefined), update3D:(Function|undefined), min:number, max:number,
+     *  value:number, description:string}>}
+     *  @memberof ParticleEffects */
+    export const particleEffectBehaviors: Array<{
+        name: string;
+        update: (Function | undefined);
+        update3D: (Function | undefined);
+        min: number;
+        max: number;
+        value: number;
+        description: string;
+    }>;
+    /** Names of the shapes the plugin draws, for an effect's shape setting
+     *  @type {Array<string>}
+     *  @memberof ParticleEffects */
+    export const particleEffectShapes: Array<string>;
+    /** Any input into a whole effect: missing fields take their defaults, bad ones are dropped or clamped
+     *  @param {Object} [raw] - {name, settings, behaviors}, from a library file, the designer or code
+     *  @return {{name:string, settings:Object, behaviors:Array<{name:string, strength:number}>}}
+     *  @memberof ParticleEffects */
+    export function particleEffectSanitize(raw?: any): {
+        name: string;
+        settings: any;
+        behaviors: {
+            name: string;
+            strength: number;
+        }[];
+    };
+    /** A copy of an effect with its four colors turned around the color wheel and their saturation scaled; lightness and
+     *  alpha stay, and grey and white have no hue to turn
+     *  @param {Object} effect
+     *  @param {number} [hue] - How far around the wheel, 1 is all the way
+     *  @param {number} [saturation] - Multiplies the saturation, 0 is grey, clamped to 1
+     *  @return {Object}
+     *  @memberof ParticleEffects */
+    export function particleEffectRecolor(effect: any, hue?: number, saturation?: number): any;
+    /** Add effects to play by name, sanitized; one with the name of an effect already there replaces it
+     *  @param {Array<Object>|Object} effects
+     *  @memberof ParticleEffects */
+    export function particleEffectsAdd(effects: Array<any> | any): void;
+    /** The effect with a name, any case, undefined if there is none
+     *  @param {string} name
+     *  @return {Object|undefined}
+     *  @memberof ParticleEffects */
+    export function particleEffectsGet(name: string): any | undefined;
+    /** A library file, or one effect, into sanitized effects; throws on bad input
+     *  @param {string} text
+     *  @return {Array<Object>}
+     *  @memberof ParticleEffects */
+    export function particleEffectsParse(text: string): Array<any>;
+    /** The text of a library file with these effects, what particleEffectsLoad and the designer read
+     *  @param {Array<Object>} effects
+     *  @return {string}
+     *  @memberof ParticleEffects */
+    export function particleEffectsText(effects: Array<any>): string;
+    /** Load a library file the particle designer saved and add its effects
+     *  @param {string} url
+     *  @return {Promise<Array<Object>>} - The effects it had
+     *  @memberof ParticleEffects */
+    export function particleEffectsLoad(url: string): Promise<Array<any>>;
+    /** The tile of a built-in shape, on a sheet the plugin draws once; undefined headless, without a canvas or without
+     *  WebGL, where an effect draws untextured squares
+     *  @param {string} name - One of particleEffectShapes
+     *  @return {TileInfo|undefined}
+     *  @memberof ParticleEffects */
+    export function particleEffectShapeTile(name: string): TileInfo | undefined;
+    /** Play an effect: a 2D emitter set to it, placed, scaled and recolored
+     *  - A continuous effect (fire, a torch) goes until destroyed or given an emitTime, a one-shot ends itself
+     *  - Any setting in the options replaces the effect's own for this play: {emitTime: .5} for a burst of a continuous
+     *    effect, {emitTime: 0, emitRate: 30} to keep a one-shot going, or speed, particleTime and the rest
+     *  - Attach it to an object with addChild to follow it
+     *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
+     *  @param {Vector2} [pos]
+     *  @param {Object} [options]
+     *  @param {number} [options.scale] - Grows the whole effect, the built-ins fit a one unit object at 1
+     *  @param {number} [options.hue] - Turns its colors around the color wheel, 1 is all the way
+     *  @param {number} [options.saturation] - Multiplies its saturation, 0 is grey
+     *  @param {number} [options.angle] - Direction, 0 is up; the effect's own angle when not given
+     *  @param {TileInfo|TextureInfo} [options.tileInfo] - The game's own art to draw with in place of the effect's shape,
+     *    tinted by its colors; a whole texture draws as one tile
+     *  @param {*} [options.settings] - Any effect setting by its name, emitTime, emitRate, speed and the rest, replacing
+     *    the effect's own for this play
+     *  @return {ParticleEmitter|undefined} - undefined when there is no such effect
+     *  @memberof ParticleEffects */
+    export function particleEffect(nameOrEffect: string | any, pos?: Vector2, options?: {
+        scale?: number;
+        hue?: number;
+        saturation?: number;
+        angle?: number;
+        tileInfo?: TileInfo | TextureInfo;
+        settings?: any;
+    }): ParticleEmitter | undefined;
+    /** Play an effect in 3D: a ParticleEmitter3D set to it, placed, scaled and recolored
+     *  - The same effect data as particleEffect, so the look carries across: a circle spawn area becomes a sphere and a
+     *    rectangle a box as deep as it is wide, both flat across the way it emits with options.flatten, a disc or a
+     *    sheet; a trail becomes a streak of the same length, and the settings the 3D emitter lacks (particleConeAngle,
+     *    randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the friction a
+     *    particle lands with
+     *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
+     *  @param {Vector3} [pos3D]
+     *  @param {Object} [options] - scale, hue, saturation, angle, tileInfo and any setting as particleEffect; angle turns it
+     *    about z, so 0 is up; flatten makes the spawn area flat across the way it emits
+     *  @return {ParticleEmitter3D|undefined} - undefined when there is no such effect
+     *  @memberof ParticleEffects */
+    export function particleEffect3D(nameOrEffect: string | any, pos3D?: Vector3, options?: any): ParticleEmitter3D | undefined;
+    /** The names of the built-in effects, in the order a gallery shows them
+     *  @type {Array<string>}
+     *  @memberof ParticleEffects */
+    export const particleEffectsBuiltIn: Array<string>;
+    /** Set a 2D emitter to an effect, live, so a running one keeps its particles
+     *  @param {ParticleEmitter} emitter
+     *  @param {Object} effect
+     *  @memberof ParticleEffects */
+    export function particleEffectApply(emitter: ParticleEmitter, effect: any): void;
+    /** Set a 3D emitter to an effect, live, so a running one keeps its particles; its place, scale and flatten stay
+     *  @param {ParticleEmitter3D} emitter
+     *  @param {Object} effect
+     *  @memberof ParticleEffects */
+    export function particleEffectApply3D(emitter: ParticleEmitter3D, effect: any): void;
+    /** An effect with a 2D emitter's settings, to save, build again, or build in 3D with particleEffect3D; its tile is
+     *  left out, since a hand made emitter's tile is its own texture and not one an effect can name, and so is its
+     *  scale, which an effect does not keep: pass it again with options.scale
+     *  @param {ParticleEmitter} emitter
+     *  @param {string} [name]
+     *  @return {Object}
+     *  @memberof ParticleEffects */
+    export function particleEffectFromEmitter(emitter: ParticleEmitter, name?: string): any;
+    /** Add a behavior effects can use by name, or replace one
+     *  @param {string} name
+     *  @param {function(Particle, number): void} update - Pushes a 2D particle, given the strength
+     *  @param {function(Particle3D, number): void} [update3D] - The same for a 3D particle, none leaves 3D alone
+     *  @param {number} [min] - Strength range the designer offers
+     *  @param {number} [max]
+     *  @param {number} [value] - Strength when first added
+     *  @param {string} [description]
+     *  @memberof ParticleEffects */
+    export function particleEffectsAddBehavior(name: string, update: (arg0: Particle, arg1: number) => void, update3D?: (arg0: Particle3D, arg1: number) => void, min?: number, max?: number, value?: number, description?: string): void;
     /**
      * LittleJS Level Editor
      * - Paint the game's tile layers while it is paused, then keep playing with the changes
@@ -9548,6 +10500,14 @@ declare module "littlejsengine" {
          *  section has Play from mouse, which starts play there, Escape at the mouse and Play at the view center
          *  @type {EditorPlayFromCallback|undefined} */
         onPlayFrom: EditorPlayFromCallback | undefined;
+        /** @property {Array<number>|undefined} - The tiles the palette shows, in its order, for a sheet that also holds
+         *  sprites and art that are not level tiles; undefined shows every tile of the sheet
+         *  @type {Array<number>|undefined} */
+        paletteTiles: Array<number> | undefined;
+        /** @property {boolean|undefined} - Which level editor opens: true the 3D one, false the 2D one, undefined the
+         *  3D one when a level was loaded with level3DLoad and there is a Render3DPlugin
+         *  @type {boolean|undefined} */
+        use3D: boolean | undefined;
         /** True while the editor is open, the game is paused under it
          *  @return {boolean} */
         get isOpen(): boolean;