littlejsengine 1.22.0 → 1.23.0

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.22.0';
+const engineVersion = '1.23.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -982,8 +982,19 @@ function tweak(){}
 function tweakButton(){}
 function tweakDivider(){}
 function tweakEngineDefaults(){}
-const levelEditor = {isOpen: false, open(){}, close(){}, onTile: undefined, onRestart: undefined, onPlayFrom: undefined,
-    paletteTiles: undefined, use3D: undefined};
+class LevelEditor
+{
+    constructor() { this.paletteTiles = this.use3D = this.tool = undefined; }
+    get isOpen() { return false; }
+    get is3D() { return false; }
+    get edit2D() { return undefined; }
+    get edit3D() { return undefined; }
+    open(){} close(){} addKey(){} addButton(){} addTool(){}
+    onTile(){} onRestart(){} onPlayFrom(){} onOpen(){} onClose(){} onUpdate(){} onDraw(){} onPanel(){}
+    onSave(){ return false; }
+}
+let levelEditor = new LevelEditor;
+function setLevelEditor(editor){ levelEditor = editor; }
 function editorMapRestore(map){ return map; }
 function editorMapLoaded(){}
 function editorJSONFetched(){}
@@ -2884,6 +2895,15 @@ let touchGamepadEnable = false;
  *  @memberof Settings */
 let touchGamepadPassthrough = false;
 
+/** True if a pinch of two fingers turns the mouse wheel: touchPinch is added to mouseWheel, so what zooms with
+ *  the wheel zooms with a pinch, the mouse is between the two fingers, and a second finger lets go of the button
+ *  the first pressed, since a pinch is not a drag; turn it off for a game with its own use for two fingers, the
+ *  first finger stays the mouse and touchPinch can still be read
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let touchPinchWheel = true;
+
 /** Size of center button if touch gamepad should have start button in the center
  *  - Prevents activating when pressed near virtual stick or face buttons
  *  - When the game is paused, any touch will press the button
@@ -3279,6 +3299,11 @@ function setTouchInputEnable(enable) { touchInputEnable = enable; }
  *  @memberof Settings */
 function setTouchGamepadEnable(enable) { touchGamepadEnable = enable; }
 
+/** Set if a pinch of two fingers turns the mouse wheel
+ *  @param {boolean} enable
+ *  @memberof Settings */
+function setTouchPinchWheel(enable) { touchPinchWheel = enable; }
+
 /** Set if touches outside the gamepad controls should still drive mouse/touch input
  *  @param {boolean} passthrough
  *  @memberof Settings */
@@ -4585,17 +4610,29 @@ class SpriteAnimator
      *  @return {SpriteAnimation} */
     get clip() { return this.clips[this.name]; }
 
+    /** The clip showing now, once a clip that has ended has called its onEnd: the callback may switch clips, and a
+     *  read gives the clip it switched to, not the one that ended
+     *  @return {SpriteAnimation}
+     *  @ignore */
+    get settledClip()
+    {
+        // each clip's own isDone calls its onEnd once; a few switches in a row at most
+        for (let i = 4, clip; i-- && clip !== this.clip;)
+            (clip = this.clip).isDone;
+        return this.clip;
+    }
+
     /** The tile of the frame showing now
      *  @return {TileInfo} */
-    get tileInfo() { return this.clip.tileInfo; }
+    get tileInfo() { return this.settledClip.tileInfo; }
 
     /** The frame of the clip showing now
      *  @return {number} */
-    get frame() { return this.clip.frame; }
+    get frame() { return this.settledClip.frame; }
 
     /** True once the clip showing now is a play that has ended
      *  @return {boolean} */
-    get isDone() { return this.clip.isDone; }
+    get isDone() { return this.settledClip.isDone; }
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -6034,6 +6071,13 @@ let mouseDeltaScreen = vec2();
  *  @memberof Input */
 let mouseWheel = 0;
 
+/** Touch pinch delta this frame, in the mouse wheel's units: two fingers moving apart are negative, as the wheel
+ *  turned up is, and moving together positive, 1 for every 50 pixels; added to mouseWheel while touchPinchWheel
+ *  is on, so a game that zooms with the wheel zooms with a pinch
+ *  @type {number}
+ *  @memberof Input */
+let touchPinch = 0;
+
 /** True if mouse was inside the document window, set to false when mouse leaves
  *  @type {boolean}
  *  @memberof Input */
@@ -6122,6 +6166,7 @@ function inputClearKey(key, device=0, clearDown=true, clearPressed=true, clearRe
 const inputWASDToArrow = {KeyW:'ArrowUp', KeyS:'ArrowDown', KeyA:'ArrowLeft', KeyD:'ArrowRight'};
 const inputArrowToWASD = {ArrowUp:'KeyW', ArrowDown:'KeyS', ArrowLeft:'KeyA', ArrowRight:'KeyD'};
 const inputKeysHeld = new Set; // the keys physically down, since an arrow's slot is shared with its alias
+let inputPinch; // the two fingers pinching and how far apart they were, undefined with no pinch
 let inputWasTouching = 0, inputTouchIdentifier; // the touch driving the mouse, cleared with the input so only a new touch presses
 let inputLastTouchTime = -1e9; // when a touch event last came, the mouse events a browser makes from a tap follow it
 
@@ -6164,6 +6209,7 @@ function inputClear()
         if (!i || inputData[i]) inputData[i] = [];
     inputKeysHeld.clear();
     inputWasTouching = 0;
+    inputPinch = undefined;
     // release the touch gamepad, a finger still on it has to lift before it can take a control again
     touchGamepadPointerRole.clear();
     touchGamepadButtons.length = 0;
@@ -6691,19 +6737,52 @@ function inputInit()
                     const pressTouch = !inputWasTouching && e.type == 'touchstart' &&
                         [...e.changedTouches].find(t=> !isGamepadTouch(t));
                     const touch = pressTouch || gameTouches[0];
+                    let pos = vec2(touch.clientX, touch.clientY);
+
+                    // two fingers pinch: how far they moved together or apart is the touch screen's wheel, a
+                    // click for every 50 pixels, and the mouse is between them, the place to zoom about; with
+                    // touchPinchWheel off the pinch is only measured, and the first finger is the mouse as ever
+                    const pinching = touching > 1 && touchPinchWheel;
+                    if (touching > 1)
+                    {
+                        const [a, b] = gameTouches, key = a.identifier + ' ' + b.identifier;
+                        const distance = hypot(a.clientX - b.clientX, a.clientY - b.clientY);
+                        if (inputPinch && inputPinch.key === key)
+                        {
+                            const delta = (inputPinch.distance - distance) / 50;
+                            touchPinch += delta;
+                            if (touchPinchWheel)
+                                mouseWheel += delta;
+                        }
+                        inputPinch = {key, distance}; // other fingers start it over, with no jump
+                        if (pinching)
+                            pos = vec2((a.clientX + b.clientX) / 2, (a.clientY + b.clientY) / 2);
+                    }
+                    else
+                        inputPinch = undefined;
 
                     // set event pos and pass it along
-                    const pos = vec2(touch.clientX, touch.clientY);
                     const mousePosScreenLast = mousePosScreen;
                     mousePosScreen = mouseEventToScreen(pos);
-                    if (inputWasTouching && touch.identifier === inputTouchIdentifier)
+                    if (pinching)
+                    {
+                        // a pinch is not a press or a drag, the finger that pressed lets go
+                        if (inputData[0][button] & 1)
+                            inputData[0][button] = inputData[0][button] & 2 | 4;
+                    }
+                    else if (inputWasTouching && touch.identifier === inputTouchIdentifier)
                         mouseDeltaScreen = mouseDeltaScreen.add(mousePosScreen.subtract(mousePosScreenLast));
                     else if (pressTouch)
                         inputData[0][button] = 3;
-                    inputTouchIdentifier = touch.identifier;
+                    // the finger left after a pinch moves the mouse from where it is, with no jump and no press
+                    inputTouchIdentifier = pinching ? undefined : touch.identifier;
+                }
+                else
+                {
+                    inputPinch = undefined;
+                    if (inputWasTouching && (inputData[0][button] & 1))
+                        inputData[0][button] = inputData[0][button] & 2 | 4; // released only if it was pressed
                 }
-                else if (inputWasTouching && (inputData[0][button] & 1))
-                    inputData[0][button] = inputData[0][button] & 2 | 4; // released only if it was pressed
 
                 // set was touching
                 inputWasTouching = touching;
@@ -6962,7 +7041,7 @@ function inputUpdatePost()
     for (const deviceInputData of inputData)
     for (const i in deviceInputData)
         deviceInputData[i] &= 1;
-    mouseWheel = 0;
+    mouseWheel = touchPinch = 0;
     mouseDelta = vec2();
     mouseDeltaScreen = vec2();
 }
@@ -7694,10 +7773,9 @@ class Sound
         false&&ASSERT(isNumber(range), 'range must be a number');
         false&&ASSERT(isNumber(taper), 'taper must be a number');
 
-        /** @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 */
+         *  to render3D.soundDefaultRange instead, which is further; setting range makes it false */
         this.rangeIsDefault = rangeIsDefault;
         /** @property {number} - At what percentage of range should it start tapering */
         this.taper = taper;
@@ -7753,6 +7831,15 @@ class Sound
         }
     }
 
+    /** World space max range of sound, 0 for no limit; a range that is set is the sound's own, in 3D too
+     *  @type {number} */
+    get range() { return this.rangeValue; }
+    set range(range)
+    {
+        this.rangeValue = range;
+        this.rangeIsDefault = false;
+    }
+
     /** Sample data for each channel
      *  Sounds keep their samples in an audio buffer, so reading this rebuilds
      *  the arrays from it and caches them. The copies are safe to hold onto,
@@ -13118,13 +13205,13 @@ class LightSystemPlugin
             // an automatic size follows the canvas, so reallocate the lightmap when
             // the canvas changed size, after the flush so the batch keeps its texture
             const size = lightSystem.textureSize;
-            if (lightSystem.textureSizeAuto &&
-                (size.x !== mainCanvasSize.x || size.y !== mainCanvasSize.y))
+            const wantX = glClampTextureSize(mainCanvasSize.x), wantY = glClampTextureSize(mainCanvasSize.y);
+            if (lightSystem.textureSizeAuto && (size.x !== wantX || size.y !== wantY))
             {
-                lightSystem.textureSize = mainCanvasSize.copy();
+                lightSystem.textureSize = vec2(wantX, wantY);
                 glContext.bindTexture(glContext.TEXTURE_2D, lightSystem.texture);
                 glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA,
-                    mainCanvasSize.x, mainCanvasSize.y, 0,
+                    wantX, wantY, 0,
                     glContext.RGBA, glContext.UNSIGNED_BYTE, null);
                 // put back the texture the engine tracks, a draw in renderLight must not sample the lightmap
                 if (glActiveTexture)
@@ -13264,8 +13351,10 @@ class LightSystemPlugin
         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));
+        if (!size) return;
+        const x = glClampTextureSize(size.x), y = glClampTextureSize(size.y);
+        if (x !== size.x || y !== size.y)
+            this.textureSize = vec2(x, y); // only when it is too large, this runs every frame
     }
 
     /** Draw a single Light's falloff blob into the currently bound lightmap.
@@ -20103,6 +20192,179 @@ function sceneUpdate() { paused || !timeScale || sceneCurrent?.update?.(); }
 function sceneRender() { sceneCurrent?.render?.(); }
 function sceneRenderPost() { sceneCurrent?.renderPost?.(); }
 
+/**
+ * LittleJS Parallax Plugin
+ * - A background layer that follows the camera by a part of its movement, so it looks far away
+ * - Repeats across the view, so a level of any width has a background
+ * - Draws mountains by default, or anything a game draws into it
+ * @namespace Parallax
+ */
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A background layer with parallax: an image that follows the camera by a part of its movement and repeats across
+ * the view, drawn once into a canvas by a function, mountains when none is given
+ * - A far layer has a parallax near 1 and a low renderOrder, a near one a smaller parallax and a higher renderOrder
+ * - The image should meet itself at its left and right edges to repeat without a seam, as the mountains do
+ * @memberof Parallax
+ * @extends CanvasLayer
+ * @example
+ * // three ranges of mountains, the far ones lighter and slower
+ * for (let i = 3; i--;)
+ *     new ParallaxLayer(vec2(0, i*2), vec2(40, 20), .9 - i*.2, -1e3 + i,
+ *         parallaxMountains(hsl(.6, .3, .7 - i*.2), hsl(.6, .5, .2), i));
+ *
+ * // or draw your own image into the layer
+ * new ParallaxLayer(vec2(), vec2(40, 20), .5, -1e3, (context, size)=>
+ * {
+ *     context.fillStyle = '#fff';
+ *     context.fillRect(size.x/2 - 20, size.y/2 - 20, 40, 40);
+ * });
+ */
+class ParallaxLayer extends CanvasLayer
+{
+    /** Create a parallax layer and draw its image
+     *  @param {Vector2} [pos] - Where the middle of the image is in the world when the camera is there too
+     *  @param {Vector2} [size] - World size of one copy of the image
+     *  @param {number|Vector2} [parallax] - How much of the camera's movement it follows, 0 stays with the world
+     *    and 1 with the screen, a Vector2 to follow x and y by different amounts
+     *  @param {number} [renderOrder] - Low to draw behind the game, far layers lowest
+     *  @param {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} [drawFunction] - Draws
+     *    the image, given the canvas context, its size in pixels and the layer; mountains when not given
+     *  @param {Vector2} [canvasSize] - Size of the image in pixels */
+    constructor(pos=vec2(), size=vec2(32, 16), parallax=.5, renderOrder=-1e3, drawFunction=parallaxMountains(),
+        canvasSize=vec2(512, 256))
+    {
+        false&&ASSERT(isNumber(parallax) || isVector2(parallax), 'parallax must be a number or a Vector2');
+        false&&ASSERT(typeof drawFunction == 'function', 'drawFunction must be a function');
+        super(pos, size, 0, renderOrder, canvasSize);
+
+        /** @property {Vector2} - How much of the camera's movement it follows on each axis, 0 stays with the world
+         *  and 1 with the screen */
+        this.parallax = isVector2(parallax) ? /** @type {Vector2} */ (parallax).copy() :
+            vec2(/** @type {number} */ (parallax));
+        /** @property {boolean} - Repeat the image across the view, left and right */
+        this.wrapX = true;
+        /** @property {boolean} - Repeat the image up and down the view */
+        this.wrapY = false;
+        /** @property {number} - How much the camera's zoom changes its size on the screen: 1 like the world, 0 not
+         *  at all, the same on the screen at any zoom as it is at zoomScale */
+        this.zoomFollow = 1;
+        /** @property {number} - The camera scale its size is given for, used when zoomFollow is under 1 */
+        this.zoomScale = cameraScale;
+        /** @property {function(OffscreenCanvasRenderingContext2D, Vector2, ParallaxLayer): void} - Draws the
+         *  image, redraw() after changing it */
+        this.drawFunction = drawFunction;
+        this.redraw();
+    }
+
+    /** Draw the image again with drawFunction, after changing it or what it draws from */
+    redraw()
+    {
+        const context = this.context;
+        if (!context) return; // headless
+        const size = vec2(this.canvas.width, this.canvas.height);
+        context.clearRect(0, 0, size.x, size.y);
+        this.drawFunction(context, size, this);
+        this.updateWebGL();
+    }
+
+    // how much smaller it is drawn than its size, from the camera's zoom and how much of it the layer follows
+    zoomFactor()
+    { return this.zoomFollow < 1 && cameraScale > 0 ? (this.zoomScale / cameraScale) ** (1 - this.zoomFollow) : 1; }
+
+    /** World size one copy of the image is drawn at now, its size unless zoomFollow is under 1
+     *  @return {Vector2} */
+    getDrawSize() { return this.size.scale(this.zoomFactor()); }
+
+    /** Where each copy of the image is drawn now, in the world: one place, or with wrapping every place that
+     *  shows in the view
+     *  @return {Array<Vector2>} */
+    getDrawPositions()
+    {
+        // its place seen from the camera is cut down by the parallax, and by the zoom it does not follow
+        const zoom = this.zoomFactor(), size = this.size.scale(zoom), p = this.parallax;
+        const offset = this.pos.subtract(cameraPos);
+        const center = cameraPos.add(vec2(offset.x * (1 - p.x) * zoom, offset.y * (1 - p.y) * zoom));
+
+        // the copies that reach into the view; a turned camera sees as far as its corner each way
+        const view = mainCanvasSize.scale(.5 / (cameraScale || 1));
+        const reach = cameraAngle ? vec2(view.length()) : view;
+        const range = (wrap, axis)=>
+        {
+            if (!wrap || !(size[axis] > 0)) return [0, 0];
+            const from = cameraPos[axis] - reach[axis] - size[axis] / 2 - center[axis];
+            const to = cameraPos[axis] + reach[axis] + size[axis] / 2 - center[axis];
+            const first = ceil(from / size[axis]);
+            return [first, min(floor(to / size[axis]), first + 99)]; // a tiny image does not draw without end
+        };
+        const [x0, x1] = range(this.wrapX, 'x'), [y0, y1] = range(this.wrapY, 'y'), positions = [];
+        for (let y = y0; y <= y1; ++y)
+        for (let x = x0; x <= x1; ++x)
+            positions.push(vec2(center.x + x * size.x, center.y + y * size.y));
+        return positions;
+    }
+
+    // Render the layer, called automatically by the engine
+    render()
+    {
+        const size = this.getDrawSize();
+        for (const pos of this.getDrawPositions())
+            this.draw(pos, size, this.color, 0, this.mirror, this.additiveColor, false);
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+// the ridge of a range of mountains: a height for each column of an image and one more, the last the same as the
+// first so the image repeats with no step; it wanders about the middle, turning now and then
+function parallaxRidge(width, height, random)
+{
+    const pointiness = .2, levelness = .005, slopeRange = height / 256; // how often it turns, how hard it is
+    const ridge = new Float32Array(width + 1), middle = height / 2;     // pulled level, how steep it gets
+    let y = middle, slope = random.float(-slopeRange, slopeRange);
+    for (let x = 0; x <= width; ++x)
+    {
+        ridge[x] = y;
+        y += slope -= (y - middle) * levelness;
+        if (random.float() < pointiness)
+            slope = random.float(-slopeRange, slopeRange);
+    }
+    // take out the difference between its ends, a little from each column, and keep it inside the image
+    const drift = ridge[width] - ridge[0];
+    for (let x = 0; x <= width; ++x)
+        ridge[x] = clamp(ridge[x] - drift * x / width, 0, height);
+    return ridge;
+}
+
+/** A draw function for a ParallaxLayer: a range of mountains across the image, shaded from the color of their
+ *  peaks down to the color of their feet, that repeats with no seam
+ *  @param {Color} [topColor] - Color at the peaks
+ *  @param {Color} [bottomColor] - Color at the bottom of the image
+ *  @param {number} [seed] - The same seed gives the same mountains, random when not given
+ *  @return {function(OffscreenCanvasRenderingContext2D, Vector2): void}
+ *  @memberof Parallax */
+function parallaxMountains(topColor=hsl(.6, .2, .6), bottomColor=hsl(.6, .3, .25), seed)
+{
+    return (context, size)=>
+    {
+        const w = size.x, h = size.y;
+        const random = new RandomGenerator(seed === undefined ? randInt(1e9) + 1 : seed * 7919 + 1);
+        const ridge = parallaxRidge(w, h, random);
+
+        // a strip one pixel wide with the shading, stretched down each column from its peak
+        const strip = createCanvasContext(1, h);
+        for (let i = h; i--;)
+        {
+            strip.fillStyle = topColor.lerp(bottomColor, i / h).toString();
+            strip.fillRect(0, i, 1, 1);
+        }
+        for (let x = w; x--;)
+            ridge[x] < h && context.drawImage(strip.canvas, 0, 0, 1, h, x, ridge[x], 1, h - ridge[x]);
+    };
+}
+
 /**
  * LittleJS PathFinder Plugin
  * - Grid-based A* pathfinder with two-pass smoothing for natural-looking paths
@@ -22369,12 +22631,17 @@ function render3DShadowCaster()
         light.intensity > 0 && light.color.a > 0 ? light : undefined;
 }
 
+// the widest cone a shadow map can look down, to each side; the light that casts the shadows lights no wider, or
+// what is past the map's edge would be lit with nothing to shade it
+const RENDER3D_SHADOW_CONE_MAX = 1.35;
+
 // 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);
+    const widest = light === render3DShadowCaster() ? RENDER3D_SHADOW_CONE_MAX : PI;
+    const angle = light.directional ? 0 : min(light.coneAngle, widest);
     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();
@@ -23161,8 +23428,9 @@ class Render3DPlugin
             // 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);
+            // the near plane stays in front of the far one however small the light
+            const far = caster.radius, near = min(max(far / 500, .02), far / 2);
+            const fov = min(caster.coneAngle, RENDER3D_SHADOW_CONE_MAX) * 2 + .1;
             this.shadowMatrix = Matrix4.perspective(fov, 1, near, far).multiply(
                 Matrix4.lookAt(pos, pos.add(forward), up).invert());
             this.shadowPlanes = render3DFrustumPlanes(this.shadowMatrix);
@@ -26596,7 +26864,7 @@ class InstancedMesh3D extends EngineObject3D
  * - intensity multiplies the color, above 1 for a light brighter than white
  * - radius is a world distance, so scale3D does not change it
  * - An alpha, an intensity or a radius of 0 switches it off, and a light that is off takes none of those slots
- * - Draws nothing itself, add a glow with drawSoftDisc or a small emissive mesh if it should be seen
+ * - Draws nothing but its glow, when it has one; add a small emissive mesh if the lamp itself should be seen
  * @extends EngineObject3D
  * @memberof Render3D
  * @example
@@ -26645,8 +26913,10 @@ class Light3D extends EngineObject3D
         const r = render3D, c = this.color, pos = render3DObjectMatrix(this).getTranslation();
         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), engineGlowTexture(this.glowFalloff), color);
+        const color = rgb(c.r, c.g, c.b, c.a * min(this.intensity, 1)), texture = engineGlowTexture(this.glowFalloff);
+        // a browser that can not make the glow's texture draws no glow, not a plain square
+        if (texture || !glContext)
+            r.drawBillboard(at, vec2(this.glow), texture, color);
     }
 }
 
@@ -26656,7 +26926,7 @@ class Light3D extends EngineObject3D
  * - It shines from its position toward the origin, like a three.js DirectionalLight: only the direction to it
  *   counts, so moving it or its parent swings the light around; parent it to a sun in the sky and it follows
  * - It cannot sit on the origin, since that leaves no direction
- * - Like every Light3D it casts no shadow, only the sun, render3D.sunDirection, does
+ * - It casts no shadow: the sun, render3D.sunDirection, does, or a spotlight set as render3D.shadowLight
  * @extends Light3D
  * @memberof Render3D
  * @example
@@ -27733,6 +28003,9 @@ class ParticleEmitter3D extends EngineObject3D
         /** @property {boolean} - Particles hit the level, the height maps and voxel maps, bouncing by restitution and
          *  sliding along by friction; off by default, it tests each particle's move against the level every frame */
         this.collideLevel = false;
+        /** @property {number} - How much a particle grips where it lands, 0 to 1: its speed along the surface is
+         *  cut by this much on each hit, on top of the friction, 1 stops it there */
+        this.stick = 0;
         /** @property {Particle3DCallback|undefined} - Called with each particle as it is made
          *  @type {Particle3DCallback|undefined} */
         this.particleCreateCallback = undefined;
@@ -27752,7 +28025,7 @@ class ParticleEmitter3D extends EngineObject3D
         /** @property {Vector3|undefined} - Where the emitter was at its last update, for when its parent is destroyed
          *  @type {Vector3|undefined} */
         this.worldPos3D = undefined;
-        this.emitTimeBuffer = 0;
+        this.emitTimeBuffer = 1; // the first particle comes at once, as the 2D emitter's does
     }
 
     /** Spawn new particles, move the live ones, and go away when done */
@@ -27769,9 +28042,10 @@ class ParticleEmitter3D extends EngineObject3D
         {
             // a rate of zero is an emitter fed by hand, and the global scale only quiets it,
             // neither is a reason to stop counting down the emit time
-            if (this.emitRate && particleEmitRateScale)
+            const rate = this.emitRate * particleEmitRateScale;
+            if (rate > 0 && rate < Infinity)
             {
-                this.emitTimeBuffer += this.emitRate * particleEmitRateScale * timeDelta;
+                this.emitTimeBuffer += rate * timeDelta;
                 for (; this.emitTimeBuffer >= 1; --this.emitTimeBuffer)
                     this.emitParticle();
             }
@@ -27811,7 +28085,9 @@ class ParticleEmitter3D extends EngineObject3D
             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());
+            // true when its collide callback destroyed it, it has had its last callback but the destroy one
+            const gone = collideLevel && this.particleCollide(k, data[k] - vx, data[k+1] - vy, data[k+2] - vz);
+            collideLevel && reread();
             const t = i * trailMax * 3;
             if (trailMax)
             {
@@ -27823,7 +28099,7 @@ class ParticleEmitter3D extends EngineObject3D
                 trail[j] = data[k], trail[j+1] = data[k+1], trail[j+2] = data[k+2];
                 data[k+20] = n + 1;
             }
-            updateCallback && (this.particleCall(updateCallback, k), reread());
+            updateCallback && !gone && (this.particleCall(updateCallback, k), reread());
             if ((data[k+17] += timeDelta) >= data[k+16])
             {
                 // dead: the last particle takes its slot, trail and all, order does not matter
@@ -27925,13 +28201,14 @@ class ParticleEmitter3D extends EngineObject3D
         out[k] = view.pos.x, out[k+1] = view.pos.y, out[k+2] = view.pos.z;
         out[k+3] = view.velocity.x, out[k+4] = view.velocity.y, out[k+5] = view.velocity.z;
         if (view.destroyed)
-            out[k+17] = max(out[k+17], out[k+16] - timeDelta); // aged past its life this update
+            out[k+17] = max(out[k+17], out[k+16]); // its life lived: a step short of it can round to just under
         return result;
     }
 
     // stop the particle at k where its last move went into the level, from where it was: back at the surface, a hair
     // off it, its speed into it turned around by restitution and its speed along it kept by friction, unless the
-    // collide callback lets it through; one that starts inside is let go, as a 2D one is
+    // collide callback lets it through; one that starts inside is let go, as a 2D one is; true when the callback
+    // destroyed it
     particleCollide(k, x, y, z)
     {
         let data = this.particleData;
@@ -27944,18 +28221,21 @@ class ParticleEmitter3D extends EngineObject3D
             if (h && (!hit || h.distance < hit.distance))
                 hit = h, level = l;
         }
-        if (!hit) return;
+        if (!hit) return false;
         const point = from.lerp(to, hit.distance);
         const callback = this.particleCollideCallback;
         if (callback && (!this.particleCall(callback, k, level, point.copy()) || this.particleView.destroyed))
-            return; // let through, or destroyed by the callback
+            return this.particleView.destroyed; // let through, or destroyed by the callback
         data = this.particleData; // as the callback left it, an emit may have grown it
 
         const n = hit.normal, v = vec3(data[k+3], data[k+4], data[k+5]), into = n.scale(v.dot(n));
-        const restitution = max(this.restitution, level.restitution), friction = max(this.friction, level.friction);
+        // the larger friction of the two, as objects take it, then the emitter's own grip, which a level can not undo
+        const restitution = max(this.restitution, level.restitution);
+        const friction = max(this.friction, level.friction) * (1 - clamp(this.stick));
         const out = v.subtract(into).scale(friction).subtract(into.scale(restitution)), p = point.add(n.scale(1e-3));
         data[k] = p.x, data[k+1] = p.y, data[k+2] = p.z;
         data[k+3] = out.x, data[k+4] = out.y, data[k+5] = out.z;
+        return false;
     }
 
     /** Draw the particles, as flat squares or as streaks when trailTime is set
@@ -28219,6 +28499,11 @@ class LensFlare3D extends EngineObject3D
          *  height; shape is glow, disc or ring
          *  @type {Array<{at: number, size: number, color: Color, shape: string}>|undefined} */
         this.elements = undefined;
+        /** @property {Light3D|undefined} - A light the flare is of in place of the sun, a lamp or a spotlight: the
+         *  flare is at the light and in its color, smaller from farther than the light reaches, hidden by what is
+         *  in front of the light, and a spotlight's shows from inside its beam only
+         *  @type {Light3D|undefined} */
+        this.light = 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 */
@@ -28257,13 +28542,30 @@ class LensFlare3D extends EngineObject3D
         return this.made;
     }
 
-    /** Where the sun is on the screen, in pixels like mousePosScreen, undefined when it is behind the camera
+    // what the flare is of, seen from the camera: the way to it, how far it is, Infinity for the sun, and a point
+    // to find it on the screen by; undefined with no sun direction, or a light that is gone or at the camera
+    flareSource()
+    {
+        const camera = render3D.camera.pos, light = this.light;
+        if (!light)
+        {
+            const sun = render3D.sunDirection;
+            if (!sun.lengthSquared()) return;
+            const direction = sun.normalize();
+            return {direction, distance: Infinity, pos: camera.add(direction.scale(100))};
+        }
+        if (light.destroyed) return;
+        const pos = light.getWorldPos3D(), offset = pos.subtract(camera), distance = offset.length();
+        return distance ? {direction: offset.scale(1 / distance), distance, pos} : undefined;
+    }
+
+    /** Where the sun, or the flare's light, 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)));
+        const source = this.flareSource();
+        return source && render3D.worldToScreen(source.pos);
     }
 
     /** The parts of the flare as they are drawn now: each one's place on the screen, its size in pixels and its
@@ -28277,7 +28579,19 @@ class LensFlare3D extends EngineObject3D
         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;
+        let tint = this.color.multiply(render3D.sunColor), height = mainCanvasSize.y * this.flareSize;
+        const light = this.light, source = light && this.flareSource();
+        if (light)
+        {
+            if (!source) return [];
+            // a light's flare is the light's color, as bright as the light up to 1, and only from inside its cone
+            const cone = render3DLightCone(light), d = source.direction;
+            const inCone = clamp(-(cone[0] * d.x + cone[1] * d.y + cone[2] * d.z) - cone[3]);
+            const c = light.color, bright = c.a * clamp(light.intensity) * inCone;
+            if (!(bright > 0)) return [];
+            tint = this.color.multiply(rgb(c.r, c.g, c.b, bright));
+            height *= min(1, light.radius / source.distance); // smaller from farther than it reaches
+        }
         return this.getElements().map((e)=>
         {
             const c = e.color.multiply(tint);
@@ -28287,15 +28601,32 @@ class LensFlare3D extends EngineObject3D
         });
     }
 
-    /** Is something between the camera and the sun: the level, or an object that is not see through
+    /** Is something between the camera and the sun, or the flare's light: 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);
+        const source = this.flareSource();
+        if (!source) return true;
+        const ray = new Ray3D(render3D.camera.pos, source.direction), reach = source.distance;
+        const blockers = engineObjects.filter((o)=> o !== this && o instanceof EngineObject3D && !o.destroyed &&
+            !o.transparent && !o.additive);
+        // a voxel map says block by block what is see through: glass, water and leaves let the sun by, and the
+        // ray goes on to the blocks behind them
+        const maps = /** @type {Array<VoxelMap>} */ (typeof VoxelMap == 'undefined' ? [] :
+            blockers.filter((o)=> o instanceof VoxelMap));
+        for (const map of maps)
+            if (map.raycast(ray, reach, (type)=> !map.blockType(type).seeThrough))
+                return true;
+        // an object is hit by its box, and a box the camera is inside, a room, a wide floor or the player's own
+        // body, says nothing of what is in the way: the ray the other way hits it too, and it is left out; so is
+        // one the light is inside, its lamp
+        const backward = ray.direction.scale(-1), back = new Ray3D(ray.origin, backward);
+        const lamp = this.light && [new Ray3D(source.pos, ray.direction), new Ray3D(source.pos, backward)];
+        const hits = (r, o)=> render3DRaycastObject(r, o) !== undefined;
+        const around = (o)=> !(o instanceof HeightMap) && (hits(back, o) || lamp && hits(lamp[0], o) && hits(lamp[1], o));
+        const hit = render3D.pick(ray, blockers.filter((o)=> !maps.some((map)=> map === o) && !around(o)));
+        return !!hit && hit.distance < reach;
     }
 
     /** Ease visible toward whether the sun shows, called automatically each frame */
@@ -29425,7 +29756,10 @@ function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
  *    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
+ *    is made a HeightMap, returned with what else was made; paint, when it has it, colors its samples: colors, a
+ *    list, and cells, runs of a count and a color along the rows, 0 for the terrain's own and 1 the list's first
+ *  - A level may hold prefabs of its own, in a prefabs block, each by its name as level3DAddPrefab takes it; they
+ *    are added before its objects are made, one the game added itself keeps its place
  *  - 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
@@ -29438,6 +29772,7 @@ 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
+    level3DPrefabsAdd(level.prefabs);
     level3DSceneApply(level.scene);
     const made = [], map = level3DVoxelMap = level3DVoxelsMake(level.voxels);
     map && made.push(map);
@@ -29548,14 +29883,49 @@ function level3DTerrainShape(terrain)
         height: isNumber(terrain.height) && terrain.height > 0 ? terrain.height : 1, heights};
 }
 
+// a hex color of a level as a Color, undefined when it is not one
+function level3DHexColor(hex)
+{ return /^#([0-9a-f]{6}|[0-9a-f]{8})$/i.test(hex) ? new Color().setHex(hex) : undefined; }
+
+// the paint of a level's terrain block, for a terrain of so many samples: its colors as they are written and a
+// color for each sample, row after row, 0 for none and 1 the first of the colors; undefined when it has none or
+// it does not fit the terrain
+function level3DTerrainPaint(terrain, samples)
+{
+    const paint = terrain?.paint, colors = paint?.colors, runs = paint?.cells;
+    if (!isArray(colors) || !isArray(runs) || colors.length > 255 || !colors.every(level3DHexColor)) return;
+    const cells = new Uint8Array(samples);
+    let at = 0;
+    for (let i = 0; i < runs.length; i += 2)
+    {
+        const count = runs[i], color = runs[i + 1];
+        if (!(count > 0 && count % 1 === 0 && color >= 0 && color % 1 === 0) || color > colors.length ||
+            at + count > samples) return;
+        cells.fill(color, at, at += count);
+    }
+    return at === samples ? {colors: colors.slice(), cells} : undefined;
+}
+
+// give a terrain's map the colors of its block: its own color over the whole of it, or with paint a color for
+// each sample, the terrain's own where it is not painted; the caller builds the map again
+function level3DTerrainSetColors(map, terrain, paint=level3DTerrainPaint(terrain, map.rows * map.columns))
+{
+    const base = level3DHexColor(terrain.color) || WHITE;
+    map.color = base, map.colors = undefined;
+    if (!paint || !paint.cells.some((v)=> v)) return;
+    const palette = [base, ...paint.colors.map(level3DHexColor)];
+    map.color = WHITE;
+    map.colors = map.heights.map((row, r)=> row.map((v, c)=> palette[paint.cells[r * map.columns + c]] || base));
+}
+
 // 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);
+    level3DTerrainSetColors(map, terrain);
+    map.colors && map.rebuild();
     return map;
 }
 
@@ -29628,6 +29998,14 @@ function level3DProperties(type, object)
 // make one object of a level from the type added for its name, undefined when there is no such type or it made
 // nothing
 function level3DMake(object)
+{
+    return level3DMakeAt(object, level3DVector(object.pos, vec3()),
+        level3DVector(object.rotation, vec3()).scale(PI / 180), level3DVector(object.scale, vec3(1)));
+}
+
+// make a level object's game object at a place, a rotation in radians and a scale, its own as level3DMake gives
+// them or the ones a prefab's instance puts it at
+function level3DMakeAt(object, pos, rotation, scale)
 {
     const type = level3DTypes.get(object.type);
     if (!type)
@@ -29635,7 +30013,7 @@ function level3DMake(object)
         debug && console.warn(`level3DLoad: no type added for ${object.type}, skipped`);
         return;
     }
-    const pos = level3DVector(object.pos, vec3()), properties = level3DProperties(type, object);
+    const properties = level3DProperties(type, object);
     const {make} = type, count = engineObjects.length;
     let result;
     try { result = make.prototype ? new make(pos, properties) : make(pos, properties); }
@@ -29653,16 +30031,263 @@ function level3DMake(object)
     if (result instanceof EngineObject3D)
     {
         level3DBaseScale.set(result, result.scale3D.copy());
-        result.rotation3D = level3DVector(object.rotation, vec3()).scale(PI / 180);
-        result.scale3D = result.scale3D.multiply(level3DVector(object.scale, vec3(1)));
+        result.rotation3D = rotation.copy();
+        result.scale3D = result.scale3D.multiply(scale);
     }
 
     // the type's own properties are set on it, one the type has no default for could be a field of the engine's
     for (const key in type.defaults)
         result[key] = properties[key];
+    // a prefab's instance makes its parts now that it is where it goes
+    result instanceof Prefab3D && result.placeAt(pos);
     return result;
 }
 
+/** Make one object of a type added with level3DAddType, level3DAddMesh or level3DAddPrefab, from code, with no
+ *  level: a prefab's instance, or a plain type
+ *  @param {string} type - The type's name
+ *  @param {Vector3} [pos3D]
+ *  @param {Vector3} [rotation3D] - In radians, as an object has it
+ *  @param {Vector3} [scale3D] - Times the scale the type makes it with
+ *  @param {Object} [properties] - Over the type's defaults
+ *  @return {any} - What the type made, a Prefab3D for a prefab, undefined when there is no such type
+ *  @memberof Level3D
+ *  @example
+ *  level3DAddPrefab('House', await fetchJSON('house.json'));
+ *  level3DSpawn('House', vec3(10, 0, 0), vec3(0, PI/2, 0)); */
+function level3DSpawn(type, pos3D=vec3(), rotation3D=vec3(), scale3D=vec3(1), properties)
+{
+    false&&ASSERT(isVector3(pos3D) && isVector3(rotation3D) && isVector3(scale3D), 'pos3D, rotation3D and scale3D are vec3');
+    return level3DMakeAt(properties ? {type, properties} : {type}, pos3D.copy(), rotation3D, scale3D);
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// prefabs: a prefab is a small level, a list of objects about its own origin, placed many times
+
+// the prefabs by name: how an instance is built, its objects, fromLevel, true for one a level's own prefabs
+// block added, which one the game adds takes the place of, and source, the object it was added from, which the
+// level editor knows a level that is a prefab by
+/** @type {Map<string, {attached: boolean, objects: Array<Object>, fromLevel: boolean, source: Object}>} */
+const level3DPrefabs = new Map;
+
+// how many prefabs deep an instance being made is, a prefab that holds itself is stopped; and how many of those
+// are attached: a prefab inside an attached one is attached too, or its parts would be left behind in the world
+let level3DPrefabDepth = 0, level3DPrefabAttached = 0;
+
+/** Add a prefab: a small level, its objects placed about its own origin, to place many times under one name
+ *  - It is a type from then on: a level's object of that type, the level editor's Place list and level3DSpawn make
+ *    an instance, a Prefab3D; an instance is made of the prefab as it is then, so the level editor, where a prefab
+ *    changes, makes its instances again
+ *  - The prefab is a level as the level editor saves it, {objects: [...]}, so the editor is the prefab editor too;
+ *    only its objects are used, and they may be of other prefabs
+ *  - With attached true in it the parts are children of the instance and move with it as one body, without
+ *    collision of their own, a prefab inside it too; its handle is at the middle of the box around them and its
+ *    size3D is that box, so setCollision makes the body solid where it is seen; otherwise each part is an object of its own in the world and collides as one placed
+ *    by hand does
+ *  - Adding a name again replaces it
+ *  @param {string} name - The type its instances have in a level
+ *  @param {Object} prefab - {objects, attached}
+ *  @memberof Level3D
+ *  @example
+ *  level3DAddPrefab('Tower', {objects: [{type: 'Box', pos: [0, 1, 0], scale: [2, 2, 2]},
+ *      {type: 'Cylinder', pos: [0, 3, 0]}]});
+ *  level3DLoad({objects: [{type: 'Tower', pos: [5, 0, 5]}, {type: 'Tower', pos: [-5, 0, 5], rotation: [0, 45, 0]}]}); */
+function level3DAddPrefab(name, prefab) { level3DPrefabSet(name, prefab, false); }
+
+// add a prefab, the game's or a level's own
+function level3DPrefabSet(name, prefab, fromLevel)
+{
+    false&&ASSERT(!!prefab && typeof prefab === 'object', 'a prefab is an object, {objects: [...]}');
+    name = String(name);
+    const objects = isArray(prefab?.objects) ? prefab.objects.filter((o)=> o && typeof o === 'object') : [];
+    // a copy, what the game or the editor does to its own afterwards does not change the instances made later
+    level3DPrefabs.set(name, {attached: !!prefab?.attached, objects: JSON.parse(JSON.stringify(objects)), fromLevel,
+        source: prefab});
+    // a class of its own, so the level editor makes its instances again as it does a class's
+    level3DTypes.set(name, {make: class extends Prefab3D { constructor(pos) { super(pos, name); } }, defaults: {},
+        tileInfo: undefined});
+}
+
+// add a level's own prefabs, each unless the game added one of that name or it is a plain type's name
+function level3DPrefabsAdd(prefabs)
+{
+    if (!prefabs || typeof prefabs !== 'object' || isArray(prefabs)) return;
+    for (const name in prefabs)
+    {
+        const known = level3DPrefabs.get(name);
+        if (known ? !known.fromLevel : level3DTypes.has(name)) continue;
+        prefabs[name] && typeof prefabs[name] === 'object' && level3DPrefabSet(name, prefabs[name], true);
+    }
+}
+
+/** Load a prefab from a file the level editor saved and add it
+ *  @param {string} name - The type its instances have in a level
+ *  @param {string} url
+ *  @return {Promise<void>}
+ *  @memberof Level3D */
+async function level3DLoadPrefab(name, url) { level3DAddPrefab(name, await fetchJSON(url)); }
+
+// where an instance puts one of its prefab's objects: the object's own place, turn and size inside the instance's
+function level3DPrefabPartTransform(instance, object)
+{
+    const pos = level3DVector(object.pos, vec3()), scale = level3DVector(object.scale, vec3(1));
+    const rotation = level3DVector(object.rotation, vec3()).scale(PI / 180);
+    // the two turns one after the other; the sizes multiply along each axis, which is exact for an instance sized
+    // evenly or a part that is not turned, and as near as a box can be otherwise
+    const turn = buildMatrix(vec3(), instance.rotation3D).multiply(buildMatrix(vec3(), rotation));
+    return {pos: buildMatrix(instance.pos3D, instance.rotation3D, instance.scale3D).transformPoint(pos),
+        rotation: turn.getRotation(), scale: scale.multiply(instance.scale3D)};
+}
+
+/**
+ * An instance of a prefab, what a prefab's type makes: a handle with no shape of its own, and its parts, what the
+ * prefab's objects made
+ * - Parts of a prefab that is not attached are objects of their own in the world: moving, turning or sizing the
+ *   handle puts them where it now says with its next update, or call placeParts; destroying it destroys them
+ * - Parts of an attached prefab are its children and move with it as one body
+ * @extends EngineObject3D
+ * @memberof Level3D
+ */
+class Prefab3D extends EngineObject3D
+{
+    /** Create an instance of a prefab, made by its type: place one with a level or level3DSpawn
+     *  @param {Vector3} [pos3D]
+     *  @param {string} [prefabName] - A prefab added with level3DAddPrefab */
+    constructor(pos3D, prefabName='')
+    {
+        super(pos3D);
+        /** @property {string} - The prefab it is an instance of */
+        this.prefabName = prefabName;
+        /** @property {boolean} - Are its parts its children, moving with it as one body */
+        this.attached = !!level3DPrefabs.get(prefabName)?.attached || level3DPrefabAttached > 0;
+        /** @property {Array<any>} - What the prefab's objects made, in the prefab's order */
+        this.parts = [];
+        /** @property {Vector3} - From the prefab's origin to the handle, in the prefab's own space: nothing for
+         *  separate parts, and for an attached prefab the middle of the box around its parts, where its handle
+         *  is, as an object's place is the middle of its body */
+        this.originOffset = vec3();
+        this.partObjects = []; // the prefab's object of each part
+        this.partsPlaced = ''; // where the handle was when its parts were last placed, undefined parts not made
+        this.partsMade = false;
+    }
+
+    /** Put the instance with its prefab's origin at a place, turned and sized as the handle is: where a level's
+     *  object or level3DSpawn says it goes; the handle of an attached prefab is then at the middle of its body
+     *  @param {Vector3} pos3D */
+    placeAt(pos3D)
+    {
+        this.pos3D = pos3D.copy();
+        this.placeParts();
+        const o = this.originOffset;
+        if (o.x || o.y || o.z)
+            this.pos3D = buildMatrix(pos3D, this.rotation3D, this.scale3D).transformPoint(o);
+    }
+
+    /** Put the parts where the handle is now, making them the first time; called by the handle's update when it
+     *  has moved, turned or changed size */
+    placeParts()
+    {
+        if (this.destroyed) return;
+        this.partsMade ||= (this.makeParts(), true);
+        this.partsPlaced = this.placeKey();
+        if (this.attached) return; // children follow by themselves
+        this.parts.forEach((part, i)=>
+        {
+            if (!(part instanceof EngineObject3D)) return; // what a function made is where it was made
+            const to = level3DPrefabPartTransform(this, this.partObjects[i]);
+            part.rotation3D = to.rotation;
+            part.scale3D = (level3DBaseScale.get(part) ?? vec3(1)).multiply(to.scale);
+            // a prefab inside this one goes by its origin, which is not where an attached one's handle is
+            part instanceof Prefab3D ? part.placeAt(to.pos) : part.pos3D = to.pos;
+        });
+    }
+
+    // the handle's place, turn and size as one text, to tell when it has changed
+    placeKey()
+    {
+        const p = this.pos3D, r = this.rotation3D, s = this.scale3D;
+        return [p.x, p.y, p.z, r.x, r.y, r.z, s.x, s.y, s.z].join();
+    }
+
+    // make the parts, each where the instance puts it, or attached at its own place inside the instance
+    makeParts()
+    {
+        const prefab = level3DPrefabs.get(this.prefabName);
+        if (!prefab) return;
+        if (level3DPrefabDepth >= 8)
+        {
+            debug && console.error(`level3DLoad: the prefab ${this.prefabName} holds itself, left out there`);
+            return;
+        }
+        ++level3DPrefabDepth;
+        this.attached && ++level3DPrefabAttached;
+        try
+        {
+            const low = vec3(Infinity), high = vec3(-Infinity), children = [];
+            for (const object of prefab.objects)
+            {
+                const local = {pos: level3DVector(object.pos, vec3()), scale: level3DVector(object.scale, vec3(1)),
+                    rotation: level3DVector(object.rotation, vec3()).scale(PI / 180)};
+                const at = this.attached ? local : level3DPrefabPartTransform(this, object);
+                const part = level3DMakeAt(object, at.pos, at.rotation, at.scale);
+                if (!part) continue; // level3DMakeAt gives an object or nothing
+                this.parts.push(part);
+                this.partObjects.push(object);
+                if (!this.attached || !(part instanceof EngineObject3D)) continue;
+                // a child rides with its parent and has no collision of its own
+                part.setCollision(false, false, false);
+                children.push(part);
+                // the corners of its box as it is turned; its place is its middle, a prefab inside this one too
+                const box = buildMatrix(part.pos3D, part.rotation3D, part.size3D.multiply(part.scale3D));
+                for (let i = 8; i--;)
+                {
+                    const p = box.transformPoint(vec3(i & 1 ? .5 : -.5, i & 2 ? .5 : -.5, i & 4 ? .5 : -.5));
+                    for (const k of ['x', 'y', 'z'])
+                        low[k] = min(low[k], p[k]), high[k] = max(high[k], p[k]);
+                }
+            }
+            // an attached instance is the box around its parts, its handle at the middle of it as an object's
+            // place is the middle of its body, so a game that makes it solid has it solid where it is seen
+            if (children.length)
+            {
+                this.size3D = high.subtract(low);
+                this.originOffset = low.add(high).scale(.5);
+            }
+            for (const part of children)
+            {
+                part.pos3D = part.pos3D.subtract(this.originOffset);
+                this.addChild(part);
+            }
+        }
+        finally
+        {
+            --level3DPrefabDepth;
+            this.attached && --level3DPrefabAttached;
+        }
+    }
+
+    /** Keep the parts with the handle, called automatically each frame */
+    update()
+    {
+        super.update();
+        if (!this.attached && this.partsPlaced !== this.placeKey())
+            this.placeParts();
+    }
+
+    /** Destroy the instance and its parts
+     *  @param {boolean} [immediate] */
+    destroy(immediate)
+    {
+        if (this.destroyed) return;
+        for (const part of this.parts)
+            part.parent === this || part.destroy?.(immediate); // children go with their parent
+        super.destroy(immediate);
+    }
+
+    /** A prefab's instance has nothing of its own to draw */
+    render3D() {}
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // the built-in types
 
@@ -29876,7 +30501,9 @@ function particleEffectSanitize(raw)
             settings[setting.name] = value === '' || particleEffectShapes.includes(value) ? value : fallback;
         else if (isNumber(value))
         {
-            const clamped = clamp(value, setting.hardMin, setting.hardMax);
+            // an angle past half a turn comes around, a clamp would point it the other way
+            const wraps = setting.name === 'angle' && isFinite(value) && abs(value) > PI;
+            const clamped = clamp(wraps ? mod(value + PI, 2*PI) - PI : value, setting.hardMin, setting.hardMax);
             settings[setting.name] = setting.step >= 1 ? round(clamped) : clamped;
         }
         else
@@ -29955,9 +30582,11 @@ function particleEffectsGet(name) { return particleEffectsByName.get(String(name
  *  @param {string} text
  *  @return {Array<Object>}
  *  @memberof ParticleEffects */
-function particleEffectsParse(text)
+function particleEffectsParse(text) { return particleEffectsFromData(JSON.parse(text)); }
+
+// a library file's data, or one effect's, into sanitized effects
+function particleEffectsFromData(data)
 {
-    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');
@@ -29976,7 +30605,7 @@ function particleEffectsText(effects) { return JSON.stringify({version:1, effect
  *  @memberof ParticleEffects */
 async function particleEffectsLoad(url)
 {
-    const effects = particleEffectsParse(JSON.stringify(await fetchJSON(url)));
+    const effects = particleEffectsFromData(await fetchJSON(url));
     particleEffectsAdd(effects);
     return effects;
 }
@@ -30154,7 +30783,13 @@ function particleEffectTileInfo(s)
  *  @memberof ParticleEffects */
 function particleEffectApply(emitter, effect)
 {
-    effect = particleEffectSanitize(effect); // an effect written by hand or changed since it was added
+    // an effect written by hand or changed since it was added
+    particleEffectSet(emitter, particleEffectSanitize(effect));
+}
+
+// set a 2D emitter to an effect that is sanitized already, as a play's is
+function particleEffectSet(emitter, effect)
+{
     const s = effect.settings, ended = emitter.emitTime < 0; // destroyed, its last particles going
     for (const setting of particleEffectSettings)
         if (!particleEffectIndirect.includes(setting.name))
@@ -30190,15 +30825,14 @@ function particleEffectResolve(nameOrEffect, options)
  *  - 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
+ *  @param {Object} [options] - What to change for this play, each left out when not wanted:
+ *    scale grows the whole effect, the built-ins fit a one unit object at 1;
+ *    hue turns its colors around the color wheel, 1 is all the way;
+ *    saturation multiplies its saturation, 0 is grey;
+ *    angle is its direction, 0 is up, the effect's own angle when not given;
+ *    tileInfo, a TileInfo or a TextureInfo, is the game's own art to draw with in place of the effect's shape,
+ *    tinted by its colors, a whole texture drawn as one tile;
+ *    and any effect setting by its name, emitTime, emitRate, speed and the rest, replaces the effect's own
  *  @return {ParticleEmitter|undefined} - undefined when there is no such effect
  *  @memberof ParticleEffects */
 function particleEffect(nameOrEffect, pos=vec2(), options={})
@@ -30206,7 +30840,7 @@ function particleEffect(nameOrEffect, pos=vec2(), options={})
     const effect = particleEffectResolve(nameOrEffect, options);
     if (!effect) return;
     const emitter = new ParticleEmitter(pos.copy());
-    particleEffectApply(emitter, effect);
+    particleEffectSet(emitter, effect);
     emitter.scale = options.scale ?? 1;
     if (options.angle !== undefined)
         emitter.angle = options.angle;
@@ -30270,7 +30904,7 @@ function particleEffectFromEmitter(emitter, name='Effect')
         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
+    // stick has no 3D push: particleEffectApply3D makes it the emitter's stick, its grip on landing
 }
 
 /** Set a 3D emitter to an effect, live, so a running one keeps its particles; its place, scale and flatten stay
@@ -30279,7 +30913,13 @@ function particleEffectFromEmitter(emitter, name='Effect')
  *  @memberof ParticleEffects */
 function particleEffectApply3D(emitter, effect)
 {
-    effect = particleEffectSanitize(effect); // an effect written by hand or changed since it was added
+    // an effect written by hand or changed since it was added
+    particleEffectSet3D(emitter, particleEffectSanitize(effect));
+}
+
+// set a 3D emitter to an effect that is sanitized already, as a play's is
+function particleEffectSet3D(emitter, effect)
+{
     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;
@@ -30292,8 +30932,8 @@ function particleEffectApply3D(emitter, effect)
         '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;
+    e.friction = s.friction;
+    e.stick = effect.behaviors.find(b=> b.name == 'stick')?.strength ?? 0; // in 3D the emitter grips on landing
     // 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);
@@ -30303,8 +30943,8 @@ function particleEffectApply3D(emitter, effect)
  *  - 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
+ *    randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the emitter's
+ *    stick, its grip where a particle lands
  *  @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
@@ -30316,7 +30956,7 @@ function particleEffect3D(nameOrEffect, pos3D=vec3(), options={})
     const effect = particleEffectResolve(nameOrEffect, options);
     if (!effect) return;
     const e = new ParticleEmitter3D(pos3D.copy());
-    particleEffectApply3D(e, effect);
+    particleEffectSet3D(e, effect);
     if (options.angle !== undefined)
         e.rotation3D = vec3(0, 0, -options.angle);
     e.scale3D = vec3(options.scale ?? 1);