littlejsengine 1.21.0 → 1.22.0

package/plugins/render3dExtras.js

@@ -908,7 +908,7 @@ const render3DParticlesCalling = new Set;
  *  @return {Particle3D} */
 function render3DParticleView(emitter)
 {
-    return {emitter, pos: vec3(), velocity: vec3(), age: 0, lifeTime: 0, destroyed: false,
+    return {emitter, pos: vec3(), velocity: vec3(), age: 0, lifeTime: 0, scale: 1, destroyed: false,
         destroy() { this.destroyed = true; }};
 }
 
@@ -921,6 +921,8 @@ function render3DParticleView(emitter)
  * @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
@@ -950,8 +952,9 @@ function render3DParticleView(emitter)
  * - 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
@@ -981,8 +984,8 @@ class ParticleEmitter3D extends EngineObject3D
      *  @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 */
@@ -997,6 +1000,9 @@ class ParticleEmitter3D extends EngineObject3D
 
         /** @property {number|Vector3} - Spawn area, a number for a sphere diameter or a vec3 for a box */
         this.emitSize = emitSize;
+        /** @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 */
+        this.emitFlat = false;
         /** @property {number} - How long to keep emitting, 0 is forever */
         this.emitTime = emitTime;
         /** @property {number} - Particles per second, 0 does not emit */
@@ -1023,6 +1029,9 @@ class ParticleEmitter3D extends EngineObject3D
         this.damping = damping;
         /** @property {number} - Per frame change to velocity y, its own number and not render3D.gravity */
         this.gravity = gravity;
+        /** @property {number} - Share of render3D.gravity added each frame on top of its own gravity, 0 by default so
+         *  an effect keeps its own fall wherever it is used; 1 falls with the world, like debris */
+        this.gravityScale = 0;
         /** @property {number} - Fraction of life spent fading, half in and half out */
         this.fadeRate = fadeRate;
         /** @property {number} - Extra randomness applied to speed, size and life */
@@ -1078,6 +1087,7 @@ class ParticleEmitter3D extends EngineObject3D
         const matrix = render3DObjectMatrix(this); // the object's own, read only
         this.worldPos3D = matrix.getTranslation(); // remembered for when the parent is destroyed
         const scale = render3DMaxScale(matrix.m);
+        this.particleView.scale = scale; // the callbacks read it from the view instead of working it out each time
 
         // emit until the emit time is up, then wait for the last particle and go away
         if (!this.emitTime || this.getAliveTime() <= this.emitTime)
@@ -1110,7 +1120,11 @@ class ParticleEmitter3D extends EngineObject3D
         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
+        // its own fall and a share of the world's, grown by the scale: a bigger effect has to fall faster to keep the
+        // same arc
+        const damping = this.damping, angleDamping = this.angleDamping, g = render3D.gravity, share = this.gravityScale;
+        const gravityX = g.x * share * scale, gravityY = (this.gravity + g.y * share) * scale;
+        const gravityZ = g.z * share * scale;
         const collideLevel = this.collideLevel && render3DLevel.length;
         const updateCallback = this.particleUpdateCallback, destroyCallback = this.particleDestroyCallback;
         for (let i = this.particleCount; i--;)
@@ -1118,7 +1132,8 @@ class ParticleEmitter3D extends EngineObject3D
             // damped first and gravity added after, the order the 2D particle uses, so the same
             // damping and gravity give the same arc in both
             const k = i * F;
-            const vx = data[k+3] *= damping, vy = data[k+4] = data[k+4] * damping + gravity, vz = data[k+5] *= damping;
+            const vx = data[k+3] = data[k+3] * damping + gravityX, vy = data[k+4] = data[k+4] * damping + gravityY;
+            const vz = data[k+5] = data[k+5] * damping + gravityZ;
             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());
@@ -1166,10 +1181,18 @@ class ParticleEmitter3D extends EngineObject3D
         // the whole effect grows with the emitter, not just the area the particles start in
         const scale = render3DMaxScale(matrix.m);
 
-        // spawn offset: inside a box or a sphere
-        const size = this.emitSize, box = /** @type {Vector3} */ (size);
-        const offset = isVector3(size) ? vec3(rand(-.5, .5) * box.x, rand(-.5, .5) * box.y, rand(-.5, .5) * box.z)
-            : randInSphere(/** @type {number} */ (size) / 2);
+        // spawn offset: inside a box or a sphere, or flat across the emitter's up, a flat rectangle or a disc
+        const size = this.emitSize, box = /** @type {Vector3} */ (size), flat = this.emitFlat;
+        let offset;
+        if (isVector3(size))
+            offset = vec3(rand(-.5, .5) * box.x, flat ? 0 : rand(-.5, .5) * box.y, rand(-.5, .5) * box.z);
+        else if (flat)
+        {
+            const disc = randInCircle(/** @type {number} */ (size) / 2);
+            offset = vec3(disc.x, 0, disc.y);
+        }
+        else
+            offset = randInSphere(/** @type {number} */ (size) / 2);
 
         // direction inside the cone around local +Y
         const direction = matrix.transformDirection(randVector3(1, this.emitConeAngle)).normalize();
@@ -1439,6 +1462,195 @@ class Trail3D extends EngineObject3D
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+// lens flare
+
+// the shapes a flare is made of, white on clear on one smooth texture made the first time it is asked for: a soft
+// glow, a flat disc with a brighter rim, and a ring; undefined headless or without a canvas
+let render3DFlareTiles;
+function render3DFlareTile(shape)
+{
+    if (!render3DFlareTiles)
+    {
+        if (headlessMode || !glContext || typeof OffscreenCanvas == 'undefined') return;
+        const cell = 128, shapes = ['glow', 'disc', 'ring'], context = createCanvasContext(cell * shapes.length, cell);
+        // each shape is how see-through it is from its middle out
+        const alpha =
+        {
+            glow: (t)=> engineGlowAlpha(t, 1),
+            disc: (t)=> t < .8 ? .4 + .1 * t : t < .92 ? .48 + (t - .8) * 3 : (1 - t) / .08 * .84,
+            ring: (t)=> max(0, 1 - abs(t - .86) / .12),
+        };
+        shapes.forEach((shape, i)=>
+        {
+            const x = i * cell + cell / 2, y = cell / 2, r = cell / 2 - 2, steps = 32;
+            const gradient = context.createRadialGradient(x, y, 0, x, y, r);
+            for (let k = 0; k <= steps; ++k)
+                gradient.addColorStop(k / steps, 'rgba(255,255,255,' + clamp(alpha[shape](k / steps)).toFixed(4) + ')');
+            context.fillStyle = gradient;
+            context.beginPath();
+            context.arc(x, y, r, 0, 2 * PI);
+            context.fill();
+        });
+        const texture = new TextureInfo(context.canvas, true, false, false); // smooth even in a pixel art game
+        render3DFlareTiles = new Map(shapes.map((shape, i)=>
+            [shape, new TileInfo(vec2(i * cell, 0), vec2(cell), texture)]));
+    }
+    return render3DFlareTiles.get(shape) || render3DFlareTiles.get('glow');
+}
+
+/**
+ * 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
+ */
+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=1, count=7, intensity=1, saturation=1, color=WHITE)
+    {
+        super(vec3(), undefined, undefined, color);
+        this.size3D = vec3(); // not a thing to pick or collect
+        /** @property {number} - Scales every part of the flare */
+        this.flareSize = size;
+        /** @property {number} - How many ghosts there are along the line, besides the glow at the sun */
+        this.count = count;
+        /** @property {number} - How bright it is */
+        this.intensity = intensity;
+        /** @property {number} - How colorful the ghosts are, 0 for all the flare's own color, 1 a rainbow */
+        this.saturation = saturation;
+        /** @property {number} - Picks the arrangement of the ghosts, another seed is another flare */
+        this.seed = 1;
+        /** @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} */
+        this.elements = undefined;
+        /** @property {boolean} - Fade out when something is between the camera and the sun */
+        this.occlusion = true;
+        /** @property {number} - Seconds the flare takes to fade out or in when the sun is hidden or shows again */
+        this.fadeTime = .15;
+        /** @property {number} - How much of the sun shows, 0 hidden or behind the camera to 1 in plain view, eased */
+        this.visible = 1;
+        this.renderOrder = 1e9; // over the game's sprites, it is light in the lens
+        this.madeKey = '';
+        /** @type {Array<{at: number, size: number, color: Color, shape: string}>} */
+        this.made = [];
+    }
+
+    /** 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()
+    {
+        if (this.elements) return this.elements;
+        const key = [this.count, this.seed, this.saturation].join();
+        if (key !== this.madeKey)
+        {
+            const random = new RandomGenerator(this.seed * 7919 + 1), s = clamp(this.saturation);
+            const made = this.made = [
+                {at: 0, size: .7, color: hsl(0, 0, 1, .5), shape: 'glow'},
+                {at: 0, size: .25, color: hsl(0, 0, 1, .9), shape: 'glow'}];
+            for (let i = 0; i < this.count; ++i)
+            {
+                // spread along the line, each a place of its own, the far ones bigger
+                const at = (i + random.float(.2, .8)) / max(this.count, 1) * 1.9 + .2;
+                const pick = random.float(), shape = pick < .5 ? 'disc' : pick < .8 ? 'ring' : 'glow';
+                made.push({at, size: random.float(.04, .1) * (1 + at), shape,
+                    color: hsl(random.float(), s * .9, .6, random.float(.15, .4))});
+            }
+            this.madeKey = key;
+        }
+        return this.made;
+    }
+
+    /** Where the sun is on the screen, in pixels like mousePosScreen, undefined when it is behind the camera
+     *  @return {Vector2|undefined} */
+    getSunScreenPos()
+    {
+        const direction = render3D.sunDirection;
+        if (!direction.lengthSquared()) return;
+        return render3D.worldToScreen(render3D.camera.pos.add(direction.normalize(100)));
+    }
+
+    /** 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()
+    {
+        const sun = this.getSunScreenPos(), center = mainCanvasSize.scale(.5);
+        if (!sun || !center.x || !center.y) return [];
+        // it fades as the sun leaves the screen, gone when it is a third of the screen past the edge
+        const off = max(abs(sun.x - center.x) / center.x, abs(sun.y - center.y) / center.y);
+        const strength = this.visible * clamp((1.3 - off) / .5) * this.intensity;
+        if (!(strength > 0)) return [];
+        const tint = this.color.multiply(render3D.sunColor), height = mainCanvasSize.y * this.flareSize;
+        return this.getElements().map((e)=>
+        {
+            const c = e.color.multiply(tint);
+            // along the line and past the middle, a lerp would stop there
+            return {pos: sun.add(center.subtract(sun).scale(e.at)), size: e.size * height, shape: e.shape,
+                color: rgb(c.r, c.g, c.b, c.a * strength)};
+        });
+    }
+
+    /** Is something between the camera and the sun: the level, or an object that is not see through
+     *  @return {boolean} */
+    isSunHidden()
+    {
+        const direction = render3D.sunDirection;
+        if (!direction.lengthSquared()) return true;
+        const blockers = engineObjects.filter((o)=> o !== this && o instanceof EngineObject3D && !o.transparent &&
+            !o.additive);
+        return !!render3D.pick(new Ray3D(render3D.camera.pos, direction.normalize()), blockers);
+    }
+
+    /** Ease visible toward whether the sun shows, called automatically each frame */
+    update()
+    {
+        super.update();
+        const shows = !!this.getSunScreenPos() && !(this.occlusion && this.isSunHidden());
+        const step = this.fadeTime > 0 ? timeDelta / this.fadeTime : 1;
+        this.visible = clamp(this.visible + (shows ? step : -step));
+    }
+
+    /** Draw the flare over the 3D scene, added onto it, called automatically in the 2D pass */
+    render()
+    {
+        if (headlessMode || !glEnable) return;
+        const elements = this.getScreenElements();
+        if (!elements.length) return;
+        setAdditiveBlendMode(true);
+        for (const e of elements)
+        {
+            const tileInfo = render3DFlareTile(e.shape);
+            tileInfo && drawTile(e.pos, vec2(e.size), tileInfo, e.color, 0, false, undefined, true, true);
+        }
+        setAdditiveBlendMode(false);
+    }
+
+    /** A flare has nothing to draw in the 3D pass */
+    render3D() {}
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // OBJ meshes
 

package/plugins/render3dLevel.js

@@ -73,6 +73,16 @@ function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
  *  - 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 */
@@ -81,7 +91,11 @@ 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 = [];
+    level3DSceneApply(level.scene);
+    const made = [], map = level3DVoxelMap = level3DVoxelsMake(level.voxels);
+    map && made.push(map);
+    const terrain = level3DTerrainMap = level3DTerrainMake(level.terrain);
+    terrain && made.push(terrain);
     for (const object of isArray(level.objects) ? level.objects : [])
     {
         if (!object || typeof object !== 'object') continue;
@@ -92,6 +106,147 @@ function level3DLoad(level)
     return made;
 }
 
+// the sheet a level's block map is made with, and what sets each one up, see level3DVoxelSetup; and the map the
+// level loaded last made, the one the 3D editor paints
+let level3DVoxelTiles, level3DVoxelSetupMap, level3DVoxelMap;
+
+/** 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 */
+function level3DVoxelSetup(tileInfo, setup)
+{
+    level3DVoxelTiles = tileInfo;
+    level3DVoxelSetupMap = setup;
+}
+
+// the most cells a level's map may have, 256 each way
+const LEVEL3D_VOXEL_CELLS = 2 ** 24;
+
+// a map's blocks as the file keeps them, runs of a count and a type, cell by cell in the map's own order
+function level3DVoxelsEncode(data)
+{
+    const blocks = [];
+    for (let i = 0; i < data.length;)
+    {
+        let end = i + 1;
+        while (end < data.length && data[end] === data[i]) ++end;
+        blocks.push(end - i, data[i]);
+        i = end;
+    }
+    return blocks;
+}
+
+// runs into a map's cells: what they do not reach is empty, a type that is not 0 to 255 is empty, and a run that
+// is not two numbers ends them
+function level3DVoxelsDecode(blocks, data)
+{
+    data.fill(0);
+    if (!isArray(blocks)) return;
+    for (let i = 0, cell = 0; i + 1 < blocks.length && cell < data.length; i += 2)
+    {
+        const count = blocks[i], type = blocks[i + 1];
+        if (!isNumber(count) || !isNumber(type) || count < 0) return;
+        const end = min(cell + floor(count), data.length);
+        data.fill(type >= 0 && type <= 255 && type % 1 === 0 ? type : 0, cell, end);
+        cell = end;
+    }
+}
+
+// the corner and the size in cells of a level's voxels block, undefined when it is not one a map can be made of
+function level3DVoxelsShape(voxels)
+{
+    if (!voxels || typeof voxels !== 'object') return;
+    const size = level3DVector(voxels.size);
+    if (!size || [size.x, size.y, size.z].some((n)=> n < 1 || n % 1) ||
+        size.x * size.y * size.z > LEVEL3D_VOXEL_CELLS) return;
+    return {pos: level3DVector(voxels.pos, vec3()), size};
+}
+
+// the VoxelMap of a level's voxels block, undefined when it has none or it is wrong
+function level3DVoxelsMake(voxels)
+{
+    const shape = level3DVoxelsShape(voxels);
+    if (!shape || typeof VoxelMap == 'undefined') return;
+    const map = new VoxelMap(shape.pos, shape.size, level3DVoxelTiles || tile());
+    level3DVoxelsDecode(voxels.blocks, map.data);
+    level3DVoxelSetupMap?.(map);
+    map.rebuild();
+    return map;
+}
+
+// the terrain the level loaded last made, the one the 3D editor sculpts, and the most samples it may have a side
+let level3DTerrainMap;
+const LEVEL3D_TERRAIN_SAMPLES = 129;
+
+// what a level's terrain block is made with: its center, its size in the world along x and z, how tall a full
+// height is, and its heights as rows of 0 to 1, a copy, each row as long as the first; undefined when it is not
+// one a HeightMap can be made of
+function level3DTerrainShape(terrain)
+{
+    if (!terrain || typeof terrain !== 'object') return;
+    const size = terrain.size, rows = terrain.heights, n = LEVEL3D_TERRAIN_SAMPLES;
+    if (!isArray(size) || size.length !== 2 || !size.every((v)=> isNumber(v) && v > 0)) return;
+    if (!isArray(rows) || rows.length < 2 || rows.length > n || !isArray(rows[0])) return;
+    const columns = rows[0].length;
+    if (columns < 2 || columns > n || !rows.every((row)=> isArray(row) && row.length === columns)) return;
+    const heights = rows.map((row)=> row.map((v)=> isNumber(v) ? clamp(v) : 0));
+    return {pos: level3DVector(terrain.pos, vec3()), size: vec2(size[0], size[1]),
+        height: isNumber(terrain.height) && terrain.height > 0 ? terrain.height : 1, heights};
+}
+
+// the HeightMap of a level's terrain block, undefined when it has none or it is wrong
+function level3DTerrainMake(terrain)
+{
+    const shape = level3DTerrainShape(terrain);
+    if (!shape || typeof HeightMap == 'undefined') return;
+    const map = new HeightMap(shape.heights, shape.size, shape.height, undefined, shape.pos);
+    if (/^#([0-9a-f]{6}|[0-9a-f]{8})$/i.test(terrain.color))
+        map.color = new Color().setHex(terrain.color);
+    return map;
+}
+
+// the sky domes levels made, a level's sky takes the place of the one before and disposes it; a dome the game made
+// itself is left whole, for the game to put back
+const level3DSkies = new WeakSet;
+
+// set the scene a level's scene block gives: sky as its top, horizon and bottom colors, with ambient how much of
+// them lights the scene, sunDirection and sunColor, fog as its start and end with fogColor, the horizon without one,
+// and shadows; a setting the block does not have, or has wrong, stays as it is
+function level3DSceneApply(scene)
+{
+    const r = render3D;
+    if (!r || !scene || typeof scene !== 'object') return;
+    const color = (value)=> /^#([0-9a-f]{6}|[0-9a-f]{8})$/i.test(value) ? new Color().setHex(value) : undefined;
+    const sky = isArray(scene.sky) && scene.sky.length === 3 ? scene.sky.map(color) : [];
+    if (sky.length && sky.every((c)=> c))
+    {
+        // as setSky does, without disposing a dome that is the game's own
+        const [top, horizon, bottom] = sky, ambient = isNumber(scene.ambient) ? scene.ambient : .5;
+        level3DSkies.has(r.sky) && r.sky.dispose();
+        level3DSkies.add(r.sky = buildSky(top, horizon, bottom));
+        r.fogColor = horizon.copy();
+        r.ambientColor = top.scale(ambient, 1);
+        r.ambientGroundColor = bottom.scale(ambient, 1);
+    }
+    const sun = level3DVector(scene.sunDirection);
+    if (sun && sun.lengthSquared())
+        r.sunDirection = sun;
+    r.sunColor = color(scene.sunColor) || r.sunColor;
+    const fog = scene.fog;
+    if (isArray(fog) && fog.length === 2 && fog.every((v)=> isNumber(v)))
+        r.fogStart = fog[0], r.fogEnd = fog[1];
+    r.fogColor = color(scene.fogColor) || r.fogColor;
+    if (typeof scene.shadows === 'boolean')
+        r.shadows = scene.shadows;
+}
+
 // a vec3 of an array of three numbers, as the file has them, or the fallback
 function level3DVector(value, fallback)
 {
@@ -184,6 +339,14 @@ level3DAddType('Sphere', function(pos, properties)
 level3DAddType('Cylinder', function(pos, properties)
     { return level3DMakeShape(pos, properties, level3DCylinderMesh ||= buildCylinder()); },
     {color: WHITE, tile: -1, solid: true});
+// a light, a spotlight with a cone: cone is the angle in degrees from its forward out to the edge of its beam, the
+// object's rotation aims it, softness is how much of the cone fades, and shadows makes it the one that casts them
 level3DAddType('Light', function(pos, properties)
-    { return new Light3D(pos, properties.radius, properties.color, properties.intensity); },
-    {color: WHITE, radius: 5, intensity: 1});
+{
+    const light = new Light3D(pos, properties.radius, properties.color, properties.intensity);
+    light.coneAngle = max(properties.cone, 0) * PI / 180;
+    light.coneSoftness = properties.softness;
+    if (properties.shadows && render3D)
+        render3D.shadowLight = light;
+    return light;
+}, {color: WHITE, radius: 5, intensity: 1, cone: 0, softness: .2, shadows: false});

package/plugins/sceneSystem.js

@@ -38,9 +38,10 @@ function setScene(scene)
 
     if (sceneCurrent)
     {
+        // a leave that throws still lets the next switch through
         sceneLeaving = true;
-        sceneCurrent.leave?.();
-        sceneLeaving = false;
+        try { sceneCurrent.leave?.(); }
+        finally { sceneLeaving = false; }
     }
     engineObjectsDestroy();
     sceneCurrent = scene;

package/src/engine.js

@@ -32,7 +32,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.21.0';
+const engineVersion = '1.22.0';
 
 /** Frames per second to update
  *  @type {number}

package/src/engineAudio.js

@@ -220,9 +220,12 @@ class Sound
      *  @param {number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
      *  @param {SoundLoadCallback} [onloadCallback] - callback function to call when sound is loaded
      */
-    constructor(asset, randomness, range=soundDefaultRange, taper=soundDefaultTaper, onloadCallback)
+    constructor(asset, randomness, range, taper=soundDefaultTaper, onloadCallback)
     {
         if (!soundEnable || headlessMode) return;
+        const rangeIsDefault = range === undefined;
+        if (rangeIsDefault)
+            range = soundDefaultRange;
 
         ASSERT(!asset || isArray(asset) || isStringLike(asset), 'asset must be a file name or zzfx array');
         ASSERT(randomness === undefined || isNumber(randomness), 'randomness must be a number');
@@ -232,6 +235,9 @@ class Sound
 
         /** @property {number} - World space max range of sound */
         this.range = range;
+        /** @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 */
+        this.rangeIsDefault = rangeIsDefault;
         /** @property {number} - At what percentage of range should it start tapering */
         this.taper = taper;
         /** @property {number} - How much to randomize frequency each time sound plays
@@ -867,7 +873,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// ZzFXMicro - Zuper Zmall Zound Zynth - v1.3.2 by Frank Force
+// ZzFXMicro - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
 
 /** Generate and play a ZzFX sound
  *
@@ -899,7 +905,7 @@ function zzfx(...zzfxSound) { return playSamples([zzfxG(...zzfxSound)]); }
  *  @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 */
 function zzfxG
 (
@@ -937,7 +943,7 @@ function zzfxG
         crush = 0,     // bit crush offset
         jump = 1,      // pitch jump timer
         length,        // sample length
-        b = [],        // sample buffer
+        b,             // sample buffer
         t = 0,         // sample time
         i = 0,         // sample index
         s = 0,         // sample value
@@ -964,9 +970,12 @@ function zzfxG
         pitchJumpTime *= sampleRate;
         repeatTime = repeatTime * sampleRate | 0;
 
+    // allocate the full sample buffer up front, much faster than growing an array
+    length = attack + decay + sustain + release + delay | 0;
+    b = new Float32Array(length > 0 ? length : 0);
+
     // generate waveform
-    for (length = attack + decay + sustain + release + delay | 0;
-        i < length; b[i++] = s * volume)                   // sample
+    for (; i < length; b[i++] = s * volume)                 // sample
     {
         if (!(++crush%(bitCrush*100|0)))                   // bit crush
         {
@@ -1002,7 +1011,7 @@ function zzfxG
 
         f = (frequency += slide += deltaSlide) *// frequency
             cos(modulation*modOffset++);        // modulation
-        t += f + f*noise*sin(i**5);             // noise
+        t += f + f*noise*(i*i*PI2%2-1);         // noise
 
         if (jump && ++jump > pitchJumpTime)     // pitch jump
         {

package/src/engineBuild.mjs

@@ -56,6 +56,7 @@ const enginePluginFiles =
     `${PLUGIN_FOLDER}/render3dExtras.js`,
     `${PLUGIN_FOLDER}/render3dVoxels.js`,
     `${PLUGIN_FOLDER}/render3dLevel.js`,
+    `${PLUGIN_FOLDER}/particleEffects.js`,
     `${PLUGIN_FOLDER}/gltf.js`,
     `${PLUGIN_FOLDER}/threejs.js`,
 ];