littlejsengine 1.24.3 → 1.26.0

package/plugins/render3dLevel.js

@@ -15,6 +15,17 @@
 
 const LEVEL3D_VERSION = 1; // the format a level's littlejs3D names
 
+/** A 3D level as it is saved, what level3DLoad takes and the 3D level editor edits
+ *  @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,
+ *    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}
+ *  @memberof Level3D */
+
 // the types a level's objects are made from, by name
 const level3DTypes = new Map;
 
@@ -33,7 +44,7 @@ const level3DBaseScale = new WeakMap;
  *  - Adding a name again replaces it, Box, Sphere, Cylinder and Light too
  *  @param {string} name - The type the objects have in the level
  *  @param {Function} make - A class made at each object's position, or a function called with it
- *  @param {Object} [defaults] - Properties of each one made, the level editor shows inputs for them
+ *  @param {Object<string, any>} [defaults] - Properties of each one made, the level editor shows inputs for them
  *  @param {TileInfo} [tileInfo] - An icon for the level editor
  *  @memberof Level3D
  *  @example
@@ -84,10 +95,11 @@ 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
- *  @param {Object} level - The level, the level editor edits this same object
+ *    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 */
 function level3DLoad(level)
@@ -290,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;
@@ -316,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
@@ -420,7 +475,7 @@ function level3DMakeAt(object, pos, rotation, scale)
  *  @param {Vector3} [pos3D]
  *  @param {Vector3} [rotation3D] - In radians, as an object has it
  *  @param {Vector3} [scale3D] - Times the scale the type makes it with
- *  @param {Object} [properties] - Over the type's defaults
+ *  @param {Object<string, any>} [properties] - Over the type's defaults
  *  @return {any} - What the type made, a Prefab3D for a prefab, undefined when there is no such type
  *  @memberof Level3D
  *  @example
@@ -459,7 +514,8 @@ const level3DPrefabMaking = [];
  *    by hand does
  *  - Adding a name again replaces it
  *  @param {string} name - The type its instances have in a level
- *  @param {Object} prefab - {objects, attached}
+ *  @param {{objects: Array<Object>, attached?: boolean}} prefab - Its objects, about its own origin, and whether
+ *    they are attached
  *  @memberof Level3D
  *  @example
  *  level3DAddPrefab('Tower', {objects: [{type: 'Box', pos: [0, 1, 0], scale: [2, 2, 2]},
@@ -533,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;
@@ -630,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);
             }
         }