littlejsengine 1.20.0 → 1.21.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,73 @@ 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;
+    };
+    /**
+     * 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;
+        /**
+         * - 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 +221,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 +265,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 +365,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 +622,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 +639,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 +958,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 +972,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 */
@@ -2006,12 +2119,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 +2159,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 +2188,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;
     }
@@ -6788,6 +6957,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 +7542,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 +7574,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 +7610,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 +7643,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
@@ -7531,6 +7718,10 @@ 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} - Size of the shadow map in pixels, bigger is sharper and slower */
@@ -7562,8 +7753,23 @@ declare module "littlejsengine" {
         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 */
+         *  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, 100 sharp
+         *  like polished metal; set from each object's shininess */
+        shininess: number;
+        /** @property {TextureInfo|undefined} - Normal map for the next draws, set from each object's normalMap
+         *  @type {TextureInfo|undefined} */
+        normalMap: TextureInfo | undefined;
+        /** @property {number} - How strongly the normal map bends the surface, set from each object's normalScale */
+        normalScale: number;
+        /** @property {number} - How much the surface reflects the sky, 0 to 1, set from each object's reflectivity */
+        reflectivity: number;
+        /** @property {TextureInfo|undefined} - Emissive map for the next draws, set from each object's emissiveMap
+         *  @type {TextureInfo|undefined} */
+        emissiveMap: TextureInfo | undefined;
+        /** @property {Color} - Multiplies the emissive map, set from each object's emissiveMapColor */
+        emissiveMapColor: Color;
         /** @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} */
@@ -7654,6 +7860,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>>} */
@@ -7953,17 +8166,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 +8210,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 +8232,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
@@ -8499,6 +8734,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 +8851,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 +9006,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 */
@@ -8786,6 +9050,12 @@ 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} - 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 +9151,39 @@ 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 {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
@@ -8900,6 +9196,10 @@ declare module "littlejsengine" {
      * - 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
      * - 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
@@ -8959,7 +9259,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 +9274,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
@@ -9025,8 +9344,8 @@ declare module "littlejsengine" {
     }
     /**
      * 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 +9473,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 +9517,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 +9633,48 @@ 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
+     *  @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>;
     /**
      * LittleJS Three.js Plugin
      * - Renders a three.js scene on a canvas behind the LittleJS canvases
@@ -9548,6 +9922,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;