littlejsengine 1.21.0 → 1.22.0

package/dist/littlejs.release.js

@@ -35,7 +35,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}
@@ -4348,8 +4348,9 @@ class TextureInfo
      * @param {boolean} [useWebGL] - Should use WebGL if available?
      * @param {boolean|Array<number>} [wrap] - Should the texture wrap (REPEAT) or clamp (CLAMP_TO_EDGE)? Or the WebGL
      *   modes across and down, like [gl.CLAMP_TO_EDGE, gl.MIRRORED_REPEAT], as a glTF sampler gives them
+     * @param {boolean} [pixelated] - Hard edged or smooth for this texture alone, undefined follows tilesPixelated
      */
-    constructor(image, useWebGL=true, wrap=false)
+    constructor(image, useWebGL=true, wrap=false, pixelated)
     {
         /** @property {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} - image source */
         this.image = image;
@@ -4364,6 +4365,10 @@ class TextureInfo
          *  across and down
          *  @type {boolean|Array<number>} */
         this.wrap = wrap;
+        /** @property {boolean|undefined} - Hard edged or smooth for this texture alone, a soft glow in a pixel art
+         *  game or pixel art in a smooth one; undefined follows tilesPixelated
+         *  @type {boolean|undefined} */
+        this.pixelated = pixelated;
         useWebGL && this.createWebGLTexture();
     }
 
@@ -4394,6 +4399,17 @@ class TextureInfo
         this.wrap = wrap;
         glSetTextureWrap(this.glTexture, wrap);
     }
+
+    /** Make this texture hard edged or smooth on its own, whatever tilesPixelated says for the rest; it is made again
+     *  with the new filtering
+     *  @param {boolean} [pixelated] - undefined follows tilesPixelated again */
+    setPixelated(pixelated)
+    {
+        this.pixelated = pixelated;
+        if (!this.glTexture) return;
+        this.destroyWebGLTexture();
+        this.createWebGLTexture();
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5937,6 +5953,33 @@ class ImageFont
     }
 }
 
+// how strong a light's glow is at a distance from its middle, 0 there to 1 at the edge: a bell, full in the middle
+// and nothing at the edge, fading faster the higher the falloff
+function engineGlowAlpha(r, falloff)
+{
+    const k = 3.5 * falloff, edge = Math.exp(-k);
+    return (Math.exp(-k * r * r) - edge) / (1 - edge);
+}
+
+// the soft round glow of the 2D and 3D lights, one texture for each falloff, rounded to a tenth so a changing falloff
+// makes only a few, each made once from a canvas; undefined headless or without a canvas
+const engineGlowTextures = new Map;
+function engineGlowTexture(falloff=1)
+{
+    false&&ASSERT(isNumber(falloff) && falloff > 0, 'glowFalloff must be a number above 0');
+    const key = max(round(falloff * 10), 1) / 10;
+    let texture = engineGlowTextures.get(key);
+    if (texture || !glContext || typeof OffscreenCanvas == 'undefined') return texture;
+    const size = 64, context = createCanvasContext(size), steps = 16;
+    const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+    for (let i = 0; i <= steps; ++i)
+        gradient.addColorStop(i / steps, 'rgba(255,255,255,' + engineGlowAlpha(i / steps, key).toFixed(4) + ')');
+    context.fillStyle = gradient;
+    context.fillRect(0, 0, size, size);
+    engineGlowTextures.set(key, texture = new TextureInfo(context.canvas, true, false, false));
+    return texture;
+}
+
 // load engine font, called automatically on startup
 async function imageFontInit()
 {
@@ -7638,9 +7681,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;
 
         false&&ASSERT(!asset || isArray(asset) || isStringLike(asset), 'asset must be a file name or zzfx array');
         false&&ASSERT(randomness === undefined || isNumber(randomness), 'randomness must be a number');
@@ -7650,6 +7696,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
@@ -8285,7 +8334,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
  *
@@ -8317,7 +8366,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
 (
@@ -8355,7 +8404,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
@@ -8382,9 +8431,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
         {
@@ -8420,7 +8472,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
         {
@@ -9598,6 +9650,13 @@ class ParticleEmitter extends EngineObject
         this.localSpace        = localSpace;
         /** @property {number} - If non zero the particle is drawn as a trail, stretched in the direction of velocity */
         this.trailScale        = 0;
+        /** @property {number} - Grows the whole effect as each particle is born: the spawn area, the particles' sizes,
+         *  speed and fall, so it looks the same only bigger; 1 is as made, and a particle keeps the scale it was born
+         *  with, so a change never moves the ones already out */
+        this.scale             = 1;
+        /** @property {number} - The effect's own fall, added to each particle's velocity y every frame, on top of the
+         *  world's gravity times gravityScale; an effect that sets its own looks the same in any game */
+        this.gravity           = 0;
         /** @property {ParticleCallback|undefined} - Callback when particle is created
          *  @type {ParticleCallback|undefined} */
         this.particleCreateCallback = undefined;
@@ -9684,9 +9743,9 @@ class ParticleEmitter extends EngineObject
         {
             // show emitter bounds
             if (this.emitCircle)
-                debugCircle(this.pos, this.emitSize.x, '#0f0', 0, false, false);
+                debugCircle(this.pos, this.emitSize.x * this.scale, '#0f0', 0, false, false);
             else
-                debugRect(this.pos, this.emitSize, '#0f0', 0, this.angle, false, false);
+                debugRect(this.pos, this.emitSize.scale(this.scale), '#0f0', 0, this.angle, false, false);
         }
     }
 
@@ -9695,10 +9754,11 @@ class ParticleEmitter extends EngineObject
     emitParticle()
     {
         // spawn a particle
+        const scale = this.scale; // grows the spawn area, the sizes and the speed of each particle born
         let pos = this.emitCircle ?            // check if circle emitter
-            randInCircle(this.emitSize.x/2)    // circle emitter
-            : vec2(rand(-.5,.5), rand(-.5,.5)) // box emitter
-                .multiply(this.emitSize);
+            randInCircle(this.emitSize.x/2 * scale) // circle emitter
+            : vec2(rand(-.5,.5) * this.emitSize.x * scale, // box emitter, one vector made
+                rand(-.5,.5) * this.emitSize.y * scale);
         let angle = rand(this.particleConeAngle, -this.particleConeAngle);
         if (!this.localSpace)
         {
@@ -9715,9 +9775,9 @@ class ParticleEmitter extends EngineObject
 
         // randomize particle settings
         const particleTime  = randomizeScale(this.particleTime);
-        const sizeStart     = randomizeScale(this.sizeStart);
-        const sizeEnd       = randomizeScale(this.sizeEnd);
-        const speed         = randomizeScale(this.speed);
+        const sizeStart     = randomizeScale(this.sizeStart) * scale;
+        const sizeEnd       = randomizeScale(this.sizeEnd) * scale;
+        const speed         = randomizeScale(this.speed) * scale;
         const angleSpeed    = randomizeScale(this.angleSpeed) * randSign();
         const coneAngle     = rand(this.emitConeAngle, -this.emitConeAngle);
         const colorStart    = randColor(this.colorStartA, this.colorStartB, this.randomColorLinear);
@@ -9751,9 +9811,13 @@ class ParticleEmitter extends EngineObject
     render()
     {
         // render all particles, the blend switched once for them all, not around each one
+        // and the tile's draw worked out once for them all, fresh each frame so a tile changed in place draws changed
         this.additive && setAdditiveBlendMode();
+        particleTile = null; // none yet, undefined is the untextured tile
+        particleTileBatch = true;
         for (const particle of this.particles)
             particle.render();
+        particleTileBatch = false;
         this.additive && setAdditiveBlendMode(false);
     }
 
@@ -9780,6 +9844,39 @@ class ParticleEmitter extends EngineObject
 // scratch vectors reused by Particle.render and the tile collision to avoid per-frame allocations
 const particleDrawPos = new Vector2, particleDrawSize = new Vector2, particleCollidePos = new Vector2;
 
+// the WebGL draw of the tile particles draw with, what drawTile works out for each sprite: kept while an emitter
+// renders its particles, so each one only writes its own values into the batch
+let particleTile, particleTileBatch = false, particleTileTextured = false, particleTileEmpty = false;
+let particleTileU0 = 0, particleTileV0 = 0, particleTileU1 = 0, particleTileV1 = 0;
+function particleTileSet(tileInfo)
+{
+    particleTile = tileInfo;
+    const textureInfo = tileInfo?.textureInfo;
+    particleTileTextured = !!textureInfo;
+    particleTileEmpty = !!textureInfo && !(tileInfo.size.x && tileInfo.size.y); // like a sprite still loading
+    if (!textureInfo || particleTileEmpty) return;
+
+    false&&ASSERT(!!textureInfo.glTexture, 'texture has no WebGL texture, draw it with useWebGL false');
+    glSetTexture(textureInfo.glTexture); // bound, and its mipmaps brought up to date, once for the emitter
+    const sizeInverse = textureInfo.sizeInverse, bleed = tileInfo.bleed;
+    const x = tileInfo.pos.x * sizeInverse.x;
+    const y = tileInfo.pos.y * sizeInverse.y;
+    const w = tileInfo.size.x * sizeInverse.x;
+    const h = tileInfo.size.y * sizeInverse.y;
+    if (bleed)
+    {
+        const bleedX = sizeInverse.x*bleed;
+        const bleedY = sizeInverse.y*bleed;
+        particleTileU0 = x + bleedX;     particleTileV0 = y + bleedY;
+        particleTileU1 = x - bleedX + w; particleTileV1 = y - bleedY + h;
+    }
+    else
+    {
+        particleTileU0 = x;     particleTileV0 = y;
+        particleTileU1 = x + w; particleTileV1 = y + h;
+    }
+}
+
 // tests if a particle collides with tiles at x, y, through its emitter's collide callback if it has one
 function particleCollideTest(particle, collideCallback, x, y)
 {
@@ -9815,6 +9912,8 @@ class Particle
     {
         /** @property {ParticleEmitter} - The emitter this particle came from */
         this.emitter = emitter;
+        /** @property {number} - The emitter's scale when it was made, which grows its fall */
+        this.scale = emitter.scale ?? 1; // a hand made emitter-like object may have none
         /** @property {Vector2} - Position, world space or local to the emitter when localSpace is set */
         this.pos = pos;
         /** @property {number} - Angle in radians */
@@ -9877,7 +9976,10 @@ class Particle
         // apply physics; only the tile collision needs where the particle was
         const solve = enablePhysicsSolver && collideLevel;
         const oldX = this.pos.x, oldY = this.pos.y;
-        let gravityX = gravity.x * gravityScale, gravityY = gravity.y * gravityScale;
+        // the world's gravity times gravityScale plus the emitter's own, grown by the particle's scale
+        const fall = this.scale;
+        let gravityX = gravity.x * gravityScale * fall;
+        let gravityY = (gravity.y * gravityScale + (emitter.gravity || 0)) * fall;
         if (emitter.localSpace && emitter.angle)
         {
             // world gravity turned into the emitter's space, the render turns it back
@@ -9931,7 +10033,9 @@ class Particle
                 }
                 if (isBlockedY || !isBlockedX)
                 {
-                    const wasFalling = this.velocity.y < 0 && gravity.y < 0 || this.velocity.y > 0 && gravity.y > 0;
+                    // down is the world's gravity, or the emitter's own fall in a world with none
+                    const down = gravity.y || emitter.gravity || 0;
+                    const wasFalling = this.velocity.y < 0 && down < 0 || this.velocity.y > 0 && down > 0;
                     if (wasFalling)
                         this.groundObject = hitLayer;
 
@@ -10010,7 +10114,24 @@ class Particle
                 angle = atan2(velocity.x, velocity.y);
             }
         }
-        drawTile(pos, size, this.tileInfo, this.color, angle, this.mirror, undefined, glEnable, false);
+        if (glEnable && !headlessMode)
+        {
+            // straight into the batch, the tile's draw worked out once for the emitter's particles
+            const tileInfo = this.tileInfo;
+            if (!particleTileBatch || tileInfo !== particleTile)
+                particleTileSet(tileInfo);
+            if (!particleTileTextured)
+                glDrawUntextured(pos.x, pos.y, size.x, size.y, angle, this.color.rgbaInt());
+            else if (!particleTileEmpty)
+            {
+                const texture = tileInfo.textureInfo.glTexture;
+                glActiveTexture === texture || glSetTexture(texture); // bound again only if a draw between changed it
+                glDraw(pos.x, pos.y, this.mirror ? -size.x : size.x, size.y, angle,
+                    particleTileU0, particleTileV0, particleTileU1, particleTileV1, this.color.rgbaInt());
+            }
+        }
+        else
+            drawTile(pos, size, this.tileInfo, this.color, angle, this.mirror, undefined, false, false);
         additive && setAdditiveBlendMode(false);
         debugParticles && debugRect(pos, size, '#f005', 0, angle, false, false);
     }
@@ -10041,6 +10162,19 @@ let glCanvas;
  *  @memberof WebGL */
 let glContext;
 
+/** The largest texture this device makes, in pixels across, 0 until WebGL starts; at least 2048 with WebGL2
+ *  @type {number}
+ *  @memberof WebGL */
+let glMaxTextureSize = 0;
+
+/** A texture size this device can make: the size asked for, or the largest it supports when that is smaller
+ *  - The engine sizes the textures it makes itself through this, the shadow maps and the like, so a size a device
+ *    does not have falls back instead of failing
+ *  @param {number} size - Pixels across
+ *  @return {number}
+ *  @memberof WebGL */
+function glClampTextureSize(size) { return glMaxTextureSize ? min(size, glMaxTextureSize) : size; }
+
 /** Should WebGL be setup with anti-aliasing? must be set before calling engineInit
  *  @type {boolean}
  *  @memberof WebGL */
@@ -10130,7 +10264,7 @@ function glInit(rootElement)
     // startup webgl, and make the textures of any texture infos made before it
     initWebGL();
     for (const info of glTextureInfos)
-        info.glTexture ||= glCreateTexture(info.image, info.wrap);
+        info.glTexture ||= glCreateTexture(info.image, info.wrap, info.pixelated);
 
     // setup context lost and restore handlers
     glCanvas.addEventListener('webglcontextlost', (e)=>
@@ -10170,7 +10304,7 @@ function glInit(rootElement)
         glPremultipliedTextures = new WeakSet; // the tile layers draw into their new textures again below
         initWebGL();
         for (const info of glTextureInfos)
-            info.glTexture = glCreateTexture(info.image, info.wrap);
+            info.glTexture = glCreateTexture(info.image, info.wrap, info.pixelated);
         pluginList.forEach(plugin=>plugin.glContextRestored?.());
 
         // a tile layer drawn on the GPU only had its tiles in the lost texture, it draws them again
@@ -10180,6 +10314,8 @@ function glInit(rootElement)
 
     function initWebGL()
     {
+        glMaxTextureSize = glContext.getParameter(glContext.MAX_TEXTURE_SIZE) | 0;
+
         // setup instanced rendering shader program
         glShader = glCreateProgram(gl_VERTEX_SOURCE,
             '#version 300 es\n' +     // specify GLSL ES version
@@ -10503,9 +10639,10 @@ function glShaderProgram(shader)
  *  Restores the active texture when done
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} [image]
  *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across and down
+ *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
  *  @return {WebGLTexture}
  *  @memberof WebGL */
-function glCreateTexture(image, wrap=false)
+function glCreateTexture(image, wrap=false, pixelated=tilesPixelated)
 {
     if (!glContext) return;
 
@@ -10514,10 +10651,10 @@ function glCreateTexture(image, wrap=false)
     let mipMap = false;
     if (image?.width)
     {
-        glSetTextureData(texture, image);
+        glSetTextureData(texture, image, pixelated);
         glContext.bindTexture(glContext.TEXTURE_2D, texture);
         // WebGL2 makes mipmaps at any size, a texture that becomes a render target keeps them only at powers of two
-        mipMap = !tilesPixelated;
+        mipMap = !pixelated;
         if (mipMap && !(isPowerOfTwo(image.width) && isPowerOfTwo(image.height)))
             glMipmapsUntilTarget.add(texture);
     }
@@ -10530,7 +10667,7 @@ function glCreateTexture(image, wrap=false)
     }
 
     // set texture filtering
-    const magFilter = tilesPixelated ? glContext.NEAREST : glContext.LINEAR;
+    const magFilter = pixelated ? glContext.NEAREST : glContext.LINEAR;
     const minFilter = mipMap ? glContext.LINEAR_MIPMAP_LINEAR : magFilter;
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MAG_FILTER, magFilter);
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MIN_FILTER, minFilter);
@@ -10561,8 +10698,9 @@ function glDeleteTexture(texture)
 /** Set WebGL texture data from an image, restores the active texture when done
  *  @param {WebGLTexture} texture
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image
+ *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
  *  @memberof WebGL */
-function glSetTextureData(texture, image)
+function glSetTextureData(texture, image, pixelated=tilesPixelated)
 {
     if (!glContext) return;
 
@@ -10580,7 +10718,7 @@ function glSetTextureData(texture, image)
     }
     // smooth filtering mixes a texel with its see through neighbors, right only for premultiplied color, or the
     // edges go dark; pixel art is sampled a texel at a time, and uploads straight color as it always has
-    const premultiply = !tilesPixelated;
+    const premultiply = !pixelated;
     glContext.pixelStorei(glContext.UNPACK_PREMULTIPLY_ALPHA_WEBGL, premultiply);
     glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, image);
     glContext.pixelStorei(glContext.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
@@ -10611,9 +10749,9 @@ function glRegisterTextureInfo(textureInfo)
 
     // create or set the texture data
     if (textureInfo.glTexture)
-        glSetTextureData(textureInfo.glTexture, textureInfo.image);
+        glSetTextureData(textureInfo.glTexture, textureInfo.image, textureInfo.pixelated);
     else
-        textureInfo.glTexture = glCreateTexture(textureInfo.image, textureInfo.wrap);
+        textureInfo.glTexture = glCreateTexture(textureInfo.image, textureInfo.wrap, textureInfo.pixelated);
 }
 
 /** Internal: tells WebGL to destroy the glTexture and stop tracking it, TextureInfo calls it
@@ -12111,8 +12249,8 @@ class PostProcessPlugin
         false&&ASSERT(!(includeMainCanvas && feedbackTexture), 'Post process cannot both include main canvas and use feedback texture');
         postProcess = this;
 
-        if (!shaderCode) // default shader pass through
-            shaderCode = 'void mainImage(out vec4 c,vec2 p){c=texture(iChannel0,p/iResolution.xy);}';
+        /** @property {string} - The shadertoy style mainImage code it shades with, see setShaderCode */
+        this.shaderCode = shaderCode || postProcessEffects(); // no code passes the frame through
 
         /** @property {WebGLProgram|undefined} - Shader for post processing
          *  @type {WebGLProgram|undefined} */
@@ -12158,7 +12296,7 @@ class PostProcessPlugin
                 'gl_Position=vec4(p+p-1.,1,1);'+ // set position
                 '}'                              // end of shader
                 ,
-                postProcessFragmentSource(shaderCode)
+                postProcessFragmentSource(postProcess.shaderCode)
             );
 
             // setup VAO for post processing
@@ -12171,6 +12309,10 @@ class PostProcessPlugin
             const pLocation = glContext.getAttribLocation(postProcess.shader, 'p');
             glContext.enableVertexAttribArray(pLocation);
             glContext.vertexAttribPointer(pLocation, 2, glContext.FLOAT, false, vertexByteStride, 0);
+
+            // the engine's own vertex array and buffer back, its next batch is written into the buffer bound
+            glContext.bindVertexArray(glPolyMode ? glPolyVAO : glInstancedVAO);
+            glContext.bindBuffer(glContext.ARRAY_BUFFER, glArrayBuffer);
         }
         function postProcessContextLost()
         {
@@ -12188,16 +12330,17 @@ class PostProcessPlugin
         {
             if (headlessMode || !glEnable) return;
 
-            // made now if WebGL was off when the plugin was made, or when a lost context came back
+            // clear out the buffer, before anything here binds its own
+            glFlush();
+
+            // made now if WebGL was off when the plugin was made, when a lost context came back, or when
+            // setShaderCode gave it new code
             if (!postProcess.shader)
             {
                 if (glContext.isContextLost()) return;
                 initPostProcess();
             }
 
-            // clear out the buffer
-            glFlush();
-
             // ensure we render to the default framebuffer (in case any earlier
             // caller this frame left a render target bound)
             glContext.bindFramebuffer(glContext.FRAMEBUFFER, null);
@@ -12266,7 +12409,9 @@ class PostProcessPlugin
 
             if (feedbackTexture)
             {
-                // keep this frame's output for the next one, then hand the first texture unit back to the engine
+                // keep this frame's output for the next one, in the feedback texture still bound to the second
+                // unit, then hand the first texture unit back to the engine
+                glContext.activeTexture(glContext.TEXTURE1);
                 glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, glCanvas);
                 glContext.activeTexture(glContext.TEXTURE0);
             }
@@ -12288,6 +12433,23 @@ class PostProcessPlugin
             glSetInstancedMode(true);
         }
     }
+
+    /** Shade with new code from the next frame on, to switch effects while the game runs; the shader is made again
+     *  @param {string} [shaderCode] - Shadertoy style mainImage code, postProcessEffects builds it; none passes the
+     *  frame through */
+    setShaderCode(shaderCode)
+    {
+        false&&ASSERT(!shaderCode || typeof shaderCode === 'string', 'shader code must be a string');
+        this.shaderCode = shaderCode || postProcessEffects();
+        if (!this.shader || headlessMode || !glContext) return;
+
+        // what the new shader replaces, made again by the next render
+        glContext.deleteProgram(this.shader);
+        glContext.deleteTexture(this.texture);
+        this.feedbackTexture && glContext.deleteTexture(this.feedbackTexture);
+        glContext.deleteVertexArray(this.vao);
+        this.shader = this.texture = this.feedbackTexture = this.vao = undefined;
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -12328,9 +12490,66 @@ function postProcessFragmentSource(shaderCode)
  */
 function postProcessBloomShader(threshold=.6, strength=1, size=6)
 {
-    false&&ASSERT(isNumber(threshold) && isNumber(strength) && isNumber(size), 'bloom settings must be numbers');
-    false&&ASSERT(size > 0, 'bloom size must be above zero');
-    false&&ASSERT(size <= 32, 'a bloom this wide takes a sample every few pixels of every ring, which is hundreds of samples a pixel', size);
+    return postProcessEffects(postProcessGlow(threshold, strength, size));
+}
+
+/**
+ * Set up post processing with a bloom effect, so bright colors and lights glow
+ * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+ * @param {number} [strength] - How much glow to add
+ * @param {number} [size] - How far the glow spreads in pixels
+ * @param {boolean} [includeMainCanvas] - Glow the 2D canvas too, off by default so HUD text stays crisp
+ *   (a HUD drawn with WebGL in gameRenderPost glows either way, draw it with useWebGL=false)
+ * @return {PostProcessPlugin}
+ * @memberof PostProcess
+ * @example
+ * postProcessBloom(); // in gameInit, after any Render3DPlugin
+ */
+function postProcessBloom(threshold=.6, strength=1, size=6, includeMainCanvas=false)
+{ return new PostProcessPlugin(postProcessBloomShader(threshold, strength, size), includeMainCanvas); }
+
+///////////////////////////////////////////////////////////////////////////////
+// Effects: pieces of shader code, each with its settings written in as numbers, that postProcessEffects joins in
+// order into one shader; a piece works on c, the pixel's color, and uv, where it is on the screen from 0 to 1, with p
+// its pixel; one that bends uv or samples the frame, the curve, chromatic and glow, goes before the ones that shade
+
+// a number as GLSL writes it, a float with a point
+const postProcessNumber = (n)=> (false&&ASSERT(isNumber(n), 'effect settings must be numbers', n), n.toFixed(4));
+
+/**
+ * Join effects into one post process shader, in the order given, for PostProcessPlugin or setShaderCode
+ * - Each effect is a piece of shader code on c, the pixel's color, and uv, where it is on the screen from 0 to 1;
+ *   your own code is a piece too, a line of GLSL or many, dropped in where you put it
+ * - Put the ones that bend the picture or sample it first: postProcessCurve, postProcessChromatic, postProcessGlow
+ * @param {...string} effects - The pieces, from the effect functions or your own code
+ * @return {string} - Shadertoy style mainImage code
+ * @example
+ * new PostProcessPlugin(postProcessEffects(
+ *     postProcessScanlines(.5), postProcessVignette(), 'c.rgb *= vec3(1, .9, .8);'));
+ * @memberof PostProcess
+ */
+function postProcessEffects(...effects)
+{
+    false&&ASSERT(effects.every((e)=> typeof e === 'string'), 'each effect is a piece of shader code, a string');
+    return 'void mainImage(out vec4 c, vec2 p)\n{\n' +
+        '    vec2 uv = p / iResolution.xy;\n' +
+        '    c = texture(iChannel0, uv);\n' +
+        effects.map((e)=> '    {\n' + e + '\n    }\n').join('') + '}\n';
+}
+
+/**
+ * Bright parts glow, the bloom as an effect to join with others; postProcessBloom sets up bloom on its own
+ * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+ * @param {number} [strength] - How much glow to add
+ * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessGlow(threshold=.6, strength=1, size=6)
+{
+    false&&ASSERT(isNumber(threshold) && isNumber(strength) && isNumber(size), 'glow settings must be numbers');
+    false&&ASSERT(size > 0, 'glow size must be above zero');
+    false&&ASSERT(size <= 32, 'a glow this wide takes a sample every few pixels of every ring, which is hundreds of samples a pixel', size);
 
     // Taps on three rings over a disc of the given size, one every three pixels or so of each ring
     // so there is no gap wide enough to show. The count follows the ring all the way out: hold it
@@ -12352,30 +12571,127 @@ function postProcessBloomShader(threshold=.6, strength=1, size=6)
             glow += max(vec3(0), texture(iChannel0, uv + vec2(cos(a), sin(a)) * ${radius.toFixed(4)} / iResolution.xy).rgb - ${threshold.toFixed(4)});
         }`;
     }
-    return `
-    void mainImage(out vec4 color, vec2 pixel)
-    {
-        vec2 uv = pixel / iResolution.xy;
-        color = texture(iChannel0, uv);
+    return `        // glow
         vec3 glow = vec3(0);${code}
-        color.rgb += glow * ${(strength / taps).toFixed(6)};
-    }`;
+        c.rgb += glow * ${(strength / taps).toFixed(6)};`;
 }
 
 /**
- * Set up post processing with a bloom effect, so bright colors and lights glow
- * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
- * @param {number} [strength] - How much glow to add
- * @param {number} [size] - How far the glow spreads in pixels
- * @param {boolean} [includeMainCanvas] - Glow the 2D canvas too, off by default so HUD text stays crisp
- *   (a HUD drawn with WebGL in gameRenderPost glows either way, draw it with useWebGL=false)
- * @return {PostProcessPlugin}
+ * Scan lines across the screen, like an old TV
+ * @param {number} [strength] - How dark the lines are, and how bright between them
+ * @param {number} [spacing] - Pixels from one line to the next
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessScanlines(strength=.5, spacing=6)
+{
+    return `        // scanlines
+        c.rgb *= 1. - ${postProcessNumber(strength)} * cos(p.y * 6.2832 / ${postProcessNumber(spacing)});`;
+}
+
+/**
+ * Static noise over the picture, changing every frame
+ * @param {number} [strength] - How bright the static is
+ * @param {number} [size] - Size of a speck in pixels
+ * @return {string}
  * @memberof PostProcess
+ */
+function postProcessNoise(strength=.1, size=2)
+{
+    return `        // noise
+        vec2 q = fract((floor(p / ${postProcessNumber(size)}) + mod(iTime * 500., 1e3)) * .3197);
+        c.rgb += ${postProcessNumber(strength)} * fract(1. + sin(51. * q.x + 73. * q.y) * 13753.3);`;
+}
+
+/**
+ * Darken toward the edges and corners
+ * @param {number} [strength] - How dark the corners get, 1 is black
+ * @param {number} [falloff] - How far in it reaches, low darkens most of the screen, high only the corners
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessVignette(strength=1, falloff=3)
+{
+    return `        // vignette
+        vec2 d = uv * 2. - 1.;
+        c.rgb *= 1. - ${postProcessNumber(strength)} * min(1., pow(dot(d, d) / 2., ${postProcessNumber(falloff)}));`;
+}
+
+/**
+ * Bend the picture like the bulged glass of an old TV, black past the corners; put it first
+ * @param {number} [strength] - How much it bends
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessCurve(strength=.1)
+{
+    return `        // curve
+        vec2 d = uv * 2. - 1.;
+        d *= 1. + ${postProcessNumber(strength)} * dot(d, d);
+        uv = d * .5 + .5;
+        c = all(lessThan(abs(d), vec2(1))) ? texture(iChannel0, uv) : vec4(0, 0, 0, 1);`;
+}
+
+/**
+ * Split red and blue apart toward the edges, like a cheap lens; put it before what shades the picture
+ * @param {number} [strength] - How far apart at the edge, as a part of the screen
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessChromatic(strength=.005)
+{
+    return `        // chromatic
+        vec2 d = (uv - .5) * ${postProcessNumber(strength)} * 2.;
+        c.r = texture(iChannel0, uv + d).r;
+        c.b = texture(iChannel0, uv - d).b;`;
+}
+
+/**
+ * Draw lines where the 3D depth jumps, around objects and along their creases; needs render3D.depthTexture on
+ * @param {Color} [color] - The lines' color, its alpha how strong they are
+ * @param {number} [thickness] - How wide the lines are in pixels
+ * @param {number} [threshold] - How big a jump makes a line, as a part of the distance, lower draws more
+ * @return {string}
+ * @memberof PostProcess
+ */
+function postProcessOutline(color=BLACK, thickness=1, threshold=.02)
+{
+    false&&ASSERT(isColor(color), 'outline color must be a Color');
+    const n = postProcessNumber;
+    return `        // outline
+        vec2 o = ${n(thickness)} / iResolution.xy;
+        float d = sceneDepth(uv);
+        float dx = abs(sceneDepth(uv + vec2(o.x, 0)) + sceneDepth(uv - vec2(o.x, 0)) - 2. * d);
+        float dy = abs(sceneDepth(uv + vec2(0, o.y)) + sceneDepth(uv - vec2(0, o.y)) - 2. * d);
+        vec4 line = vec4(${n(color.r)}, ${n(color.g)}, ${n(color.b)}, ${n(color.a)});
+        c.rgb = mix(c.rgb, line.rgb, line.a * step(${n(threshold)}, max(dx, dy) / d));`;
+}
+
+/**
+ * The look of an old TV, as one effect to use alone or join with others: static noise, scan lines, a soft glow and
+ * a vignette, and a bulged screen when curve is set; any setting at 0 leaves that part out
+ * @param {Object} [settings]
+ * @param {number} [settings.noise] - Static noise strength
+ * @param {number} [settings.scanlines] - Scan line strength
+ * @param {number} [settings.scanlineSpacing] - Pixels from one scan line to the next
+ * @param {number} [settings.glow] - Soft glow strength
+ * @param {number} [settings.vignette] - Vignette strength
+ * @param {number} [settings.curve] - How much the screen bulges, 0 by default for flat
+ * @return {string}
  * @example
- * postProcessBloom(); // in gameInit, after any Render3DPlugin
+ * new PostProcessPlugin(postProcessEffects(postProcessTV({scanlines: .4, curve: .1})));
+ * @memberof PostProcess
  */
-function postProcessBloom(threshold=.6, strength=1, size=6, includeMainCanvas=false)
-{ return new PostProcessPlugin(postProcessBloomShader(threshold, strength, size), includeMainCanvas); }
+function postProcessTV({noise=.1, scanlines=.5, scanlineSpacing=6, glow=.4, vignette=1, curve=0}={})
+{
+    const parts = [];
+    curve && parts.push(postProcessCurve(curve));
+    glow && parts.push(postProcessGlow(0, glow, 2));
+    scanlines && parts.push(postProcessScanlines(scanlines, scanlineSpacing));
+    noise && parts.push(postProcessNoise(noise, 1));
+    vignette && parts.push(postProcessVignette(vignette, 6));
+    return parts.map((part)=> '    {\n' + part + '\n    }').join('\n');
+}
 
 /**
  * LittleJS Light System Plugin
@@ -12399,6 +12715,8 @@ function postProcessBloom(threshold=.6, strength=1, size=6, includeMainCanvas=fa
  *   shadow map through renderShadow(), which calls render() by default; obj.castShadow = false keeps it
  *   out (a floor TileLayer, a background), a draw's alpha sets how much light it blocks, and
  *   setShadowTransparent lets its color tint the light
+ * - Set light.glow for a soft hazy glow over a light, like a lamp at night; it is added over the lit scene after the
+ *   lightmap, so it shows in the dark and sits in front of everything there
  * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
  * @namespace LightSystem
  */
@@ -12533,6 +12851,7 @@ class LightSystemPlugin
             // again on a context restore, the canvas may have changed since
             if (lightSystem.textureSizeAuto)
                 lightSystem.textureSize = mainCanvasSize.copy();
+            lightSystem.clampTextureSizes();
 
             // allocate the lightmap texture with null data at textureSize
             lightSystem.texture = glContext.createTexture();
@@ -12724,6 +13043,7 @@ class LightSystemPlugin
             const ls = lightSystem;
 
             // make the resources the first time, and again when a size changed
+            ls.clampTextureSizes();
             if (!ls.shadowMap || ls.shadowMapSize !== ls.shadowMapSizeAllocated
                 || ls.shadowTextureSize !== ls.shadowTextureSizeAllocated)
             {
@@ -12911,8 +13231,14 @@ class LightSystemPlugin
             //    is, and any debug text / future draw could sample the lightmap)
             if (glActiveTexture)
                 glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
-            setAdditiveBlendMode(prevAdditive);
             glSetInstancedMode(true);
+
+            // 7. the lights' glows, added over the lit scene so the darkness does not dim them
+            setAdditiveBlendMode();
+            for (const o of engineObjects)
+                o instanceof Light && !o.destroyed && o.renderGlow();
+            glFlush();
+            setAdditiveBlendMode(prevAdditive);
         }
         function lightSystemContextLost()
         {
@@ -12931,6 +13257,17 @@ class LightSystemPlugin
         }
     }
 
+    /** Bring the sizes of the textures it makes down to what the device can make: shadowMapSize, shadowTextureSize
+     *  and a textureSize given by hand; called before they are made, so a size too big falls back instead of failing */
+    clampTextureSizes()
+    {
+        this.shadowMapSize = glClampTextureSize(this.shadowMapSize);
+        this.shadowTextureSize = glClampTextureSize(this.shadowTextureSize);
+        const size = this.textureSize;
+        if (size)
+            this.textureSize = vec2(glClampTextureSize(size.x), glClampTextureSize(size.y));
+    }
+
     /** Draw a single Light's falloff blob into the currently bound lightmap.
      *  Called by Light.renderLight() during the plugin's render pass.
      *  @param {Light} light */
@@ -13080,6 +13417,14 @@ class Light extends EngineObject
          *  or torch that holds it, or the player carrying it, does not block it; it has to reach past that object's
          *  corners, about half its diagonal and a little more, or dark rays run out from them */
         this.shadowCore = 0;
+        /** @property {number} - Size across of a soft hazy glow drawn over the light, like a lamp at night, 0 for
+         *  none; it is added over the lit scene, in front of everything there */
+        this.glow = 0;
+        /** @property {number} - How fast the glow fades from its middle: 1 by default, .5 a wide haze, 2 a tight
+         *  bright core */
+        this.glowFalloff = 1;
+        /** @type {TileInfo|undefined} */
+        this.glowTileInfo = undefined; // the whole glow texture, kept for the falloff it was made for
     }
 
     /** Lights are invisible in the main render pass — they only contribute
@@ -13093,6 +13438,20 @@ class Light extends EngineObject
     {
         lightSystem && lightSystem.drawLight(this);
     }
+
+    /** Draw this light's glow, soft and round, its glow size across and in its color, added over the lit scene;
+     *  called by LightSystemPlugin after the lightmap is applied */
+    renderGlow()
+    {
+        if (!(this.glow > 0)) return;
+        const size = vec2(this.glow);
+        if (!isOnScreen(this.pos, size)) return;
+        const texture = engineGlowTexture(this.glowFalloff);
+        if (!texture) return;
+        if (this.glowTileInfo?.textureInfo !== texture)
+            this.glowTileInfo = new TileInfo(vec2(), texture.size, texture);
+        drawTile(this.pos, size, this.glowTileInfo, this.color, 0, false, undefined, true, false);
+    }
 }
 
 /**
@@ -19724,9 +20083,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;
@@ -20902,15 +21262,7 @@ class Matrix4
     static rotation(euler, matrix=new Matrix4)
     {
         false&&ASSERT_VECTOR3_VALID(euler);
-        const cx = cos(euler.x), sx = sin(euler.x);
-        const cy = cos(euler.y), sy = sin(euler.y);
-        const cz = cos(euler.z), sz = sin(euler.z);
-        const m = matrix.m;
-        // R = Ry * Rx * Rz written out, column major, every element set so a reused matrix comes out clean
-        m[0] = cy*cz + sy*sx*sz;  m[1] = cx*sz;  m[2]  = -sy*cz + cy*sx*sz; m[3] = 0;
-        m[4] = -cy*sz + sy*sx*cz; m[5] = cx*cz;  m[6]  = sy*sz + cy*sx*cz;  m[7] = 0;
-        m[8] = sy*cx;             m[9] = -sx;    m[10] = cy*cx;             m[11] = 0;
-        m[12] = m[13] = m[14] = 0; m[15] = 1;
+        matrix4RotationAt(matrix.m, 0, euler);
         return matrix;
     }
 
@@ -21158,24 +21510,54 @@ class Matrix4
  * @memberof Math3D
  */
 function buildMatrix(pos, rotation, scale, matrix=new Matrix4)
+{
+    false&&ASSERT(matrix instanceof Matrix4, 'the matrix to write into must be a Matrix4');
+    matrix4Compose(matrix.m, 0, pos, rotation, scale);
+    return matrix;
+}
+
+// the rotation matrix of euler angles written into 16 floats of an array at k
+function matrix4RotationAt(m, k, euler)
+{
+    const cx = cos(euler.x), sx = sin(euler.x);
+    const cy = cos(euler.y), sy = sin(euler.y);
+    const cz = cos(euler.z), sz = sin(euler.z);
+    // R = Ry * Rx * Rz written out, column major, every element set so a reused matrix comes out clean
+    m[k]   = cy*cz + sy*sx*sz;  m[k+1] = cx*sz;  m[k+2]  = -sy*cz + cy*sx*sz; m[k+3] = 0;
+    m[k+4] = -cy*sz + sy*sx*cz; m[k+5] = cx*cz;  m[k+6]  = sy*sz + cy*sx*cz;  m[k+7] = 0;
+    m[k+8] = sy*cx;             m[k+9] = -sx;    m[k+10] = cy*cx;             m[k+11] = 0;
+    m[k+12] = m[k+13] = m[k+14] = 0; m[k+15] = 1;
+}
+
+// the transform buildMatrix makes, written into 16 floats of an array at k, so an instance buffer takes it straight in
+// the rotation columns are scaled and the position dropped in, instead of multiplying three matrices, each value
+// worked out whole and stored once; InstancedMesh3D.setTransforms writes the same expressions for many at a time
+function matrix4Compose(m, k, pos, rotation, scale)
 {
     false&&ASSERT(!pos || isVector3(pos), 'pos must be a Vector3', pos);
     false&&ASSERT(!scale || isVector3(scale), 'scale must be a Vector3', scale);
-    false&&ASSERT(matrix instanceof Matrix4, 'the matrix to write into must be a Matrix4');
-    // scale the rotation columns and drop the position in, instead of multiplying three matrices
+    const scaleX = scale ? scale.x : 1, scaleY = scale ? scale.y : 1, scaleZ = scale ? scale.z : 1;
     // an object that is not turned at all is most of a big scene, and identity is what the six
     // trig calls would have worked out to anyway
-    const turned = rotation && (rotation.x || rotation.y || rotation.z), m = matrix.m;
-    turned ? Matrix4.rotation(rotation, matrix) : m.set(matrix4Identity);
-    if (scale)
+    if (rotation && (rotation.x || rotation.y || rotation.z))
     {
-        m[0] *= scale.x; m[1] *= scale.x; m[2]  *= scale.x;
-        m[4] *= scale.y; m[5] *= scale.y; m[6]  *= scale.y;
-        m[8] *= scale.z; m[9] *= scale.z; m[10] *= scale.z;
+        false&&ASSERT_VECTOR3_VALID(rotation);
+        const cx = cos(rotation.x), sx = sin(rotation.x);
+        const cy = cos(rotation.y), sy = sin(rotation.y);
+        const cz = cos(rotation.z), sz = sin(rotation.z);
+        // R = Ry * Rx * Rz written out, column major, as matrix4RotationAt, each column times its scale
+        m[k]   = (cy*cz + sy*sx*sz) * scaleX;  m[k+1] = cx*sz * scaleX; m[k+2]  = (-sy*cz + cy*sx*sz) * scaleX;
+        m[k+4] = (-cy*sz + sy*sx*cz) * scaleY; m[k+5] = cx*cz * scaleY; m[k+6]  = (sy*sz + cy*sx*cz) * scaleY;
+        m[k+8] = sy*cx * scaleZ;               m[k+9] = -sx * scaleZ;   m[k+10] = cy*cx * scaleZ;
     }
-    if (pos)
-        m[12] = pos.x, m[13] = pos.y, m[14] = pos.z;
-    return matrix;
+    else
+    {
+        m[k]   = scaleX; m[k+1] = 0;      m[k+2]  = 0;
+        m[k+4] = 0;      m[k+5] = scaleY; m[k+6]  = 0;
+        m[k+8] = 0;      m[k+9] = 0;      m[k+10] = scaleZ;
+    }
+    m[k+3] = m[k+7] = m[k+11] = 0; m[k+15] = 1;
+    m[k+12] = pos ? pos.x : 0, m[k+13] = pos ? pos.y : 0, m[k+14] = pos ? pos.z : 0;
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -21583,6 +21965,9 @@ const RENDER3D_VERTEX_BYTES = RENDER3D_VERTEX_FLOATS * 4;
 // uv rect (12); constants for one draw, one per instance for a batch; the shader derives the normal matrix
 const RENDER3D_INSTANCE_FLOATS = 24;
 const RENDER3D_INSTANCE_BYTES = RENDER3D_INSTANCE_FLOATS * 4;
+// an InstancedMesh3D keeps them apart: 16 floats of matrix, and 8 of tint and uv rect uploaded only when they change
+const RENDER3D_MATRIX_FLOATS = 16;
+const RENDER3D_COLOR_FLOATS = 8;
 const RENDER3D_INSTANCE_ATTRIBS = [[4, 4, 0], [5, 4, 16], [6, 4, 32], [7, 4, 48], [11, 4, 64], [12, 4, 80]];
 const RENDER3D_VERTEX_INPUTS =
     'layout(location=0) in vec3 p;layout(location=1) in vec3 n;layout(location=2) in vec2 t;layout(location=3) in vec4 c;' +
@@ -21626,22 +22011,49 @@ function render3DCanDraw()
 }
 
 // the draw state fields a batch is drawn under; lights and fog are not captured, they are read live at flush
-// the three functions below write them out by hand for speed, so a new field goes in all four; emissiveMapColor is
-// compared by its values, so two objects with equal colors batch
+// each is an accessor on the plugin over render3D.drawState, and a real change moves render3D.stateVersion, so a
+// batch checks that one number at each draw while the state holds; the three functions below write the fields out
+// by hand for speed, so a new field goes in all four, in drawState and gets an accessor; emissiveMapColor is
+// compared by its rgb, so two objects with equal colors batch
+/** The draw state's values, behind render3D's accessors, and the rgb emissiveMapColor had when it was set
+ *  @typedef {Object} Render3DDrawState
+ *  @property {boolean} blend
+ *  @property {boolean} additive
+ *  @property {boolean} depthTest
+ *  @property {boolean} depthWrite
+ *  @property {boolean} cullBackFaces
+ *  @property {boolean} mirrored
+ *  @property {boolean} lighting
+ *  @property {number} emissive
+ *  @property {boolean} receiveShadow
+ *  @property {number} specular
+ *  @property {boolean} pixelated
+ *  @property {Shader|undefined} shader
+ *  @property {TextureInfo|undefined} normalMap
+ *  @property {number} normalScale
+ *  @property {number} shininess
+ *  @property {number} reflectivity
+ *  @property {TextureInfo|undefined} emissiveMap
+ *  @property {Color} emissiveMapColor
+ *  @property {number} emissiveR
+ *  @property {number} emissiveG
+ *  @property {number} emissiveB
+ *  @memberof Render3D */
 const RENDER3D_STATE_FIELDS = ['blend', 'additive', 'depthTest', 'depthWrite', 'cullBackFaces', 'mirrored', 'lighting',
     'emissive', 'receiveShadow', 'specular', 'pixelated', 'shader', 'normalMap', 'normalScale', 'shininess',
     'reflectivity', 'emissiveMap', 'emissiveMapColor'];
 
-// a copy of the draw state in one fixed shape, the fields of RENDER3D_STATE_FIELDS written out so the
-// compare below stays a handful of direct reads, it runs for every instance drawn
+// a copy of the draw state in one fixed shape, the fields of RENDER3D_STATE_FIELDS written out, and the version
+// it was taken at
 function render3DCaptureBatchState()
 {
-    const r = render3D;
-    return {blend: r.blend, additive: r.additive, depthTest: r.depthTest, depthWrite: r.depthWrite,
-        cullBackFaces: r.cullBackFaces, mirrored: r.mirrored, lighting: r.lighting, emissive: r.emissive,
-        receiveShadow: r.receiveShadow, specular: r.specular, pixelated: r.pixelated, shader: r.shader,
-        normalMap: r.normalMap, normalScale: r.normalScale, shininess: r.shininess, reflectivity: r.reflectivity,
-        emissiveMap: r.emissiveMap, emissiveMapColor: (r.emissiveMapColor || WHITE).copy()}; // the caller may change it
+    const r = render3D, d = r.drawState;
+    return {blend: d.blend, additive: d.additive, depthTest: d.depthTest, depthWrite: d.depthWrite,
+        cullBackFaces: d.cullBackFaces, mirrored: d.mirrored, lighting: d.lighting, emissive: d.emissive,
+        receiveShadow: d.receiveShadow, specular: d.specular, pixelated: d.pixelated, shader: d.shader,
+        normalMap: d.normalMap, normalScale: d.normalScale, shininess: d.shininess, reflectivity: d.reflectivity,
+        emissiveMap: d.emissiveMap, emissiveMapColor: (d.emissiveMapColor || WHITE).copy(), // the caller may change it
+        version: r.stateVersion};
 }
 
 // put a captured draw state back, written out the same way; the transparent stage does this for every queued draw
@@ -21655,21 +22067,23 @@ function render3DApplyBatchState(s)
     r.reflectivity = s.reflectivity, r.emissiveMap = s.emissiveMap, r.emissiveMapColor = s.emissiveMapColor;
 }
 
-// true when the current draw state differs from a captured one, so a pending batch must flush first
+// true when the current draw state differs from a captured one, so a pending batch must flush first; it runs for
+// every instance drawn, so while nothing was set since the capture it checks the version alone
 function render3DStateChanged(s)
 {
     const r = render3D;
-    return r.blend !== s.blend || r.additive !== s.additive || r.depthTest !== s.depthTest
-        || r.depthWrite !== s.depthWrite || r.cullBackFaces !== s.cullBackFaces || r.mirrored !== s.mirrored
-        || r.lighting !== s.lighting || r.emissive !== s.emissive || r.receiveShadow !== s.receiveShadow
-        || r.specular !== s.specular || r.pixelated !== s.pixelated || r.shader !== s.shader
-        || r.normalMap !== s.normalMap || r.normalScale !== s.normalScale || r.shininess !== s.shininess
-        || r.reflectivity !== s.reflectivity || r.emissiveMap !== s.emissiveMap
-        || render3DColorChanged(r.emissiveMapColor || WHITE, s.emissiveMapColor);
-}
-
-// whether two colors differ in their rgb, for the batch key's emissiveMapColor
-function render3DColorChanged(a, b) { return a.r !== b.r || a.g !== b.g || a.b !== b.b;
+    if (s.version === r.stateVersion) return false;
+    const d = r.drawState, c = s.emissiveMapColor;
+    if (d.blend !== s.blend || d.additive !== s.additive || d.depthTest !== s.depthTest
+        || d.depthWrite !== s.depthWrite || d.cullBackFaces !== s.cullBackFaces || d.mirrored !== s.mirrored
+        || d.lighting !== s.lighting || d.emissive !== s.emissive || d.receiveShadow !== s.receiveShadow
+        || d.specular !== s.specular || d.pixelated !== s.pixelated || d.shader !== s.shader
+        || d.normalMap !== s.normalMap || d.normalScale !== s.normalScale || d.shininess !== s.shininess
+        || d.reflectivity !== s.reflectivity || d.emissiveMap !== s.emissiveMap
+        || d.emissiveR !== c.r || d.emissiveG !== c.g || d.emissiveB !== c.b)
+        return true;
+    s.version = r.stateVersion; // set and set back to what it was: the batch goes on, checking the version again
+    return false;
 }
 
 // whether a sphere is inside the view, or the shadow map's box during the shadow pass, without a vector
@@ -21747,7 +22161,10 @@ function render3DMaxScale(m)
 // how far a matrix at offset k can move a point that is one unit from its origin, for a bounding sphere: the
 // longest axis when the axes are square to each other, more when they are not, as a turned child under a parent
 // scaled on one axis leaves them; the axes' dot products bound the largest stretch by their largest row sum
-function render3DMaxStretch(m, k=0)
+function render3DMaxStretch(m, k=0) { return render3DMaxStretchSquared(m, k) ** .5; }
+
+// the same, squared, for bounds that grow many times before they are read
+function render3DMaxStretchSquared(m, k=0)
 {
     const xx = m[k]*m[k] + m[k+1]*m[k+1] + m[k+2]*m[k+2];
     const yy = m[k+4]*m[k+4] + m[k+5]*m[k+5] + m[k+6]*m[k+6];
@@ -21755,7 +22172,7 @@ function render3DMaxStretch(m, k=0)
     const xy = abs(m[k]*m[k+4] + m[k+1]*m[k+5] + m[k+2]*m[k+6]);
     const xz = abs(m[k]*m[k+8] + m[k+1]*m[k+9] + m[k+2]*m[k+10]);
     const yz = abs(m[k+4]*m[k+8] + m[k+5]*m[k+9] + m[k+6]*m[k+10]);
-    return max(xx + xy + xz, yy + xy + yz, zz + xz + yz) ** .5;
+    return max(xx + xy + xz, yy + xy + yz, zz + xz + yz);
 }
 
 // a quad as a strip from its center and half axes, the same corner order as render3DQuadStrip
@@ -21805,10 +22222,11 @@ function render3DDrawObjects(objects)
     render3DSetObjectState();
 }
 
-// add a draw of a mesh to its batch; a batch is one mesh under one texture and draw state, so a change flushes it
+// add a draw of a mesh to its batch; a batch is one mesh under one texture and draw state, so a change flushes it,
+// and under one winding: a mirroring transform, one with a negative determinant, turns it around
 function render3DInstance(mesh, matrix, tileInfo, color)
 {
-    const k = render3DInstanceSlot(mesh, render3DTextureOf(tileInfo)), data = mesh.instanceData;
+    const k = render3DInstanceSlot(mesh, render3DTextureOf(tileInfo), render3DMirrors(matrix)), data = mesh.instanceData;
     data.set(matrix.m, k);
     // the tint; this batch is never blended, so in the shadow pass the depth shader cuts it by its texture alpha
     // alone, a see through caster draws blended instead and is cut by its tint alpha too
@@ -21819,14 +22237,18 @@ function render3DInstance(mesh, matrix, tileInfo, color)
 
 // make room for one more instance of a mesh under a texture and the current draw state, flushing a batch that
 // differs first, and return where its 24 floats go in mesh.instanceData: the matrix, the tint and the uv rect
-function render3DInstanceSlot(mesh, textureInfo)
+// drawMesh passes whether its matrix mirrors, and its batch then culls by the mesh and winds by that at the flush,
+// so it never sets the draw state for them, which would move the state's version at every draw
+function render3DInstanceSlot(mesh, textureInfo, mirrored)
 {
     const r = render3D;
-    if (mesh.instanceCount && (mesh.instanceTextureInfo !== textureInfo || render3DStateChanged(mesh.instanceState)))
+    if (mesh.instanceCount && (mesh.instanceTextureInfo !== textureInfo || mesh.instanceMirrored !== mirrored
+        || render3DStateChanged(mesh.instanceState)))
         render3DFlushInstances(mesh);
     if (!mesh.instanceCount)
     {
         mesh.instanceTextureInfo = textureInfo;
+        mesh.instanceMirrored = mirrored;
         mesh.instanceState = render3DCaptureBatchState();
         r.instanceMeshes.push(mesh);
     }
@@ -21857,7 +22279,10 @@ function render3DFlushInstances(only)
         const buffers = r.instanceBuffers, buffer = buffers[r.instanceBufferIndex = (r.instanceBufferIndex + 1) % buffers.length];
         gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
         gl.bufferData(gl.ARRAY_BUFFER, mesh.instanceData, gl.DYNAMIC_DRAW, 0, count * RENDER3D_INSTANCE_FLOATS);
-        render3DDrawInstanced(mesh, buffer, count, mesh.instanceTextureInfo, mesh.instanceState);
+        const state = mesh.instanceState;
+        if (mesh.instanceMirrored !== undefined) // a drawMesh batch: culled by its mesh, wound by its matrices
+            state.cullBackFaces = !mesh.doubleSided, state.mirrored = mesh.instanceMirrored;
+        render3DDrawInstanced(mesh, buffer, count, mesh.instanceTextureInfo, state);
     }
     if (!only)
         r.instanceMeshes.length = 0;
@@ -21872,13 +22297,16 @@ function render3DFlushInstances(only)
 // the arrays are turned on with their instance divisor for this one call and both are turned off after: a single
 // draw reads these slots as constant attributes, and in Firefox a draw that reads a constant through a slot whose
 // divisor is set leaves the next batch on that slot reading the wrong values
-function render3DDrawInstanced(mesh, buffer, count, textureInfo, state)
+// colorBuffer holds the tint and uv rect apart from the matrices, as an InstancedMesh3D keeps them
+function render3DDrawInstanced(mesh, buffer, count, textureInfo, state, colorBuffer)
 {
-    const gl = glContext;
-    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    const gl = glContext, matrixBytes = RENDER3D_MATRIX_FLOATS * 4;
     for (const [location, size, offset] of RENDER3D_INSTANCE_ATTRIBS)
     {
-        gl.vertexAttribPointer(location, size, gl.FLOAT, false, RENDER3D_INSTANCE_BYTES, offset);
+        const inColors = colorBuffer && offset >= matrixBytes;
+        const stride = !colorBuffer ? RENDER3D_INSTANCE_BYTES : inColors ? RENDER3D_COLOR_FLOATS * 4 : matrixBytes;
+        gl.bindBuffer(gl.ARRAY_BUFFER, inColors ? colorBuffer : buffer);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, stride, inColors ? offset - matrixBytes : offset);
         gl.enableVertexAttribArray(location);
         gl.vertexAttribDivisor(location, 1);
     }
@@ -21923,11 +22351,36 @@ function render3DCollectLights()
         for (const light of lights)
             distances.set(light, light.directional ? -1 : light.getWorldPos3D().distanceSquared(cameraPos));
         lights.sort((a, b)=> distances.get(a) - distances.get(b));
+        // the light that casts the shadows keeps a slot however far it is, in place of the farthest
+        const caster = render3DShadowCaster();
+        if (caster && lights.indexOf(caster) >= RENDER3D_MAX_LIGHTS)
+            lights[RENDER3D_MAX_LIGHTS - 1] = caster;
         lights.length = RENDER3D_MAX_LIGHTS;
     }
     return lights;
 }
 
+// the spotlight that casts the shadows in place of the sun: render3D.shadowLight while it is a light that is on
+// and has a cone, undefined for the sun
+function render3DShadowCaster()
+{
+    const light = render3D.shadowLight;
+    return light && !light.destroyed && !light.directional && light.coneAngle > 0 && light.radius > 0 &&
+        light.intensity > 0 && light.color.a > 0 ? light : undefined;
+}
+
+// a light's cone as the four numbers the shader gets: the way it shines, scaled so that its dot with the way to
+// a point, less the fourth number, is 0 at the edge of the cone and 1 where its fade starts; a light with no cone
+// gets numbers that make it 1 every way
+function render3DLightCone(light)
+{
+    const angle = light.directional ? 0 : min(light.coneAngle, PI);
+    if (!(angle > 0)) return [0, 0, 0, -1];
+    const outer = cos(angle), inner = cos(angle * (1 - clamp(light.coneSoftness)));
+    const k = 1 / max(inner - outer, 1e-4), forward = light.getForward3D();
+    return [forward.x * k, forward.y * k, forward.z * k, outer * k];
+}
+
 // unit circle directions for a number of sides, [cos, sin, cos, sin, ...] including the closing point, cached
 const render3DCircleCache = new Map;
 function render3DCircle(sides)
@@ -21979,7 +22432,15 @@ class Render3DPlugin
     {
         false&&ASSERT(!render3D, 'Render3D plugin already initialized');
         render3D = this;
-        false&&ASSERT(Object.keys(render3DCaptureBatchState()).join() === RENDER3D_STATE_FIELDS.join(),
+        // the draw state, read at each draw through the accessors below the constructor
+        /** @type {Render3DDrawState} */
+        this.drawState = {blend: false, additive: false, depthTest: true, depthWrite: true, cullBackFaces: false,
+            mirrored: false, lighting: true, emissive: 0, receiveShadow: true, specular: 0, pixelated: false,
+            shader: undefined, normalMap: undefined, normalScale: 1, shininess: 16, reflectivity: 0,
+            emissiveMap: undefined, emissiveMapColor: WHITE, emissiveR: 1, emissiveG: 1, emissiveB: 1};
+        /** @property {number} - Goes up when a draw state field changes, so a batch sees at a glance that none did */
+        this.stateVersion = 0;
+        false&&ASSERT(Object.keys(render3DCaptureBatchState()).join() === [...RENDER3D_STATE_FIELDS, 'version'].join(),
             'the batch state functions must list RENDER3D_STATE_FIELDS');
 
         /** @property {Camera3D} - The camera */
@@ -22025,8 +22486,16 @@ class Render3DPlugin
         // shadows
         /** @property {boolean} - Cast real shadows from the sun, off by default and free when off */
         this.shadows = false;
+        /** @property {number} - How far a sound played with playSound is heard when it was made with no range of
+         *  its own, in world units; further than the 2D soundDefaultRange, a 3D world is bigger */
+        this.soundDefaultRange = 100;
         /** @property {number} - Size of the shadow map in pixels, bigger is sharper and slower */
         this.shadowMapSize = 1024;
+        /** @property {Light3D|undefined} - A spotlight, a Light3D with a coneAngle, to cast the shadows in place
+         *  of the sun, a flashlight in the dark: the shadow map looks down its cone, as far as its radius, and the
+         *  sun still lights the scene but casts none; undefined for the sun, as is a light that is off or has no cone
+         *  @type {Light3D|undefined} */
+        this.shadowLight = undefined;
         /** @property {number} - World size the shadow map covers around shadowCenter, smaller is sharper; it is a
          *  square facing the light, so it turns as the light does, and about 1.5 times an area's width covers it from
          *  any angle */
@@ -22039,50 +22508,6 @@ class Render3DPlugin
         /** @property {number} - How much to blur the shadow edges */
         this.shadowSoftness = 1;
 
-        // draw state, read at each draw
-        /** @property {boolean} - Apply lighting, when false draws plain vertex color times texture and casts no shadow;
-         *  off for billboards, lines, ribbons and soft discs, an object sets emissive instead */
-        this.lighting = true;
-        /** @property {number} - How much a surface lights itself, set per object by its emissive */
-        this.emissive = 0;
-        /** @property {boolean} - Additive blending instead of alpha, in the transparent stage */
-        this.additive = false;
-        /** @property {boolean} - Test against the depth buffer, reset to true before each object and callback; a draw
-         *  with it off goes over what was drawn before it and under what is drawn after, by render order, which
-         *  ends the batch of meshes before it, so one per object costs a draw per object */
-        this.depthTest = true;
-        /** @property {boolean} - Write to the depth buffer, owned by the stages: on for opaque, off for transparent */
-        this.depthWrite = true;
-        // batch state set by drawMesh from each mesh: whether its back faces are skipped, off for strips so they
-        // show from both sides, and whether its transform mirrors it so the other winding is the front
-        this.cullBackFaces = false;
-        this.mirrored = false;
-        /** @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; shininess sets its size */
-        this.specular = 0;
-        /** @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 */
-        this.shininess = 16;
-        /** @property {TextureInfo|undefined} - Normal map for the next draws, set from each object's normalMap
-         *  @type {TextureInfo|undefined} */
-        this.normalMap = undefined;
-        /** @property {number} - How strongly the normal map bends the surface, set from each object's normalScale */
-        this.normalScale = 1;
-        /** @property {number} - How much the surface reflects the sky, 0 to 1, set from each object's reflectivity */
-        this.reflectivity = 0;
-        /** @property {TextureInfo|undefined} - Emissive map for the next draws, set from each object's emissiveMap
-         *  @type {TextureInfo|undefined} */
-        this.emissiveMap = undefined;
-        /** @property {Color} - Multiplies the emissive map, set from each object's emissiveMapColor */
-        this.emissiveMapColor = WHITE;
-        /** @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} */
-        this.shader = undefined;
-        /** @property {boolean} - Darken by the shadow map when shadows are on, turn it off for things that should stay
-         *  lit inside a shadow */
-        this.receiveShadow = true;
-
         // the pass
         /** @property {Function|undefined} - Draw solid world here, it runs again for shadows so only draw in it
          *  @type {Function|undefined} */
@@ -22105,9 +22530,6 @@ class Render3DPlugin
         /** @property {boolean} - Sample textures through mipmaps so they do not shimmer in the distance, false uses
          *  each texture's own filtering like 2D */
         this.mipmaps = true;
-        /** @property {boolean} - Draw state: keep texture pixels hard edged, no mipmaps and no blending between them,
-         *  set per object by pixelated */
-        this.pixelated = false;
         /** @property {number} - Anisotropic filtering for textures seen at an angle, 1 to 16, 1 is off; needs mipmaps */
         this.anisotropy = 4;
 
@@ -22151,7 +22573,6 @@ class Render3DPlugin
         this.cameraBack = vec3(0, 0, 1); // its opposite, the normal of camera facing draws
 
         // internal state
-        this.blend = false;          // blending on, set by the stages
         /** @type {Array<Array<number>>} */
         this.frustumPlanes = [];     // the view as six inward planes [x, y, z, w]
         /** @type {Array<Array<number>>} */
@@ -22191,6 +22612,9 @@ class Render3DPlugin
         this.passIsDefault = true;   // the running pass is the default layer, the only one shadowed
         this.lightPositions = new Float32Array(RENDER3D_MAX_LIGHTS * 4); // Light3D uniforms, filled each pass
         this.lightColors = new Float32Array(RENDER3D_MAX_LIGHTS * 4);
+        this.lightCones = new Float32Array(RENDER3D_MAX_LIGHTS * 4); // each light's cone, see render3DLightCone
+        this.shadowLightIndex = -1;  // which of the lights sent casts the shadows, -1 for the sun
+        this.shadowDepthBias = 0;    // the bias as the shadow lookup takes it, set with the shadow matrix
 
         // the stream of immediate mode draws
         /** @type {WebGLBuffer|undefined} */
@@ -22218,6 +22642,116 @@ class Render3DPlugin
         engineAddPlugin(undefined, render3DRender, render3DContextLost, render3DContextRestored, render3DPreRender);
     }
 
+    ///////////////////////////////////////////////////////////////////////////
+    // Draw state: each field an accessor over drawState, whose setter moves stateVersion only on a real change
+
+    /** Apply lighting, when false draws plain vertex color times texture and casts no shadow;
+     *  off for billboards, lines, ribbons and soft discs, an object sets emissive instead
+     *  @return {boolean} */
+    get lighting() { return this.drawState.lighting; }
+    set lighting(v) { const d = this.drawState; d.lighting === v || (d.lighting = v, ++this.stateVersion); }
+
+    /** How much a surface lights itself, set per object by its emissive
+     *  @return {number} */
+    get emissive() { return this.drawState.emissive; }
+    set emissive(v) { const d = this.drawState; d.emissive === v || (d.emissive = v, ++this.stateVersion); }
+
+    /** Additive blending instead of alpha, in the transparent stage
+     *  @return {boolean} */
+    get additive() { return this.drawState.additive; }
+    set additive(v) { const d = this.drawState; d.additive === v || (d.additive = v, ++this.stateVersion); }
+
+    /** Test against the depth buffer, reset to true before each object and callback; a draw
+     *  with it off goes over what was drawn before it and under what is drawn after, by render order, which
+     *  ends the batch of meshes before it, so one per object costs a draw per object
+     *  @return {boolean} */
+    get depthTest() { return this.drawState.depthTest; }
+    set depthTest(v) { const d = this.drawState; d.depthTest === v || (d.depthTest = v, ++this.stateVersion); }
+
+    /** Write to the depth buffer, owned by the stages: on for opaque, off for transparent
+     *  @return {boolean} */
+    get depthWrite() { return this.drawState.depthWrite; }
+    set depthWrite(v) { const d = this.drawState; d.depthWrite === v || (d.depthWrite = v, ++this.stateVersion); }
+
+    /** Skip back faces, set by drawMesh from each mesh: off for strips so they show from
+     *  both sides
+     *  @return {boolean} */
+    get cullBackFaces() { return this.drawState.cullBackFaces; }
+    set cullBackFaces(v) { const d = this.drawState; d.cullBackFaces === v || (d.cullBackFaces = v, ++this.stateVersion); }
+
+    /** The transform mirrors the draw, so the other winding is the front, set by drawMesh
+     *  from each transform
+     *  @return {boolean} */
+    get mirrored() { return this.drawState.mirrored; }
+    set mirrored(v) { const d = this.drawState; d.mirrored === v || (d.mirrored = v, ++this.stateVersion); }
+
+    /** Strength of the highlight where the sun and the Light3D objects reflect, 0 is none and
+     *  1 adds a light's full color at its brightest; shininess sets its size
+     *  @return {number} */
+    get specular() { return this.drawState.specular; }
+    set specular(v) { const d = this.drawState; d.specular === v || (d.specular = v, ++this.stateVersion); }
+
+    /** The highlight's exponent, how small and sharp it is: 4 is broad like rubber, 100 sharp
+     *  like polished metal; set from each object's shininess
+     *  @return {number} */
+    get shininess() { return this.drawState.shininess; }
+    set shininess(v) { const d = this.drawState; d.shininess === v || (d.shininess = v, ++this.stateVersion); }
+
+    /** Normal map for the next draws, set from each object's normalMap
+     *  @return {TextureInfo|undefined} */
+    get normalMap() { return this.drawState.normalMap; }
+    set normalMap(v) { const d = this.drawState; d.normalMap === v || (d.normalMap = v, ++this.stateVersion); }
+
+    /** How strongly the normal map bends the surface, set from each object's normalScale
+     *  @return {number} */
+    get normalScale() { return this.drawState.normalScale; }
+    set normalScale(v) { const d = this.drawState; d.normalScale === v || (d.normalScale = v, ++this.stateVersion); }
+
+    /** How much the surface reflects the sky, 0 to 1, set from each object's reflectivity
+     *  @return {number} */
+    get reflectivity() { return this.drawState.reflectivity; }
+    set reflectivity(v) { const d = this.drawState; d.reflectivity === v || (d.reflectivity = v, ++this.stateVersion); }
+
+    /** Emissive map for the next draws, set from each object's emissiveMap
+     *  @return {TextureInfo|undefined} */
+    get emissiveMap() { return this.drawState.emissiveMap; }
+    set emissiveMap(v) { const d = this.drawState; d.emissiveMap === v || (d.emissiveMap = v, ++this.stateVersion); }
+
+    /** Multiplies the emissive map, set from each object's emissiveMapColor; compared by its rgb, so a Color
+     *  changed in place is seen when it is set again, and undefined is white
+     *  @return {Color} */
+    get emissiveMapColor() { return this.drawState.emissiveMapColor; }
+    set emissiveMapColor(v)
+    {
+        const d = this.drawState, c = v || WHITE;
+        d.emissiveMapColor = v;
+        if (c.r !== d.emissiveR || c.g !== d.emissiveG || c.b !== d.emissiveB)
+            d.emissiveR = c.r, d.emissiveG = c.g, d.emissiveB = c.b, ++this.stateVersion;
+    }
+
+    /** Custom Shader for the next draws, set from each object's shader; undefined draws
+     *  with the plugin's own
+     *  @return {Shader|undefined} */
+    get shader() { return this.drawState.shader; }
+    set shader(v) { const d = this.drawState; d.shader === v || (d.shader = v, ++this.stateVersion); }
+
+    /** Darken by the shadow map when shadows are on, turn it off for things that should
+     *  stay lit inside a shadow
+     *  @return {boolean} */
+    get receiveShadow() { return this.drawState.receiveShadow; }
+    set receiveShadow(v) { const d = this.drawState; d.receiveShadow === v || (d.receiveShadow = v, ++this.stateVersion); }
+
+    /** Keep texture pixels hard edged, no mipmaps and no blending between them, set per
+     *  object by pixelated
+     *  @return {boolean} */
+    get pixelated() { return this.drawState.pixelated; }
+    set pixelated(v) { const d = this.drawState; d.pixelated === v || (d.pixelated = v, ++this.stateVersion); }
+
+    /** Blending on, set by the stages
+     *  @return {boolean} */
+    get blend() { return this.drawState.blend; }
+    set blend(v) { const d = this.drawState; d.blend === v || (d.blend = v, ++this.stateVersion); }
+
     ///////////////////////////////////////////////////////////////////////////
     // Matrices and picking
 
@@ -22327,7 +22861,8 @@ class Render3DPlugin
     }
 
     /** Play a sound at a 3D position, quieter with distance from the camera and panned by its side, like Sound.play
-     *  with a 2D position
+     *  with a 2D position; a sound made with no range of its own is heard to soundDefaultRange, 100, and one given
+     *  a range keeps it
      *  @param {Sound} sound
      *  @param {Vector3} pos3D
      *  @param {number} [volume]
@@ -22341,7 +22876,9 @@ class Render3DPlugin
         // the 3D range fade and pan, Sound.play with no position does the rest
         false&&ASSERT(sound instanceof Sound, 'sound must be a Sound');
         false&&ASSERT(isVector3(pos3D), 'pos3D must be a vec3');
-        const offset = pos3D.subtract(this.camera.pos), range = sound.range;
+        // a sound with no range of its own is heard further in 3D than in 2D
+        const offset = pos3D.subtract(this.camera.pos);
+        const range = sound.rangeIsDefault ? this.soundDefaultRange : sound.range;
         if (range)
         {
             const distance = offset.length();
@@ -22405,15 +22942,15 @@ class Render3DPlugin
         if (this.frustumCulling && !render3DSphereVisible(m[12], m[13], m[14], mesh.radius * render3DMaxStretch(m)))
             return;
         // the mesh says whether its back faces can be skipped, and a mirroring transform, one with a negative
-        // determinant, turns the winding around so the other one is its front
-        const cullBackFaces = this.cullBackFaces, mirrored = this.mirrored;
-        this.cullBackFaces = !mesh.doubleSided;
-        this.mirrored = render3DMirrors(matrix);
-        // the stage draws the batch at its end
+        // determinant, turns the winding around so the other one is its front; the stage draws a batch at its
+        // end, which keys on those itself
         if (!this.blend && this.depthTest && (mesh.instanced ?? this.instancing))
             render3DInstance(mesh, matrix, tileInfo, color);
         else
         {
+            const cullBackFaces = this.cullBackFaces, mirrored = this.mirrored;
+            this.cullBackFaces = !mesh.doubleSided;
+            this.mirrored = render3DMirrors(matrix);
             this.flush();
             render3DFlushBeforeOverlay();
             render3DSetDrawUniforms(matrix, tileInfo, color);
@@ -22421,8 +22958,8 @@ class Render3DPlugin
             glContext.drawElements(glContext.TRIANGLES, mesh.bufferCount, mesh.indexType, 0);
             ++drawCount;
             primitiveCount += mesh.bufferCount / 3;
+            this.cullBackFaces = cullBackFaces, this.mirrored = mirrored;
         }
-        this.cullBackFaces = cullBackFaces, this.mirrored = mirrored;
     }
 
     /** Draw a triangle strip, batched into the stream with the current draw state
@@ -22618,6 +23155,23 @@ class Render3DPlugin
     /** Rebuild the light's view projection around the shadow center, called automatically each frame shadows are on */
     updateShadowMatrix()
     {
+        const caster = render3DShadowCaster();
+        if (caster)
+        {
+            // a spotlight's map looks down its cone with perspective, from just in front of it out to its radius
+            const pos = caster.getWorldPos3D(), forward = caster.getForward3D();
+            const up = abs(forward.y) > .99 ? vec3(0, 0, 1) : vec3(0, 1, 0);
+            const far = caster.radius, near = max(far / 500, .02);
+            const fov = min(min(caster.coneAngle, PI) * 2 + .1, 2.8);
+            this.shadowMatrix = Matrix4.perspective(fov, 1, near, far).multiply(
+                Matrix4.lookAt(pos, pos.add(forward), up).invert());
+            this.shadowPlanes = render3DFrustumPlanes(this.shadowMatrix);
+            // depth is not even with perspective: the lookup divides this by the distance squared, which makes
+            // the bias the same distance in the world near the light and far from it
+            this.shadowDepthBias = this.shadowBias * far * far * near / (far - near);
+            return;
+        }
+        this.shadowDepthBias = this.shadowBias; // the sun's map is flat, its depth even
         false&&ASSERT(this.shadowRange > 0, 'shadowRange must be positive');
         const range = this.shadowRange > 0 ? this.shadowRange : 1, half = range / 2;
         const toSun = this.sunDirection.normalize();
@@ -23047,6 +23601,7 @@ function render3DFragmentSource(fragmentCode)
         'precision highp float;' +
         'uniform vec4 lightDir,lightColor,ambientFog,ambientGround,fogColor,shadowParams;' +
         'uniform vec4 extraLights[' + RENDER3D_MAX_LIGHTS + '],extraLightColors[' + RENDER3D_MAX_LIGHTS + '];' +
+        'uniform vec4 extraLightCones[' + RENDER3D_MAX_LIGHTS + '];' +
         'uniform int extraLightCount;' +
         'uniform vec3 cameraPos;' +
         'uniform vec4 materialParams,emissiveTint,skyTop,skyHorizon,skyBottom;' +
@@ -23055,12 +23610,14 @@ function render3DFragmentSource(fragmentCode)
         'uniform highp sampler2DShadow shadowMap;' +
         'in vec3 P,N;in vec2 T,L;in vec4 C,S;' +
         'out vec4 o;' +
-        // the sun shadow at this fragment, 0 to 1: the light's depth map with a 3x3 blur, outside the map is lit
+        // the shadow at this fragment, 0 to 1: the light's depth map with a 3x3 blur, outside the map is lit; the
+        // sun's map is flat and S.w is 1, a spotlight's has perspective and S.w is the distance from it, where the
+        // bias shrinks by its square to stay the same distance in the world
         'float shadow(){' +
-        'if(shadowParams.x<=0.)return 1.;' +
+        'if(shadowParams.x<=0.||S.w<=0.)return 1.;' +
         'vec3 q=S.xyz/S.w*.5+.5;' +
         'if(any(greaterThanEqual(abs(q-.5),vec3(.5))))return 1.;' +
-        'q.z-=shadowParams.y;' +
+        'q.z-=shadowParams.y/(S.w*S.w);' +
         'float s=0.;' +
         'for(int x=-1;x<=1;++x)for(int y=-1;y<=1;++y)' +
         's+=texture(shadowMap,vec3(q.xy+vec2(x,y)*shadowParams.z,q.z));' +
@@ -23088,7 +23645,9 @@ function render3DFragmentSource(fragmentCode)
         'if(!gl_FrontFacing)n=-n;' + // only a double sided mesh shows a back face, light it on the side that is seen
         'if(materialParams.x!=0.)n=normalMapNormal(n);' +
         'float nl=dot(n,-lightDir.xyz);' +
-        'float s=shadow();' +
+        // the shadow is the sun's, or one spotlight's: shadowParams.x is 1 for the sun, 2 and up for that Light3D
+        'float sh=shadow(),s=shadowParams.x<1.5?sh:1.;' +
+        'int si=int(shadowParams.x+.5)-2;' +
         // the ambient: one color, or blended from the ground color below to the sky color above by the way the face points
         'vec3 l=(ambientGround.a>0.?mix(ambientGround.rgb,ambientFog.rgb,n.y*.5+.5):ambientFog.rgb)+lightColor.rgb*max(nl,0.)*s;' +
         // the Light3D objects: a point light falls off with distance, a directional one does not and carries the
@@ -23104,6 +23663,11 @@ function render3DFragmentSource(fragmentCode)
         'v/=max(d,1e-6);' +
         'float ln=dot(n,v);' +
         'vec3 lc=extraLightColors[i].rgb*extraLightColors[i].a*a*a;' +
+        // a spotlight's cone: full where its fade starts, nothing at its edge, smooth between; 1 with no cone
+        'vec4 K=extraLightCones[i];' +
+        'float k=clamp(dot(K.xyz,-v)-K.w,0.,1.);' +
+        'lc*=k*k*(3.-2.*k);' +
+        'if(i==si)lc*=sh;' +
         'l+=lc*max(0.,ln);' +
         'if(lightColor.a>0.)sp+=lc*pow(max(dot(reflect(-v,n),eye),0.),materialParams.y)*step(0.,ln);' +
         '}' +
@@ -23158,6 +23722,7 @@ function render3DUseProgram(program)
     {
         gl.uniform4fv(render3DUniform('extraLights'), r.lightPositions, 0, r.lightCount * 4);
         gl.uniform4fv(render3DUniform('extraLightColors'), r.lightColors, 0, r.lightCount * 4);
+        gl.uniform4fv(render3DUniform('extraLightCones'), r.lightCones, 0, r.lightCount * 4);
     }
     if (program !== r.program)
     {
@@ -23298,18 +23863,19 @@ function render3DUpdateSamplers()
     r.samplers.clear();
 }
 
-// the sampler for a texture's wrap modes, smooth or hard edged, made the first time it is needed
-function render3DSampler(wrap, pixelated)
+// the sampler for a texture's wrap modes, smooth or hard edged, made the first time it is needed; pixelated is the
+// draw's, texturePixelated the texture's own, which a smooth texture in a pixel art game sets false
+function render3DSampler(wrap, pixelated, texturePixelated=tilesPixelated)
 {
     const gl = glContext, r = render3D, [wrapS, wrapT] = glWrapModes(wrap);
-    const key = wrapS * 1e5 + wrapT * 2 + (pixelated ? 1 : 0); // the modes are 5 digit numbers
+    const key = wrapS * 1e5 + wrapT * 4 + (pixelated ? 1 : 0) + (texturePixelated ? 2 : 0); // the modes are 5 digit numbers
     let sampler = r.samplers.get(key);
     if (sampler) return sampler;
     sampler = gl.createSampler();
-    const sharp = pixelated || tilesPixelated;
+    const sharp = pixelated || texturePixelated;
     gl.samplerParameteri(sampler, gl.TEXTURE_MAG_FILTER, sharp ? gl.NEAREST : gl.LINEAR);
     gl.samplerParameteri(sampler, gl.TEXTURE_MIN_FILTER, pixelated ? gl.NEAREST
-        : tilesPixelated ? gl.NEAREST_MIPMAP_LINEAR : gl.LINEAR_MIPMAP_LINEAR);
+        : texturePixelated ? gl.NEAREST_MIPMAP_LINEAR : gl.LINEAR_MIPMAP_LINEAR);
     gl.samplerParameteri(sampler, gl.TEXTURE_WRAP_S, wrapS);
     gl.samplerParameteri(sampler, gl.TEXTURE_WRAP_T, wrapT);
     const anisotropy = gl.getExtension('EXT_texture_filter_anisotropic');
@@ -23337,7 +23903,7 @@ function render3DBindTexture(tileInfo, state=render3D, unit=0)
                                     // or anisotropy, and filtering it that way costs every untextured fragment
     else
     {
-        gl.bindSampler(unit, render3DSampler(textureInfo?.wrap, state.pixelated));
+        gl.bindSampler(unit, render3DSampler(textureInfo?.wrap, state.pixelated, textureInfo?.pixelated ?? tilesPixelated));
         glUpdateMipmaps(texture); // drawn into since its mipmaps were made
         if (!state.pixelated && !glMipmappedTextures.has(texture)) // a hard edged draw never reads them
         {
@@ -23517,7 +24083,9 @@ function render3DSetDrawUniforms(matrix, tileInfo, tint, uvRect, state=render3D)
     // 0 blends them away instead, and -1 is additive, which has to fade into fog differently
     const blendMode = state.blend ? (state.additive ? -1 : 0) : 1;
     const receives = r.shadows && r.passIsDefault && state.receiveShadow ? 1 : 0;
-    render3DUniform4f('shadowParams', receives, r.shadowBias, r.shadowSoftness / r.shadowTextureSize, blendMode);
+    // 1 the sun's shadow, 2 and up the shadow of that Light3D, the spotlight that casts them
+    const shadowOf = receives && r.shadowLightIndex >= 0 ? 2 + r.shadowLightIndex : receives;
+    render3DUniform4f('shadowParams', shadowOf, r.shadowDepthBias, r.shadowSoftness / r.shadowTextureSize, blendMode);
 
     // a render target's texture holds premultiplied color, the blend writes it that way, so the shader undoes it
     const textureInfo = render3DTextureOf(tileInfo);
@@ -23583,6 +24151,8 @@ function render3DRenderPass(after2D)
     // gathered before the gl state is taken over, so an assert here leaves nothing to hand back
     const lights = render3DCollectLights();
     r.lightCount = lights.length;
+    const caster = render3DShadowCaster();
+    r.shadowLightIndex = caster ? lights.indexOf(caster) : -1;
     const positions = r.lightPositions, colors = r.lightColors;
     lights.forEach((light, i)=>
     {
@@ -23593,6 +24163,7 @@ function render3DRenderPass(after2D)
         positions[k] = p.x, positions[k+1] = p.y, positions[k+2] = p.z;
         positions[k+3] = light.directional ? -1 : max(0, light.radius); // a negative radius marks a direction
         colors[k] = c.r, colors[k+1] = c.g, colors[k+2] = c.b, colors[k+3] = c.a * light.intensity;
+        r.lightCones.set(render3DLightCone(light), k);
     });
 
     // take over the gl state
@@ -23664,6 +24235,7 @@ function render3DUpdateShadowMap(size)
 {
     const gl = glContext, r = render3D;
     false&&ASSERT(size > 0, 'shadowMapSize must be positive');
+    size = glClampTextureSize(size); // a size the device does not have falls back to the largest it has
     if (r.shadowTexture && r.shadowTextureSize === size) return;
     r.shadowTexture && gl.deleteTexture(r.shadowTexture);
     r.shadowFramebuffer && gl.deleteFramebuffer(r.shadowFramebuffer);
@@ -25716,20 +26288,24 @@ function engineObjectsCallback3D(pos, size, callback, objects=engineObjects, tes
  * InstancedMesh3D - Many copies of one mesh drawn as one call, with their transforms kept on the GPU
  * - For big sets that mostly stay put: an instance costs nothing per frame until it changes, so a hundred thousand
  *   trees cost what one tree does; objects and drawMesh batch by themselves too, but rebuild their batch every frame
- * - setMatrixAt and setColorAt change one instance, and only the changed range uploads before the next draw
+ * - setTransformAt, setMatrixAt and setColorAt change one instance, and only the changed range uploads before the
+ *   next draw; the matrices and the colors are kept apart, so moving instances uploads 64 bytes each
+ * - For many instances moving every frame, setTransforms places a run of them from arrays of positions, rotations
+ *   and scales in one loop, the fastest way; or write matrixData directly and call markDirtyRange
  * - The instances are in world space; the object's own pos3D, rotation3D and scale3D do not move them
- * - The whole set is culled by one bounding sphere around the origin, and casts and receives shadows like any object
+ * - The whole set is culled by one bounding sphere around the origin, worked out when culling reads it, or set by hand
+ *   with radius; it casts and receives shadows like any object
  * - The object's flags cover the whole set, one emissive, one tileInfo, one shader; only the colors are per instance
  * - A mirrored instance, one with a negative scale, shows its inside unless the mesh is doubleSided
  * - A transparent set draws in one go in the transparent stage, its instances are not sorted against each other;
  *   the set sorts against other transparent draws by the object's position, so put pos3D at its middle
- * - pick, the raycast and the collect helpers do not see the instances, test them yourself from instanceData
+ * - pick, the raycast and the collect helpers do not see the instances, test them yourself from matrixData
  * @extends EngineObject3D
  * @memberof Render3D
  * @example
  * const forest = new InstancedMesh3D(treeMesh, 1000);
  * for (let i = 0; i < 1000; ++i)
- *     forest.setMatrixAt(i, buildMatrix(randomGroundPos(), vec3(0, rand(2*PI), 0)));
+ *     forest.setTransformAt(i, randomGroundPos(), vec3(0, rand(2*PI), 0));
  */
 class InstancedMesh3D extends EngineObject3D
 {
@@ -25748,39 +26324,112 @@ class InstancedMesh3D extends EngineObject3D
         this.count = count;
         /** @property {number} - How many instances it was made with */
         this.maxCount = count;
-        /** @property {Float32Array} - The per instance values the shader reads, 24 floats each: the matrix, the color
-         *  and the uv rect; edit it directly and call markDirty for the instances changed */
-        this.instanceData = new Float32Array(count * RENDER3D_INSTANCE_FLOATS);
-        /** @property {number} - Radius of the sphere around the origin that holds every instance set so far, for
-         *  culling; from the farthest instance and the largest scale, and the mesh's size when it draws */
-        this.radius = 0;
-        this.reach = 0;    // the farthest any instance's position has been from the origin
-        this.maxScale = 0; // and the largest scale any instance has had
-        /** @property {number} - First instance to upload before the next draw */
+        /** @property {Float32Array} - Each instance's matrix, 16 floats, what moving them uploads; edit it directly and
+         *  call markDirty for the instances changed */
+        this.matrixData = new Float32Array(count * RENDER3D_MATRIX_FLOATS);
+        /** @property {Float32Array} - Each instance's color and uv rect, 8 floats, uploaded only when they change; edit
+         *  it directly and call markColorDirty for the instances changed */
+        this.colorData = new Float32Array(count * RENDER3D_COLOR_FLOATS);
+        /** @property {number} - First instance whose matrix uploads before the next draw */
         this.dirtyStart = 0;
-        /** @property {number} - One past the last instance to upload, so nothing uploads when it is not past dirtyStart */
+        /** @property {number} - One past the last instance whose matrix uploads, nothing when it is not past dirtyStart */
         this.dirtyEnd = count;
-        this.buffer = undefined;    // the GPU copy of instanceData
-        this.bufferGeneration = -1; // the context it was made under
-        this.uvTileInfo = tileInfo; // the tile the uv rects were written for
-        const uv = render3DGetTileUVs(tileInfo), data = this.instanceData;
+        /** @property {number} - First instance whose color uploads before the next draw */
+        this.colorDirtyStart = 0;
+        /** @property {number} - One past the last instance whose color uploads */
+        this.colorDirtyEnd = count;
+        // the farthest any instance's position has been from the origin, and the largest scale any has had, both
+        // squared, and the instances set since radius last took them in: setting one does no bounds work at all
+        this.reachSquared = 0;
+        this.scaleSquared = 0;
+        this.boundsStart = 0;
+        this.boundsEnd = count;
+        /** @type {number|undefined} */
+        this.fixedRadius = undefined; // a radius set by hand, see radius
+        this.buffer = undefined;      // the GPU copy of matrixData
+        /** @type {WebGLBuffer|undefined} */
+        this.colorBuffer = undefined; // and of colorData
+        this.bufferGeneration = -1;   // the context they were made under
+        this.uvTileInfo = tileInfo;   // the tile the uv rects were written for
+        const uv = render3DGetTileUVs(tileInfo), matrices = this.matrixData, colors = this.colorData;
         for (let i = 0; i < count; ++i)
         {
-            this.setMatrixAt(i, RENDER3D_IDENTITY);
-            const k = i * RENDER3D_INSTANCE_FLOATS;
-            data[k+16] = color.r; data[k+17] = color.g; data[k+18] = color.b; data[k+19] = color.a;
-            data[k+20] = uv.x; data[k+21] = uv.y; data[k+22] = uv.w; data[k+23] = uv.h;
+            matrices.set(RENDER3D_IDENTITY.m, i * RENDER3D_MATRIX_FLOATS);
+            const k = i * RENDER3D_COLOR_FLOATS;
+            colors[k] = color.r; colors[k+1] = color.g; colors[k+2] = color.b; colors[k+3] = color.a;
+            colors[k+4] = uv.x; colors[k+5] = uv.y; colors[k+6] = uv.w; colors[k+7] = uv.h;
         }
     }
 
+    /** Place an instance by its position, rotation and scale, what buildMatrix takes, written straight in with no
+     *  matrix made; in world space
+     *  @param {number} i
+     *  @param {Vector3} [pos]
+     *  @param {Vector3} [rotation] - Euler angles in radians
+     *  @param {Vector3} [scale] */
+    setTransformAt(i, pos, rotation, scale)
+    {
+        false&&ASSERT(i >= 0 && i < this.maxCount, 'instance index out of range');
+        matrix4Compose(this.matrixData, i * RENDER3D_MATRIX_FLOATS, pos, rotation, scale);
+        this.markDirty(i);
+    }
+
+    /** Place a run of instances from arrays indexed by instance, plain or typed, as a game keeps them: each is placed
+     *  as setTransformAt places it, all in one loop with nothing made, the fastest way to move many every frame;
+     *  in world space
+     *  @param {number} start - First instance
+     *  @param {number} count - How many
+     *  @param {ArrayLike<number>} x - Positions
+     *  @param {ArrayLike<number>} y
+     *  @param {ArrayLike<number>} z
+     *  @param {ArrayLike<number>} [rx] - Euler angles in radians, all three or none for upright
+     *  @param {ArrayLike<number>} [ry]
+     *  @param {ArrayLike<number>} [rz]
+     *  @param {ArrayLike<number>} [sx] - Scales, all three or none for 1
+     *  @param {ArrayLike<number>} [sy]
+     *  @param {ArrayLike<number>} [sz] */
+    setTransforms(start, count, x, y, z, rx, ry, rz, sx, sy, sz)
+    {
+        false&&ASSERT(start >= 0 && count >= 0 && start + count <= this.maxCount, 'instance range out of range');
+        false&&ASSERT(!rx === !ry && !rx === !rz && !sx === !sy && !sx === !sz, 'rotations and scales come in threes');
+        const m = this.matrixData, end = start + count;
+        for (let i = start; i < end; ++i)
+        {
+            // matrix4Compose's expressions, so a run placed here is the same as each placed by setTransformAt
+            const k = i * RENDER3D_MATRIX_FLOATS;
+            const scaleX = sx ? sx[i] : 1, scaleY = sy ? sy[i] : 1, scaleZ = sz ? sz[i] : 1;
+            if (rx)
+            {
+                const cx = cos(rx[i]), sinX = sin(rx[i]);
+                const cy = cos(ry[i]), sinY = sin(ry[i]);
+                const cz = cos(rz[i]), sinZ = sin(rz[i]);
+                m[k]   = (cy*cz + sinY*sinX*sinZ) * scaleX;  m[k+1] = cx*sinZ * scaleX;
+                m[k+2] = (-sinY*cz + cy*sinX*sinZ) * scaleX;
+                m[k+4] = (-cy*sinZ + sinY*sinX*cz) * scaleY; m[k+5] = cx*cz * scaleY;
+                m[k+6] = (sinY*sinZ + cy*sinX*cz) * scaleY;
+                m[k+8] = sinY*cx * scaleZ;                   m[k+9] = -sinX * scaleZ; m[k+10] = cy*cx * scaleZ;
+            }
+            else
+            {
+                m[k]   = scaleX; m[k+1] = 0;      m[k+2]  = 0;
+                m[k+4] = 0;      m[k+5] = scaleY; m[k+6]  = 0;
+                m[k+8] = 0;      m[k+9] = 0;      m[k+10] = scaleZ;
+            }
+            m[k+3] = m[k+7] = m[k+11] = 0; m[k+15] = 1;
+            m[k+12] = x[i], m[k+13] = y[i], m[k+14] = z[i];
+        }
+        count && this.markDirtyRange(start, end);
+    }
+
     /** Place an instance, in world space
      *  @param {number} i
      *  @param {Matrix4} matrix */
     setMatrixAt(i, matrix)
     {
         false&&ASSERT(i >= 0 && i < this.maxCount, 'instance index out of range');
-        const data = this.instanceData, k = i * RENDER3D_INSTANCE_FLOATS, m = matrix.m;
-        data.set(m, k);
+        const data = this.matrixData, k = i * RENDER3D_MATRIX_FLOATS, m = matrix.m;
+        for (let j = 0; j < 16; ++j)
+            data[k+j] = m[j]; // for 16 floats a loop beats set's call
         this.markDirty(i);
     }
 
@@ -25790,8 +26439,8 @@ class InstancedMesh3D extends EngineObject3D
     getMatrixAt(i)
     {
         false&&ASSERT(i >= 0 && i < this.maxCount, 'instance index out of range');
-        const k = i * RENDER3D_INSTANCE_FLOATS, matrix = new Matrix4;
-        matrix.m.set(this.instanceData.subarray(k, k + 16));
+        const k = i * RENDER3D_MATRIX_FLOATS, matrix = new Matrix4;
+        matrix.m.set(this.matrixData.subarray(k, k + 16));
         return matrix;
     }
 
@@ -25802,26 +26451,71 @@ class InstancedMesh3D extends EngineObject3D
     {
         false&&ASSERT(i >= 0 && i < this.maxCount, 'instance index out of range');
         false&&ASSERT(isColor(color), 'color must be a Color');
-        const data = this.instanceData, k = i * RENDER3D_INSTANCE_FLOATS;
-        data[k+16] = color.r; data[k+17] = color.g; data[k+18] = color.b; data[k+19] = color.a;
-        this.markDirty(i);
+        const data = this.colorData, k = i * RENDER3D_COLOR_FLOATS;
+        data[k] = color.r; data[k+1] = color.g; data[k+2] = color.b; data[k+3] = color.a;
+        this.markColorDirty(i);
     }
 
-    /** Note that an instance changed, so it uploads before the next draw and the bounds hold it; setMatrixAt and
-     *  setColorAt call this, and so must an edit made straight to instanceData
+    /** Note that an instance's matrix changed, so it uploads before the next draw and the bounds take it in when
+     *  they are read; setTransformAt and setMatrixAt call this, and so must an edit made straight to matrixData
      *  @param {number} i */
     markDirty(i)
     {
-        this.dirtyStart = min(this.dirtyStart, i);
-        this.dirtyEnd = max(this.dirtyEnd, i + 1);
+        if (i < this.dirtyStart) this.dirtyStart = i;
+        if (i >= this.dirtyEnd) this.dirtyEnd = i + 1;
+        if (i < this.boundsStart) this.boundsStart = i;
+        if (i >= this.boundsEnd) this.boundsEnd = i + 1;
+    }
+
+    /** Note that a run of instances' matrices changed, for code that writes matrixData directly, the lowest level
+     *  way to move many: they upload before the next draw and the bounds take them in when they are read
+     *  @param {number} start - First instance
+     *  @param {number} end - One past the last */
+    markDirtyRange(start, end)
+    {
+        false&&ASSERT(start >= 0 && end <= this.maxCount && start <= end, 'instance range out of range');
+        if (start < this.dirtyStart) this.dirtyStart = start;
+        if (end > this.dirtyEnd) this.dirtyEnd = end;
+        if (start < this.boundsStart) this.boundsStart = start;
+        if (end > this.boundsEnd) this.boundsEnd = end;
+    }
 
-        // the bounds grow to hold where it is now and how big, read back from the matrix it has
-        const d = this.instanceData, k = i * RENDER3D_INSTANCE_FLOATS;
-        this.reach = max(this.reach, hypot(d[k+12], d[k+13], d[k+14]));
-        this.maxScale = max(this.maxScale, render3DMaxStretch(d, k));
-        const meshRadius = this.mesh.radius || this.mesh.computeRadius(); // measured once, the draw takes a new size up
-        this.radius = this.reach + meshRadius * this.maxScale;
+    /** Note that an instance's color changed, so it uploads before the next draw; setColorAt calls this, and so must
+     *  an edit made straight to colorData
+     *  @param {number} i */
+    markColorDirty(i)
+    {
+        if (i < this.colorDirtyStart) this.colorDirtyStart = i;
+        if (i >= this.colorDirtyEnd) this.colorDirtyEnd = i + 1;
+    }
+
+    /** Radius of the sphere around the origin that holds every instance set so far, for culling: the farthest
+     *  instance, and the mesh's size at the largest scale; it only grows, and takes in the instances set since it
+     *  was last read, so with frustum culling off it is never worked out. Set it to fix the sphere, which a big set
+     *  that is culled can use to skip that work, and set it to undefined to go back to the bounds
+     *  @return {number} */
+    get radius()
+    {
+        if (this.fixedRadius !== undefined) return this.fixedRadius;
+        if (this.boundsEnd > this.boundsStart)
+        {
+            // the bounds grow to hold where each is now and how big, read back from its matrix, squared
+            const d = this.matrixData;
+            let reachSquared = this.reachSquared, scaleSquared = this.scaleSquared;
+            for (let i = this.boundsStart; i < this.boundsEnd; ++i)
+            {
+                const k = i * RENDER3D_MATRIX_FLOATS, x = d[k+12], y = d[k+13], z = d[k+14];
+                const reach = x*x + y*y + z*z, scale = render3DMaxStretchSquared(d, k);
+                if (reach > reachSquared) reachSquared = reach;
+                if (scale > scaleSquared) scaleSquared = scale;
+            }
+            this.reachSquared = reachSquared, this.scaleSquared = scaleSquared;
+            this.boundsStart = Infinity, this.boundsEnd = 0;
+        }
+        const mesh = this.mesh, meshRadius = mesh.radius || mesh.computeRadius(); // the mesh measured once
+        return this.reachSquared ** .5 + meshRadius * this.scaleSquared ** .5;
     }
+    set radius(radius) { this.fixedRadius = radius; }
 
     /** Draws every instance as one call, uploading the ones that changed first
      *  @return {void} */
@@ -25835,41 +26529,46 @@ class InstancedMesh3D extends EngineObject3D
         if (r.shadowPass && !r.lighting) return; // unlit things cast no shadow
         render3DMeshUpload(mesh);
         if (!mesh.bufferCount) return;
-        this.radius = this.reach + mesh.radius * this.maxScale; // the mesh may have grown since
         if (r.frustumCulling && !render3DSphereVisible(0, 0, 0, this.radius)) return;
 
         // the uv rect is the object's tile for every instance, rewritten when the tile changes
         if (this.uvTileInfo !== this.tileInfo)
         {
-            const uv = render3DGetTileUVs(this.tileInfo), data = this.instanceData;
-            for (let k = 20; k < data.length; k += RENDER3D_INSTANCE_FLOATS)
+            const uv = render3DGetTileUVs(this.tileInfo), data = this.colorData;
+            for (let k = 4; k < data.length; k += RENDER3D_COLOR_FLOATS)
                 data[k] = uv.x, data[k+1] = uv.y, data[k+2] = uv.w, data[k+3] = uv.h;
             this.uvTileInfo = this.tileInfo;
-            this.dirtyStart = 0, this.dirtyEnd = this.maxCount;
+            this.colorDirtyStart = 0, this.colorDirtyEnd = this.maxCount;
         }
 
-        // the GPU copy: all of it under a fresh context, otherwise just the changed range
+        // the GPU copies: all of each under a fresh context, otherwise just the changed ranges
         if (!this.buffer || this.bufferGeneration !== r.contextGeneration)
         {
-            this.buffer = gl.createBuffer();
             this.bufferGeneration = r.contextGeneration;
-            gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
-            gl.bufferData(gl.ARRAY_BUFFER, this.instanceData, gl.DYNAMIC_DRAW);
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer = gl.createBuffer());
+            gl.bufferData(gl.ARRAY_BUFFER, this.matrixData, gl.DYNAMIC_DRAW);
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.colorBuffer = gl.createBuffer());
+            gl.bufferData(gl.ARRAY_BUFFER, this.colorData, gl.DYNAMIC_DRAW);
         }
-        else if (this.dirtyEnd > this.dirtyStart)
+        else
         {
-            const start = this.dirtyStart * RENDER3D_INSTANCE_FLOATS, end = this.dirtyEnd * RENDER3D_INSTANCE_FLOATS;
-            gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
-            gl.bufferSubData(gl.ARRAY_BUFFER, start * 4, this.instanceData, start, end - start);
+            const upload = (buffer, data, floats, start, end)=>
+            {
+                if (end <= start) return;
+                gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+                gl.bufferSubData(gl.ARRAY_BUFFER, start * floats * 4, data, start * floats, (end - start) * floats);
+            };
+            upload(this.buffer, this.matrixData, RENDER3D_MATRIX_FLOATS, this.dirtyStart, this.dirtyEnd);
+            upload(this.colorBuffer, this.colorData, RENDER3D_COLOR_FLOATS, this.colorDirtyStart, this.colorDirtyEnd);
         }
-        this.dirtyStart = Infinity, this.dirtyEnd = 0;
+        this.dirtyStart = this.colorDirtyStart = Infinity, this.dirtyEnd = this.colorDirtyEnd = 0;
 
         // one draw under the object's state, the mesh setting the culling as drawMesh does
         r.flush();
         render3DFlushBeforeOverlay(); // as in drawMesh, what was drawn before goes under it
         const cullBackFaces = r.cullBackFaces, tileInfo = this.tileInfo;
         r.cullBackFaces = !mesh.doubleSided;
-        render3DDrawInstanced(mesh, this.buffer, this.count, render3DTextureOf(tileInfo), r);
+        render3DDrawInstanced(mesh, this.buffer, this.count, render3DTextureOf(tileInfo), r, this.colorBuffer);
         r.cullBackFaces = cullBackFaces;
     }
 
@@ -25878,8 +26577,8 @@ class InstancedMesh3D extends EngineObject3D
     destroy(immediate)
     {
         if (this.buffer && this.bufferGeneration === render3D?.contextGeneration)
-            glContext?.deleteBuffer(this.buffer);
-        this.buffer = undefined;
+            glContext?.deleteBuffer(this.buffer), glContext?.deleteBuffer(this.colorBuffer);
+        this.buffer = this.colorBuffer = undefined;
         super.destroy(immediate);
     }
 }
@@ -25888,7 +26587,10 @@ class InstancedMesh3D extends EngineObject3D
 /**
  * Light3D - A light that is an EngineObject3D, so it can move, follow a parent or be destroyed like anything else
  * - A point light: it lights what is near it and fades out by its radius, DirectionalLight3D shines from far away
- * - Only the sun, render3D.sunDirection, casts shadows; these light and make highlights without one
+ * - A coneAngle makes it a spotlight: it shines along its own forward, turned by rotation3D or by what it is
+ *   attached to, inside the cone, fading over the part of it coneSoftness says
+ * - The sun, render3D.sunDirection, casts the shadows; a spotlight can cast them in its place, see
+ *   render3D.shadowLight; the other lights light and make highlights without one
  * - Only the 8 lights nearest the camera are used each frame
  * - radius is where the light fades out, and it fades fast, so a small radius wants a higher intensity
  * - intensity multiplies the color, above 1 for a light brighter than white
@@ -25920,6 +26622,12 @@ class Light3D extends EngineObject3D
         /** @property {boolean} - Shine from far away, from its position toward the origin, instead of out from its
          *  position with a falloff; DirectionalLight3D sets it */
         this.directional = false;
+        /** @property {number} - Makes it a spotlight: the angle in radians from its forward out to the edge of its
+         *  cone, so the beam is twice this across; 0 for a light that shines every way */
+        this.coneAngle = 0;
+        /** @property {number} - How much of the cone is its fading edge: 0 a hard edge, .2 by default, the outer
+         *  fifth, 1 fading all the way from the middle of the beam */
+        this.coneSoftness = .2;
         /** @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 */
         this.glow = 0;
@@ -25938,37 +26646,10 @@ class Light3D extends EngineObject3D
         const toCamera = r.camera.pos.subtract(pos), distance = toCamera.length();
         const at = distance ? pos.add(toCamera.scale(min(this.glow, distance) / 2 / distance)) : pos;
         const color = rgb(c.r, c.g, c.b, c.a * min(this.intensity, 1));
-        r.drawBillboard(at, vec2(this.glow), render3DGlow(this.glowFalloff), color);
+        r.drawBillboard(at, vec2(this.glow), engineGlowTexture(this.glowFalloff), color);
     }
 }
 
-// how strong a light's glow is at a distance from its middle, 0 there to 1 at the edge: a bell, full in the middle
-// and nothing at the edge, fading faster the higher the falloff
-function render3DGlowAlpha(r, falloff)
-{
-    const k = 3.5 * falloff, edge = Math.exp(-k);
-    return (Math.exp(-k * r * r) - edge) / (1 - edge);
-}
-
-// the soft round glow of the lights, one texture for each falloff, rounded to a tenth so a changing falloff makes
-// only a few, each made once from a canvas; undefined headless or without a canvas
-const render3DGlowTextures = new Map;
-function render3DGlow(falloff=1)
-{
-    false&&ASSERT(isNumber(falloff) && falloff > 0, 'glowFalloff must be a number above 0');
-    const key = max(round(falloff * 10), 1) / 10;
-    let texture = render3DGlowTextures.get(key);
-    if (texture || !glContext || typeof OffscreenCanvas == 'undefined') return texture;
-    const size = 64, context = createCanvasContext(size), steps = 16;
-    const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
-    for (let i = 0; i <= steps; ++i)
-        gradient.addColorStop(i / steps, 'rgba(255,255,255,' + render3DGlowAlpha(i / steps, key).toFixed(4) + ')');
-    context.fillStyle = gradient;
-    context.fillRect(0, 0, size, size);
-    render3DGlowTextures.set(key, texture = new TextureInfo(context.canvas));
-    return texture;
-}
-
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * DirectionalLight3D - A Light3D that shines from far away with no falloff, like sunlight
@@ -26902,7 +27583,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; }};
 }
 
@@ -26915,6 +27596,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
@@ -26944,8 +27627,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
@@ -26975,8 +27659,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 */
@@ -26991,6 +27675,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 */
@@ -27017,6 +27704,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 */
@@ -27072,6 +27762,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)
@@ -27104,7 +27795,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--;)
@@ -27112,7 +27807,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());
@@ -27160,10 +27856,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();
@@ -27433,6 +28137,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
 
@@ -28527,6 +29420,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 */
@@ -28535,7 +29438,11 @@ function level3DLoad(level)
     false&&ASSERT(!!level && typeof level === 'object', 'a level is an object, {} for a new one');
     false&&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;
@@ -28546,6 +29453,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)
 {
@@ -28638,9 +29686,761 @@ 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});
+
+/**
+ * LittleJS Particle Effects Plugin
+ * - Ready made particle effects in one line, particleEffect('fire', pos), and particleEffect3D for 3D
+ * - Every built-in effect is tuned around a one unit emitter; options.scale grows it to fit, options.hue and
+ *   options.saturation recolor it
+ * - Effects are plain data, {name, settings, behaviors}, the format the particle designer saves: load a library the
+ *   designer saved with particleEffectsLoad and play its effects by name
+ * - The built-in effects draw with a sheet of shapes the plugin draws itself, so they need no image
+ * @namespace ParticleEffects
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+// settings, what an effect sets on an emitter
+
+/** The groups the settings are in, in order
+ *  @type {Array<string>}
+ *  @memberof ParticleEffects */
+const particleEffectGroups = ['Emitter', 'Particles', 'Color', 'Motion', 'Collision', 'Texture', 'Behaviors'];
+
+/** Every setting an effect has: its name, kind (number, checkbox, color or shape), default, the range the designer's
+ *  slider covers (min, max, step), the hard limits a typed value is clamped to, and whether it is set after the
+ *  emitter is made rather than passed to its constructor (extra)
+ *  @type {Array<{group:string, name:string, kind:string, value:any, min:number, max:number, step:number,
+ *  description:string, hardMin:number, hardMax:number, extra:boolean}>}
+ *  @memberof ParticleEffects */
+const particleEffectSettings = [];
+let particleEffectSettingGroup; // the group settings are being added to
+
+// the slider covers min to max, typed values may go out to hardMin and hardMax
+function particleEffectAddSetting(name, kind, value, min, max, step, description, hardMin=min, hardMax=max)
+{
+    // extras are not constructor arguments, the code export assigns them after
+    const extra = ['trailScale', 'velocityInheritance', 'localSpace', 'restitution', 'friction', 'gravity'].includes(name);
+    particleEffectSettings.push({group:particleEffectSettingGroup, name, kind, value, min, max, step, description,
+        hardMin, hardMax, extra});
+}
+
+particleEffectSettingGroup = 'Emitter';
+particleEffectAddSetting('emitRate', 'number', 100, 0, 500, .1,
+    'Particles per second, 0 emits none', 0, 1e4);
+particleEffectAddSetting('emitTime', 'number', 0, 0, 5, .05,
+    'Seconds to emit for, 0 is forever', 0, 1e9);
+particleEffectAddSetting('emitSize', 'number', 0, 0, 10, .05,
+    'Diameter, or width when rectangular', 0, 1e9);
+particleEffectAddSetting('emitRect', 'checkbox', false, 0, 0, 0,
+    'Rectangle emitter, off is a circle');
+particleEffectAddSetting('emitHeight', 'number', 0, 0, 10, .05,
+    'Rectangle height', 0, 1e9);
+particleEffectAddSetting('emitConeAngle', 'number', PI, 0, PI, .01,
+    'Half angle particles move in, 3.14 is all ways');
+particleEffectAddSetting('angle', 'number', 0, -3.14, 3.14, .01,
+    'Emitter angle, 0 points up', -PI, PI); // the slider steps from its min
+
+particleEffectSettingGroup = 'Particles';
+particleEffectAddSetting('particleTime', 'number', .5, 0, 5, .05,
+    'Seconds each particle lives', 0, 1e9);
+particleEffectAddSetting('sizeStart', 'number', .1, 0, 5, .01,
+    'Size at the start of life', 0, 1e9);
+particleEffectAddSetting('sizeEnd', 'number', 1, 0, 5, .01,
+    'Size at the end of life', 0, 1e9);
+particleEffectAddSetting('fadeRate', 'number', .1, 0, 1, .01,
+    'Share of life spent fading in and out');
+particleEffectAddSetting('randomness', 'number', .2, 0, 1, .01,
+    'How much each particle varies');
+particleEffectAddSetting('particleConeAngle', 'number', PI, 0, PI, .01,
+    'Half angle of start rotation, 3.14 is any');
+particleEffectAddSetting('trailScale', 'number', 0, 0, 20, .1,
+    'Stretch along the motion, 0 is off', 0, 1e9);
+particleEffectAddSetting('additive', 'checkbox', false, 0, 0, 0,
+    'Glow with additive blending');
+
+particleEffectSettingGroup = 'Color';
+particleEffectAddSetting('colorStartA', 'color', [1,1,1,1], 0, 1, .01,
+    'Start color, each particle picks between A and B');
+particleEffectAddSetting('colorStartB', 'color', [1,1,1,1], 0, 1, .01,
+    'Second start color');
+particleEffectAddSetting('colorEndA', 'color', [1,1,1,0], 0, 1, .01,
+    'End color, each particle picks between A and B');
+particleEffectAddSetting('colorEndB', 'color', [1,1,1,0], 0, 1, .01,
+    'Second end color');
+particleEffectAddSetting('randomColorLinear', 'checkbox', true, 0, 0, 0,
+    'Pick along A to B, off picks each channel');
+
+particleEffectSettingGroup = 'Motion';
+particleEffectAddSetting('speed', 'number', .1, 0, .5, .005,
+    'Start speed, world units per frame', 0, 1e9);
+particleEffectAddSetting('angleSpeed', 'number', .05, 0, .5, .005,
+    'Spin speed, radians per frame', 0, 1e9);
+particleEffectAddSetting('damping', 'number', 1, .8, 1, .001,
+    'Speed kept each frame, 1 keeps it all', 0, 1);
+particleEffectAddSetting('angleDamping', 'number', 1, .8, 1, .001,
+    'Spin kept each frame', 0, 1);
+particleEffectAddSetting('gravityScale', 'number', 0, -2, 2, .05,
+    'How much gravity pulls', -1e9, 1e9);
+particleEffectAddSetting('gravity', 'number', 0, -.02, .02, .0005,
+    'Its own fall each frame, the same in any game', -1, 1);
+particleEffectAddSetting('velocityInheritance', 'number', 0, 0, 1, .01,
+    'Share of emitter motion passed on');
+particleEffectAddSetting('localSpace', 'checkbox', false, 0, 0, 0,
+    'Particles move with the emitter');
+
+particleEffectSettingGroup = 'Collision';
+particleEffectAddSetting('collideLevel', 'checkbox', false, 0, 0, 0,
+    'Hit tiles, the preview adds a floor');
+particleEffectAddSetting('restitution', 'number', 0, 0, 1, .01,
+    'Bounce when hitting tiles');
+particleEffectAddSetting('friction', 'number', .8, 0, 1, .01,
+    'Speed kept sliding along tiles');
+
+particleEffectSettingGroup = 'Texture';
+particleEffectAddSetting('shape', 'shape', 'soft', 0, 0, 0,
+    'Built-in shape, none uses the tile');
+particleEffectAddSetting('tileIndex', 'number', -1, -1, 63, 1,
+    'Tile in texture 0 when no shape, -1 is untextured', -1, 1e4);
+particleEffectAddSetting('tileSize', 'number', 16, 1, 128, 1,
+    'Tile size in texture pixels', 1, 4096);
+particleEffectAddSetting('tilePadding', 'number', 1, 0, 8, 1,
+    'Pixels of padding around each tile', 0, 64);
+
+/** The behaviors an effect can use, each a push applied to every particle every update, with a 2D and a 3D version
+ *  @type {Array<{name:string, update:(Function|undefined), update3D:(Function|undefined), min:number, max:number,
+ *  value:number, description:string}>}
+ *  @memberof ParticleEffects */
+const particleEffectBehaviors =
+[
+    {name:'wobble',     min:0,  max:5, value:1, description:'Sway from side to side'},
+    {name:'swirl',      min:-2, max:2, value:1, description:'Turn the direction of travel'},
+    {name:'turbulence', min:0,  max:5, value:1, description:'Random pushes every frame'},
+    {name:'attract',    min:-2, max:2, value:1, description:'Pull toward the emitter, negative pushes away'},
+    {name:'orbit',      min:-2, max:2, value:1, description:'Push around the emitter, add attract to circle it'},
+    {name:'wind',       min:-2, max:2, value:1, description:'A sideways push that grows with age'},
+    {name:'stick',      min:0,  max:1, value:1, description:'Grip on landing, pair with collideLevel'},
+].map(b=> ({...b, update: undefined, update3D: undefined}));
+const particleEffectBehavior = (name)=> particleEffectBehaviors.find(b=> b.name === name);
+
+/** Names of the shapes the plugin draws, for an effect's shape setting
+ *  @type {Array<string>}
+ *  @memberof ParticleEffects */
+const particleEffectShapes = ['dot', 'soft', 'glow', 'smoke', 'spark', 'square', 'triangle', 'ring', 'star', 'plus'];
+
+///////////////////////////////////////////////////////////////////////////////
+// effects
+
+// a color from an [r,g,b,a] array or a Color, undefined if it is neither
+function particleEffectColor(value)
+{
+    if (value instanceof Color)
+        value = [value.r, value.g, value.b, value.a];
+    if (isArray(value) && value.length === 4 && value.every(isNumber))
+        return value.map(c=> clamp(c));
+}
+
+/** Any input into a whole effect: missing fields take their defaults, bad ones are dropped or clamped
+ *  @param {Object} [raw] - {name, settings, behaviors}, from a library file, the designer or code
+ *  @return {{name:string, settings:Object, behaviors:Array<{name:string, strength:number}>}}
+ *  @memberof ParticleEffects */
+function particleEffectSanitize(raw)
+{
+    // one line of text, line breaks and control characters made spaces
+    const text = typeof raw?.name === 'string' ? raw.name.replace(/[\x00-\x1f\x7f]+/g, ' ').trim() : '';
+    const name = text ? text.slice(0, 60) : 'Effect';
+    const input = raw?.settings && typeof raw.settings === 'object' ? {...raw.settings} : {};
+    input.collideLevel ??= input.collideTiles; // its name before 1.20
+    // a library saved before shapes names its tile and no shape, it keeps its tile
+    if (input.shape === undefined && isNumber(input.tileIndex))
+        input.shape = '';
+    const settings = {};
+    for (const setting of particleEffectSettings)
+    {
+        const value = input[setting.name], fallback = setting.value;
+        if (setting.kind === 'checkbox')
+            settings[setting.name] = typeof value === 'boolean' ? value : value === 0 || value === 1 ? !!value : fallback;
+        else if (setting.kind === 'color')
+            settings[setting.name] = particleEffectColor(value) || fallback.slice();
+        else if (setting.kind === 'shape')
+            settings[setting.name] = value === '' || particleEffectShapes.includes(value) ? value : fallback;
+        else if (isNumber(value))
+        {
+            const clamped = clamp(value, setting.hardMin, setting.hardMax);
+            settings[setting.name] = setting.step >= 1 ? round(clamped) : clamped;
+        }
+        else
+            settings[setting.name] = fallback;
+    }
+
+    // local space particles are placed relative to the emitter, the tile collision is in the world
+    if (settings.localSpace)
+        settings.collideLevel = false;
+
+    // known behaviors once each, in table order
+    const behaviors = [];
+    const list = isArray(raw?.behaviors) ? raw.behaviors : [];
+    for (const b of particleEffectBehaviors)
+    {
+        const found = list.find(x=> x?.name === b.name);
+        if (!found)
+            continue;
+        const strength = isNumber(found.strength) ? clamp(found.strength, b.min, b.max) : b.value;
+        behaviors.push({name:b.name, strength});
+    }
+
+    // behaviors not known yet stay, a game may add them after the effect is loaded
+    for (const x of list)
+        if (typeof x?.name === 'string' && x.name && !particleEffectBehavior(x.name) &&
+            !behaviors.some(b=> b.name === x.name))
+            behaviors.push({name:x.name, strength: isNumber(x.strength) ? x.strength : 1});
+    return {name, settings, behaviors};
+}
+
+/** A copy of an effect with its four colors turned around the color wheel and their saturation scaled; lightness and
+ *  alpha stay, and grey and white have no hue to turn
+ *  @param {Object} effect
+ *  @param {number} [hue] - How far around the wheel, 1 is all the way
+ *  @param {number} [saturation] - Multiplies the saturation, 0 is grey, clamped to 1
+ *  @return {Object}
+ *  @memberof ParticleEffects */
+function particleEffectRecolor(effect, hue=0, saturation=1)
+{
+    effect = particleEffectSanitize(effect); // colors as channels, whatever it was given
+    const settings = {...effect.settings};
+    for (const name of ['colorStartA', 'colorStartB', 'colorEndA', 'colorEndB'])
+    {
+        const [h, s, l, a] = new Color(...settings[name]).HSLA();
+        const c = new Color().setHSLA(mod(h + hue), clamp(s * saturation), l, a);
+        settings[name] = [c.r, c.g, c.b, c.a];
+    }
+    return {...effect, settings, behaviors: effect.behaviors.map(b=> ({...b}))};
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// libraries
+
+// the effects by lower case name, the built-ins and any a game adds or loads
+const particleEffectsByName = new Map;
+
+/** Add effects to play by name, sanitized; one with the name of an effect already there replaces it
+ *  @param {Array<Object>|Object} effects
+ *  @memberof ParticleEffects */
+function particleEffectsAdd(effects)
+{
+    for (const effect of isArray(effects) ? effects : [effects])
+    {
+        const clean = particleEffectSanitize(effect);
+        particleEffectsByName.set(clean.name.toLowerCase(), clean);
+    }
+}
+
+/** The effect with a name, any case, undefined if there is none
+ *  @param {string} name
+ *  @return {Object|undefined}
+ *  @memberof ParticleEffects */
+function particleEffectsGet(name) { return particleEffectsByName.get(String(name).toLowerCase()); }
+
+/** A library file, or one effect, into sanitized effects; throws on bad input
+ *  @param {string} text
+ *  @return {Array<Object>}
+ *  @memberof ParticleEffects */
+function particleEffectsParse(text)
+{
+    const data = JSON.parse(text);
+    const list = isArray(data?.effects) ? data.effects : data?.settings ? [data] : undefined;
+    if (!list || !list.length)
+        throw new Error('no effects in this file');
+    return list.map(particleEffectSanitize);
+}
+
+/** The text of a library file with these effects, what particleEffectsLoad and the designer read
+ *  @param {Array<Object>} effects
+ *  @return {string}
+ *  @memberof ParticleEffects */
+function particleEffectsText(effects) { return JSON.stringify({version:1, effects}, undefined, 1); }
+
+/** Load a library file the particle designer saved and add its effects
+ *  @param {string} url
+ *  @return {Promise<Array<Object>>} - The effects it had
+ *  @memberof ParticleEffects */
+async function particleEffectsLoad(url)
+{
+    const effects = particleEffectsParse(JSON.stringify(await fetchJSON(url)));
+    particleEffectsAdd(effects);
+    return effects;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// the shape sheet: every shape white on clear in a cell of one canvas, drawn the first time one is asked for
+
+let particleEffectShapeTiles;
+
+/** The tile of a built-in shape, on a sheet the plugin draws once; undefined headless, without a canvas or without
+ *  WebGL, where an effect draws untextured squares
+ *  @param {string} name - One of particleEffectShapes
+ *  @return {TileInfo|undefined}
+ *  @memberof ParticleEffects */
+function particleEffectShapeTile(name)
+{
+    if (!particleEffectShapeTiles)
+    {
+        if (headlessMode || !glContext || typeof OffscreenCanvas == 'undefined') return;
+        // drawn at 4 times 32 pixel cells, so a big soft shape stays smooth when textures are pixelated
+        const cell = 32, r = 15, count = particleEffectShapes.length, res = 4;
+        const context = createCanvasContext(cell * count * res, cell * res);
+        context.scale(res, res);
+        context.fillStyle = context.strokeStyle = '#fff';
+        const soft = (x, y, radius, alpha=(t)=> 1 - t)=>
+        {
+            // a round falloff from the middle out
+            const g = context.createRadialGradient(x, y, 0, x, y, radius);
+            for (let i = 0; i <= 8; ++i)
+                g.addColorStop(i/8, 'rgba(255,255,255,' + alpha(i/8).toFixed(3) + ')');
+            context.fillStyle = g;
+            context.beginPath(); context.arc(x, y, radius, 0, 2*PI); context.fill();
+            context.fillStyle = '#fff';
+        };
+        const draw =
+        {
+            dot:      (x, y)=> { context.beginPath(); context.arc(x, y, r, 0, 2*PI); context.fill(); },
+            soft:     (x, y)=> soft(x, y, r),
+            glow:     (x, y)=> soft(x, y, r, (t)=> engineGlowAlpha(t, 1)),
+            smoke:    (x, y)=>
+            {
+                // a lumpy puff of soft circles
+                for (const [dx, dy, dr] of [[-4,-3,9], [4,-2,8], [0,4,9], [-5,5,6], [6,5,6]])
+                    soft(x + dx, y + dy, dr, (t)=> (1 - t) * .7);
+            },
+            spark:    (x, y)=>
+            {
+                // a glow squeezed thin, a streak along the tile's up
+                context.save(); context.translate(x, y); context.scale(.3, 1);
+                soft(0, 0, r, (t)=> engineGlowAlpha(t, .6));
+                context.restore();
+            },
+            square:   (x, y)=> context.fillRect(x - r, y - r, 2*r, 2*r),
+            triangle: (x, y)=>
+            {
+                context.beginPath(); context.moveTo(x, y - r); context.lineTo(x + r, y + r); context.lineTo(x - r, y + r);
+                context.fill();
+            },
+            ring:     (x, y)=>
+            {
+                context.lineWidth = 3;
+                context.beginPath(); context.arc(x, y, r - 2, 0, 2*PI); context.stroke();
+            },
+            star:     (x, y)=>
+            {
+                context.beginPath();
+                for (let i = 0; i < 10; ++i)
+                {
+                    const a = i * PI / 5 - PI/2, d = i % 2 ? r * .45 : r;
+                    context.lineTo(x + cos(a) * d, y + sin(a) * d);
+                }
+                context.fill();
+            },
+            plus:     (x, y)=> { context.fillRect(x - r, y - 4, 2*r, 8); context.fillRect(x - 4, y - r, 8, 2*r); },
+        };
+        particleEffectShapes.forEach((name, i)=> draw[name](i * cell + cell/2, cell/2));
+        const texture = new TextureInfo(context.canvas, true, false, false); // smooth even in a pixel art game
+        particleEffectShapeTiles = new Map(particleEffectShapes.map((name, i)=>
+            [name, new TileInfo(vec2((i * cell + 1) * res, res), vec2((cell - 2) * res), texture)]));
+    }
+    return particleEffectShapeTiles.get(name);
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// behaviors, the 2D pushes: a distance moved grows with the particle's scale, so a bigger effect moves the same way
+
+{
+    const b = particleEffectBehavior;
+    b('wobble').update = (p, s)=>
+    {
+        // each particle on its own beat, from its randomized life, so nothing is added to it
+        p.velocity.x += s * .003 * p.scale * sin(time*6 + p.lifeTime * 97 % 9);
+    };
+    b('swirl').update = (p, s)=>
+    {
+        // turn the direction of travel a little each frame
+        const a = s * .05, c = cos(a), n = sin(a), v = p.velocity;
+        v.set(v.x*c - v.y*n, v.x*n + v.y*c);
+    };
+    b('turbulence').update = (p, s)=>
+    {
+        p.velocity.x += rand(-1, 1) * s * .005 * p.scale;
+        p.velocity.y += rand(-1, 1) * s * .005 * p.scale;
+    };
+    b('attract').update = (p, s)=>
+    {
+        // pull toward the emitter by the distance, which grows with the scale already
+        const e = p.emitter, x = e.localSpace ? 0 : e.pos.x, y = e.localSpace ? 0 : e.pos.y;
+        p.velocity.x += (x - p.pos.x) * s * .002;
+        p.velocity.y += (y - p.pos.y) * s * .002;
+    };
+    b('orbit').update = (p, s)=>
+    {
+        const e = p.emitter, x = e.localSpace ? 0 : e.pos.x, y = e.localSpace ? 0 : e.pos.y;
+        p.velocity.x -= (p.pos.y - y) * s * .002;
+        p.velocity.y += (p.pos.x - x) * s * .002;
+    };
+    b('wind').update = (p, s)=>
+        p.velocity.x += s * .004 * p.scale * min((time - p.spawnTime) / p.lifeTime, 1);
+    b('stick').update = (p, s)=>
+    {
+        // grip the ground on landing, pair with collideLevel
+        if (!p.groundObject) return;
+        p.velocity.x *= 1 - s;
+        p.angleVelocity *= 1 - s;
+    };
+}
+
+/** Add a behavior effects can use by name, or replace one
+ *  @param {string} name
+ *  @param {function(Particle, number): void} update - Pushes a 2D particle, given the strength
+ *  @param {function(Particle3D, number): void} [update3D] - The same for a 3D particle, none leaves 3D alone
+ *  @param {number} [min] - Strength range the designer offers
+ *  @param {number} [max]
+ *  @param {number} [value] - Strength when first added
+ *  @param {string} [description]
+ *  @memberof ParticleEffects */
+function particleEffectsAddBehavior(name, update, update3D, min=-2, max=2, value=1, description='')
+{
+    const old = particleEffectBehavior(name);
+    old && particleEffectBehaviors.splice(particleEffectBehaviors.indexOf(old), 1);
+    particleEffectBehaviors.push({name, update, update3D, min, max, value, description});
+}
+
+// the update callback that runs an effect's behaviors, in 2D or 3D, undefined when it has none for that
+function particleEffectUpdateCallback(behaviors, is3D)
+{
+    const calls = behaviors.map(b=> [particleEffectBehavior(b.name)?.[is3D ? 'update3D' : 'update'], b.strength])
+        .filter(c=> c[0]);
+    if (calls.length)
+        return (p)=> { for (const [update, strength] of calls) update(p, strength); };
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// 2D effects
+
+// the settings the builders set themselves instead of copying across
+const particleEffectIndirect = ['emitSize', 'emitRect', 'emitHeight', 'tileIndex', 'tileSize', 'tilePadding', 'shape'];
+
+// the tile an effect draws with: its shape, else its tile in texture 0 when that fits, else none
+function particleEffectTileInfo(s)
+{
+    if (s.shape)
+        return particleEffectShapeTile(s.shape);
+    if (s.tileIndex < 0) return;
+    const texture = textureInfos[0], cell = s.tileSize + s.tilePadding*2;
+    if (!texture || !texture.size.x) return;
+    if (s.tileIndex < floor(texture.size.x / cell) * floor(texture.size.y / cell))
+        return tile(s.tileIndex, s.tileSize, 0, s.tilePadding);
+}
+
+/** Set a 2D emitter to an effect, live, so a running one keeps its particles
+ *  @param {ParticleEmitter} emitter
+ *  @param {Object} effect
+ *  @memberof ParticleEffects */
+function particleEffectApply(emitter, effect)
+{
+    effect = particleEffectSanitize(effect); // an effect written by hand or changed since it was added
+    const s = effect.settings, ended = emitter.emitTime < 0; // destroyed, its last particles going
+    for (const setting of particleEffectSettings)
+        if (!particleEffectIndirect.includes(setting.name))
+            emitter[setting.name] = setting.kind === 'color' ? new Color(...s[setting.name]) : s[setting.name];
+    ended && (emitter.emitTime = -1);
+    emitter.emitCircle = !s.emitRect;
+    emitter.emitSize = vec2(s.emitSize, s.emitRect ? s.emitHeight : s.emitSize);
+    emitter.tileInfo = particleEffectTileInfo(s);
+    emitter.renderOrder = s.additive ? 1e9 : 0;
+    emitter.particleUpdateCallback = particleEffectUpdateCallback(effect.behaviors);
+}
+
+// an effect from a name or an effect, recolored by the options
+function particleEffectResolve(nameOrEffect, options)
+{
+    const found = typeof nameOrEffect == 'string' ? particleEffectsGet(nameOrEffect) : nameOrEffect;
+    false&&ASSERT(!!found, 'no particle effect named ' + nameOrEffect);
+    if (!found) return;
+    // any setting in the options replaces the effect's own for this play, emitTime for a burst or a loop
+    const settings = {...found.settings};
+    for (const setting of particleEffectSettings)
+        if (options[setting.name] !== undefined)
+            settings[setting.name] = options[setting.name];
+    // sanitized each time, an effect may be written by hand or changed after it was added
+    const effect = particleEffectSanitize({...found, settings}), {hue=0, saturation=1} = options;
+    return hue || saturation != 1 ? particleEffectRecolor(effect, hue, saturation) : effect;
+}
+
+/** Play an effect: a 2D emitter set to it, placed, scaled and recolored
+ *  - A continuous effect (fire, a torch) goes until destroyed or given an emitTime, a one-shot ends itself
+ *  - Any setting in the options replaces the effect's own for this play: {emitTime: .5} for a burst of a continuous
+ *    effect, {emitTime: 0, emitRate: 30} to keep a one-shot going, or speed, particleTime and the rest
+ *  - Attach it to an object with addChild to follow it
+ *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
+ *  @param {Vector2} [pos]
+ *  @param {Object} [options]
+ *  @param {number} [options.scale] - Grows the whole effect, the built-ins fit a one unit object at 1
+ *  @param {number} [options.hue] - Turns its colors around the color wheel, 1 is all the way
+ *  @param {number} [options.saturation] - Multiplies its saturation, 0 is grey
+ *  @param {number} [options.angle] - Direction, 0 is up; the effect's own angle when not given
+ *  @param {TileInfo|TextureInfo} [options.tileInfo] - The game's own art to draw with in place of the effect's shape,
+ *    tinted by its colors; a whole texture draws as one tile
+ *  @param {*} [options.settings] - Any effect setting by its name, emitTime, emitRate, speed and the rest, replacing
+ *    the effect's own for this play
+ *  @return {ParticleEmitter|undefined} - undefined when there is no such effect
+ *  @memberof ParticleEffects */
+function particleEffect(nameOrEffect, pos=vec2(), options={})
+{
+    const effect = particleEffectResolve(nameOrEffect, options);
+    if (!effect) return;
+    const emitter = new ParticleEmitter(pos.copy());
+    particleEffectApply(emitter, effect);
+    emitter.scale = options.scale ?? 1;
+    if (options.angle !== undefined)
+        emitter.angle = options.angle;
+    const tileInfo = options.tileInfo; // the game's own art in place of the shape, a whole texture as one tile
+    if (tileInfo)
+        emitter.tileInfo = tileInfo instanceof TextureInfo ? new TileInfo(vec2(), tileInfo.size, tileInfo) : tileInfo;
+    return emitter;
+}
+
+/** An effect with a 2D emitter's settings, to save, build again, or build in 3D with particleEffect3D; its tile is
+ *  left out, since a hand made emitter's tile is its own texture and not one an effect can name, and so is its
+ *  scale, which an effect does not keep: pass it again with options.scale
+ *  @param {ParticleEmitter} emitter
+ *  @param {string} [name]
+ *  @return {Object}
+ *  @memberof ParticleEffects */
+function particleEffectFromEmitter(emitter, name='Effect')
+{
+    const settings = {};
+    for (const setting of particleEffectSettings)
+        if (!particleEffectIndirect.includes(setting.name) && emitter[setting.name] !== undefined)
+            settings[setting.name] = emitter[setting.name]; // a Color is taken as its channels by the sanitizer
+    settings.emitRect = !emitter.emitCircle;
+    settings.emitSize = emitter.emitSize.x;
+    settings.emitHeight = emitter.emitSize.y;
+    settings.shape = '';
+    settings.tileIndex = -1;
+    return particleEffectSanitize({name, settings});
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// 3D effects
+
+// the 3D pushes: a 3D particle is one view object the emitter reuses, so what differs per particle comes from its
+// randomized lifetime, and distances grow with the emitter's scale
+{
+    const b = particleEffectBehavior;
+    const center = (p)=> p.emitter.worldPos3D || p.emitter.pos3D; // where it was this update
+    b('wobble').update3D = (p, s)=> p.velocity.x += s * .003 * p.scale * sin(time*6 + p.lifeTime * 97 % 9);
+    b('swirl').update3D = (p, s)=>
+    {
+        const a = s * .05, c = cos(a), n = sin(a), v = p.velocity;
+        v.set(v.x*c - v.y*n, v.x*n + v.y*c, v.z);
+    };
+    b('turbulence').update3D = (p, s)=>
+    {
+        const k = s * .005 * p.scale;
+        p.velocity.x += rand(-1, 1) * k, p.velocity.y += rand(-1, 1) * k, p.velocity.z += rand(-1, 1) * k;
+    };
+    b('attract').update3D = (p, s)=>
+    {
+        const c = center(p);
+        p.velocity.x += (c.x - p.pos.x) * s * .002;
+        p.velocity.y += (c.y - p.pos.y) * s * .002;
+        p.velocity.z += (c.z - p.pos.z) * s * .002;
+    };
+    b('orbit').update3D = (p, s)=>
+    {
+        const c = center(p);
+        p.velocity.x -= (p.pos.y - c.y) * s * .002;
+        p.velocity.y += (p.pos.x - c.x) * s * .002;
+    };
+    b('wind').update3D = (p, s)=> p.velocity.x += s * .004 * p.scale * min(p.age / p.lifeTime, 1);
+    // stick has no 3D push: particleEffect3D makes it the friction a particle lands with
+}
+
+/** Set a 3D emitter to an effect, live, so a running one keeps its particles; its place, scale and flatten stay
+ *  @param {ParticleEmitter3D} emitter
+ *  @param {Object} effect
+ *  @memberof ParticleEffects */
+function particleEffectApply3D(emitter, effect)
+{
+    effect = particleEffectSanitize(effect); // an effect written by hand or changed since it was added
+    const s = effect.settings, e = emitter;
+    // a circle is a sphere and a rectangle a box as deep as it is wide
+    e.emitSize = s.emitRect ? vec3(s.emitSize, s.emitHeight, s.emitSize) : s.emitSize;
+    e.emitTime = e.emitTime < 0 ? -1 : s.emitTime; // destroyed, its last particles going, stays so
+    e.emitRate = s.emitRate, e.emitConeAngle = s.emitConeAngle;
+    e.tileInfo = particleEffectTileInfo(s);
+    for (const name of ['colorStartA', 'colorStartB', 'colorEndA', 'colorEndB'])
+        e[name] = new Color(...s[name]);
+    for (const name of ['particleTime', 'sizeStart', 'sizeEnd', 'speed', 'damping', 'gravity', 'fadeRate',
+        'randomness', 'additive', 'gravityScale', 'angleSpeed', 'angleDamping', 'collideLevel', 'restitution'])
+        e[name] = s[name];
+    e.trailTime = s.trailScale / 60; // a stretch of speed times trailScale is a streak of that many frames
+    const stick = effect.behaviors.find(b=> b.name == 'stick'); // in 3D, a grip on landing is less sliding
+    e.friction = stick ? min(s.friction, 1 - stick.strength) : s.friction;
+    // a 2D emitter at angle a shoots along (sin a, cos a), a z turn r takes up to (-sin r, cos r), so r is -a
+    e.rotation3D = vec3(0, 0, -s.angle);
+    e.particleUpdateCallback = particleEffectUpdateCallback(effect.behaviors, true);
+}
+
+/** Play an effect in 3D: a ParticleEmitter3D set to it, placed, scaled and recolored
+ *  - The same effect data as particleEffect, so the look carries across: a circle spawn area becomes a sphere and a
+ *    rectangle a box as deep as it is wide, both flat across the way it emits with options.flatten, a disc or a
+ *    sheet; a trail becomes a streak of the same length, and the settings the 3D emitter lacks (particleConeAngle,
+ *    randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the friction a
+ *    particle lands with
+ *  @param {string|Object} nameOrEffect - A built-in or added effect's name, or an effect
+ *  @param {Vector3} [pos3D]
+ *  @param {Object} [options] - scale, hue, saturation, angle, tileInfo and any setting as particleEffect; angle turns it
+ *    about z, so 0 is up; flatten makes the spawn area flat across the way it emits
+ *  @return {ParticleEmitter3D|undefined} - undefined when there is no such effect
+ *  @memberof ParticleEffects */
+function particleEffect3D(nameOrEffect, pos3D=vec3(), options={})
+{
+    const effect = particleEffectResolve(nameOrEffect, options);
+    if (!effect) return;
+    const e = new ParticleEmitter3D(pos3D.copy());
+    particleEffectApply3D(e, effect);
+    if (options.angle !== undefined)
+        e.rotation3D = vec3(0, 0, -options.angle);
+    e.scale3D = vec3(options.scale ?? 1);
+    e.emitFlat = !!options.flatten; // a sphere a disc, a box a sheet, across the way it emits
+    if (options.tileInfo)
+        e.tileInfo = options.tileInfo;
+    return e;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// the built-in effects, each tuned around a one unit emitter; one-shots have an emitTime and end themselves
+
+/** The names of the built-in effects, in the order a gallery shows them
+ *  @type {Array<string>}
+ *  @memberof ParticleEffects */
+const particleEffectsBuiltIn = [];
+{
+    const add = (name, settings, behaviors=[])=>
+    {
+        particleEffectsBuiltIn.push(name);
+        particleEffectsAdd({name, settings, behaviors});
+    };
+    const clear = (h, s, l)=> hsl(h, s, l, 0);
+
+    // fire
+    add('fire', {emitRate:120, emitSize:.6, emitConeAngle:.3, shape:'glow', particleTime:.8, sizeStart:.7,
+        sizeEnd:.15, speed:.02, angleSpeed:.02, damping:.95, gravity:.003, fadeRate:.3, randomness:.3, additive:true,
+        colorStartA:hsl(.08,1,.6), colorStartB:hsl(.14,1,.65), colorEndA:clear(.02,1,.5), colorEndB:clear(0,1,.3)});
+    add('torch', {emitRate:60, emitSize:.25, emitConeAngle:.2, shape:'glow', particleTime:.6, sizeStart:.45,
+        sizeEnd:.1, speed:.015, angleSpeed:.02, damping:.95, gravity:.003, fadeRate:.3, randomness:.3, additive:true,
+        colorStartA:hsl(.09,1,.6), colorStartB:hsl(.13,1,.7), colorEndA:clear(.03,1,.5), colorEndB:clear(0,1,.35)});
+    add('smoke', {emitRate:25, emitSize:.5, emitConeAngle:.3, shape:'smoke', particleTime:3, sizeStart:.5,
+        sizeEnd:2, speed:.01, angleSpeed:.01, damping:.99, gravity:.0004, fadeRate:.5, randomness:.3,
+        colorStartA:hsl(0,0,.5,.5), colorStartB:hsl(0,0,.3,.5), colorEndA:clear(0,0,.2), colorEndB:clear(0,0,.4)},
+        [{name:'wobble', strength:.5}]);
+    add('steam', {emitRate:30, emitSize:.4, emitConeAngle:.2, shape:'smoke', particleTime:1.5, sizeStart:.3,
+        sizeEnd:1.5, speed:.02, damping:.98, gravity:.0008, fadeRate:.6, randomness:.3,
+        colorStartA:hsl(0,0,1,.4), colorStartB:hsl(.6,.2,.9,.3), colorEndA:clear(0,0,1), colorEndB:clear(.6,.2,.9)},
+        [{name:'wobble', strength:.3}]);
+
+    // impacts
+    add('explosion', {emitRate:600, emitTime:.1, emitSize:.5, shape:'glow', particleTime:.6, sizeStart:1,
+        sizeEnd:.1, speed:.1, damping:.9, fadeRate:.2, randomness:.5, additive:true,
+        colorStartA:hsl(.12,1,.65), colorStartB:hsl(.06,1,.55), colorEndA:clear(0,1,.5), colorEndB:clear(0,0,.3)});
+    add('sparks', {emitRate:100, emitSize:.2, shape:'soft', particleTime:.6, sizeStart:.08, sizeEnd:.04,
+        speed:.07, damping:.96, gravity:-.006, fadeRate:.1, randomness:.4, additive:true, trailScale:3,
+        colorStartA:hsl(.17,1,.9), colorStartB:hsl(.12,1,.65), colorEndA:clear(.07,1,.5), colorEndB:clear(.03,1,.5)});
+    add('hit', {emitRate:400, emitTime:.05, emitSize:.2, shape:'spark', particleTime:.35, sizeStart:.5,
+        sizeEnd:.1, speed:.08, damping:.85, fadeRate:.1, randomness:.4, additive:true, trailScale:2,
+        colorStartA:hsl(0,0,1), colorStartB:hsl(0,1,.7), colorEndA:clear(0,1,.5), colorEndB:clear(0,1,.4)});
+    add('dust', {emitRate:300, emitTime:.05, emitSize:1, emitRect:true, emitHeight:.1, emitConeAngle:1.2,
+        shape:'smoke', particleTime:.8, sizeStart:.3, sizeEnd:.8, speed:.04, damping:.9, gravity:.0005,
+        fadeRate:.5, randomness:.4, colorStartA:hsl(.1,.3,.6,.5), colorStartB:hsl(.08,.2,.5,.5),
+        colorEndA:clear(.1,.3,.6), colorEndB:clear(.08,.2,.5)});
+    add('debris', {emitRate:200, emitTime:.05, emitSize:.5, emitConeAngle:1, shape:'square', particleTime:1.5,
+        sizeStart:.15, sizeEnd:.1, speed:.07, angleSpeed:.2, damping:.99, gravity:-.008, fadeRate:.1,
+        randomness:.5, colorStartA:hsl(.08,.4,.35), colorStartB:hsl(0,0,.4), colorEndA:hsl(.08,.4,.3),
+        colorEndB:hsl(0,0,.35)});
+
+    // pickups and magic
+    add('sparkle', {emitRate:30, emitSize:1, shape:'star', particleTime:.8, sizeStart:.3, sizeEnd:0,
+        speed:.005, angleSpeed:.05, fadeRate:.5, randomness:.3, additive:true,
+        colorStartA:hsl(.14,1,.7), colorStartB:hsl(0,0,1), colorEndA:clear(.14,1,.7), colorEndB:clear(0,0,1)});
+    add('magic', {emitRate:60, emitSize:1, shape:'soft', particleTime:1.5, sizeStart:.25, sizeEnd:0,
+        speed:.015, fadeRate:.3, randomness:.3, additive:true, colorStartA:hsl(.55,1,.65),
+        colorStartB:hsl(.79,1,.65), colorEndA:clear(0,0,1), colorEndB:clear(0,0,1)}, [{name:'swirl', strength:.5}]);
+    add('heal', {emitRate:30, emitSize:.8, emitConeAngle:.2, shape:'plus', particleTime:1.2, sizeStart:.25,
+        sizeEnd:.1, speed:.015, angleSpeed:0, particleConeAngle:0, gravity:.0005, fadeRate:.4, randomness:.3,
+        additive:true, colorStartA:hsl(.33,1,.6), colorStartB:hsl(.3,1,.75), colorEndA:clear(.33,1,.6),
+        colorEndB:clear(.3,1,.75)});
+    add('poison', {emitRate:20, emitSize:.8, shape:'smoke', particleTime:2, sizeStart:.3, sizeEnd:1,
+        speed:.006, gravity:.0002, fadeRate:.6, randomness:.4, colorStartA:hsl(.3,.8,.45,.6),
+        colorStartB:hsl(.8,.6,.45,.6), colorEndA:clear(.3,.8,.4), colorEndB:clear(.8,.6,.4)},
+        [{name:'wobble', strength:.5}]);
+    add('portal', {emitRate:80, emitSize:1, shape:'soft', particleTime:1, sizeStart:.15, sizeEnd:.05,
+        speed:.02, fadeRate:.3, randomness:.3, additive:true, colorStartA:hsl(.75,1,.6),
+        colorStartB:hsl(.6,1,.6), colorEndA:clear(.75,1,.6), colorEndB:clear(.6,1,.6)},
+        [{name:'orbit', strength:1}, {name:'attract', strength:.5}]);
+
+    // weather and ambience, one unit across at scale 1, so scale them to the view
+    add('rain', {emitRate:30, emitSize:1, emitRect:true, emitHeight:.6, angle:PI, emitConeAngle:0,
+        shape:'soft', particleTime:.8, sizeStart:.02, sizeEnd:.02, speed:.03, gravity:-.001, fadeRate:.1,
+        randomness:.2, trailScale:5, colorStartA:hsl(.63,1,.8,.6), colorStartB:hsl(.63,1,.8,.4),
+        colorEndA:hsl(.63,1,.8,.6), colorEndB:hsl(.63,1,.8,.4)});
+    add('snow', {emitRate:6, emitSize:1, emitRect:true, emitHeight:.6, angle:PI, emitConeAngle:.3,
+        shape:'soft', particleTime:4, sizeStart:.05, sizeEnd:.05, speed:.004, damping:.98, gravity:-.0002,
+        fadeRate:.2, randomness:.3, colorStartA:hsl(0,0,1), colorStartB:hsl(.58,1,.9), colorEndA:hsl(0,0,1),
+        colorEndB:hsl(.58,1,.9)}, [{name:'wobble', strength:.15}]);
+    add('leaves', {emitRate:3, emitSize:1, emitRect:true, emitHeight:.2, angle:PI, emitConeAngle:.5,
+        shape:'triangle', particleTime:4, sizeStart:.12, sizeEnd:.12, speed:.003, angleSpeed:.05, damping:.98,
+        gravity:-.0001, fadeRate:.2, randomness:.4, randomColorLinear:false, colorStartA:hsl(.25,.7,.4),
+        colorStartB:hsl(.07,.8,.5), colorEndA:hsl(.08,.6,.35), colorEndB:hsl(.05,.7,.4)},
+        [{name:'wobble', strength:.15}, {name:'wind', strength:.05}]);
+    add('bubbles', {emitRate:8, emitSize:1, emitRect:true, emitHeight:.1, emitConeAngle:.2, shape:'ring',
+        particleTime:2, sizeStart:.1, sizeEnd:.2, speed:.01, gravity:.0003, fadeRate:.2, randomness:.4,
+        colorStartA:hsl(.55,.8,.8,.8), colorStartB:hsl(.5,.6,.9,.6), colorEndA:hsl(.55,.8,.8,.3),
+        colorEndB:hsl(.5,.6,.9,.2)}, [{name:'wobble', strength:.3}]);
+    add('fireflies', {emitRate:3, emitSize:1, shape:'glow', particleTime:3, sizeStart:.15, sizeEnd:.15,
+        speed:.003, damping:.99, fadeRate:.8, randomness:.3, additive:true, colorStartA:hsl(.2,1,.6),
+        colorStartB:hsl(.15,1,.7), colorEndA:hsl(.2,1,.6), colorEndB:hsl(.15,1,.7)},
+        [{name:'turbulence', strength:.3}]);
+
+    // trails and shots
+    add('trail', {emitRate:60, shape:'soft', particleTime:.5, sizeStart:.4, sizeEnd:0, speed:0, angleSpeed:0,
+        fadeRate:.1, randomness:.2, additive:true, colorStartA:hsl(.08,1,.6), colorStartB:hsl(.12,1,.65),
+        colorEndA:clear(.03,1,.5), colorEndB:clear(0,1,.4)});
+    add('muzzle', {emitRate:300, emitTime:.05, emitConeAngle:.3, shape:'glow', particleTime:.2,
+        sizeStart:.5, sizeEnd:.1, speed:.1, damping:.8, fadeRate:.1, randomness:.3, additive:true,
+        colorStartA:hsl(.14,1,.8), colorStartB:hsl(.1,1,.6), colorEndA:clear(.08,1,.5), colorEndB:clear(.05,1,.4)});
+
+    // other
+    add('blood', {emitRate:300, emitTime:.1, emitConeAngle:.8, shape:'dot', particleTime:3, sizeStart:.15,
+        sizeEnd:.1, speed:.09, gravity:-.01, fadeRate:.1, randomness:.4, collideLevel:true, restitution:.1,
+        colorStartA:hsl(0,1,.35), colorStartB:hsl(0,1,.2), colorEndA:hsl(0,1,.25), colorEndB:hsl(0,1,.15)},
+        [{name:'stick', strength:1}]);
+    add('confetti', {emitRate:200, emitTime:.1, emitSize:.2, emitConeAngle:.6, shape:'square', particleTime:3,
+        sizeStart:.1, sizeEnd:.1, speed:.09, angleSpeed:.15, damping:.96, gravity:-.004, fadeRate:.1,
+        randomness:.4, randomColorLinear:false, colorStartA:hsl(0,1,.5), colorStartB:hsl(.6,1,.6),
+        colorEndA:hsl(0,1,.5), colorEndB:hsl(.6,1,.6)}, [{name:'wobble', strength:.3}]);
+    add('splash', {emitRate:300, emitTime:.05, emitSize:.5, emitConeAngle:.6, shape:'soft', particleTime:.7,
+        sizeStart:.12, sizeEnd:.06, speed:.08, gravity:-.008, fadeRate:.2, randomness:.4,
+        colorStartA:hsl(.58,.8,.7,.8), colorStartB:hsl(.55,.6,.85,.8), colorEndA:hsl(.58,.8,.7,.2),
+        colorEndB:hsl(.55,.6,.85,.2)});
+}
 
 /**
  * LittleJS glTF Plugin
@@ -29003,7 +30803,13 @@ async function loadGLTF(url)
     const response = await fetch(url);
     if (!response.ok)
         throw new Error('loadGLTF failed: ' + url);
-    return parseGLTF(await response.arrayBuffer(), url.slice(0, url.lastIndexOf('/') + 1));
+    // the files beside it are beside where it came from, after any redirect; a blob or data url has nothing
+    // beside it, and a model in one is whole, or parsed with parseGLTF and a base of its own
+    const from = response.url || url;
+    let base = '';
+    if (!/^(blob|data):/i.test(from))
+        base = response.url ? new URL('.', from).href : from.slice(0, from.lastIndexOf('/') + 1);
+    return parseGLTF(await response.arrayBuffer(), base);
 }
 
 /** Parse a model from GLB bytes or glTF JSON, fetching the buffers and images it refers to