littlejsengine 1.25.0 → 1.26.1

package/plugins/render3dDebug.js

@@ -18,15 +18,12 @@ function render3DRenderDebug()
 {
     if (!render3DDebugPrimitives.length) return;
     render3DDebugPrimitives = render3DDebugPrimitives.filter(p=> p.clearCount === debugClearCount);
-    if (!debugVideoCaptureIsActive()) // hidden from a video capture like the 2D ones, but they still expire
+    render3DWithState({lighting: false, depthTest: false, receiveShadow: false, additive: false, shader: undefined,
+        emissiveMap: undefined}, ()=>
     {
-        render3DWithState({lighting: false, depthTest: false, receiveShadow: false, additive: false, shader: undefined,
-            emissiveMap: undefined}, ()=>
-        {
-            for (const p of render3DDebugPrimitives)
-                p.draw();
-        });
-    }
+        for (const p of render3DDebugPrimitives)
+            p.draw();
+    });
     render3DDebugPrimitives = render3DDebugPrimitives.filter(p=> p.timer < 0); // a Timer compares as negative until it elapses
 }
 

package/plugins/render3dEditor.js

@@ -354,7 +354,8 @@ 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, sunFlare: !!level3DSunFlare && !level3DSunFlare.destroyed};
+        sunColor: r.sunColor.copy(), shadows: r.shadows, sunFlare: !!level3DSunFlare && !level3DSunFlare.destroyed,
+        skyBox: r.skyBox, environment: r.environment};
 }
 function editor3DSceneRestore(state)
 {
@@ -370,6 +371,9 @@ function editor3DSceneRestore(state)
     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 cube maps, and a scene's load still running for them lands no more
+    r.skyBox = state.skyBox, r.environment = state.environment;
+    ++level3DSceneCubeLoads.skyBox, ++level3DSceneCubeLoads.environment;
 }
 
 // the scene on screen as a block, to start a level's scene from: a sky only when the dome's colors are known
@@ -486,6 +490,7 @@ function editor3DHash(text)
 // puts in the edits it autosaved for the file, or keeps them waiting when the file changed since
 function editor3DLevelLoaded(level)
 {
+    editor3DAutosaveFlush(); // what the last level has waiting is written before this one reads the autosaves
     if (editor3DLevel !== level)
     {
         // another level, the selection and the edit being made were the last one's
@@ -1147,7 +1152,7 @@ function editor3DStrokeEnd()
         partsBefore: stroke.parts, partsAfter: parts});
     editor3DUndoList.length > 100 && editor3DUndoList.shift();
     editor3DRedoList.length = 0;
-    editor3DAutosave();
+    editor3DAutosaveSoon();
 }
 
 // take the edit being made back, with nothing to undo
@@ -1171,7 +1176,7 @@ function editor3DUndo(redo=false)
     (redo ? editor3DUndoList : editor3DRedoList).push(entry);
     editor3DSetObjects(redo ? entry.after : entry.before);
     editor3DSetParts(redo ? entry.partsAfter : entry.partsBefore);
-    editor3DAutosave();
+    editor3DAutosaveSoon();
     return true;
 }
 
@@ -1465,6 +1470,7 @@ function editor3DPrefabClear()
 // origin, with an undo of its own, and the level it is in put away; false when it is not a prefab's instance
 function editor3DPrefabEnter(id)
 {
+    editor3DAutosaveFlush(); // the level's waiting autosave, before another level is the one edited
     const selected = editor3DSelected();
     id ??= selected.length === 1 ? selected[0].id : undefined;
     const made = editor3DInstances.get(id), from = editor3DLevel;
@@ -1647,6 +1653,7 @@ function editor3DSetOpen(open)
         editor3DMouseOnPanel = false; // the panel hides, with no mouseleave
         editor3DStrokeEnd();
         while (editor3DPrefabBack()); // the game plays the level, not a prefab that was open
+        editor3DAutosaveFlush(); // the game plays on with what the editor has kept
         editor3DToolHeld = false;
         editor3DIsOpen = false;
         setPaused(editor3DGamePaused);
@@ -1842,6 +1849,7 @@ function editor3DAutosave(level=editor3DLevel, known)
         root && editor3DAutosave(Object.keys(prefabs).length ? {...root, prefabs} : root, editor3DRecords.get(root));
         return;
     }
+    editor3DAutosaveWaiting.delete(level); // written now
     const record = known ?? editor3DRecords.get(level);
     if (!record || record.pending) return; // edits waiting to be applied keep their autosave
     const saves = editor3DSaves(), objects = isArray(level.objects) ? level.objects : [];
@@ -1853,9 +1861,35 @@ function editor3DAutosave(level=editor3DLevel, known)
     else
         saves[record.key] = {hash: record.hash, savedHash: record.savedHash, objects: editor3DCopy(objects),
             ...parts};
-    const failed = editorSaveFailed; // the 2D editor's own flag is its own
+    const failed = editorSaveFailed, size = editorAutosaveSize; // the 2D editor's flag and size are its own
     editor3DSaveFailed = editorWriteSaves(saves, record.key, editor3DSaveName());
-    editorSaveFailed = failed;
+    editor3DAutosaveSize = editorAutosaveSize;
+    editorSaveFailed = failed, editorAutosaveSize = size;
+}
+
+// a level whose autosave writes more than EDITOR_AUTOSAVE_WAIT_SIZE characters, a big terrain's or block map's,
+// waits until the edits stop for a moment, as the 2D editor's map does, since writing it after every stroke would
+// cost more than the stroke; a small one is written at once
+let editor3DAutosaveSize = 0, editor3DAutosaveTimer;
+const editor3DAutosaveWaiting = new Set;
+
+// autosave a level after an edit: at once when its autosave is small, or a second after the last of a run of edits;
+// inside a prefab at once, since its autosave is the level it is in, found through the prefabs open, which Back
+// changes
+function editor3DAutosaveSoon(level=editor3DLevel)
+{
+    if (editor3DAutosaveSize < EDITOR_AUTOSAVE_WAIT_SIZE || editor3DPrefabLevels.has(level))
+        return editor3DAutosave(level);
+    editor3DAutosaveWaiting.add(level);
+    clearTimeout(editor3DAutosaveTimer);
+    editor3DAutosaveTimer = setTimeout(editor3DAutosaveFlush, 1e3);
+}
+
+// write every autosave that is waiting, as the editor closes, the page hides or another level loads
+function editor3DAutosaveFlush()
+{
+    clearTimeout(editor3DAutosaveTimer);
+    [...editor3DAutosaveWaiting].forEach((level)=> editor3DAutosave(level));
 }
 
 // put the autosaved edits of a file that changed into the level, as one undo
@@ -2549,11 +2583,16 @@ function editor3DEditorUpdate(seconds)
 
 // Ctrl with a letter the editor uses is not the browser's while the editor is open, Ctrl+D would bookmark the page
 if (debug && globalThis.document?.addEventListener)
+{
     document.addEventListener('keydown', (e)=>
     {
         if (editor3DIsOpen && (e.ctrlKey || e.metaKey) && /^Key[ZYCXVDG]$/.test(e.code) && !editorIsTextField(e.target))
             e.preventDefault();
     });
+    // a page going away writes what is waiting, the last event it is sure to get
+    document.addEventListener('visibilitychange', ()=> document.hidden && editor3DAutosaveFlush());
+    globalThis.addEventListener?.('pagehide', editor3DAutosaveFlush);
+}
 
 ///////////////////////////////////////////////////////////////////////////////
 // what the panel does to the level, and what it says
@@ -3060,7 +3099,8 @@ function editor3DPrefabBoxUpdate(box)
         unpack.title = 'Ctrl+Shift+G: turn this instance into the objects it is made of';
         unpack.onclick = ()=> { editor3DUnpack(); unpack.blur(); };
         const save = editorElement('button', line, press, 'Export');
-        save.title = 'Save the prefab as a file of its own, to load with level3DLoadPrefab';
+        save.title = 'Save the prefab as a file of its own, to load with level3DLoadPrefab; a prefab used inside it ' +
+            'is named by its type, and the game adds that one too';
         save.onclick = ()=>
         {
             saveText(editor3DPrefabJSON(instance.prefabName), instance.prefabName + '.json', 'application/json');
@@ -3398,6 +3438,41 @@ function editor3DSceneUpdate(box)
     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));
+
+    // a sky box of six images, their urls in one field by commas, and whether shiny things reflect it; the
+    // environment follows the sky box while it is the same images
+    const urls = (list)=> isArray(list) && list.length === 6 ? list.join(', ') : '';
+    const skyBox = editorElement('input', line('Sky box', 'Six image urls by commas, +x, -x, +y, -y, +z and -z, a ' +
+        'comma and a space between data urls, loaded as a cube map for the sky; empty for none'), field + ';width:120px');
+    skyBox.value = urls(scene.skyBox);
+    skyBox.onchange = ()=>
+    {
+        // by a comma and a space, so a data url keeps its own comma, or by commas alone when that is not six
+        const value = skyBox.value.replace(/[,\s]+$/, ''); // a comma left at the end is not part of the last url
+        const split = (by)=> value.split(by).map((url)=> url.trim()).filter((url)=> url);
+        let list = split(/,\s+/);
+        list.length === 6 || (list = split(','));
+        if (list.length && list.length !== 6)
+            skyBox.value = urls(editor3DScene()?.skyBox); // not six, what it has now shows again
+        else editor3DChangeScene((s={})=>
+        {
+            const {skyBox, environment, ...rest} = s, reflected = !!urls(skyBox) && urls(environment) === urls(skyBox);
+            return {...rest, ...list.length && {skyBox: list},
+                ...(reflected ? list.length && {environment: [...list]} : environment && {environment})};
+        });
+        editor3DStrokeEnd();
+        skyBox.blur();
+    };
+    if (urls(scene.skyBox))
+        toggle('Reflect it', 'Shiny things reflect the sky box, as render3D.environment',
+            urls(scene.environment) === urls(scene.skyBox), (on)=> editor3DChangeScene((s={})=>
+            {
+                const {environment, ...rest} = s;
+                return on && isArray(s.skyBox) ? {...rest, environment: [...s.skyBox]} : rest;
+            }));
+    else if (urls(scene.environment)) // one of its own, with no sky box, can still be taken out
+        toggle('Environment', 'The level\'s own environment, six images that shiny things reflect; off takes it out',
+            true, (on)=> on || editor3DChangeScene((s={})=> { const {environment, ...rest} = s; return rest; }));
 }
 
 // the properties box: the position, rotation and scale of the one selected object and an input for each default

package/plugins/render3dExtras.js

@@ -14,14 +14,14 @@
 // the way the 2D font does, but extruded glyphs seen from an angle then overlap the line below
 const RENDER3D_TEXT_LEADING = 1.3;
 
-// let go of the parent but stay where the object was in the world, which removeChild keeps by itself; a destroyed
-// parent has already let go, so the position remembered by the last update stands in
+// let go of the parent but stay where and as the object was in the world, which removeChild keeps by itself; a
+// destroyed parent has already let go, so the world matrix last built with it in stands in, scale and turn as well
 function render3DDetach(o)
 {
     if (o.parent)
         o.parent.removeChild(o);
-    else if (o.worldPos3D)
-        o.pos3D = o.worldPos3D;
+    else if (o.matrixParent)
+        render3DTakeWorld(o, o.worldMatrix);
 }
 
 // a soft white dot for untextured particles, made once from a canvas, undefined headless or without a canvas
@@ -404,13 +404,14 @@ function buildText3D(text, size=1, depth=.2, font=engineImageFont)
     let glyphs = render3DGlyphCache.get(font); // unit sized, scaled when combined
     glyphs || render3DGlyphCache.set(font, glyphs = new Map);
     const charSize = vec2(size * tileInfo.size.x / tileInfo.size.y, size);
-    const mesh = new Mesh, lines = (text + '').split('\n');
+    const mesh = new Mesh, lines = textLines(text); // a Windows line ending too
     lines.forEach((line, j)=>
     {
         const y = ((lines.length - 1) / 2 - j) * charSize.y * RENDER3D_TEXT_LEADING;
-        for (let i = 0; i < line.length; ++i)
+        const characters = textCharacters(line); // as ImageFont reads them, an emoji one box
+        for (let i = 0; i < characters.length; ++i)
         {
-            const charCode = line.charCodeAt(i);
+            const charCode = textCharacterCode(characters, i);
             const index = charCode < 32 || charCode > 127 ? 95 : charCode - 32; // like ImageFont
             if (!index) continue; // space
             let glyph = glyphs.get(index);
@@ -419,7 +420,7 @@ function buildText3D(text, size=1, depth=.2, font=engineImageFont)
                 const pos = font.getGlyphPos(index); // where ImageFont finds it
                 glyphs.set(index, glyph = buildExtrude(new TileInfo(pos, tileInfo.size, tileInfo.textureInfo)));
             }
-            const x = (i - (line.length - 1) / 2) * charSize.x;
+            const x = (i - (characters.length - 1) / 2) * charSize.x;
             mesh.combine(glyph, buildMatrix(vec3(x, y, 0), undefined, vec3(charSize.x, charSize.y, depth)));
         }
     });
@@ -630,11 +631,15 @@ class HeightMap extends EngineObject3D
      *  @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 undefined; // 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 undefined; // above all the way, or under from the start
-        const distance = a / (a - b);
+        // a move above the highest the ground goes misses it, which is most particles most of the time
+        const top = this.pos3D.y + max(this.height, 0);
+        if (from.y > top && to.y > top) return undefined;
+        if (from.y < this.getHeight(from.x, from.z)) return undefined; // under from the start, let go
+        // the ground is flat in each triangle, not between the ends, so a ridge both ends are above is still met:
+        // the exact raycast along the move, which walks every triangle it crosses, the first one it goes under
+        const distance = this.raycast(new Ray3D(from, to.subtract(from)));
+        // over the move, and not a touch where it starts on the surface and leaves it
+        if (distance === undefined || distance > 1 || !distance && to.y >= this.getHeight(to.x, to.z)) return undefined;
         return {distance, normal: this.getNormal(from.x + (to.x - from.x) * distance, from.z + (to.z - from.z) * distance)};
     }
 
@@ -647,11 +652,26 @@ class HeightMap extends EngineObject3D
     {
         const p = o.pos3D, m = this.pos3D, size = this.mapSize;
         if (abs(p.x - m.x) > size.x / 2 || abs(p.z - m.z) > size.y / 2) return; // off the map
-        const half = o.size3D.y * abs(o.scale3D.y) / 2, ground = this.getHeight(p.x, p.z);
-        // one that stood on it and is not rising keeps to it going downhill, as far down as it moved across, so it
-        // stays grounded down a slope as steep as 45 degrees instead of falling in small hops
-        const follow = wasOn && o.velocity3D.y <= 0 ? hypot(p.x - oldPos.x, p.z - oldPos.z) : 0;
-        if (p.y - half > ground + follow) return;
+        const half = o.size3D.y * abs(o.scale3D.y) / 2;
+        let ground = this.getHeight(p.x, p.z);
+        // only the ends of a move are kept above the ground, so a ridge it goes over is met by a sweep, as a
+        // particle's move is, a quarter of its height up from its foot, from where it was to where it would stand: a
+        // bump lower than that is walked over as before, and it goes up on the near side of anything taller
+        const lift = half / 2, endFoot = max(p.y - half, ground) + lift;
+        const hit = oldPos && this.levelSegment3D(vec3(oldPos.x, oldPos.y - half + lift, oldPos.z), vec3(p.x, endFoot, p.z));
+        if (hit && hit.distance)
+        {
+            p.x = oldPos.x + (p.x - oldPos.x) * hit.distance;
+            p.z = oldPos.z + (p.z - oldPos.z) * hit.distance;
+            ground = this.getHeight(p.x, p.z);
+        }
+        else
+        {
+            // one that stood on it and is not rising keeps to it going downhill, as far down as it moved across, so
+            // it stays grounded down a slope as steep as 45 degrees instead of falling in small hops
+            const follow = wasOn && o.velocity3D.y <= 0 ? hypot(p.x - oldPos.x, p.z - oldPos.z) : 0;
+            if (p.y - half > ground + follow) return;
+        }
         p.y = ground + half;
         const v = o.velocity3D;
         if (v.y < 0)
@@ -1003,7 +1023,8 @@ class ParticleEmitter3D extends EngineObject3D
         /** @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 */
+        /** @property {number} - How long to keep emitting, 0 is forever; raised while its particles are still alive,
+         *  it emits again for the added time */
         this.emitTime = emitTime;
         /** @property {number} - Particles per second, 0 does not emit */
         this.emitRate = emitRate;
@@ -1081,6 +1102,12 @@ class ParticleEmitter3D extends EngineObject3D
          *  @type {Vector3|undefined} */
         this.worldPos3D = undefined;
         this.emitTimeBuffer = 1; // the first particle comes at once, as the 2D emitter's does
+        this.emitElapsed = 0; // seconds of its emit time it has emitted for, counted by its updates
+        // where it was last update, and how far back toward it the particle being made starts, 0 to 1: a moving
+        // emitter spreads an update's particles along its move, as the 2D emitter does
+        /** @type {Vector3|undefined} */
+        this.emitFrom = undefined;
+        this.emitBehind = 0;
     }
 
     /** Spawn new particles, move the live ones, and go away when done */
@@ -1088,21 +1115,37 @@ class ParticleEmitter3D extends EngineObject3D
     {
         // one transform for the frame: where the emitter is, and how big the effect it makes is
         const matrix = render3DObjectMatrix(this); // the object's own, read only
+        this.emitFrom = this.worldPos3D;
         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)
+        if (!this.emitTime || this.emitElapsed < this.emitTime)
         {
             // a rate of zero is an emitter fed by hand, and the global scale only quiets it,
-            // neither is a reason to stop counting down the emit time
+            // neither is a reason to stop counting down the emit time; the part of this update inside the emit time,
+            // counted by its own updates, as the 2D emitter does, so a one shot gives the same count on any frame
             const rate = this.emitRate * particleEmitRateScale;
+            const step = this.emitTime ? min(timeDelta, this.emitTime - this.emitElapsed) : timeDelta;
+            this.emitElapsed += timeDelta;
             if (rate > 0 && rate < Infinity)
             {
-                this.emitTimeBuffer += rate * timeDelta;
-                for (; this.emitTimeBuffer >= 1; --this.emitTimeBuffer)
-                    this.emitParticle();
+                // the update that ends the emit time adds a hair, as the steps' sum comes out a rounding under it
+                this.emitTimeBuffer += rate * step + (this.emitTime && this.emitElapsed >= this.emitTime ? 1e-6 : 0);
+                // spread along the move since the last update, the last one where it is now; a jump further than
+                // anything travels in an update, twice objectMaxSpeed, a teleport or a respawn, spreads nothing
+                const travelled = this.emitFrom && this.worldPos3D.distance(this.emitFrom) <= 2 * objectMaxSpeed;
+                const count = floor(this.emitTimeBuffer);
+                try
+                {
+                    for (let i = count; i--; --this.emitTimeBuffer)
+                    {
+                        this.emitBehind = travelled ? i / count : 0;
+                        this.emitParticle();
+                    }
+                }
+                finally { this.emitBehind = 0; } // a create callback that throws leaves no offset for the next
             }
         }
         else if (!this.particleCount)
@@ -1129,7 +1172,7 @@ class ParticleEmitter3D extends EngineObject3D
         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 collideLevel = this.collideLevel && enablePhysicsSolver && render3DLevel.length; // as 2D particles
         const updateCallback = this.particleUpdateCallback, destroyCallback = this.particleDestroyCallback;
         for (let i = this.particleCount; i--;)
         {
@@ -1204,6 +1247,12 @@ class ParticleEmitter3D extends EngineObject3D
         const direction = matrix.transformDirection(randVector3(1, this.emitConeAngle)).normalize();
 
         const pos = matrix.transformPoint(offset), speed = this.speed * random() * scale;
+        const from = this.emitFrom, behind = this.emitBehind; // back along its move, as the update spreads them
+        if (from && behind)
+        {
+            const here = this.worldPos3D;
+            pos.x += (from.x - here.x) * behind, pos.y += (from.y - here.y) * behind, pos.z += (from.z - here.z) * behind;
+        }
         const colorStart = randColor(this.colorStartA, this.colorStartB, true), colorEnd = randColor(this.colorEndA, this.colorEndB, true);
 
         // room for one more, doubling as the set grows, the trails along with it
@@ -1233,11 +1282,13 @@ 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.particleView.scale = scale; // the scale it was made at, emitted before the first update too
         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
+    /** @private */
     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
@@ -1245,6 +1296,7 @@ class ParticleEmitter3D extends EngineObject3D
         // emit into a full emitter grows them
         const nested = render3DParticlesCalling.has(this);
         const view = nested ? render3DParticleView(this) : this.particleView, data = this.particleData;
+        view.scale = this.particleView.scale; // a nested view's too
         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;
@@ -1264,6 +1316,7 @@ class ParticleEmitter3D extends EngineObject3D
     // 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; true when the callback
     // destroyed it
+    /** @private */
     particleCollide(k, x, y, z)
     {
         let data = this.particleData;
@@ -1634,8 +1687,9 @@ class LensFlare3D extends EngineObject3D
         /** @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, off the screen or behind the camera to 1 in
-         *  plain view, eased */
-        this.visible = 1;
+         *  plain view, eased; the first update sets it at once, so a sun hidden from the start never shows */
+        this.visible = 0;
+        this.visibleFound = false; // the first update has found it
         this.renderOrder = 1e9; // over the game's sprites, it is light in the lens
         this.madeKey = '';
         /** @type {Array<LensFlareElement>} */
@@ -1736,6 +1790,13 @@ class LensFlare3D extends EngineObject3D
      *      tileInfo: TileInfo|undefined, angle: number}>} */
     getScreenElements()
     {
+        // one made while the game is paused, as the 3D editor makes them, has had no update to find it, and while
+        // paused nothing updates it, so it is found at once each time it is drawn, as the camera turns
+        if (!this.visibleFound || paused)
+        {
+            this.visibleFound = false;
+            this.updateVisible(0);
+        }
         const look = this.visible > 0 && this.flareLook();
         if (!look) return [];
         const {sun, center, tint, height} = look, strength = look.strength * this.visible;
@@ -1759,7 +1820,7 @@ class LensFlare3D extends EngineObject3D
         if (!source) return true;
         const ray = new Ray3D(render3D.camera.pos, source.direction), reach = source.distance;
         const blockers = engineObjects.filter((o)=> o !== this && o instanceof EngineObject3D && !o.destroyed &&
-            !o.transparent && !o.additive);
+            !o.transparent && !render3DSetting(o, 'additive'));
         // a voxel map says block by block what is see through: glass, water and leaves let the sun by, and the
         // ray goes on to the blocks behind them
         const maps = /** @type {Array<VoxelMap>} */ (typeof VoxelMap == 'undefined' ? [] :
@@ -1800,9 +1861,20 @@ class LensFlare3D extends EngineObject3D
         super.update();
         if (this.light?.destroyed)
             return this.destroy(); // the flare of a light that is gone
+        this.updateVisible(timeDelta);
+    }
+
+    /** Ease visible toward whether the sun shows over some seconds; the first time it is found at once, from the
+     *  camera as it is, its matrices made, by the first update or the first draw, whichever comes first
+     *  @param {number} seconds
+     *  @ignore */
+    updateVisible(seconds)
+    {
+        this.visibleFound || render3D.updateMatrices();
         const shows = !!this.flareLook() && !(this.occlusion && this.isHidden());
-        const step = this.fadeTime > 0 ? timeDelta / this.fadeTime : 1;
+        const step = this.fadeTime > 0 && this.visibleFound ? seconds / this.fadeTime : 1;
         this.visible = clamp(this.visible + (shows ? step : -step));
+        this.visibleFound = true;
     }
 
     /** Draw the flare over the 3D scene, added onto it, called automatically in the 2D pass */
@@ -1918,9 +1990,9 @@ function parseOBJ(text, smooth=render3D?.smoothShading)
  */
 async function loadOBJ(url, smooth=render3D?.smoothShading)
 {
-    const response = await fetch(url);
+    const response = await loadFetch(url, 'loadOBJ');
     if (!response.ok)
-        throw new Error('loadOBJ failed: ' + url);
+        throw new Error(`loadOBJ: could not load ${url}, ${response.status} ${response.statusText}`);
     const text = await response.text(), mesh = parseOBJ(text, smooth);
     // a mesh of nothing draws nothing, so it says why, a web page being what a dev server sends for a mistyped path
     mesh.points.length || console.warn('loadOBJ: ' + url + ' has no faces' +

package/plugins/render3dLevel.js

@@ -19,7 +19,8 @@ const LEVEL3D_VERSION = 1; // the format a level's littlejs3D names
  *  @typedef {Object} Level3D
  *  @property {number} [littlejs3D] - The format's version, 1
  *  @property {Array<Object>} objects - Each {id, type, pos, rotation, scale, properties}, all but type optional
- *  @property {Object} [scene] - The scene block: sky, ambient, sunDirection, sunColor, fog, fogColor, shadows, lensFlare
+ *  @property {Object} [scene] - The scene block: sky, ambient, sunDirection, sunColor, fog, fogColor, shadows, lensFlare,
+ *    skyBox, environment
  *  @property {Object} [voxels] - A block map: {pos, size, blocks}
  *  @property {Object} [terrain] - A height map: {pos, size, height, color, heights, paint}
  *  @property {Object} [prefabs] - The level's own prefabs by name, each {objects, attached}
@@ -94,9 +95,10 @@ 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, 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
+ *    sunColor, fog, its start and end, fogColor, the horizon color when not given, shadows, lensFlare, the
+ *    sun's lens flare, and skyBox and environment, each six image urls as loadCubeMap takes them, which load in
+ *    the background and are set when they have; what the block leaves out stays as the game set it, and a level
+ *    with no block changes nothing
  *  @param {Level3D} 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 */
@@ -300,6 +302,8 @@ const level3DSkies = new WeakSet;
 // and shadows; a setting the block does not have, or has wrong, stays as it is
 function level3DSceneApply(scene)
 {
+    // a sky box or environment an earlier scene is still loading does not land on this one's
+    ++level3DSceneCubeLoads.skyBox, ++level3DSceneCubeLoads.environment;
     const r = render3D;
     if (!r || !scene || typeof scene !== 'object') return;
     const color = level3DHexColor;
@@ -326,6 +330,47 @@ function level3DSceneApply(scene)
         r.shadows = scene.shadows;
     if (typeof scene.lensFlare === 'boolean')
         level3DSceneFlare(scene.lensFlare);
+    level3DSceneCubeMap('skyBox', scene.skyBox);
+    level3DSceneCubeMap('environment', scene.environment);
+}
+
+// the cube maps scene blocks loaded, by their six urls, the four used last, so the same ones load once; a load that
+// failed is not kept, and is tried again by the next scene that names it
+const level3DSceneCubeMaps = new Map;
+const level3DSceneCubeLoaded = new WeakMap; // the cube map each of their loads gave, once it has
+
+// which load each of render3D.skyBox and environment waits for: every scene applied, or the editor putting the
+// game's back, moves it on, and a load that finishes after is dropped
+const level3DSceneCubeLoads = {skyBox: 0, environment: 0};
+
+// load the six urls a scene block gives for render3D.skyBox or environment and set it when they have loaded; a value
+// that is not six strings leaves it as it is, and a failed load says so and leaves it too
+function level3DSceneCubeMap(field, urls)
+{
+    if (!isArray(urls) || urls.length !== 6 || !urls.every((url)=> typeof url === 'string')) return;
+    const key = urls.join('\n'), load = ++level3DSceneCubeLoads[field], before = render3D[field];
+    // kept by the urls, newest last: one used again moves to the end, and past four the oldest goes, its texture
+    // freed unless it is still on screen
+    let cube = level3DSceneCubeMaps.get(key);
+    level3DSceneCubeMaps.delete(key);
+    level3DSceneCubeMaps.set(key, cube ||= loadCubeMap(urls));
+    cube.then((map)=> level3DSceneCubeLoaded.set(cube, map), ()=> {});
+    for (const [oldKey, old] of level3DSceneCubeMaps)
+    {
+        if (level3DSceneCubeMaps.size <= 4) break;
+        // one on screen stays, so it is not loaded again and the copy on screen left behind
+        const map = level3DSceneCubeLoaded.get(old);
+        if (map && (map === render3D.skyBox || map === render3D.environment)) continue;
+        level3DSceneCubeMaps.delete(oldKey);
+        old.then((map)=> map !== render3D.skyBox && map !== render3D.environment && map.dispose(), ()=> {});
+    }
+    // set when it has loaded, unless a newer scene came, or the game set the field itself meanwhile
+    const landed = (map)=> load === level3DSceneCubeLoads[field] && render3D[field] === before && (render3D[field] = map);
+    cube.then(landed, (error)=>
+    {
+        level3DSceneCubeMaps.get(key) === cube && level3DSceneCubeMaps.delete(key);
+        console.warn(error.message);
+    });
 }
 
 // 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
@@ -544,12 +589,14 @@ class Prefab3D extends EngineObject3D
         this.prefabName = prefabName;
         /** @property {boolean} - Are its parts its children, moving with it as one body */
         this.attached = !!level3DPrefabs.get(prefabName)?.attached || level3DPrefabAttached > 0;
-        /** @property {Array<any>} - What the prefab's objects made, in the prefab's order */
+        /** @property {Array<EngineObject3D>} - What the prefab's objects made, in the prefab's order
+         *  @type {Array<EngineObject3D>} */
         this.parts = [];
         /** @property {Vector3} - From the prefab's origin to the handle, in the prefab's own space: nothing for
          *  separate parts, and for an attached prefab the middle of the box around its parts, where its handle
          *  is, as an object's place is the middle of its body */
         this.originOffset = vec3();
+        /** @type {Array<{id?: number, type: string, pos?: Array<number>, rotation?: Array<number>, scale?: Array<number>|number, properties?: Object}>} */
         this.partObjects = []; // the prefab's object of each part
         this.partsPlaced = ''; // where the handle was when its parts were last placed, undefined parts not made
         this.partsMade = false;
@@ -641,6 +688,7 @@ class Prefab3D extends EngineObject3D
             for (const part of children)
             {
                 part.pos3D = part.pos3D.subtract(this.originOffset);
+                render3DShareSettings(part, this); // drawn with what is set on the handle, its own otherwise
                 this.addChild(part);
             }
         }