littlejsengine 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "littlejsengine",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "LittleJS - Tiny and Fast HTML5 Game Engine",
   "main": "dist/littlejs.esm.js",
   "types": "dist/littlejs.d.ts",

package/plugins/gltf.js

@@ -8,6 +8,8 @@
  *   GLTFObject that createObject makes; a skinned character's walk is not read
  * - Materials give a base color and texture and whether they blend; glass made with KHR_materials_transmission blends too,
  *   and a KHR_materials_unlit material comes in emissive, its own color with no shading
+ * - A material's normal map and emissive map load too, with its normal scale and emissive factor, read at the base
+ *   color texture's uvs; roughness, metalness and occlusion maps are not loaded
  * - The base color texture reads the uv set its texCoord names, moved by KHR_texture_transform as gltfpack and
  *   Blender write it
  * - An OPAQUE material, the default, ignores its texture's alpha as the format says: a texture only such materials
@@ -56,6 +58,17 @@ class GLTFPart
         /** @property {boolean} - The material is unlit (KHR_materials_unlit), its own color with no shading; the object
          *  createObject makes draws it with emissive 1 */
         this.unlit = false;
+        /** @property {TextureInfo|undefined} - The material's normal map, drawn with the base color texture's uvs
+         *  @type {TextureInfo|undefined} */
+        this.normalMap = undefined;
+        /** @property {number} - The normal map's strength, its scale in the file */
+        this.normalScale = 1;
+        /** @property {TextureInfo|undefined} - The material's emissive map, or a white texture when it has an
+         *  emissiveFactor and no texture, so it glows all over
+         *  @type {TextureInfo|undefined} */
+        this.emissiveMap = undefined;
+        /** @property {Color} - The emissiveFactor, which multiplies the emissive map */
+        this.emissiveMapColor = WHITE;
     }
 }
 
@@ -201,8 +214,8 @@ class GLTFModel
         for (const part of this.parts)
             part.mesh.dispose();
         this.mesh.dispose();
-        for (const textureInfo of new Set(this.parts.map(p=> p.textureInfo)))
-            textureInfo?.destroyWebGLTexture();
+        for (const textureInfo of new Set(this.parts.flatMap(p=> [p.textureInfo, p.normalMap, p.emissiveMap])))
+            textureInfo !== gltfWhiteTextureInfo && textureInfo?.destroyWebGLTexture(); // the white one is shared
     }
 
     /** Make an object at a position with a child per part, so each keeps its own texture, color and blending, and
@@ -260,6 +273,8 @@ class GLTFObject extends EngineObject3D
             o.transparent = part.transparent;
             o.pixelated = part.pixelated;
             o.emissive = part.unlit ? 1 : 0;
+            o.normalMap = part.normalMap, o.normalScale = part.normalScale;
+            o.emissiveMap = part.emissiveMap, o.emissiveMapColor = part.emissiveMapColor.copy(); // its own, as color is
             const rest = model.nodeTree?.restPose?.[part.node];
             if (rest)
             {
@@ -396,13 +411,15 @@ async function parseGLTF(data, baseUrl='')
         return gltfFetch(buffer.uri, baseUrl).then(r=> r.arrayBuffer());
     }));
 
-    // the textures, decoded together first; none without WebGL, and a failed image only logs; only the base color
-    // textures are drawn with, so the normal, roughness and other maps are not loaded at all
-    const baseColorTextures = new Set((json.materials || []).map(m=> m.pbrMetallicRoughness?.baseColorTexture?.index));
+    // the textures, decoded together first; none without WebGL, and a failed image only logs; the base color, normal
+    // and emissive textures are drawn with, the roughness and occlusion maps are not loaded at all
+    const usedTextures = new Set((json.materials || []).flatMap(m=> [m.pbrMetallicRoughness?.baseColorTexture?.index,
+        m.normalTexture?.index, m.emissiveTexture?.index]));
+    const normalTextures = new Set((json.materials || []).map(m=> m.normalTexture?.index));
     const opaqueTextures = gltfOpaqueTextures(json);
     const textures = await Promise.all((json.textures || []).map(async (texture, index)=>
     {
-        if (!glContext || typeof createImageBitmap == 'undefined' || !baseColorTextures.has(index)) return;
+        if (!glContext || typeof createImageBitmap == 'undefined' || !usedTextures.has(index)) return;
         try
         {
             // a WebP or AVIF image is named by its extension, the browser decodes those like any other
@@ -419,7 +436,11 @@ async function parseGLTF(data, baseUrl='')
             // an OPAQUE material ignores its texture's alpha, which the 3D pass would cut holes by, so a texture only
             // those use has it set to 1; decoded as stored for that, and a jpeg has no alpha to set
             const opaque = opaqueTextures.has(index) && blob.type !== 'image/jpeg';
-            const bitmap = opaque ? await createImageBitmap(blob, {premultiplyAlpha: 'none'}).then(gltfOpaqueImage) : await createImageBitmap(blob);
+            // a normal map is directions, not colors, so it is decoded as stored; one a material also uses as a
+            // color, an odd file, is decoded that way too
+            const bitmap = normalTextures.has(index) ?
+                await createImageBitmap(blob, {colorSpaceConversion: 'none', premultiplyAlpha: 'none'}) :
+                opaque ? await createImageBitmap(blob, {premultiplyAlpha: 'none'}).then(gltfOpaqueImage) : await createImageBitmap(blob);
             return new TextureInfo(bitmap, true, [sampler.wrapS ?? 10497, sampler.wrapT ?? 10497]); // REPEAT by default
         }
         catch (e) { LOG('glTF image not loaded', e); }
@@ -495,7 +516,7 @@ async function parseGLTF(data, baseUrl='')
     }
 
     // a texture none of the parts draws with, another scene's, goes now too, since dispose finds them by the parts
-    const used = new Set(parts.map(p=> p.textureInfo));
+    const used = new Set(parts.flatMap(p=> [p.textureInfo, p.normalMap, p.emissiveMap]));
     for (const texture of textures)
         texture && !used.has(texture) && texture.destroyWebGLTexture();
     return new GLTFModel(parts, animations, {nodes: json.nodes, parents, restInverse, restPose});
@@ -731,9 +752,34 @@ function gltfPart(json, buffers, textures, primitive, matrix, name)
         textureRef ? textures[textureRef.index] : undefined, blend || transmission > 0);
     part.pixelated = json.samplers?.[texture?.sampler]?.magFilter === 9728; // NEAREST
     part.unlit = !!material.extensions?.KHR_materials_unlit;
+
+    // the normal and emissive maps, read at the base color texture's uvs; the emissive texture is multiplied by the
+    // factor, which is black by default as the format says, so a texture alone does not glow; a factor with no
+    // texture glows all over
+    const normalRef = material.normalTexture, emissiveRef = material.emissiveTexture;
+    part.normalMap = normalRef && textures[normalRef.index];
+    part.normalScale = normalRef?.scale ?? 1;
+    const [er, eg, eb] = material.emissiveFactor || [0, 0, 0];
+    if (er || eg || eb)
+    {
+        part.emissiveMap = emissiveRef ? textures[emissiveRef.index] : gltfWhiteTexture();
+        part.emissiveMapColor = rgb(gltfSRGB(er), gltfSRGB(eg), gltfSRGB(eb));
+    }
     return part;
 }
 
+// a 1 by 1 white texture, the emissive map of a material that glows all over with no texture; made once and never
+// freed, like the engine's own white texture, undefined without WebGL
+let gltfWhiteTextureInfo;
+function gltfWhiteTexture()
+{
+    if (gltfWhiteTextureInfo || !glContext || typeof OffscreenCanvas == 'undefined') return gltfWhiteTextureInfo;
+    const context = createCanvasContext(1);
+    context.fillStyle = '#fff';
+    context.fillRect(0, 0, 1, 1);
+    return gltfWhiteTextureInfo = new TextureInfo(context.canvas);
+}
+
 // a glTF color factor or vertex color is linear, where the renderer works in sRGB like the textures, so it is
 // brought across at load or a mid gray material would come out nearly black; 0 and 1 stay exact
 function gltfSRGB(c)

package/plugins/math3d.js

@@ -652,36 +652,62 @@ class Ray3D
 
 ///////////////////////////////////////////////////////////////////////////////
 // 3D collision helpers, none of them change anything that is passed in
-// Boxes sit centered on pos and take a full size, like drawRect
+// Boxes sit centered on pos and take a full size, like drawRect, upright unless given a rotation, an Euler vec3 like
+// rotation3D, which turns them about their center
 // Cylinders stand up the Y axis, centered on pos, with a full height
 // Names that could be mistaken for 2D functions get a 3D suffix
 
+// whether a rotation turns anything, a missing one does not
+const isTurned3D = (rotation)=> !!rotation && !!(rotation.x || rotation.y || rotation.z);
+
+// a turned box's three unit axes, the columns of its rotation
+function boxAxes3D(rotation)
+{
+    const m = buildMatrix(undefined, rotation).m;
+    return [vec3(m[0], m[1], m[2]), vec3(m[4], m[5], m[6]), vec3(m[8], m[9], m[10])];
+}
+
+// a point in a turned box's own space, from its center, and a vector from that space back to the world's
+function boxLocal3D(point, pos, axes)
+{
+    const d = point.subtract(pos);
+    return vec3(d.dot(axes[0]), d.dot(axes[1]), d.dot(axes[2]));
+}
+const boxWorld3D = (v, axes)=> axes[0].scale(v.x).add(axes[1].scale(v.y)).add(axes[2].scale(v.z));
+
 /**
- * Check if a point is inside an axis aligned box, boundary is inclusive
+ * Check if a point is inside a box, boundary is inclusive
  * @param {Vector3} point
  * @param {Vector3} pos - Center of the box
  * @param {Vector3} size - Full size of the box
+ * @param {Vector3} [rotation] - How the box is turned, upright when left out
  * @return {boolean}
  * @memberof Math3D
  */
-function isPointInBox3D(point, pos, size)
+function isPointInBox3D(point, pos, size, rotation)
 {
+    if (isTurned3D(rotation))
+        return isPointInBox3D(boxLocal3D(point, pos, boxAxes3D(rotation)), vec3(), size);
     return abs(point.x - pos.x) <= size.x/2 &&
         abs(point.y - pos.y) <= size.y/2 &&
         abs(point.z - pos.z) <= size.z/2;
 }
 
 /**
- * Check if two axis aligned boxes are overlapping, touching edges do not overlap
+ * Check if two boxes are overlapping, touching edges do not overlap
  * @param {Vector3} posA
  * @param {Vector3} sizeA - Full size of box A
  * @param {Vector3} posB
  * @param {Vector3} [sizeB] - Full size of box B, zero for a point
+ * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+ * @param {Vector3} [rotationB] - How box B is turned
  * @return {boolean}
  * @memberof Math3D
  */
-function isOverlapping3D(posA, sizeA, posB, sizeB=vec3())
+function isOverlapping3D(posA, sizeA, posB, sizeB=vec3(), rotationA, rotationB)
 {
+    if (isTurned3D(rotationA) || isTurned3D(rotationB))
+        return !!collideBoxBox3D(posA, sizeA, posB, sizeB, rotationA, rotationB);
     const d = posA.subtract(posB);
     return abs(d.x) < (sizeA.x + sizeB.x)/2 &&
         abs(d.y) < (sizeA.y + sizeB.y)/2 &&
@@ -710,16 +736,19 @@ function collideSphereSphere(posA, radiusA, posB, radiusB)
 }
 
 /**
- * Returns the vector to move a sphere out of an axis aligned box, or undefined
+ * Returns the vector to move a sphere out of a box, or undefined
  * @param {Vector3} pos - Sphere center
  * @param {number} radius
  * @param {Vector3} boxPos
  * @param {Vector3} boxSize - Full size of the box
+ * @param {Vector3} [boxRotation] - How the box is turned, upright when left out
  * @return {Vector3|undefined}
  * @memberof Math3D
  */
-function collideSphereBox(pos, radius, boxPos, boxSize)
+function collideSphereBox(pos, radius, boxPos, boxSize, boxRotation)
 {
+    if (isTurned3D(boxRotation))
+        return collideSphereOrientedBox3D(pos, radius, boxPos, boxSize, boxAxes3D(boxRotation));
     const h = boxSize.scale(.5);
     const closest = vec3(
         clamp(pos.x, boxPos.x - h.x, boxPos.x + h.x),
@@ -807,15 +836,20 @@ function collideSphereCylinder(pos, radius, cylinderPos, cylinderRadius, cylinde
 /**
  * Returns the vector to move box A by so it no longer overlaps box B, the shortest way out, or undefined
  * - The 3D twin of collideBoxBox
+ * - Turned boxes are tested by the separating axis test, the push is along the direction they overlap least on
  * @param {Vector3} posA
  * @param {Vector3} sizeA - Full size of box A
  * @param {Vector3} posB
  * @param {Vector3} sizeB - Full size of box B
+ * @param {Vector3} [rotationA] - How box A is turned, upright when left out
+ * @param {Vector3} [rotationB] - How box B is turned
  * @return {Vector3|undefined}
  * @memberof Math3D
  */
-function collideBoxBox3D(posA, sizeA, posB, sizeB)
+function collideBoxBox3D(posA, sizeA, posB, sizeB, rotationA, rotationB)
 {
+    if (isTurned3D(rotationA) || isTurned3D(rotationB))
+        return collideOrientedBoxes3D(posA, sizeA, boxAxes3D(rotationA), posB, sizeB, boxAxes3D(rotationB));
     const d = posA.subtract(posB);
     const overlapX = (sizeA.x + sizeB.x)/2 - abs(d.x);
     const overlapY = (sizeA.y + sizeB.y)/2 - abs(d.y);
@@ -825,6 +859,44 @@ function collideBoxBox3D(posA, sizeA, posB, sizeB)
     return pushOutAxis3D(d, overlapX, overlapY, overlapZ);
 }
 
+// the push to move a sphere out of a box turned to these axes: in the box's own space it is upright, and the push
+// goes back out turned
+function collideSphereOrientedBox3D(pos, radius, boxPos, boxSize, axes)
+{
+    const push = collideSphereBox(boxLocal3D(pos, boxPos, axes), radius, vec3(), boxSize);
+    return push && boxWorld3D(push, axes);
+}
+
+// the world's axes, for an upright box among turned ones
+const BOX_WORLD_AXES = Object.freeze([vec3(1, 0, 0), vec3(0, 1, 0), vec3(0, 0, 1)]);
+
+// the shortest push to move box A out of box B by the separating axis test: each box's three face directions and
+// the nine across an edge of each; a gap on any of them is no touch, and the push is along the least overlap, from
+// B to A; an edge direction has to overlap clearly less to win, so a box lying on another leaves by the face
+function collideOrientedBoxes3D(posA, sizeA, axesA, posB, sizeB, axesB)
+{
+    const d = posA.subtract(posB), ha = sizeA.scale(.5), hb = sizeB.scale(.5);
+    const reach = (h, axes, n)=> h.x * abs(axes[0].dot(n)) + h.y * abs(axes[1].dot(n)) + h.z * abs(axes[2].dot(n));
+    let push, least = Infinity;
+    const separated = (axis, weight)=>
+    {
+        const lengthSquared = axis.lengthSquared();
+        if (lengthSquared < 1e-12) return false; // parallel edges give no direction to test
+        const n = axis.scale(lengthSquared ** -.5), along = d.dot(n);
+        const overlap = reach(ha, axesA, n) + reach(hb, axesB, n) - abs(along);
+        if (overlap <= 0) return true;
+        if (overlap * weight < least)
+            least = overlap * weight, push = n.scale(along < 0 ? -overlap : overlap);
+        return false;
+    };
+    for (const axis of [...axesA, ...axesB])
+        if (separated(axis, 1)) return;
+    for (const a of axesA)
+    for (const b of axesB)
+        if (separated(a.cross(b), 1.05)) return;
+    return push;
+}
+
 /**
  * Returns the distance along the ray to the first intersection with a sphere, or undefined
  * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
@@ -873,17 +945,25 @@ function raycastPlane(ray, planePos, planeNormal)
 }
 
 /**
- * Returns the distance along the ray to the first intersection with an axis aligned box, or undefined
+ * Returns the distance along the ray to the first intersection with a box, or undefined
  * - The hit is ray.getPosition(distance), a direction that is not unit length scales the distance
  * - A ray starting inside the box is already there, so it gets back 0
  * @param {Ray3D} ray
  * @param {Vector3} pos - Center of the box
  * @param {Vector3} size - Full size of the box
+ * @param {Vector3} [rotation] - How the box is turned, upright when left out
  * @return {number|undefined}
  * @memberof Math3D
  */
-function raycastBox(ray, pos, size)
+function raycastBox(ray, pos, size, rotation)
 {
+    if (isTurned3D(rotation))
+    {
+        // the ray in the box's own space, where the box is upright; turning keeps the distances
+        const axes = boxAxes3D(rotation), d = ray.direction;
+        const direction = vec3(d.dot(axes[0]), d.dot(axes[1]), d.dot(axes[2]));
+        return raycastBox(new Ray3D(boxLocal3D(ray.origin, pos, axes), direction), vec3(), size);
+    }
     const {origin, direction} = ray;
     const h = size.scale(.5);
     const boxMin = pos.subtract(h), boxMax = pos.add(h);

package/plugins/pluginExport.js

@@ -103,6 +103,10 @@ export
     tweenUpdate,
     Ease,
 
+    // Scene System
+    setScene,
+    getScene,
+
     // Path Finding
     PathFinder,
     PathFinderNode,
@@ -151,6 +155,7 @@ export
     buildRibbon,
     buildLoft,
     buildSky,
+    normalMapFromHeight,
     buildExtrude,
     buildText3D,
     HeightMap,
@@ -177,6 +182,11 @@ export
     debugLine3D,
     debugPoint3D,
 
+    // 3D Level
+    level3DAddType,
+    level3DAddMesh,
+    level3DLoad,
+
     // Three.js
     threeJS,
     ThreeJSPlugin,

package/plugins/postProcess.js

@@ -93,18 +93,7 @@ class PostProcessPlugin
                 'gl_Position=vec4(p+p-1.,1,1);'+ // set position
                 '}'                              // end of shader
                 ,
-                '#version 300 es\n' +            // specify GLSL ES version
-                'precision highp float;'+        // use highp for accuracy
-                'uniform sampler2D iChannel0;'+  // input texture
-                'uniform sampler2D iChannel1;'+  // the previous frame's output, when feedbackTexture is set
-                'uniform vec3 iResolution;'+     // size of output texture
-                'uniform float iTime;'+          // time
-                'out vec4 c;'+                   // out color
-                '\n' + shaderCode + '\n'+        // insert custom shader code
-                'void main(){'+                  // shader entry point
-                'mainImage(c,gl_FragCoord.xy);'+ // call post process function
-                'c.a=1.;'+                       // always use full alpha
-                '}'                              // end of shader
+                postProcessFragmentSource(shaderCode)
             );
 
             // setup VAO for post processing
@@ -192,10 +181,20 @@ class PostProcessPlugin
                 glContext.bindTexture(glContext.TEXTURE_2D, postProcess.feedbackTexture);
             }
 
+            // the 3D depth, when render3D draws it, on the third texture unit, with what sceneDepth needs to read it
+            const depth = typeof render3D != 'undefined' && render3D?.depthTexture ? render3D : undefined;
+            glContext.activeTexture(glContext.TEXTURE2);
+            glContext.bindTexture(glContext.TEXTURE_2D, depth?.cameraDepthTexture || null);
+            glContext.activeTexture(glContext.TEXTURE0);
+            const camera = depth?.camera;
+            camera && glContext.uniform3f(glUniformLocation(postProcess.shader, 'iDepthRange'), camera.near,
+                camera.far == Infinity ? 0 : camera.far, camera.orthographic ? 1 : 0);
+
             // set uniforms and draw
             const uniformLocation = (name)=>glUniformLocation(postProcess.shader, name);
             glContext.uniform1i(uniformLocation('iChannel0'), 0);
             glContext.uniform1i(uniformLocation('iChannel1'), 1);
+            glContext.uniform1i(uniformLocation('iChannel2'), 2);
             glContext.uniform1f(uniformLocation('iTime'), time);
             glContext.uniform3f(uniformLocation('iResolution'), mainCanvas.width, mainCanvas.height, 1);
             glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, 4);
@@ -207,6 +206,11 @@ class PostProcessPlugin
                 glContext.activeTexture(glContext.TEXTURE0);
             }
 
+            // the depth leaves the third unit for whatever draws next
+            glContext.activeTexture(glContext.TEXTURE2);
+            glContext.bindTexture(glContext.TEXTURE_2D, null);
+            glContext.activeTexture(glContext.TEXTURE0);
+
             // restore defaults so subsequent dynamic texture uploads aren't flipped or premultiplied
             glContext.pixelStorei(glContext.UNPACK_FLIP_Y_WEBGL, false);
             glContext.pixelStorei(glContext.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
@@ -223,6 +227,31 @@ class PostProcessPlugin
 
 ///////////////////////////////////////////////////////////////////////////////
 
+// the fragment shader of the post process pass around its mainImage snippet: the frame on iChannel0, the last output
+// on iChannel1 with a feedback texture, and the 3D depth on iChannel2 when render3D.depthTexture is on, read with
+// sceneDepth(uv), the distance from the camera along its view in world units, uv 0 to 1 across the screen
+function postProcessFragmentSource(shaderCode)
+{
+    return '#version 300 es\n' +        // specify GLSL ES version
+        'precision highp float;'+        // use highp for accuracy
+        'uniform sampler2D iChannel0;'+  // input texture
+        'uniform sampler2D iChannel1;'+  // the previous frame's output, when feedbackTexture is set
+        'uniform sampler2D iChannel2;'+  // the 3D depth, when render3D.depthTexture is on
+        'uniform vec3 iResolution;'+     // size of output texture
+        'uniform float iTime;'+          // time
+        'uniform vec3 iDepthRange;'+     // the camera's near, its far or 0 for none, and 1 when orthographic
+        'out vec4 c;'+                   // out color
+        // the depth texture's value back to a distance, as the camera's projection put it there
+        'float sceneDepth(vec2 uv){'+
+        'float d=texture(iChannel2,uv).r*2.-1.,n=iDepthRange.x,f=iDepthRange.y;'+
+        'return iDepthRange.z>0.?(d*(f-n)+f+n)/2.:f>0.?2.*n*f/(f+n-d*(f-n)):2.*n/(1.-d);}'+
+        '\n' + shaderCode + '\n'+        // insert custom shader code
+        'void main(){'+                  // shader entry point
+        'mainImage(c,gl_FragCoord.xy);'+ // call post process function
+        'c.a=1.;'+                       // always use full alpha
+        '}';                             // end of shader
+}
+
 /**
  * Shader code for a bloom effect, the bright parts of the image blurred back over it
  * - Pass it to PostProcessPlugin, or edit the string to build an effect on top of it