littlejsengine 1.20.0 → 1.21.0

package/plugins/render3dExtras.js

@@ -38,6 +38,54 @@ function render3DSoftDot()
     return render3DSoftDotTexture = new TextureInfo(context.canvas);
 }
 
+/** 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 */
+function normalMapFromHeight(size, heightFunction, strength=1)
+{
+    ASSERT(isVector2(size) && size.x >= 1 && size.y >= 1, 'normalMapFromHeight size must be a Vector2 of pixels');
+    const width = size.x | 0, height = size.y | 0;
+    if (typeof OffscreenCanvas == 'undefined')
+    {
+        // headless, nothing to draw into; the right size so what reads it still works
+        const textureInfo = new TextureInfo(undefined, false, true);
+        textureInfo.size = vec2(width, height), textureInfo.sizeInverse = vec2(1 / width, 1 / height);
+        return textureInfo;
+    }
+    const context = createCanvasContext(width, height);
+    const pixels = render3DNormalMapPixels(width, height, heightFunction, strength);
+    context.putImageData(new ImageData(pixels, width, height), 0, 0);
+    return new TextureInfo(context.canvas, true, true);
+}
+
+// the pixels of a normal map made from heights, rgba with the top row first: each normal leans away from the uphill
+// side, green up the image as OpenGL has it, and a flat height is (128, 128, 255); rounded before they are stored,
+// since the clamped array would round a flat 127.5 to even
+function render3DNormalMapPixels(width, height, heightFunction, strength)
+{
+    const heights = new Float32Array(width * height), pixels = new Uint8ClampedArray(width * height * 4);
+    for (let y = 0; y < height; ++y)
+    for (let x = 0; x < width; ++x)
+        heights[y * width + x] = heightFunction(x, y);
+    const h = (x, y)=> heights[mod(y, height) * width + mod(x, width)];
+    for (let y = 0; y < height; ++y)
+    for (let x = 0; x < width; ++x)
+    {
+        const dx = (h(x+1, y) - h(x-1, y)) / 2 * strength, dy = (h(x, y+1) - h(x, y-1)) / 2 * strength;
+        const k = 1 / hypot(dx, dy, 1), i = (y * width + x) * 4;
+        pixels[i] = round((-dx * k * .5 + .5) * 255);
+        pixels[i+1] = round((dy * k * .5 + .5) * 255);
+        pixels[i+2] = round((k * .5 + .5) * 255);
+        pixels[i+3] = 255;
+    }
+    return pixels;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // The rest of the shape builders: buildLathe, buildSphere, buildBox, buildGrid and buildSky live with the
 // renderer, since it hands those out itself
@@ -574,6 +622,22 @@ class HeightMap extends EngineObject3D
      *  @ignore */
     levelRaycast3D(ray) { return this.raycast(ray); }
 
+    /** 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, to)
+    {
+        const m = this.pos3D, size = this.mapSize;
+        if (abs(to.x - m.x) > size.x / 2 || abs(to.z - m.z) > size.y / 2) return; // off the map
+        const a = from.y - this.getHeight(from.x, from.z), b = to.y - this.getHeight(to.x, to.z);
+        if (a < 0 || b >= 0) return; // above all the way, or under from the start
+        const distance = a / (a - b);
+        return {distance, normal: this.getNormal(from.x + (to.x - from.x) * distance, from.z + (to.z - from.z) * distance)};
+    }
+
     /** 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
@@ -762,7 +826,7 @@ class FirstPersonCamera3D extends EngineObject3D
         /** @property {boolean} - Capture the mouse on a click, so looking needs no button held */
         this.lockPointer = true;
         /** @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 */
         this.jumpSpeed = 0;
         /** @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
@@ -833,6 +897,49 @@ class FirstPersonCamera3D extends EngineObject3D
 const RENDER3D_PARTICLE_FLOATS = 21;
 // the position, color and size of the particle being drawn, shared by every emitter so the draw loop makes no objects
 const render3DParticlePos = vec3(), render3DParticleColor = new Color, render3DParticleSize = vec2();
+// where a particle was and is, for the level collision
+const render3DParticleFrom = vec3(), render3DParticleTo = vec3();
+
+// the emitters inside a particle callback now, whose nested calls each get a view of their own
+const render3DParticlesCalling = new Set;
+
+// a particle as a ParticleEmitter3D's callbacks see it, set from the particle for each call
+/** @param {ParticleEmitter3D} emitter
+ *  @return {Particle3D} */
+function render3DParticleView(emitter)
+{
+    return {emitter, pos: vec3(), velocity: vec3(), age: 0, lifeTime: 0, destroyed: false,
+        destroy() { this.destroyed = true; }};
+}
+
+/**
+ * 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
@@ -846,6 +953,10 @@ const render3DParticlePos = vec3(), render3DParticleColor = new Color, render3DP
  * - 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
@@ -918,7 +1029,8 @@ class ParticleEmitter3D extends EngineObject3D
         this.randomness = randomness;
         /** @property {boolean} - Additive blending */
         this.additive = additive;
-        /** @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 */
         this.trailTime = 0;
         /** @property {number} - Radians per frame each particle turns in the camera plane, either way; 0 is no spin */
         this.angleSpeed = 0;
@@ -934,6 +1046,25 @@ class ParticleEmitter3D extends EngineObject3D
         this.trailData = undefined;
         /** @property {number} - Trail points kept per particle, from trailTime */
         this.trailMax = 0;
+        /** @property {boolean} - Particles hit the level, the height maps and voxel maps, bouncing by restitution and
+         *  sliding along by friction; off by default, it tests each particle's move against the level every frame */
+        this.collideLevel = false;
+        /** @property {Particle3DCallback|undefined} - Called with each particle as it is made
+         *  @type {Particle3DCallback|undefined} */
+        this.particleCreateCallback = undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle each update, after it moves
+         *  @type {Particle3DCallback|undefined} */
+        this.particleUpdateCallback = 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} */
+        this.particleCollideCallback = undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle as it goes, its life over or destroyed
+         *  @type {Particle3DCallback|undefined} */
+        this.particleDestroyCallback = undefined;
+        /** @property {Particle3D} - The particle the callbacks get, one object for every particle and call
+         *  @type {Particle3D} */
+        this.particleView = render3DParticleView(this);
         /** @property {Vector3|undefined} - Where the emitter was at its last update, for when its parent is destroyed
          *  @type {Vector3|undefined} */
         this.worldPos3D = undefined;
@@ -963,8 +1094,9 @@ class ParticleEmitter3D extends EngineObject3D
         else if (!this.particleCount)
             this.destroy();
 
-        // the trail storage follows trailTime, a change starts every trail over
-        const trailMax = this.trailTime ? max(1, round(this.trailTime / timeDelta)) : 0;
+        // the trail storage follows trailTime at the fixed rate, a change starts every trail over, so a varying
+        // timeDelta can not; with engineVariableStep a trail keeps that many updates
+        const trailMax = this.trailTime ? max(1, round(this.trailTime * frameRate)) : 0;
         if (trailMax !== this.trailMax)
         {
             this.trailMax = trailMax;
@@ -974,8 +1106,13 @@ class ParticleEmitter3D extends EngineObject3D
         }
 
         // move the particles and drop the dead ones, all in the typed array: this runs for every particle every frame
-        const F = RENDER3D_PARTICLE_FLOATS, data = this.particleData, trail = this.trailData;
+        // a callback can emit, which grows the arrays when they are full, so they are read again after each one
+        const F = RENDER3D_PARTICLE_FLOATS;
+        let data = this.particleData, trail = this.trailData;
+        const reread = ()=> { data = this.particleData, trail = this.trailData; };
         const damping = this.damping, gravity = this.gravity * scale, angleDamping = this.angleDamping; // a bigger effect has to fall faster to keep the same arc
+        const collideLevel = this.collideLevel && render3DLevel.length;
+        const updateCallback = this.particleUpdateCallback, destroyCallback = this.particleDestroyCallback;
         for (let i = this.particleCount; i--;)
         {
             // damped first and gravity added after, the order the 2D particle uses, so the same
@@ -984,6 +1121,7 @@ class ParticleEmitter3D extends EngineObject3D
             const vx = data[k+3] *= damping, vy = data[k+4] = data[k+4] * damping + gravity, vz = data[k+5] *= damping;
             data[k] += vx, data[k+1] += vy, data[k+2] += vz;
             data[k+18] += data[k+19] *= angleDamping;
+            collideLevel && (this.particleCollide(k, data[k] - vx, data[k+1] - vy, data[k+2] - vz), reread());
             const t = i * trailMax * 3;
             if (trailMax)
             {
@@ -995,9 +1133,11 @@ class ParticleEmitter3D extends EngineObject3D
                 trail[j] = data[k], trail[j+1] = data[k+1], trail[j+2] = data[k+2];
                 data[k+20] = n + 1;
             }
+            updateCallback && (this.particleCall(updateCallback, k), reread());
             if ((data[k+17] += timeDelta) >= data[k+16])
             {
                 // dead: the last particle takes its slot, trail and all, order does not matter
+                destroyCallback && (this.particleCall(destroyCallback, k), reread());
                 const last = --this.particleCount, kl = last * F;
                 if (i !== last)
                 {
@@ -1064,6 +1204,60 @@ class ParticleEmitter3D extends EngineObject3D
         data[k+18] = this.angleSpeed ? rand(2*PI) : 0;
         data[k+19] = this.angleSpeed ? this.angleSpeed * random() * randSign() : 0;
         data[k+20] = 0; // trail points
+        this.particleCreateCallback && this.particleCall(this.particleCreateCallback, k);
+    }
+
+    // call a particle callback with the particle at k: the emitter's one Particle3D is set from its numbers, and
+    // what the callback changes is written back; a particle it destroys has lived its life, the update removes it
+    particleCall(callback, k, level, pos)
+    {
+        // a callback that emits runs the create callback inside itself, which gets a view of its own so this one
+        // keeps its particle; what the callback changes is written to the arrays as they are after it, since an
+        // emit into a full emitter grows them
+        const nested = render3DParticlesCalling.has(this);
+        const view = nested ? render3DParticleView(this) : this.particleView, data = this.particleData;
+        view.pos.set(data[k], data[k+1], data[k+2]);
+        view.velocity.set(data[k+3], data[k+4], data[k+5]);
+        view.age = data[k+17], view.lifeTime = data[k+16], view.destroyed = false;
+        render3DParticlesCalling.add(this);
+        let result;
+        try { result = callback(view, level, pos); }
+        finally { nested || render3DParticlesCalling.delete(this); }
+        const out = this.particleData;
+        out[k] = view.pos.x, out[k+1] = view.pos.y, out[k+2] = view.pos.z;
+        out[k+3] = view.velocity.x, out[k+4] = view.velocity.y, out[k+5] = view.velocity.z;
+        if (view.destroyed)
+            out[k+17] = max(out[k+17], out[k+16] - timeDelta); // aged past its life this update
+        return result;
+    }
+
+    // stop the particle at k where its last move went into the level, from where it was: back at the surface, a hair
+    // off it, its speed into it turned around by restitution and its speed along it kept by friction, unless the
+    // collide callback lets it through; one that starts inside is let go, as a 2D one is
+    particleCollide(k, x, y, z)
+    {
+        let data = this.particleData;
+        const from = render3DParticleFrom.set(x, y, z);
+        const to = render3DParticleTo.set(data[k], data[k+1], data[k+2]);
+        let hit, level;
+        for (const l of render3DLevel)
+        {
+            const h = l.destroyed ? undefined : l.levelSegment3D(from, to);
+            if (h && (!hit || h.distance < hit.distance))
+                hit = h, level = l;
+        }
+        if (!hit) return;
+        const point = from.lerp(to, hit.distance);
+        const callback = this.particleCollideCallback;
+        if (callback && (!this.particleCall(callback, k, level, point.copy()) || this.particleView.destroyed))
+            return; // let through, or destroyed by the callback
+        data = this.particleData; // as the callback left it, an emit may have grown it
+
+        const n = hit.normal, v = vec3(data[k+3], data[k+4], data[k+5]), into = n.scale(v.dot(n));
+        const restitution = max(this.restitution, level.restitution), friction = max(this.friction, level.friction);
+        const out = v.subtract(into).scale(friction).subtract(into.scale(restitution)), p = point.add(n.scale(1e-3));
+        data[k] = p.x, data[k+1] = p.y, data[k+2] = p.z;
+        data[k+3] = out.x, data[k+4] = out.y, data[k+5] = out.z;
     }
 
     /** Draw the particles, as flat squares or as streaks when trailTime is set

package/plugins/render3dLevel.js

@@ -0,0 +1,189 @@
+/**
+ * LittleJS 3D Level Plugin
+ * - A 3D level is a list of objects, each a type name, a position, and a rotation, scale and properties where
+ *   they are not the default, kept as plain JSON that can be written by hand
+ * - level3DAddType names the types a game makes them from, as objectLayersAddType does in 2D
+ * - level3DLoad makes every object of a level
+ * - Box, Sphere, Cylinder and Light are built in, to block out and light a level with no code
+ * - The 3D level editor, in debug builds, edits the level a game loaded
+ * @namespace Level3D
+ */
+
+'use strict';
+
+///////////////////////////////////////////////////////////////////////////////
+
+const LEVEL3D_VERSION = 1; // the format a level's littlejs3D names
+
+// the types a level's objects are made from, by name
+const level3DTypes = new Map;
+
+// the scale each object had when it was made, the level's scale multiplies it
+const level3DBaseScale = new WeakMap;
+
+/** 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); */
+function level3DAddType(name, make, defaults={}, tileInfo)
+{
+    ASSERT(isStringLike(name), 'object type name must be a string');
+    ASSERT(typeof make === 'function', 'make must be a class or function');
+    ASSERT(!!defaults && typeof defaults === 'object', 'defaults must be an object');
+    level3DTypes.set(String(name), {make, defaults, tileInfo});
+}
+
+/** 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)); */
+function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
+{
+    ASSERT(mesh instanceof Mesh, 'mesh must be a Mesh');
+    ASSERT(isColor(color), 'color must be a color');
+    level3DAddType(name, function(pos, properties) { return level3DMakeShape(pos, properties, mesh, tileInfo); },
+        {color, solid: false}, tileInfo);
+}
+
+/** 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 */
+function level3DLoad(level)
+{
+    ASSERT(!!level && typeof level === 'object', 'a level is an object, {} for a new one');
+    ASSERT(!(level.littlejs3D > LEVEL3D_VERSION), 'the level was made by a newer LittleJS');
+    editor3DLevelLoaded(level); // debug builds: the 3D editor takes the level, its autosaved edits go in first
+    const made = [];
+    for (const object of isArray(level.objects) ? level.objects : [])
+    {
+        if (!object || typeof object !== 'object') continue;
+        const result = level3DMake(object);
+        editor3DObjectMade(object, result); // debug builds link it for the 3D editor
+        result && made.push(result);
+    }
+    return made;
+}
+
+// a vec3 of an array of three numbers, as the file has them, or the fallback
+function level3DVector(value, fallback)
+{
+    return isArray(value) && value.length === 3 && value.every((v)=> isNumber(v)) ?
+        vec3(value[0], value[1], value[2]) : fallback;
+}
+
+// the defaults of an object's type, a Color or vector copied for each object, then its own properties over them,
+// each read as its default is; one the file got wrong, a value not of its default's type, keeps the default, and
+// one the type has no default for is kept as it is
+function level3DProperties(type, object)
+{
+    const properties = {}, own = object.properties;
+    for (const [key, value] of Object.entries(type.defaults))
+        properties[key] = value?.copy ? value.copy() : value;
+    for (const [key, value] of Object.entries(own && typeof own === 'object' ? own : {}))
+    {
+        const d = type.defaults[key];
+        if (isColor(d))
+            /^#([0-9a-f]{6}|[0-9a-f]{8})$/i.test(value) && (properties[key] = new Color().setHex(value));
+        else if (isVector3(d))
+            properties[key] = level3DVector(value, properties[key]);
+        else if (isVector2(d))
+            isArray(value) && value.length === 2 && value.every((v)=> isNumber(v)) &&
+                (properties[key] = vec2(value[0], value[1]));
+        else if (d === undefined || typeof value === typeof d)
+            properties[key] = value;
+    }
+    return properties;
+}
+
+// make one object of a level from the type added for its name, undefined when there is no such type or it made
+// nothing
+function level3DMake(object)
+{
+    const type = level3DTypes.get(object.type);
+    if (!type)
+    {
+        debug && console.warn(`level3DLoad: no type added for ${object.type}, skipped`);
+        return;
+    }
+    const pos = level3DVector(object.pos, vec3()), properties = level3DProperties(type, object);
+    const {make} = type, count = engineObjects.length;
+    let result;
+    try { result = make.prototype ? new make(pos, properties) : make(pos, properties); }
+    catch (error)
+    {
+        // a value the type can not be made with: in debug builds, where asserts throw, the object is skipped with
+        // what it made so far, so the rest of the level loads and the level editor can put the value right
+        if (!debug) throw error;
+        console.error(`level3DLoad: ${object.type} ${object.id} could not be made, skipped:`, error);
+        for (const o of engineObjects.slice(count))
+            o.destroy();
+        return;
+    }
+    if (!result || typeof result !== 'object') return;
+    if (result instanceof EngineObject3D)
+    {
+        level3DBaseScale.set(result, result.scale3D.copy());
+        result.rotation3D = level3DVector(object.rotation, vec3()).scale(PI / 180);
+        result.scale3D = result.scale3D.multiply(level3DVector(object.scale, vec3(1)));
+    }
+
+    // the type's own properties are set on it, one the type has no default for could be a field of the engine's
+    for (const key in type.defaults)
+        result[key] = properties[key];
+    return result;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// the built-in types
+
+// a static object of a mesh, with the color, tile and solid properties the built-in types have
+function level3DMakeShape(pos, properties, mesh, tileInfo, asSphere=false)
+{
+    const o = new EngineObject3D(pos, mesh, properties.tile >= 0 ? tile(properties.tile) : tileInfo, properties.color);
+    o.collideAsSphere3D = asSphere;
+    properties.solid && o.setCollision();
+    return o;
+}
+
+// the cylinder all Cylinder objects share, built the first time one is made
+let level3DCylinderMesh;
+
+level3DAddType('Box', function(pos, properties) { return level3DMakeShape(pos, properties, render3D.boxMesh); },
+    {color: WHITE, tile: -1, solid: true});
+level3DAddType('Sphere', function(pos, properties)
+    { return level3DMakeShape(pos, properties, render3D.sphereMesh, undefined, true); },
+    {color: WHITE, tile: -1, solid: true});
+level3DAddType('Cylinder', function(pos, properties)
+    { return level3DMakeShape(pos, properties, level3DCylinderMesh ||= buildCylinder()); },
+    {color: WHITE, tile: -1, solid: true});
+level3DAddType('Light', function(pos, properties)
+    { return new Light3D(pos, properties.radius, properties.color, properties.intensity); },
+    {color: WHITE, radius: 5, intensity: 1});

package/plugins/render3dVoxels.js

@@ -465,6 +465,18 @@ class VoxelMap extends EngineObject3D
      *  @ignore */
     levelRaycast3D(ray) { return this.raycast(ray)?.distance; }
 
+    /** 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, to)
+    {
+        const hit = this.raycast(new Ray3D(from, to.subtract(from)), 1);
+        return hit && hit.distance > 0 ? {distance: hit.distance, normal: hit.normal} : undefined;
+    }
+
     /** Keeps an eye on its placement, called automatically each frame */
     update()
     {

package/plugins/sceneSystem.js

@@ -0,0 +1,58 @@
+/**
+ * LittleJS Scene System Plugin
+ * - A game's states, like a title, the game and game over, as scene objects
+ * - setScene leaves the current scene, destroys the objects and enters the next
+ * - Objects with the persistent flag set outlive every switch
+ * - Pause is the engine's paused flag, a scene's update stops with gameUpdate
+ * @namespace SceneSystem
+ */
+
+'use strict';
+
+///////////////////////////////////////////////////////////////////////////////
+
+/** A scene, any object with the hooks it needs, each optional and called as a method so this is the scene
+ *  @typedef {Object} Scene
+ *  @property {function():void} [enter] - Called when the scene starts, after the old one left and the objects were destroyed
+ *  @property {function():void} [leave] - Called before the next scene starts, while the scene is current and its objects are still there
+ *  @property {function():void} [update] - Called each update after gameUpdate, not while paused or at time scale 0
+ *  @property {function():void} [render] - Called before gameRender, to draw under the objects
+ *  @property {function():void} [renderPost] - Called after gameRenderPost, to draw over the game, while paused too; plugins made after the first setScene draw over it
+ *  @memberof SceneSystem */
+
+let sceneCurrent, sceneLeaving = false, scenePluginAdded = false;
+
+/** 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 */
+function setScene(scene)
+{
+    ASSERT(!sceneLeaving, 'setScene can not be called from a scene leave');
+    if (!scenePluginAdded)
+    {
+        scenePluginAdded = true;
+        engineAddPlugin(sceneUpdate, sceneRenderPost, undefined, undefined, sceneRender);
+    }
+
+    if (sceneCurrent)
+    {
+        sceneLeaving = true;
+        sceneCurrent.leave?.();
+        sceneLeaving = false;
+    }
+    engineObjectsDestroy();
+    sceneCurrent = scene;
+    scene?.enter?.();
+}
+
+/** Get the current scene
+ *  @return {Scene|undefined}
+ *  @memberof SceneSystem */
+function getScene() { return sceneCurrent; }
+
+// the plugin hooks, update skips the frozen ticks that skip gameUpdate
+function sceneUpdate() { paused || !timeScale || sceneCurrent?.update?.(); }
+function sceneRender() { sceneCurrent?.render?.(); }
+function sceneRenderPost() { sceneCurrent?.renderPost?.(); }

package/plugins/tweenSystem.js

@@ -596,7 +596,9 @@ function tweenUpdate(gameDelta, realDelta)
     for (let i = list.length; i--;)
     {
         const t = list[i];
-        if (!t.active || t.activePass === pass) continue; // stopped, or started again by a callback this update
+        // stopped, or started again by a callback this update, or during an update a callback ran inside it, which
+        // counts on from this one
+        if (!t.active || t.activePass >= pass) continue;
         let dt;
         if (enginePath)
         {
@@ -620,7 +622,7 @@ function tweenUpdate(gameDelta, realDelta)
             // Completion: fire end value, remove from active, start the next iteration
             // of a loop or pingPong, or when there is none it has completed, fire onComplete
             t.callback(t.interp(0));
-            if (!t.active || t.activePass === pass)
+            if (!t.active || t.activePass >= pass)
                 continue; // stopped or restarted by its own callback, the run it was on ends without completing
             tweenDeactivate(t);
             const next = t.thenCallback;