littlejsengine 1.20.0 → 1.22.0

package/plugins/render3dExtras.js

@@ -38,6 +38,54 @@ function render3DSoftDot()
     return render3DSoftDotTexture = new TextureInfo(context.canvas);
 }
 
+/** Make a normal map from a height at each pixel, for bumps and grooves with no image file: the slope at each pixel
+ *  from its neighbors' heights, taken around the edges so the map tiles; set it as an object's normalMap
+ *  @param {Vector2} size - In pixels
+ *  @param {function(number, number): number} heightFunction - The height 0 to 1 at a pixel, x across and y down
+ *  @param {number} [strength] - How steep the slopes are: a height change of 1 over one pixel leans the normal
+ *  by strength
+ *  @return {TextureInfo} - Wraps; headless it has no image
+ *  @memberof Render3D */
+function normalMapFromHeight(size, heightFunction, strength=1)
+{
+    ASSERT(isVector2(size) && size.x >= 1 && size.y >= 1, 'normalMapFromHeight size must be a Vector2 of pixels');
+    const width = size.x | 0, height = size.y | 0;
+    if (typeof OffscreenCanvas == 'undefined')
+    {
+        // headless, nothing to draw into; the right size so what reads it still works
+        const textureInfo = new TextureInfo(undefined, false, true);
+        textureInfo.size = vec2(width, height), textureInfo.sizeInverse = vec2(1 / width, 1 / height);
+        return textureInfo;
+    }
+    const context = createCanvasContext(width, height);
+    const pixels = render3DNormalMapPixels(width, height, heightFunction, strength);
+    context.putImageData(new ImageData(pixels, width, height), 0, 0);
+    return new TextureInfo(context.canvas, true, true);
+}
+
+// the pixels of a normal map made from heights, rgba with the top row first: each normal leans away from the uphill
+// side, green up the image as OpenGL has it, and a flat height is (128, 128, 255); rounded before they are stored,
+// since the clamped array would round a flat 127.5 to even
+function render3DNormalMapPixels(width, height, heightFunction, strength)
+{
+    const heights = new Float32Array(width * height), pixels = new Uint8ClampedArray(width * height * 4);
+    for (let y = 0; y < height; ++y)
+    for (let x = 0; x < width; ++x)
+        heights[y * width + x] = heightFunction(x, y);
+    const h = (x, y)=> heights[mod(y, height) * width + mod(x, width)];
+    for (let y = 0; y < height; ++y)
+    for (let x = 0; x < width; ++x)
+    {
+        const dx = (h(x+1, y) - h(x-1, y)) / 2 * strength, dy = (h(x, y+1) - h(x, y-1)) / 2 * strength;
+        const k = 1 / hypot(dx, dy, 1), i = (y * width + x) * 4;
+        pixels[i] = round((-dx * k * .5 + .5) * 255);
+        pixels[i+1] = round((dy * k * .5 + .5) * 255);
+        pixels[i+2] = round((k * .5 + .5) * 255);
+        pixels[i+3] = 255;
+    }
+    return pixels;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // The rest of the shape builders: buildLathe, buildSphere, buildBox, buildGrid and buildSky live with the
 // renderer, since it hands those out itself
@@ -574,6 +622,22 @@ class HeightMap extends EngineObject3D
      *  @ignore */
     levelRaycast3D(ray) { return this.raycast(ray); }
 
+    /** Where a short move goes under the surface, for a particle's move in one frame: the part of the move made
+     *  before it, 0 to 1, and the surface normal there; undefined when it stays above, starts under, or is off the map
+     *  @param {Vector3} from
+     *  @param {Vector3} to
+     *  @return {{distance: number, normal: Vector3}|undefined}
+     *  @ignore */
+    levelSegment3D(from, to)
+    {
+        const m = this.pos3D, size = this.mapSize;
+        if (abs(to.x - m.x) > size.x / 2 || abs(to.z - m.z) > size.y / 2) return; // off the map
+        const a = from.y - this.getHeight(from.x, from.z), b = to.y - this.getHeight(to.x, to.z);
+        if (a < 0 || b >= 0) return; // above all the way, or under from the start
+        const distance = a / (a - b);
+        return {distance, normal: this.getNormal(from.x + (to.x - from.x) * distance, from.z + (to.z - from.z) * distance)};
+    }
+
     /** Keep an object above the ground, called by the engine for each object with collideLevel
      *  @param {EngineObject3D} o
      *  @param {Vector3} oldPos - Where it was before it moved
@@ -762,7 +826,7 @@ class FirstPersonCamera3D extends EngineObject3D
         /** @property {boolean} - Capture the mouse on a click, so looking needs no button held */
         this.lockPointer = true;
         /** @property {number} - Speed of a jump in world units a frame, 0 for none; Space or gamepad button 0 jumps
-         *  while it stands on something, a height map or voxel map it collides with, see collideLevel */
+         *  while it stands on something, a height map, a voxel map or a solid, see groundObject */
         this.jumpSpeed = 0;
         /** @property {number} - How far above its position the eye is, in its own space, so with a size3D the eye can
          *  sit toward the top of the body instead of its middle; keep it under half the body's height, or the eye is
@@ -833,6 +897,51 @@ class FirstPersonCamera3D extends EngineObject3D
 const RENDER3D_PARTICLE_FLOATS = 21;
 // the position, color and size of the particle being drawn, shared by every emitter so the draw loop makes no objects
 const render3DParticlePos = vec3(), render3DParticleColor = new Color, render3DParticleSize = vec2();
+// where a particle was and is, for the level collision
+const render3DParticleFrom = vec3(), render3DParticleTo = vec3();
+
+// the emitters inside a particle callback now, whose nested calls each get a view of their own
+const render3DParticlesCalling = new Set;
+
+// a particle as a ParticleEmitter3D's callbacks see it, set from the particle for each call
+/** @param {ParticleEmitter3D} emitter
+ *  @return {Particle3D} */
+function render3DParticleView(emitter)
+{
+    return {emitter, pos: vec3(), velocity: vec3(), age: 0, lifeTime: 0, scale: 1, destroyed: false,
+        destroy() { this.destroyed = true; }};
+}
+
+/**
+ * A particle as a ParticleEmitter3D's callbacks see it: one object the emitter reuses, set from the particle for each
+ * call and written back after it, so copy what you keep
+ * @typedef {Object} Particle3D
+ * @property {ParticleEmitter3D} emitter - The emitter it is in
+ * @property {Vector3} pos - Where it is, change it to move it
+ * @property {Vector3} velocity - How far it moves each frame
+ * @property {number} age - Seconds it has lived
+ * @property {number} lifeTime - Seconds it lives
+ * @property {number} scale - How much the emitter grows its effect, from its scale3D and its parents', as the 2D
+ *   particle's scale
+ * @property {boolean} destroyed - Set by destroy
+ * @property {function(): void} destroy - End it this update, the destroy callback gets it
+ * @memberof Render3D
+ */
+
+/**
+ * @callback Particle3DCallback - A function a ParticleEmitter3D calls with one of its particles
+ * @param {Particle3D} particle
+ * @memberof Render3D
+ */
+
+/**
+ * @callback Particle3DCollideCallback - Decides whether a particle stops where it hits the level, a filter as in 2D
+ * @param {Particle3D} particle
+ * @param {EngineObject3D} level - The HeightMap or VoxelMap it hit
+ * @param {Vector3} pos - Where it hit
+ * @return {boolean|void} - true to stop it there; a callback that returns nothing lets it pass through
+ * @memberof Render3D
+ */
 
 /**
  * ParticleEmitter3D - Spawns camera facing particles, the 3D twin of ParticleEmitter
@@ -843,9 +952,14 @@ const render3DParticlePos = vec3(), render3DParticleColor = new Color, render3DP
  * - emitConeAngle spreads them, PI sprays in every direction
  * - Speeds are per frame and sizes are world units, the same as the 2D emitter
  * - scale3D, its own or a parent's, grows the whole effect: the spawn area, the sizes, the speed and the fall
- * - gravity here is its own number added to velocity y each frame: it is neither the engine's 2D
- *   gravity nor render3D.gravity, so an effect keeps its own fall wherever it is used
+ * - gravity here is its own number added to velocity y each frame, so an effect keeps its own fall wherever it is
+ *   used, the same as the 2D emitter's gravity; gravityScale adds a share of render3D.gravity on top, as the 2D
+ *   emitter's gravityScale adds the engine's gravity
  * - An emitter with an emitTime destroys itself once its last particle is gone, like the 2D emitter
+ * - Callbacks as the 2D emitter's: particleCreateCallback, particleUpdateCallback, particleCollideCallback and
+ *   particleDestroyCallback, each given a Particle3D, one object the emitter reuses for every particle and call
+ * - collideLevel, off by default, has particles hit the height maps and voxel maps, bouncing by restitution and
+ *   sliding by friction
  * @extends EngineObject3D
  * @memberof Render3D
  * @example
@@ -870,8 +984,8 @@ class ParticleEmitter3D extends EngineObject3D
      *  @param {number} [sizeEnd] - Particle size at end of life
      *  @param {number} [speed] - Spawn speed in world units per frame
      *  @param {number} [damping] - Per frame velocity multiplier, 1 is none
-     *  @param {number} [gravity] - Per frame change to velocity y, negative pulls down; its own number,
-     *    not render3D.gravity, so the 2D emitter's gravityScale has no equivalent here
+     *  @param {number} [gravity] - Per frame change to velocity y, negative pulls down; its own number, and
+     *    gravityScale adds a share of render3D.gravity on top
      *  @param {number} [fadeRate] - Fraction of life spent fading, half in and half out
      *  @param {number} [randomness] - Extra randomness applied to speed, size and life
      *  @param {boolean} [additive] - Additive blending */
@@ -886,6 +1000,9 @@ class ParticleEmitter3D extends EngineObject3D
 
         /** @property {number|Vector3} - Spawn area, a number for a sphere diameter or a vec3 for a box */
         this.emitSize = emitSize;
+        /** @property {boolean} - Flatten the spawn area across the way it emits, its own up: a sphere becomes a disc
+         *  and a box a flat rectangle, for rain from a sheet of sky or flames from a patch of ground */
+        this.emitFlat = false;
         /** @property {number} - How long to keep emitting, 0 is forever */
         this.emitTime = emitTime;
         /** @property {number} - Particles per second, 0 does not emit */
@@ -912,13 +1029,17 @@ class ParticleEmitter3D extends EngineObject3D
         this.damping = damping;
         /** @property {number} - Per frame change to velocity y, its own number and not render3D.gravity */
         this.gravity = gravity;
+        /** @property {number} - Share of render3D.gravity added each frame on top of its own gravity, 0 by default so
+         *  an effect keeps its own fall wherever it is used; 1 falls with the world, like debris */
+        this.gravityScale = 0;
         /** @property {number} - Fraction of life spent fading, half in and half out */
         this.fadeRate = fadeRate;
         /** @property {number} - Extra randomness applied to speed, size and life */
         this.randomness = randomness;
         /** @property {boolean} - Additive blending */
         this.additive = additive;
-        /** @property {number} - Seconds of each particle's path to draw as a ribbon behind it, 0 draws billboards */
+        /** @property {number} - Seconds of each particle's path to draw as a ribbon behind it, 0 draws billboards;
+         *  with engineVariableStep it keeps trailTime * frameRate updates of path */
         this.trailTime = 0;
         /** @property {number} - Radians per frame each particle turns in the camera plane, either way; 0 is no spin */
         this.angleSpeed = 0;
@@ -934,6 +1055,25 @@ class ParticleEmitter3D extends EngineObject3D
         this.trailData = undefined;
         /** @property {number} - Trail points kept per particle, from trailTime */
         this.trailMax = 0;
+        /** @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 {Particle3DCallback|undefined} - Called with each particle as it is made
+         *  @type {Particle3DCallback|undefined} */
+        this.particleCreateCallback = undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle each update, after it moves
+         *  @type {Particle3DCallback|undefined} */
+        this.particleUpdateCallback = undefined;
+        /** @property {Particle3DCollideCallback|undefined} - Decides if a particle stops where it hits the level,
+         *  with collideLevel on; a callback that returns nothing lets it through
+         *  @type {Particle3DCollideCallback|undefined} */
+        this.particleCollideCallback = undefined;
+        /** @property {Particle3DCallback|undefined} - Called with each particle as it goes, its life over or destroyed
+         *  @type {Particle3DCallback|undefined} */
+        this.particleDestroyCallback = undefined;
+        /** @property {Particle3D} - The particle the callbacks get, one object for every particle and call
+         *  @type {Particle3D} */
+        this.particleView = render3DParticleView(this);
         /** @property {Vector3|undefined} - Where the emitter was at its last update, for when its parent is destroyed
          *  @type {Vector3|undefined} */
         this.worldPos3D = undefined;
@@ -947,6 +1087,7 @@ class ParticleEmitter3D extends EngineObject3D
         const matrix = render3DObjectMatrix(this); // the object's own, read only
         this.worldPos3D = matrix.getTranslation(); // remembered for when the parent is destroyed
         const scale = render3DMaxScale(matrix.m);
+        this.particleView.scale = scale; // the callbacks read it from the view instead of working it out each time
 
         // emit until the emit time is up, then wait for the last particle and go away
         if (!this.emitTime || this.getAliveTime() <= this.emitTime)
@@ -963,8 +1104,9 @@ class ParticleEmitter3D extends EngineObject3D
         else if (!this.particleCount)
             this.destroy();
 
-        // the trail storage follows trailTime, a change starts every trail over
-        const trailMax = this.trailTime ? max(1, round(this.trailTime / timeDelta)) : 0;
+        // the trail storage follows trailTime at the fixed rate, a change starts every trail over, so a varying
+        // timeDelta can not; with engineVariableStep a trail keeps that many updates
+        const trailMax = this.trailTime ? max(1, round(this.trailTime * frameRate)) : 0;
         if (trailMax !== this.trailMax)
         {
             this.trailMax = trailMax;
@@ -974,16 +1116,27 @@ class ParticleEmitter3D extends EngineObject3D
         }
 
         // move the particles and drop the dead ones, all in the typed array: this runs for every particle every frame
-        const F = RENDER3D_PARTICLE_FLOATS, data = this.particleData, trail = this.trailData;
-        const damping = this.damping, gravity = this.gravity * scale, angleDamping = this.angleDamping; // a bigger effect has to fall faster to keep the same arc
+        // a callback can emit, which grows the arrays when they are full, so they are read again after each one
+        const F = RENDER3D_PARTICLE_FLOATS;
+        let data = this.particleData, trail = this.trailData;
+        const reread = ()=> { data = this.particleData, trail = this.trailData; };
+        // its own fall and a share of the world's, grown by the scale: a bigger effect has to fall faster to keep the
+        // same arc
+        const damping = this.damping, angleDamping = this.angleDamping, g = render3D.gravity, share = this.gravityScale;
+        const gravityX = g.x * share * scale, gravityY = (this.gravity + g.y * share) * scale;
+        const gravityZ = g.z * share * scale;
+        const collideLevel = this.collideLevel && render3DLevel.length;
+        const updateCallback = this.particleUpdateCallback, destroyCallback = this.particleDestroyCallback;
         for (let i = this.particleCount; i--;)
         {
             // damped first and gravity added after, the order the 2D particle uses, so the same
             // damping and gravity give the same arc in both
             const k = i * F;
-            const vx = data[k+3] *= damping, vy = data[k+4] = data[k+4] * damping + gravity, vz = data[k+5] *= damping;
+            const vx = data[k+3] = data[k+3] * damping + gravityX, vy = data[k+4] = data[k+4] * damping + gravityY;
+            const vz = data[k+5] = data[k+5] * damping + gravityZ;
             data[k] += vx, data[k+1] += vy, data[k+2] += vz;
             data[k+18] += data[k+19] *= angleDamping;
+            collideLevel && (this.particleCollide(k, data[k] - vx, data[k+1] - vy, data[k+2] - vz), reread());
             const t = i * trailMax * 3;
             if (trailMax)
             {
@@ -995,9 +1148,11 @@ 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());
             if ((data[k+17] += timeDelta) >= data[k+16])
             {
                 // dead: the last particle takes its slot, trail and all, order does not matter
+                destroyCallback && (this.particleCall(destroyCallback, k), reread());
                 const last = --this.particleCount, kl = last * F;
                 if (i !== last)
                 {
@@ -1026,10 +1181,18 @@ class ParticleEmitter3D extends EngineObject3D
         // the whole effect grows with the emitter, not just the area the particles start in
         const scale = render3DMaxScale(matrix.m);
 
-        // spawn offset: inside a box or a sphere
-        const size = this.emitSize, box = /** @type {Vector3} */ (size);
-        const offset = isVector3(size) ? vec3(rand(-.5, .5) * box.x, rand(-.5, .5) * box.y, rand(-.5, .5) * box.z)
-            : randInSphere(/** @type {number} */ (size) / 2);
+        // spawn offset: inside a box or a sphere, or flat across the emitter's up, a flat rectangle or a disc
+        const size = this.emitSize, box = /** @type {Vector3} */ (size), flat = this.emitFlat;
+        let offset;
+        if (isVector3(size))
+            offset = vec3(rand(-.5, .5) * box.x, flat ? 0 : rand(-.5, .5) * box.y, rand(-.5, .5) * box.z);
+        else if (flat)
+        {
+            const disc = randInCircle(/** @type {number} */ (size) / 2);
+            offset = vec3(disc.x, 0, disc.y);
+        }
+        else
+            offset = randInSphere(/** @type {number} */ (size) / 2);
 
         // direction inside the cone around local +Y
         const direction = matrix.transformDirection(randVector3(1, this.emitConeAngle)).normalize();
@@ -1064,6 +1227,60 @@ class ParticleEmitter3D extends EngineObject3D
         data[k+18] = this.angleSpeed ? rand(2*PI) : 0;
         data[k+19] = this.angleSpeed ? this.angleSpeed * random() * randSign() : 0;
         data[k+20] = 0; // trail points
+        this.particleCreateCallback && this.particleCall(this.particleCreateCallback, k);
+    }
+
+    // call a particle callback with the particle at k: the emitter's one Particle3D is set from its numbers, and
+    // what the callback changes is written back; a particle it destroys has lived its life, the update removes it
+    particleCall(callback, k, level, pos)
+    {
+        // a callback that emits runs the create callback inside itself, which gets a view of its own so this one
+        // keeps its particle; what the callback changes is written to the arrays as they are after it, since an
+        // emit into a full emitter grows them
+        const nested = render3DParticlesCalling.has(this);
+        const view = nested ? render3DParticleView(this) : this.particleView, data = this.particleData;
+        view.pos.set(data[k], data[k+1], data[k+2]);
+        view.velocity.set(data[k+3], data[k+4], data[k+5]);
+        view.age = data[k+17], view.lifeTime = data[k+16], view.destroyed = false;
+        render3DParticlesCalling.add(this);
+        let result;
+        try { result = callback(view, level, pos); }
+        finally { nested || render3DParticlesCalling.delete(this); }
+        const out = this.particleData;
+        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
+        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
+    particleCollide(k, x, y, z)
+    {
+        let data = this.particleData;
+        const from = render3DParticleFrom.set(x, y, z);
+        const to = render3DParticleTo.set(data[k], data[k+1], data[k+2]);
+        let hit, level;
+        for (const l of render3DLevel)
+        {
+            const h = l.destroyed ? undefined : l.levelSegment3D(from, to);
+            if (h && (!hit || h.distance < hit.distance))
+                hit = h, level = l;
+        }
+        if (!hit) return;
+        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
+        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);
+        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;
     }
 
     /** Draw the particles, as flat squares or as streaks when trailTime is set
@@ -1245,6 +1462,195 @@ class Trail3D extends EngineObject3D
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////
+// lens flare
+
+// the shapes a flare is made of, white on clear on one smooth texture made the first time it is asked for: a soft
+// glow, a flat disc with a brighter rim, and a ring; undefined headless or without a canvas
+let render3DFlareTiles;
+function render3DFlareTile(shape)
+{
+    if (!render3DFlareTiles)
+    {
+        if (headlessMode || !glContext || typeof OffscreenCanvas == 'undefined') return;
+        const cell = 128, shapes = ['glow', 'disc', 'ring'], context = createCanvasContext(cell * shapes.length, cell);
+        // each shape is how see-through it is from its middle out
+        const alpha =
+        {
+            glow: (t)=> engineGlowAlpha(t, 1),
+            disc: (t)=> t < .8 ? .4 + .1 * t : t < .92 ? .48 + (t - .8) * 3 : (1 - t) / .08 * .84,
+            ring: (t)=> max(0, 1 - abs(t - .86) / .12),
+        };
+        shapes.forEach((shape, i)=>
+        {
+            const x = i * cell + cell / 2, y = cell / 2, r = cell / 2 - 2, steps = 32;
+            const gradient = context.createRadialGradient(x, y, 0, x, y, r);
+            for (let k = 0; k <= steps; ++k)
+                gradient.addColorStop(k / steps, 'rgba(255,255,255,' + clamp(alpha[shape](k / steps)).toFixed(4) + ')');
+            context.fillStyle = gradient;
+            context.beginPath();
+            context.arc(x, y, r, 0, 2 * PI);
+            context.fill();
+        });
+        const texture = new TextureInfo(context.canvas, true, false, false); // smooth even in a pixel art game
+        render3DFlareTiles = new Map(shapes.map((shape, i)=>
+            [shape, new TileInfo(vec2(i * cell, 0), vec2(cell), texture)]));
+    }
+    return render3DFlareTiles.get(shape) || render3DFlareTiles.get('glow');
+}
+
+/**
+ * LensFlare3D - The sun's lens flare, the old kind: a glow at the sun and a row of discs and rings of different
+ * sizes along the line from the sun through the middle of the screen
+ * - Make one and it shows, over the 3D scene and under what the game draws after, a HUD; destroy it to take it away
+ * - It follows render3D.sunDirection, and fades out as the sun leaves the screen or goes behind something
+ * - flareSize, count, intensity and saturation set its look, seed picks another arrangement, and its color tints it,
+ *   with the sun's own color; or give it elements of your own
+ * - visible is how much of the sun shows, 0 to 1, eased over fadeTime, there for a game to read
+ * - What hides the sun is found with a ray from the camera, against the level and every object that is not see
+ *   through, each as the box around its mesh, see render3D.pick; turn it off with occlusion
+ * - It needs WebGL, and it draws nothing in the shadow of renderAfter2D
+ * @extends EngineObject3D
+ * @memberof Render3D
+ * @example
+ * new LensFlare3D;                // the sun flares
+ * new LensFlare3D(1.5, 10, .7, 0); // bigger, 10 ghosts, dimmer, all one color
+ */
+class LensFlare3D extends EngineObject3D
+{
+    /** Create the sun's lens flare
+     *  @param {number} [size] - Scales every part of it, 1 by default
+     *  @param {number} [count] - How many ghosts there are along the line, besides the glow at the sun
+     *  @param {number} [intensity] - How bright it is
+     *  @param {number} [saturation] - How colorful the ghosts are, 0 for all the flare's own color, 1 a rainbow
+     *  @param {Color} [color] - Tints the whole flare, with the sun's color */
+    constructor(size=1, count=7, intensity=1, saturation=1, color=WHITE)
+    {
+        super(vec3(), undefined, undefined, color);
+        this.size3D = vec3(); // not a thing to pick or collect
+        /** @property {number} - Scales every part of the flare */
+        this.flareSize = size;
+        /** @property {number} - How many ghosts there are along the line, besides the glow at the sun */
+        this.count = count;
+        /** @property {number} - How bright it is */
+        this.intensity = intensity;
+        /** @property {number} - How colorful the ghosts are, 0 for all the flare's own color, 1 a rainbow */
+        this.saturation = saturation;
+        /** @property {number} - Picks the arrangement of the ghosts, another seed is another flare */
+        this.seed = 1;
+        /** @property {Array<{at: number, size: number, color: Color, shape: string}>|undefined} - The parts of the
+         *  flare, to set your own in place of the ones made from count, seed and saturation: at is where along the
+         *  line, 0 the sun, 1 the middle of the screen, 2 as far past it; size is across, as a part of the screen's
+         *  height; shape is glow, disc or ring
+         *  @type {Array<{at: number, size: number, color: Color, shape: string}>|undefined} */
+        this.elements = undefined;
+        /** @property {boolean} - Fade out when something is between the camera and the sun */
+        this.occlusion = true;
+        /** @property {number} - Seconds the flare takes to fade out or in when the sun is hidden or shows again */
+        this.fadeTime = .15;
+        /** @property {number} - How much of the sun shows, 0 hidden or behind the camera to 1 in plain view, eased */
+        this.visible = 1;
+        this.renderOrder = 1e9; // over the game's sprites, it is light in the lens
+        this.madeKey = '';
+        /** @type {Array<{at: number, size: number, color: Color, shape: string}>} */
+        this.made = [];
+    }
+
+    /** The parts of the flare: the elements set by hand, or the ones made from count, seed and saturation, a glow
+     *  and a core at the sun and the ghosts, made again when one of those changes
+     *  @return {Array<{at: number, size: number, color: Color, shape: string}>} */
+    getElements()
+    {
+        if (this.elements) return this.elements;
+        const key = [this.count, this.seed, this.saturation].join();
+        if (key !== this.madeKey)
+        {
+            const random = new RandomGenerator(this.seed * 7919 + 1), s = clamp(this.saturation);
+            const made = this.made = [
+                {at: 0, size: .7, color: hsl(0, 0, 1, .5), shape: 'glow'},
+                {at: 0, size: .25, color: hsl(0, 0, 1, .9), shape: 'glow'}];
+            for (let i = 0; i < this.count; ++i)
+            {
+                // spread along the line, each a place of its own, the far ones bigger
+                const at = (i + random.float(.2, .8)) / max(this.count, 1) * 1.9 + .2;
+                const pick = random.float(), shape = pick < .5 ? 'disc' : pick < .8 ? 'ring' : 'glow';
+                made.push({at, size: random.float(.04, .1) * (1 + at), shape,
+                    color: hsl(random.float(), s * .9, .6, random.float(.15, .4))});
+            }
+            this.madeKey = key;
+        }
+        return this.made;
+    }
+
+    /** Where the sun is on the screen, in pixels like mousePosScreen, undefined when it is behind the camera
+     *  @return {Vector2|undefined} */
+    getSunScreenPos()
+    {
+        const direction = render3D.sunDirection;
+        if (!direction.lengthSquared()) return;
+        return render3D.worldToScreen(render3D.camera.pos.add(direction.normalize(100)));
+    }
+
+    /** The parts of the flare as they are drawn now: each one's place on the screen, its size in pixels and its
+     *  color, dimmed by how much of the sun shows; empty when there is nothing to draw
+     *  @return {Array<{pos: Vector2, size: number, color: Color, shape: string}>} */
+    getScreenElements()
+    {
+        const sun = this.getSunScreenPos(), center = mainCanvasSize.scale(.5);
+        if (!sun || !center.x || !center.y) return [];
+        // it fades as the sun leaves the screen, gone when it is a third of the screen past the edge
+        const off = max(abs(sun.x - center.x) / center.x, abs(sun.y - center.y) / center.y);
+        const strength = this.visible * clamp((1.3 - off) / .5) * this.intensity;
+        if (!(strength > 0)) return [];
+        const tint = this.color.multiply(render3D.sunColor), height = mainCanvasSize.y * this.flareSize;
+        return this.getElements().map((e)=>
+        {
+            const c = e.color.multiply(tint);
+            // along the line and past the middle, a lerp would stop there
+            return {pos: sun.add(center.subtract(sun).scale(e.at)), size: e.size * height, shape: e.shape,
+                color: rgb(c.r, c.g, c.b, c.a * strength)};
+        });
+    }
+
+    /** Is something between the camera and the sun: the level, or an object that is not see through
+     *  @return {boolean} */
+    isSunHidden()
+    {
+        const direction = render3D.sunDirection;
+        if (!direction.lengthSquared()) return true;
+        const blockers = engineObjects.filter((o)=> o !== this && o instanceof EngineObject3D && !o.transparent &&
+            !o.additive);
+        return !!render3D.pick(new Ray3D(render3D.camera.pos, direction.normalize()), blockers);
+    }
+
+    /** Ease visible toward whether the sun shows, called automatically each frame */
+    update()
+    {
+        super.update();
+        const shows = !!this.getSunScreenPos() && !(this.occlusion && this.isSunHidden());
+        const step = this.fadeTime > 0 ? timeDelta / this.fadeTime : 1;
+        this.visible = clamp(this.visible + (shows ? step : -step));
+    }
+
+    /** Draw the flare over the 3D scene, added onto it, called automatically in the 2D pass */
+    render()
+    {
+        if (headlessMode || !glEnable) return;
+        const elements = this.getScreenElements();
+        if (!elements.length) return;
+        setAdditiveBlendMode(true);
+        for (const e of elements)
+        {
+            const tileInfo = render3DFlareTile(e.shape);
+            tileInfo && drawTile(e.pos, vec2(e.size), tileInfo, e.color, 0, false, undefined, true, true);
+        }
+        setAdditiveBlendMode(false);
+    }
+
+    /** A flare has nothing to draw in the 3D pass */
+    render3D() {}
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // OBJ meshes