littlejsengine 1.23.1 → 1.24.0

package/dist/littlejs.release.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.23.1';
+const engineVersion = '1.24.0';
 
 /** Frames per second to update
  *  @type {number}
@@ -7557,7 +7557,7 @@ function touchGamepadPointerUp(e)
  * - 2D spatial audio based on camera position with distance-based falloff
  * - Sound instance management (pause, resume, stop)
  * - Speech synthesis for text-to-speech
- * - Music playback with ZzFXM support
+ * - Music playback from audio files, looping by default
  * - Web Audio API integration with master gain control
  * - Sounds and the master bus can route through effects, see the audio effects plugin
  * @namespace Audio
@@ -8435,7 +8435,7 @@ function playAudioBuffer(buffer, volume=1, rate=1, pan=0, loop=false, gainNode,
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-// ZzFXMicro - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
+// ZzFX - Zuper Zmall Zound Zynth - v1.4.0 by Frank Force
 
 /** Generate and play a ZzFX sound
  *
@@ -8720,6 +8720,10 @@ const tileLayersTiledFlips = [[0,0], [3,1], [2,1], [3,0], [0,1], [1,0], [2,0], [
  * Load tile layers from exported data
  * - Tiled maps come in as they are, flipped and turned tiles included, from one tileset image (a second tileset's
  *   tiles continue its numbering), finite maps in the CSV or array layer format; layer offsets and parallax are not read
+ * - A tileset kept in the map with a margin or a spacing, a sheet with gaps between its tiles, is read where its
+ *   tiles are, whatever padding the tile info has; one in a file of its own (a tsx) is not read, pass a tile info
+ *   with its padding
+ * - An LDtk level loads through tileLayersFromLDtk, which makes it a map like these
  * - Group layers are flattened in order, each replaced by the layers inside it, so the layer indices
  *   (collisionLayer and the returned array) count that flattened list; a group's tint, opacity and
  *   visibility carry to the layers inside it
@@ -8752,6 +8756,18 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
     false&&ASSERT(tileMapData.width && tileMapData.height);
     false&&ASSERT(tileMapData.layers && tileMapData.layers.length);
 
+    // a sheet with a margin around its tiles or a spacing between them: the first tile is at the margin and each
+    // cell is a tile and a spacing, which is a padding of half the spacing counted from there, by the tileset's
+    // own count of columns, since the image's width does not say with a spacing that is not all around
+    const tileset = tileMapData.tilesets?.[0];
+    if (tileInfo && tileset && (tileset.margin > 0 || tileset.spacing > 0))
+    {
+        const margin = tileset.margin || 0, spacing = tileset.spacing || 0, size = tileInfo.size;
+        const width = tileInfo.textureInfo?.size.x || 0;
+        const columns = tileset.columns || max(1, floor((width - margin*2 + spacing) / (size.x + spacing)));
+        tileInfo = new TileInfo(vec2(margin), size, tileInfo.textureInfo, spacing / 2, tileInfo.bleed, columns);
+    }
+
     // flatten group layers in order, a group's color and visibility carry to the layers inside it
     /** @type {Array<{dataLayer: Object, color?: Color, visible?: boolean}>} */
     const layers = [];
@@ -8829,6 +8845,107 @@ function tileLayersLoad(tileMapData, tileInfo=tileLayerDefaultTile(), renderOrde
 function tileLayersColor(hex)
 { return new Color().setHex(hex.length === 9 ? '#' + hex.slice(3) + hex.slice(1, 3) : hex); }
 
+// the Tiled property type of an LDtk field type, for the ones Tiled has a property for
+const tileLayersLDtkTypes = {Int: 'int', Float: 'float', Bool: 'bool', String: 'string', Multilines: 'string',
+    Color: 'color', FilePath: 'file'};
+
+/**
+ * Make a Tiled map of a level of an LDtk project, to load with tileLayersLoad and objectLayersLoad
+ * - Each Tiles, AutoLayer and IntGrid layer is a tile layer, the bottom one first as in Tiled, so the last layer
+ *   of the LDtk file is layer 0; where LDtk stacks tiles in a cell, an edge over a fill, each tile over another
+ *   goes in a layer of its own just above, named with (2), (3) and so on, so a layer of the first tiles has one
+ *   wherever the LDtk layer has any, which makes it the one for collision
+ * - An IntGrid layer with no tiles is a hidden layer of its values, for collision: pass its index as collisionLayer
+ * - An Entities layer is an object layer: an entity's name is its type for objectLayersAddType, it is placed at
+ *   its middle, and its Int, Float, Bool, String, Color and FilePath fields are its properties (an enum is a string)
+ * - The tileset is the first tile layer's, with its padding and spacing; give tileLayersLoad a tile info of its image
+ * - The level is in the project file (not saved as separate level files), its layers of one grid size; a layer of
+ *   another grid size or another tileset is left out, with a warning in debug builds
+ * - The level editor edits the map this returns, and saves it as a Tiled map
+ * @param {Object} ldtk - The LDtk project, its JSON
+ * @param {number|string} [level] - Which level, by its index or its identifier
+ * @return {Object} - A Tiled map: width, height, tilewidth, tileheight, tilesets and layers
+ * @example
+ * const map = tileLayersFromLDtk(await fetchJSON('world.ldtk'), 'Level_0');
+ * const layers = tileLayersLoad(map, tile(0, 16), 0, 1); // layer 1 is solid
+ * objectLayersLoad(map);
+ * @memberof TileLayers */
+function tileLayersFromLDtk(ldtk, level=0)
+{
+    const levels = ldtk?.levels || [];
+    const data = typeof level === 'string' ? levels.find((l)=> l.identifier === level) : levels[level];
+    false&&ASSERT(data, 'LDtk level not found', level);
+    false&&ASSERT(isArray(data.layerInstances), 'LDtk level has no layers: levels saved as separate files are not read');
+    const instances = data.layerInstances;
+    const tiled = (l)=> l.__type !== 'Entities';
+    const first = instances.find((l)=> tiled(l) && l.__tilesetDefUid != undefined) || instances.find(tiled) || instances[0];
+    const grid = first?.__gridSize || 16;
+    const width = first?.__cWid || ceil(data.pxWid / grid), height = first?.__cHei || ceil(data.pxHei / grid);
+    const map = {width, height, tilewidth: grid, tileheight: grid, orientation: 'orthogonal', renderorder: 'right-down',
+        infinite: false, layers: [], nextlayerid: 1, nextobjectid: 1};
+
+    // the tileset of the first layer that has one, where its tiles are in its image
+    const tileset = (ldtk?.defs?.tilesets || []).find((t)=> t.uid === first?.__tilesetDefUid);
+    if (tileset)
+        map.tilesets = [{firstgid: 1, name: String(tileset.relPath || '').replace(/^.*[\\/]/, '').replace(/\.\w+$/, ''),
+            image: tileset.relPath, imagewidth: tileset.pxWid, imageheight: tileset.pxHei,
+            tilewidth: tileset.tileGridSize, tileheight: tileset.tileGridSize, margin: tileset.padding || 0,
+            spacing: tileset.spacing || 0, columns: tileset.__cWid, tilecount: tileset.__cWid * tileset.__cHei}];
+
+    // LDtk lists the top layer first, Tiled the bottom one
+    for (let i = instances.length; i--;)
+    {
+        const instance = instances[i], name = instance.__identifier, id = map.nextlayerid++;
+        if (!tiled(instance))
+        {
+            const objects = (instance.entityInstances || []).map((entity)=>
+            {
+                // an entity is placed by its pivot, an object here by its middle
+                const [pivotX=0, pivotY=0] = entity.__pivot || [], w = entity.width || 0, h = entity.height || 0;
+                const properties = [];
+                for (const field of entity.fieldInstances || [])
+                {
+                    const type = tileLayersLDtkTypes[field.__type] || (/^(Local|Extern)Enum\./.test(field.__type) && 'string');
+                    type && field.__value != undefined && properties.push({name: field.__identifier, type, value: field.__value});
+                }
+                return {id: map.nextobjectid++, name: '', type: entity.__identifier, x: entity.px[0] + (.5 - pivotX) * w,
+                    y: entity.px[1] + (.5 - pivotY) * h, width: w, height: h, rotation: 0, visible: true, properties};
+            });
+            map.layers.push({id, name, type: 'objectgroup', objects, opacity: 1, visible: true, x: 0, y: 0});
+            continue;
+        }
+        const tiles = [...(instance.autoLayerTiles || []), ...(instance.gridTiles || [])];
+        const usable = instance.__gridSize === grid && instance.__cWid === width && instance.__cHei === height &&
+            (!tiles.length || instance.__tilesetDefUid === tileset?.uid);
+        if (!usable)
+        {
+            debug && console.warn(`tileLayersFromLDtk: layer ${name} has another grid or tileset, left out`);
+            continue;
+        }
+        const empty = ()=> new Array(width * height).fill(0), stacks = [empty()];
+        if (tiles.length)
+        {
+            // a tile's place in pixels, its tile in the sheet, and its flips: bit 0 across, bit 1 down, which are
+            // Tiled's two top bits; LDtk lists them in the order it draws them, so the first in a cell is the
+            // bottom one and each after it goes a layer higher
+            const depth = new Uint16Array(width * height);
+            for (const t of tiles)
+            {
+                const x = floor(t.px[0] / grid), y = floor(t.px[1] / grid), cell = x + y * width;
+                if (x >= 0 && x < width && y >= 0 && y < height)
+                    (stacks[depth[cell]++] ||= empty())[cell] =
+                        (t.t + 1 | (t.f & 1 ? 0x80000000 : 0) | (t.f & 2 ? 0x40000000 : 0)) >>> 0;
+            }
+        }
+        else
+            (instance.intGridCsv || []).forEach((value, k)=> k < stacks[0].length && (stacks[0][k] = value));
+        const visible = instance.__type === 'IntGrid' && !tiles.length ? false : instance.visible !== false;
+        stacks.forEach((data, k)=> map.layers.push({id: k ? map.nextlayerid++ : id, name: k ? `${name} (${k + 1})` : name,
+            type: 'tilelayer', width, height, data, opacity: instance.__opacity ?? 1, visible, x: 0, y: 0}));
+    }
+    return map;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // Object layers
 
@@ -13570,166 +13687,6 @@ class Light extends EngineObject
     }
 }
 
-/**
- * LittleJS ZzFXM Plugin
- * - A port of ZzFXM, the Zuper Zmall Zound Zynth music player, by Keith Clark and Frank Force, MIT licensed,
- *   https://github.com/keithclark/ZzFXM; its notice is in COPYRIGHT.txt
- * @namespace ZzFXM
- */
-
-/**
- * Music Object - Stores a zzfx music track for later use
- * 
- * <a href=https://keithclark.github.io/ZzFXM/>Create music with the ZzFXM tracker.</a>
- * @extends Sound
- * @memberof ZzFXM
- * @example
- * // create some music
- * const music_example = new ZzFXMusic(
- * [
- *     [                         // instruments
- *       [,0,400]                // simple note
- *     ], 
- *     [                         // patterns
- *         [                     // pattern 1
- *             [                 // channel 0
- *                 0, -1,        // instrument 0, left speaker
- *                 1, 0, 9, 1    // channel notes
- *             ], 
- *             [                 // channel 1
- *                 0, 1,         // instrument 0, right speaker
- *                 0, 12, 17, -1 // channel notes
- *             ]
- *         ],
- *     ],
- *     [0, 0, 0, 0], // sequence, play pattern 0 four times
- *     90            // BPM
- * ]);
- * 
- * // play the music on a loop
- * music_example.playMusic();
- */
-class ZzFXMusic extends Sound
-{
-    /** Create a music object and cache the zzfx music samples for later use
-     *  @param {[Array, Array, Array, number?, ...any[]]} zzfxMusic - Array of zzfx music parameters: instruments, patterns, sequence, and an optional BPM; anything after it, like the tracker's metadata, is ignored
-     */
-    constructor(zzfxMusic)
-    {
-        super(undefined);
-
-        if (!soundEnable || headlessMode) return;
-        const [instruments, patterns, sequence, BPM] = zzfxMusic;
-        super.sampleChannels = zzfxM(instruments, patterns, sequence, BPM); // the setter, without declaring a field that hides it in the typings
-        this.buildSampleBuffer(); // hand the samples to an audio buffer now, like a zzfx sound, so the arrays are released
-        this.loadedPercent = 1; // generated in place, so it is loaded like a zzfx sound
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-// ZzFX Music Renderer v2.0.3 by Keith Clark and Frank Force
-
-/** Generate samples for a ZzFM song with given parameters
- *  @param {Array} instruments - Array of ZzFX sound parameters
- *  @param {Array} patterns - Array of pattern data
- *  @param {Array} sequence - Array of pattern indexes
- *  @param {number} [BPM] - Playback speed of the song in BPM
- *  @return {Array} - Left and right channel sample data
- *  @memberof ZzFXM */
-function zzfxM(instruments, patterns, sequence, BPM = 125) 
-{
-  let i, j, k;
-  let instrumentParameters;
-  let note;
-  let sample;
-  let patternChannel;
-  let notFirstBeat;
-  let stop;
-  let instrument;
-  let attenuation;
-  let outSampleOffset;
-  let isSequenceEnd;
-  let sampleOffset = 0;
-  let nextSampleOffset;
-  let sampleBuffer = [];
-  let leftChannelBuffer = [];
-  let rightChannelBuffer = [];
-  let channelIndex = 0;
-  let panning = 0;
-  let hasMore = 1;
-  let sampleCache = {};
-  let beatLength = audioDefaultSampleRate / BPM * 60 >> 2;
-
-  // for each channel in order until there are no more
-  for (; hasMore; channelIndex++) {
-
-    // reset current values
-    sampleBuffer = [hasMore = notFirstBeat = outSampleOffset = 0];
-
-    // for each pattern in sequence
-    sequence.forEach((patternIndex, sequenceIndex)=> {
-      // get pattern for current channel, use empty 1 note pattern if none found
-      patternChannel = patterns[patternIndex][channelIndex] || [0, 0, 0];
-
-      // check if there are more channels
-      hasMore |= patterns[patternIndex][channelIndex]&&1;
-
-      // get next offset, use the length of first channel
-      nextSampleOffset = outSampleOffset + (patterns[patternIndex][0].length - 2 - (notFirstBeat?0:1)) * beatLength;
-      // for each beat in pattern, plus one extra if end of sequence
-      isSequenceEnd = sequenceIndex === sequence.length - 1;
-      for (i = 2, k = outSampleOffset; i < patternChannel.length + isSequenceEnd; notFirstBeat = ++i) {
-
-        // <channel-note>
-        note = patternChannel[i];
-
-        // stop if end, different instrument or new note
-        stop = i === patternChannel.length + isSequenceEnd - 1 && isSequenceEnd ||
-            instrument !== (patternChannel[0] || 0) || note | 0;
-
-        // fill buffer with samples for previous beat, most cpu intensive part
-        for (j = 0; j < beatLength && notFirstBeat;
-
-            // fade off attenuation at end of beat if stopping note, prevents clicking
-            j++ > beatLength - 99 && stop && attenuation < 1? attenuation += 1 / 99 : 0
-        ) {
-          // copy sample to stereo buffers with panning
-          sample = (1 - attenuation) * sampleBuffer[sampleOffset++] / 2 || 0;
-          leftChannelBuffer[k] = (leftChannelBuffer[k] || 0) - sample * panning + sample;
-          rightChannelBuffer[k] = (rightChannelBuffer[k++] || 0) + sample * panning + sample;
-        }
-
-        // set up for next note
-        if (note) {
-          // set attenuation
-          attenuation = note % 1;
-          panning = patternChannel[1] || 0;
-          if (note |= 0) {
-            // get cached sample
-            sampleBuffer = sampleCache[
-              [
-                instrument = patternChannel[sampleOffset = 0] || 0,
-                note
-              ]
-            ] = sampleCache[[instrument, note]] || (
-                // add sample to cache
-                instrumentParameters = [...instruments[instrument]],
-                instrumentParameters[2] = (instrumentParameters[2] || 220) * 2**(note / 12 - 1),
-
-                // allow negative values to stop notes
-                note > 0 ? zzfxG(...instrumentParameters) : []
-            );
-          }
-        }
-      }
-
-      // update the sample offset
-      outSampleOffset = nextSampleOffset;
-    });
-  }
-
-  return [leftChannelBuffer, rightChannelBuffer];
-}
 /**
  * LittleJS Audio Effects Plugin
  * - Web Audio effects with a wet/dry mix: filter, reverb, delay, distortion, compressor
@@ -23152,8 +23109,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
@@ -26520,8 +26477,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;
@@ -26538,25 +26495,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;
-
-    // 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'])
+    if (hit === undefined || !ray.direction.lengthSquared())
+        return hit; // a ray of no length is where it starts, inside the box
+    return render3DRaycastMesh(local, mesh);
+}
+
+// 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)
     {
-        const d = local.direction[k];
-        if (d)
-            exit = min(exit, ((d > 0 ? bounds.max[k] : bounds.min[k]) - local.origin[k]) / d);
+        // 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 exit === Infinity ? 0 : exit; // a ray of no length is where it starts
+    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
@@ -26934,10 +26921,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
 {
@@ -26972,6 +26961,49 @@ 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
+     *  @return {LensFlare3D} - The flare, to change: light.addFlare().shapes = ['hex'] */
+    addFlare(size, count, intensity, saturation)
+    {
+        const flare = new LensFlare3D(size, count, intensity, saturation);
+        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
@@ -28490,31 +28522,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)=>
@@ -28523,16 +28598,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 off the screen, 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
@@ -28562,48 +28653,61 @@ 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, 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;
@@ -28611,69 +28715,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()
-    {
-        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()
+    // 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 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;
@@ -28687,22 +28807,29 @@ 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
+        const lamp = (o)=>
+        {
+            if (!this.light || reach === Infinity || !o.mesh || o instanceof HeightMap) return false;
+            const matrix = render3DObjectMatrix(o);
+            if (!matrix.determinant()) return false;
+            const p = matrix.copy().invert().transformPoint(source.pos), b = o.mesh.bounds || o.mesh.getBounds();
+            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));
     }
@@ -28716,8 +28843,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);
     }
@@ -29831,8 +29959,9 @@ function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
  *    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
- *    leaves out stays as the game set it, and a level with no block changes nothing
+ *    sunColor, fog, its start and end, fogColor, the horizon color when not given, shadows, and lensFlare, the
+ *    sun's lens flare; what the block leaves out stays as the game set it, and a level with no block changes
+ *    nothing
  *  @param {Object} level - The level, the level editor edits this same object
  *  @return {Array<any>} - What each object's type made, a function that made nothing is left out
  *  @memberof Level3D */
@@ -30057,7 +30186,24 @@ function level3DSceneApply(scene)
     r.fogColor = color(scene.fogColor) || r.fogColor;
     if (typeof scene.shadows === 'boolean')
         r.shadows = scene.shadows;
+    if (typeof scene.lensFlare === 'boolean')
+        level3DSceneFlare(scene.lensFlare);
+}
+
+// the sun's lens flare as a scene sets it: on makes one unless the sun has a flare already, the game's own or an
+// earlier level's, and off takes away the one a scene made, never the game's
+let level3DSunFlare;
+function level3DSceneFlare(on)
+{
+    if (!on)
+    {
+        level3DSunFlare && !level3DSunFlare.destroyed && level3DSunFlare.destroy();
+        level3DSunFlare = undefined;
+    }
+    else if (!level3DSunHasFlare())
+        level3DSunFlare = new LensFlare3D;
 }
+const level3DSunHasFlare = ()=> engineObjects.some((o)=> o instanceof LensFlare3D && !o.destroyed && !o.light);
 
 // a vec3 of an array of three numbers, as the file has them, or the fallback
 function level3DVector(value, fallback)
@@ -30407,7 +30553,8 @@ level3DAddType('Cylinder', function(pos, properties)
     { return level3DMakeShape(pos, properties, level3DCylinderMesh ||= buildCylinder()); },
     {color: WHITE, tile: -1, solid: true});
 // a light, a spotlight with a cone: cone is the angle in degrees from its forward out to the edge of its beam, the
-// object's rotation aims it, softness is how much of the cone fades, and shadows makes it the one that casts them
+// object's rotation aims it, softness is how much of the cone fades, shadows makes it the one that casts them, and
+// lensFlare gives it a lens flare; not flare, since a property is also set on the object, where flare is the flare
 level3DAddType('Light', function(pos, properties)
 {
     const light = new Light3D(pos, properties.radius, properties.color, properties.intensity);
@@ -30415,8 +30562,9 @@ level3DAddType('Light', function(pos, properties)
     light.coneSoftness = properties.softness;
     if (properties.shadows && render3D)
         render3D.shadowLight = light;
+    properties.lensFlare && light.addFlare();
     return light;
-}, {color: WHITE, radius: 5, intensity: 1, cone: 0, softness: .2, shadows: false});
+}, {color: WHITE, radius: 5, intensity: 1, cone: 0, softness: .2, shadows: false, lensFlare: false});
 
 /**
  * LittleJS Particle Effects Plugin