littlejsengine 1.23.1 → 1.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.23.1",
+  "version": "1.24.1",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",
@@ -40,6 +40,7 @@
     "!plugins/box2d.wasm.*",
     "COPYRIGHT.txt",
     "FAQ.md",
+    "CHANGELOG.md",
     "REFERENCE.md",
     "EDITOR.md"
   ],

package/plugins/box2d.js

@@ -414,7 +414,7 @@ class Box2dObject extends EngineObject
 
         const points = [];
         const radius = diameter/2;
-        for (let i=sides; i--;)
+        for (let i=sides; i-- > 0;) // a count that is not a whole number still ends
             points.push(vec2(radius,0).rotate((i+.5)/sides*PI*2));
         return this.addPoly(points, density, friction, restitution, isSensor);
     }

package/plugins/pluginExport.js

@@ -44,10 +44,6 @@ export
     LightSystemPlugin,
     Light,
 
-    // ZzFXMusic
-    ZzFXMusic,
-    zzfxM,
-
     // Audio Effects
     AudioEffect,
     AudioFilter,

package/plugins/render3d.js

@@ -915,8 +915,8 @@ class Render3DPlugin
     }
 
     /** Find the nearest object under a screen position or along a ray, for clicking on things
-     *  - Each object is tested as the box around its mesh in its own space, or a sprite as the quad it draws,
-     *    not triangle by triangle
+     *  - A mesh is hit on its triangles, the ones that face the ray as they are drawn, both sides of a doubleSided
+     *    mesh; a sprite is hit as the quad it draws, and a height map or a voxel map on its surface
      *  - engineObjectsRaycast3D is the other half of this, every object along a ray instead of the nearest
      *  @param {Vector2|Ray3D} from - A screen position like mousePosScreen, or a ray to look along
      *  @param {Array<EngineObject>} [objects] - Defaults to every object; only those with a mesh or a sprite count
@@ -4283,8 +4283,8 @@ function engineObjectsCollect3D(pos, size, objects=engineObjects, testCenters=fa
     return collected;
 }
 
-// how far along a ray an object is hit, or undefined for a miss; each one is tested as the box around its mesh in
-// its own space, or a sprite as the quad it draws, not triangle by triangle
+// how far along a ray an object is hit, or undefined for a miss; a mesh is hit on its triangles, in its own space,
+// and a sprite as the quad it draws
 function render3DRaycastObject(ray, o)
 {
     if (o.destroyed || !(o instanceof EngineObject3D)) return;
@@ -4301,25 +4301,55 @@ function render3DRaycastObject(ray, o)
     const distance = raycastSphere(ray, center, radius);
     if (distance === undefined) return;
 
-    // the sphere is a quick reject, a mesh is hit where the ray meets its box in its own space, since a wide floor's
-    // sphere reaches far above it; the direction is not made unit length, so the distance holds in the world;
+    // the sphere and then the box in the mesh's own space are quick rejects, and a ray that meets the box is tested
+    // against the triangles; the direction is not made unit length, so the distance holds in the world;
     // a mesh flattened to nothing on an axis has no inverse, it is hit as a disc like a sprite
     if (!matrix.determinant()) return render3DRaycastDisc(ray, center, radius);
     const inverse = matrix.copy().invert(), bounds = mesh.bounds || mesh.getBounds();
     const local = new Ray3D(inverse.transformPoint(ray.origin), inverse.transformDirection(ray.direction));
     const hit = raycastBox(local, bounds.min.add(bounds.max).scale(.5), bounds.max.subtract(bounds.min));
-    if (hit !== 0) return hit;
+    if (hit === undefined || !ray.direction.lengthSquared())
+        return hit; // a ray of no length is where it starts, inside the box
+    return render3DRaycastMesh(local, mesh);
+}
 
-    // it starts inside the box, like a camera on terrain or in a room, so it is hit where it leaves, and what stands
-    // inside comes first
-    let exit = Infinity;
-    for (const k of ['x', 'y', 'z'])
-    {
-        const d = local.direction[k];
-        if (d)
-            exit = min(exit, ((d > 0 ? bounds.max[k] : bounds.min[k]) - local.origin[k]) / d);
-    }
-    return exit === Infinity ? 0 : exit; // a ray of no length is where it starts
+// how far along a ray, in the mesh's own space, its nearest triangle is hit, or undefined: the triangles that face
+// the ray as the pass draws them, clockwise from the front, and the back faces too of a doubleSided mesh; a strip's
+// triangle i is (i-2, i-1, i), the odd ones read the other way, and a join between its pieces has no area and is
+// never hit; nothing is kept between calls, so a mesh that changed is hit as it is now
+function render3DRaycastMesh(ray, mesh)
+{
+    const points = mesh.points, indices = mesh.indices, both = mesh.doubleSided;
+    const ox = ray.origin.x, oy = ray.origin.y, oz = ray.origin.z;
+    const dx = ray.direction.x, dy = ray.direction.y, dz = ray.direction.z;
+    const count = indices ? indices.length / 3 | 0 : points.length - 2;
+    let nearest;
+    for (let i = 0; i < count; ++i)
+    {
+        // the corners clockwise from the front: an indexed list is written the other way round
+        let a, b, c;
+        if (indices)
+            a = points[indices[i*3]], b = points[indices[i*3+2]], c = points[indices[i*3+1]];
+        else
+            a = points[i & 1 ? i + 1 : i], b = points[i & 1 ? i : i + 1], c = points[i + 2];
+
+        // Moller and Trumbore: the determinant is the ray along the face's normal, below zero from the front
+        const e1x = b.x - a.x, e1y = b.y - a.y, e1z = b.z - a.z;
+        const e2x = c.x - a.x, e2y = c.y - a.y, e2z = c.z - a.z;
+        const hx = dy * e2z - dz * e2y, hy = dz * e2x - dx * e2z, hz = dx * e2y - dy * e2x;
+        const det = e1x * hx + e1y * hy + e1z * hz;
+        if (both ? !det : !(det < 0)) continue;
+        const sx = ox - a.x, sy = oy - a.y, sz = oz - a.z;
+        const u = (sx * hx + sy * hy + sz * hz) / det;
+        if (!(u >= 0 && u <= 1)) continue;
+        const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;
+        const v = (dx * qx + dy * qy + dz * qz) / det;
+        if (!(v >= 0 && u + v <= 1)) continue;
+        const t = (e2x * qx + e2y * qy + e2z * qz) / det;
+        if (t >= 0 && !(t >= nearest))
+            nearest = t;
+    }
+    return nearest;
 }
 
 // a sprite is the quad drawBillboard draws, its size3D grown by the x and y scale as the draw does, facing the camera
@@ -4697,10 +4727,12 @@ class InstancedMesh3D extends EngineObject3D
  * - 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 but its glow, when it has one; add a small emissive mesh if the lamp itself should be seen
+ * - addFlare gives it a lens flare, see LensFlare3D
  * @extends EngineObject3D
  * @memberof Render3D
  * @example
  * const torch = new Light3D(vec3(0, 3, 0), 10, hsl(.1, 1, .65));
+ * torch.addFlare();   // light in the lens when the torch is in view
  */
 class Light3D extends EngineObject3D
 {
@@ -4735,6 +4767,50 @@ class Light3D extends EngineObject3D
          *  bright core */
         this.glowFalloff = 1;
         this.additive = true; // the glow is added on, in the transparent stage; a light with none draws nothing
+        /** @type {LensFlare3D|undefined} */
+        this.flareObject = undefined;
+    }
+
+    /** Give the light a lens flare, made with the arguments of LensFlare3D, in place of the one it had
+     *  @param {number} [size] - Scales every part of it
+     *  @param {number} [count] - How many ghosts there are, besides the glow at the light
+     *  @param {number} [intensity] - How bright it is
+     *  @param {number} [saturation] - How colorful the ghosts are
+     *  @param {Color} [color] - Tints the flare, with the light's own color
+     *  @return {LensFlare3D} - The flare, to change: light.addFlare().shapes = ['hex'] */
+    addFlare(size, count, intensity, saturation, color)
+    {
+        const flare = new LensFlare3D(size, count, intensity, saturation, color);
+        this.flare = flare;
+        return flare;
+    }
+
+    /** The light's lens flare, undefined for none: addFlare makes it, or set a LensFlare3D of your own, and
+     *  destroying the flare takes it away
+     *  - The flare is the light's: it is attached to the light as its child, so it stays through a scene change
+     *    when the light does, and is destroyed with the light or when another takes its place
+     *  @type {LensFlare3D|undefined} */
+    get flare() { return this.flareObject && !this.flareObject.destroyed ? this.flareObject : undefined; }
+
+    set flare(flare)
+    {
+        const old = this.flare; // a flare that was destroyed on its own is no flare
+        if (flare === old) return;
+        old && old.destroy();
+        if (flare)
+        {
+            flare.light = this;
+            flare.parent || this.addChild(flare);
+        }
+        this.flareObject = flare || undefined;
+    }
+
+    /** Destroy the light, and its flare with it
+     *  @param {boolean} [immediate] */
+    destroy(immediate)
+    {
+        this.flare = undefined;
+        super.destroy(immediate);
     }
 
     /** Draw the glow, a quad facing the camera with a soft round glow on it, pulled toward the camera by half its

package/plugins/render3dEditor.js

@@ -354,7 +354,7 @@ function editor3DSceneState()
     const r = render3D;
     return {sky: r.sky, ambientColor: r.ambientColor.copy(), ambientGroundColor: r.ambientGroundColor?.copy(),
         fogStart: r.fogStart, fogEnd: r.fogEnd, fogColor: r.fogColor?.copy(), sunDirection: r.sunDirection.copy(),
-        sunColor: r.sunColor.copy(), shadows: r.shadows};
+        sunColor: r.sunColor.copy(), shadows: r.shadows, sunFlare: !!level3DSunFlare && !level3DSunFlare.destroyed};
 }
 function editor3DSceneRestore(state)
 {
@@ -369,6 +369,7 @@ function editor3DSceneRestore(state)
     r.sunDirection = state.sunDirection.copy();
     r.sunColor = state.sunColor.copy();
     r.shadows = state.shadows;
+    level3DSceneFlare(state.sunFlare); // a flare an earlier level's scene gave the sun, never the game's own
 }
 
 // the scene on screen as a block, to start a level's scene from: a sky only when the dome's colors are known
@@ -390,6 +391,7 @@ function editor3DSceneFromView()
     scene.fog = [editor3DRound(r.fogStart || 0), editor3DRound(r.fogEnd || 0)];
     scene.fogColor = editor3DHex(r.fogColor || canvasClearColor);
     scene.shadows = !!r.shadows;
+    scene.lensFlare = level3DSunHasFlare();
     return scene;
 }
 
@@ -547,9 +549,11 @@ function editor3DLevelLoaded(level)
         level.objects = editor3DCopy(saved.objects);
         for (const name of editor3DLevelPartNames)
             parts[name] ? level[name] = editor3DCopy(parts[name]) : delete level[name];
+        saved.stale && console.warn(`LittleJS editor: the edits brought back to ${record.fileName} are older than ` +
+            'the last ones, which storage had no room for');
     }
-    else if (saved)
-        record.pending = saved;
+    else if (saved && isArray(saved.objects))
+        record.pending = saved; // one that is broken is passed by, and the next autosave writes over it
 }
 
 // called by level3DLoad for each object, with what its type made
@@ -3378,6 +3382,8 @@ function editor3DSceneUpdate(box)
     color('Fog color', 'The sky\'s horizon color when the level has a sky and no fog color',
         scene.fogColor ?? (sky ? sky[1] : view.fogColor), (hex)=> change('fogColor', hex));
     toggle('Shadows', 'The sun casts shadows', !!value('shadows'), (on)=> change('shadows', on));
+    toggle('Lens flare', 'The sun flares in the lens when it is in view', !!value('lensFlare'), (on)=>
+        change('lensFlare', on));
 }
 
 // the properties box: the position, rotation and scale of the one selected object and an input for each default

package/plugins/render3dExtras.js

@@ -1476,31 +1476,74 @@ 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
+// glow, a flat disc with a brighter rim, a ring, a hexagon like the blades of a lens, a streak across, and a star
+// of six rays; undefined headless or without a canvas
+const render3DFlareShapes = ['glow', 'disc', 'ring', 'hex', 'streak', 'star'];
 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);
+        const cell = 128, shapes = render3DFlareShapes, 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),
+            hex: (t)=> t < .8 ? .4 + .1 * t : t < .92 ? .48 + (t - .8) * 3 : (1 - t) / .08 * .84,
+            streak: (t)=> (1 - t) ** 1.5,
         };
-        shapes.forEach((shape, i)=>
+        // a round gradient from the middle of the cell out, squashed for a ray and cut to a path for the hexagon
+        const fill = (shape, r, path)=>
         {
-            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);
+            const steps = 32, gradient = context.createRadialGradient(0, 0, 0, 0, 0, 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);
+            path ? path() : context.arc(0, 0, r, 0, 2 * PI);
             context.fill();
+        };
+        const ray = (r, angle)=>
+        {
+            context.save();
+            context.rotate(angle);
+            context.scale(1, .07);
+            fill('streak', r);
+            context.restore();
+        };
+        shapes.forEach((shape, i)=>
+        {
+            const r = cell / 2 - 2;
+            context.save();
+            context.translate(i * cell + cell / 2, cell / 2);
+            if (shape == 'hex')
+            {
+                // a gradient is round, so the hexagon is set pixel by pixel, by how far each is toward a side
+                const image = context.createImageData(cell, cell), data = image.data, apothem = r * cos(PI / 6);
+                for (let k = 0; k < cell * cell; ++k)
+                {
+                    const x = abs(k % cell + .5 - cell / 2), y = abs((k / cell | 0) + .5 - cell / 2);
+                    const t = max(y, x * cos(PI / 6) + y / 2) / apothem;
+                    data[k * 4] = data[k * 4 + 1] = data[k * 4 + 2] = 255;
+                    data[k * 4 + 3] = t < 1 ? clamp(alpha.hex(t)) * 255 : 0;
+                }
+                context.putImageData(image, i * cell, 0);
+            }
+            else if (shape == 'streak')
+                ray(r, 0);
+            else if (shape == 'star')
+            {
+                for (let k = 3; k--;)
+                    ray(r, k * PI / 3 + PI / 2);
+                context.scale(.3, .3);
+                fill('glow', r);
+            }
+            else
+                fill(shape, r);
+            context.restore();
         });
         const texture = new TextureInfo(context.canvas, true, false, false); // smooth even in a pixel art game
         render3DFlareTiles = new Map(shapes.map((shape, i)=>
@@ -1509,16 +1552,32 @@ function render3DFlareTile(shape)
     return render3DFlareTiles.get(shape) || render3DFlareTiles.get('glow');
 }
 
+/**
+ * A part of a lens flare
+ * @typedef {Object} LensFlareElement
+ * @property {number} at - Where along the line: 0 the sun, 1 the middle of the screen, 2 as far past it
+ * @property {number|Vector2} size - How big across, as a part of the screen's height, a vector for a part wider
+ *  than it is tall
+ * @property {Color} color - Its color, the alpha how bright
+ * @property {string} [shape] - glow, disc, ring, hex, streak or star, a glow when left out
+ * @property {TileInfo} [tileInfo] - A tile of the game's own to draw in place of a shape, best white on clear
+ * @property {number} [angle] - How far it is turned, in radians
+ * @memberof Render3D
+ */
+
 /**
  * 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
+ * - A Light3D gets one of its own with light.addFlare()
  * - 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
+ *   with the sun's own color; shapes says what its ghosts are, glowSize and ghostSize how big its parts are; or
+ *   give it elements of your own, which may be tiles of the game's
+ * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read; it is 0 while the
+ *   sun is too far off the screen for the flare to show, a third of the screen past its edge, where nothing is tested
  * - 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
+ *   through, each on the triangles of 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
@@ -1548,48 +1607,62 @@ class LensFlare3D extends EngineObject3D
         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} */
+        /** @property {Array<string>|undefined} - The shapes the ghosts are picked from, glow, disc, ring, hex,
+         *  streak or star: ['hex'] makes every ghost a hexagon, and a shape listed twice is picked twice as often;
+         *  discs, rings and glows when not set
+         *  @type {Array<string>|undefined} */
+        this.shapes = undefined;
+        /** @property {number} - Scales the glow at the sun, 0 for none */
+        this.glowSize = 1;
+        /** @property {number} - Scales the ghosts */
+        this.ghostSize = 1;
+        /** @property {Array<LensFlareElement>|undefined} - The parts of the flare, to set your own in place of the
+         *  ones made from count, seed, saturation, shapes, glowSize and ghostSize
+         *  @type {Array<LensFlareElement>|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
+         *  in front of the light but its lamp, a mesh around it no wider than half its radius, and a spotlight's
+         *  shows from inside its beam only; a DirectionalLight3D's is far
+         *  away where it shines from, like the sun's; the flare is destroyed when its light is; light.addFlare
+         *  sets this
          *  @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 */
         this.fadeTime = .15;
-        /** @property {number} - How much of the sun shows, 0 hidden or behind the camera to 1 in plain view, eased */
+        /** @property {number} - How much of the sun shows, 0 hidden, off the screen 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}>} */
+        /** @type {Array<LensFlareElement>} */
         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}>} */
+    /** The parts of the flare: the elements set by hand, or the ones made from count, seed, saturation, shapes,
+     *  glowSize and ghostSize, a glow and a core at the sun and the ghosts, made again when one of those changes
+     *  @return {Array<LensFlareElement>} */
     getElements()
     {
         if (this.elements) return this.elements;
-        const key = [this.count, this.seed, this.saturation].join();
+        const shapes = this.shapes?.length ? this.shapes : undefined, glow = this.glowSize, ghost = this.ghostSize;
+        const key = [this.count, this.seed, this.saturation, glow, ghost, shapes?.length, shapes].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'}];
+            /** @type {Array<LensFlareElement>} */
+            const made = this.made = glow > 0 ? [
+                {at: 0, size: .7 * glow, color: hsl(0, 0, 1, .5), shape: 'glow'},
+                {at: 0, size: .25 * glow, 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,
+                const pick = random.float(), shape = shapes ? shapes[min(pick * shapes.length | 0, shapes.length - 1)] :
+                    pick < .5 ? 'disc' : pick < .8 ? 'ring' : 'glow';
+                made.push({at, size: random.float(.04, .1) * (1 + at) * ghost, shape,
                     color: hsl(random.float(), s * .9, .6, random.float(.15, .4))});
             }
             this.madeKey = key;
@@ -1597,69 +1670,85 @@ class LensFlare3D extends EngineObject3D
         return this.made;
     }
 
-    // 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
+    // what the flare is of, seen from the camera: the way to it, how far it is, Infinity for the sun and for a
+    // directional light, which shines from its place toward the origin, and a point to find it on the screen by;
+    // undefined with no direction, or a light that is gone or at the camera
     flareSource()
     {
         const camera = render3D.camera.pos, light = this.light;
-        if (!light)
+        if (light?.destroyed) return;
+        if (!light || light.directional)
         {
-            const sun = render3D.sunDirection;
-            if (!sun.lengthSquared()) return;
-            const direction = sun.normalize();
+            const from = light ? light.getWorldPos3D() : render3D.sunDirection;
+            if (!from.lengthSquared()) return;
+            const direction = from.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()
+    // how the flare would show with nothing in the way: where its source is on the screen, how strong it is there,
+    // fading as it leaves the screen, its tint and the height its sizes are parts of; undefined when it would not
+    // show at all, behind the camera, off the screen, or of a light that is off or seen from outside its cone
+    flareLook()
     {
-        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
-     *  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 [];
+        const source = this.flareSource(), center = mainCanvasSize.scale(.5);
+        const sun = source && render3D.worldToScreen(source.pos);
+        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 strength = clamp((1.3 - off) / .5) * this.intensity;
+        if (!(strength > 0)) return;
         let tint = this.color.multiply(render3D.sunColor), height = mainCanvasSize.y * this.flareSize;
-        const light = this.light, source = light && this.flareSource();
+        const light = this.light;
         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 [];
+            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
+            if (!light.directional)
+                height *= min(1, light.radius / source.distance); // smaller from farther than it reaches
         }
+        return height > 0 ? {sun, center, strength, tint, height} : 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} */
+    getScreenPos()
+    {
+        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, a vector
+     *  when the element's is, and its color, dimmed by how much of the sun shows; empty when there is nothing to draw
+     *  @return {Array<{pos: Vector2, size: number|Vector2, color: Color, shape: string|undefined,
+     *      tileInfo: TileInfo|undefined, angle: number}>} */
+    getScreenElements()
+    {
+        const look = this.visible > 0 && this.flareLook();
+        if (!look) return [];
+        const {sun, center, tint, height} = look, strength = look.strength * this.visible;
         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)};
+            const size = typeof e.size == 'number' ? e.size * height : e.size.scale(height);
+            return {pos: sun.add(center.subtract(sun).scale(e.at)), size, shape: e.shape, tileInfo: e.tileInfo,
+                angle: e.angle || 0, color: rgb(c.r, c.g, c.b, c.a * strength)};
         });
     }
 
     /** Is something between the camera and the sun, or the flare's light: the level, or an object that is not see
-     *  through
+     *  through, hit on its triangles as render3D.pick hits it, so a mesh the camera is inside hides nothing unless
+     *  it is doubleSided
      *  @return {boolean} */
-    isSunHidden()
+    isHidden()
     {
         const source = this.flareSource();
         if (!source) return true;
@@ -1673,22 +1762,31 @@ class LensFlare3D extends EngineObject3D
         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)));
+        // a light's lamp, the mesh the light is inside, does not hide it: one whose box, in its own space, the light
+        // is in, and no wider than half the light's reach, since a room or a whole level has a box around its lights
+        // too, and its walls do hide them from outside
+        const lamp = (o)=>
+        {
+            if (!this.light || reach === Infinity || !o.mesh || o instanceof HeightMap) return false;
+            const matrix = render3DObjectMatrix(o), b = o.mesh.bounds || o.mesh.getBounds();
+            const side = max(b.max.x - b.min.x, b.max.y - b.min.y, b.max.z - b.min.z) * render3DMaxStretch(matrix.m);
+            if (!matrix.determinant() || side > this.light.radius / 2) return false;
+            const p = matrix.copy().invert().transformPoint(source.pos);
+            return p.x >= b.min.x && p.x <= b.max.x && p.y >= b.min.y && p.y <= b.max.y &&
+                p.z >= b.min.z && p.z <= b.max.z;
+        };
+        const hit = render3D.pick(ray, blockers.filter((o)=> !maps.some((map)=> map === o) && !lamp(o)));
         return !!hit && hit.distance < reach;
     }
 
-    /** Ease visible toward whether the sun shows, called automatically each frame */
+    /** Ease visible toward whether the sun shows, called automatically each frame; a flare that would not show
+     *  wherever the sun is, off the screen or its light off, looks for nothing in the way */
     update()
     {
         super.update();
-        const shows = !!this.getSunScreenPos() && !(this.occlusion && this.isSunHidden());
+        if (this.light?.destroyed)
+            return this.destroy(); // the flare of a light that is gone
+        const shows = !!this.flareLook() && !(this.occlusion && this.isHidden());
         const step = this.fadeTime > 0 ? timeDelta / this.fadeTime : 1;
         this.visible = clamp(this.visible + (shows ? step : -step));
     }
@@ -1702,8 +1800,9 @@ class LensFlare3D extends EngineObject3D
         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);
+            const tileInfo = e.tileInfo || render3DFlareTile(e.shape);
+            const size = typeof e.size == 'number' ? vec2(e.size) : e.size;
+            tileInfo && drawTile(e.pos, size, tileInfo, e.color, e.angle, false, undefined, true, true);
         }
         setAdditiveBlendMode(false);
     }