littlejsengine 1.24.3 → 1.25.0

package/plugins/postProcess.js

@@ -49,6 +49,18 @@ class PostProcessPlugin
         /** @property {string} - The shadertoy style mainImage code it shades with, see setShaderCode */
         this.shaderCode = shaderCode || postProcessEffects(); // no code passes the frame through
 
+        /** @property {Object<string, number|Array<number>>} - The game's own values for the shader, a uniform each
+         *  by its name, a number a float and a list of 2 to 4 numbers a vector, set every frame as they are; an
+         *  effect setting can be one of these names, so it changes every frame without making the shader again, all
+         *  but glow's size, which sets how many samples it takes; adding or removing a name makes the shader again,
+         *  and the shader is first made at the first render, so values set right after the plugin are in it; a name
+         *  is a GLSL name not starting with an underscore, which the effects keep for their own, nor i and a capital
+         *  or gl_, and not c, uv or p, the names mainImage works on
+         *  @type {Object<string, number|Array<number>>} */
+        this.values = {};
+        // the names of the values the shader was made with
+        this.valueNames = '';
+
         /** @property {WebGLProgram|undefined} - Shader for post processing
          *  @type {WebGLProgram|undefined} */
         this.shader = undefined;
@@ -62,18 +74,14 @@ class PostProcessPlugin
          *  @type {WebGLVertexArrayObject|undefined} */
         this.vao = undefined;
 
-        // setup the post processing plugin
-        initPostProcess();
+        // the shader is made at the first render, so values the game sets after this, which its code may name, are
+        // declared in it
+        !headlessMode && !glEnable && console.warn('PostProcessPlugin: WebGL not enabled!');
         engineAddPlugin(undefined, postProcessRender, postProcessContextLost, postProcessContextRestored);
 
         function initPostProcess()
         {
-            if (headlessMode) return;
-            if (!glEnable)
-            {
-                console.warn('PostProcessPlugin: WebGL not enabled!');
-                return;
-            }
+            if (headlessMode || !glEnable) return;
 
             // create resources, the feedback starting black, as if the frame before the first were empty
             if (feedbackTexture)
@@ -93,8 +101,9 @@ class PostProcessPlugin
                 'gl_Position=vec4(p+p-1.,1,1);'+ // set position
                 '}'                              // end of shader
                 ,
-                postProcessFragmentSource(postProcess.shaderCode)
+                postProcessFragmentSource(postProcess.shaderCode, postProcess.values)
             );
+            postProcess.valueNames = postProcessValueKey(postProcess.values);
 
             // setup VAO for post processing
             postProcess.vao = glContext.createVertexArray();
@@ -130,13 +139,17 @@ class PostProcessPlugin
             // clear out the buffer, before anything here binds its own
             glFlush();
 
-            // made now if WebGL was off when the plugin was made, when a lost context came back, or when
-            // setShaderCode gave it new code
+            // made now if WebGL was off when the plugin was made, when a lost context came back, when setShaderCode
+            // gave it new code, or when the game added or took away a value, which the shader declares
+            if (postProcess.shader && postProcessValueKey(postProcess.values) !== postProcess.valueNames)
+                postProcess.setShaderCode(postProcess.shaderCode);
             if (!postProcess.shader)
             {
                 if (glContext.isContextLost()) return;
                 initPostProcess();
             }
+            if (glFailedPrograms.has(postProcess.shader))
+                return; // a shader that did not build in a release build, the frame shows as it is
 
             // ensure we render to the default framebuffer (in case any earlier
             // caller this frame left a render target bound)
@@ -194,9 +207,10 @@ class PostProcessPlugin
             glContext.activeTexture(glContext.TEXTURE2);
             glContext.bindTexture(glContext.TEXTURE_2D, depth?.cameraDepthTexture || null);
             glContext.activeTexture(glContext.TEXTURE0);
+            // all 0 without one, which an effect reads as no depth
             const camera = depth?.camera;
-            camera && glContext.uniform3f(glUniformLocation(postProcess.shader, 'iDepthRange'), camera.near,
-                camera.far == Infinity ? 0 : camera.far, camera.orthographic ? 1 : 0);
+            glContext.uniform3f(glUniformLocation(postProcess.shader, 'iDepthRange'), camera?.near || 0,
+                !camera || camera.far == Infinity ? 0 : camera.far, camera?.orthographic ? 1 : 0);
 
             // set uniforms and draw
             const uniformLocation = (name)=>glUniformLocation(postProcess.shader, name);
@@ -205,6 +219,14 @@ class PostProcessPlugin
             glContext.uniform1i(uniformLocation('iChannel2'), 2);
             glContext.uniform1f(uniformLocation('iTime'), time);
             glContext.uniform3f(uniformLocation('iResolution'), mainCanvas.width, mainCanvas.height, 1);
+            for (const name in postProcess.values)
+            {
+                const value = postProcess.values[name], location = uniformLocation(name);
+                if (isArray(value))
+                    [, , glContext.uniform2fv, glContext.uniform3fv, glContext.uniform4fv][value.length]?.call(glContext, location, value);
+                else
+                    glContext.uniform1f(location, value);
+            }
             glContext.drawArrays(glContext.TRIANGLE_STRIP, 0, 4);
 
             if (feedbackTexture)
@@ -254,24 +276,40 @@ class PostProcessPlugin
 
 ///////////////////////////////////////////////////////////////////////////////
 
+// what the shader declares of the game's values, each name and its length, so a value that changes either makes the
+// shader again
+const postProcessValueKey = (values)=> Object.entries(values).map(([name, v])=> name + ':' + (isArray(v) ? v.length : 1)).join();
+
 // 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)
+// sceneDepth(uv), the distance from the camera along its view in world units, uv 0 to 1 across the screen; and a
+// uniform for each of the game's values, a float or a vector of the list's length
+function postProcessFragmentSource(shaderCode, values={})
 {
+    let declared = '';
+    for (const name in values)
+    {
+        const value = values[name], length = isArray(value) ? value.length : 1;
+        ASSERT(postProcessNameCheck(name), 'a postProcess value needs a name GLSL takes that the shader does not use', name);
+        ASSERT(!isArray(value) || length >= 2 && length <= 4, 'a postProcess value is a number or 2 to 4 of them', name);
+        declared += `uniform ${length > 1 ? 'vec' + length : 'float'} ${name};`;
+    }
     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 highp sampler2D iChannel2;'+ // the 3D depth, when render3D.depthTexture is on, highp or it is 11 bits
         '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
+        declared +                       // the game's own values
         '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);}'+
+        'return iDepthRange.z>0.?(d*(f-n)+f+n)/2.:f>0.?2.*n*f/(f+n-d*(f-n)):2.*n/max(1.-d,1e-7);}'+
+        // whether there is depth to read: a range of all 0 is none, an orthographic near plane may be behind
+        '\n#define LJS_HAS_DEPTH (iDepthRange != vec3(0))\n'+ // a define needs a line of its own
         '\n' + shaderCode + '\n'+        // insert custom shader code
         'void main(){'+                  // shader entry point
         'mainImage(c,gl_FragCoord.xy);'+ // call post process function
@@ -282,9 +320,10 @@ function postProcessFragmentSource(shaderCode)
 /**
  * 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
- * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
- * @param {number} [strength] - How much glow to add
- * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes
+ * @param {number|string} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+ * @param {number|string} [strength] - How much glow to add
+ * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes, so a
+ *   number and not a value's name
  * @return {string}
  * @memberof PostProcess
  */
@@ -295,8 +334,8 @@ function postProcessBloomShader(threshold=.6, strength=1, size=6)
 
 /**
  * Set up post processing with a bloom effect, so bright colors and lights glow
- * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
- * @param {number} [strength] - How much glow to add
+ * @param {number|string} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+ * @param {number|string} [strength] - How much glow to add
  * @param {number} [size] - How far the glow spreads in pixels
  * @param {boolean} [includeMainCanvas] - Glow the 2D canvas too, off by default so HUD text stays crisp
  *   (a HUD drawn with WebGL in gameRenderPost glows either way, draw it with useWebGL=false)
@@ -314,7 +353,32 @@ function postProcessBloom(threshold=.6, strength=1, size=6, includeMainCanvas=fa
 // its pixel; one that bends uv or samples the frame, the curve, chromatic and glow, goes before the ones that shade
 
 // a number as GLSL writes it, a float with a point
-const postProcessNumber = (n)=> (ASSERT(isNumber(n), 'effect settings must be numbers', n), n.toFixed(4));
+// an effect setting: a number written into the code, or the name of a postProcess value, read from it each frame
+const postProcessNumber = (n)=> typeof n === 'string' ?
+    (ASSERT(postProcessNameCheck(n), 'an effect setting is a number or the name of a postProcess value', n), n) :
+    (ASSERT(isNumber(n) && isFinite(n), 'an effect setting is a finite number or the name of a postProcess value', n),
+        n && abs(n) < .01 ? String(n) : n.toFixed(4)); // a small one keeps its digits, as 1.5e-7 or 0.00015
+
+// a GLSL name for a value or a setting, which no part of the shader uses already: not the engine's own, i and a
+// capital, nor those of mainImage or an effect's own locals, which start with an underscore, nor a GLSL word
+const postProcessGLSLWords = new Set(('c uv p sceneDepth mainImage main ' +
+    // keywords and reserved words
+    'attribute const uniform varying layout centroid flat smooth noperspective patch sample break continue do for ' +
+    'while switch case default if else subroutine in out inout float double int void bool true false invariant ' +
+    'precise discard return lowp mediump highp precision struct common partition active asm class union enum ' +
+    'typedef template this resource goto inline noinline public static extern external interface long short half ' +
+    'fixed unsigned superp input output filter sizeof cast namespace using coherent volatile restrict readonly ' +
+    'writeonly atomic_uint uint mat2 mat3 mat4 vec2 vec3 vec4 ivec2 ivec3 ivec4 bvec2 bvec3 bvec4 uvec2 uvec3 uvec4 ' +
+    // built in functions
+    'radians degrees sin cos tan asin acos atan sinh cosh tanh asinh acosh atanh pow exp log exp2 log2 sqrt ' +
+    'inversesqrt abs sign floor trunc round roundEven ceil fract mod modf min max clamp mix step smoothstep isnan ' +
+    'isinf length distance dot cross normalize faceforward reflect refract matrixCompMult outerProduct transpose ' +
+    'determinant inverse lessThan lessThanEqual greaterThan greaterThanEqual equal notEqual any all not textureSize ' +
+    'texture textureProj textureLod textureOffset texelFetch texelFetchOffset textureProjOffset textureLodOffset ' +
+    'textureProjLod textureProjLodOffset textureGrad textureGradOffset textureProjGrad textureProjGradOffset dFdx ' +
+    'dFdy fwidth').split(' '));
+const postProcessNameCheck = (name)=> /^[A-Za-z][A-Za-z0-9_]*$/.test(name) && !name.includes('__') &&
+    !/^(i[A-Z]|gl_|webgl_|GL_|mat[2-4]|[dfh]vec[2-4]|[iu]?(sampler|image)([123]D|Cube|Buffer|External))/.test(name) && !postProcessGLSLWords.has(name);
 
 /**
  * Join effects into one post process shader, in the order given, for PostProcessPlugin or setShaderCode
@@ -339,15 +403,16 @@ function postProcessEffects(...effects)
 
 /**
  * Bright parts glow, the bloom as an effect to join with others; postProcessBloom sets up bloom on its own
- * @param {number} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
- * @param {number} [strength] - How much glow to add
- * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes
+ * @param {number|string} [threshold] - Brightness where the glow starts, 0 is everything and 1 is only pure white
+ * @param {number|string} [strength] - How much glow to add
+ * @param {number} [size] - How far the glow spreads in pixels, which also sets how many samples it takes, so a
+ *   number and not a value's name
  * @return {string}
  * @memberof PostProcess
  */
 function postProcessGlow(threshold=.6, strength=1, size=6)
 {
-    ASSERT(isNumber(threshold) && isNumber(strength) && isNumber(size), 'glow settings must be numbers');
+    ASSERT(isNumber(size), 'glow size is a number, it sets how many samples the glow takes');
     ASSERT(size > 0, 'glow size must be above zero');
     ASSERT(size <= 32, 'a glow this wide takes a sample every few pixels of every ring, which is hundreds of samples a pixel', size);
 
@@ -365,21 +430,22 @@ function postProcessGlow(threshold=.6, strength=1, size=6)
         const count = max(5 + 2 * j, round(2 * radius)) | 1;
         taps += count;
         code += `
-        for (int k = 0; k < ${count}; ++k)
+        for (int _k = 0; _k < ${count}; ++_k)
         {
-            float a = float(k) * ${(2 * PI / count).toFixed(7)}${j ? ' + ' + (j * 2.3999632).toFixed(7) : ''};
-            glow += max(vec3(0), texture(iChannel0, uv + vec2(cos(a), sin(a)) * ${radius.toFixed(4)} / iResolution.xy).rgb - ${threshold.toFixed(4)});
+            float _a = float(_k) * ${(2 * PI / count).toFixed(7)}${j ? ' + ' + (j * 2.3999632).toFixed(7) : ''};
+            _glow += max(vec3(0), texture(iChannel0, uv + vec2(cos(_a), sin(_a)) * ${radius.toFixed(4)} / iResolution.xy).rgb - ${postProcessNumber(threshold)});
         }`;
     }
     return `        // glow
-        vec3 glow = vec3(0);${code}
-        c.rgb += glow * ${(strength / taps).toFixed(6)};`;
+        vec3 _glow = vec3(0);${code}
+        c.rgb += _glow * ${typeof strength === 'string' ? postProcessNumber(strength) + ' / ' + taps + '.' :
+            (strength / taps).toFixed(6)};`; // a number as before, a value's name divided in the shader
 }
 
 /**
  * Scan lines across the screen, like an old TV
- * @param {number} [strength] - How dark the lines are, and how bright between them
- * @param {number} [spacing] - Pixels from one line to the next
+ * @param {number|string} [strength] - How dark the lines are, and how bright between them
+ * @param {number|string} [spacing] - Pixels from one line to the next
  * @return {string}
  * @memberof PostProcess
  */
@@ -391,66 +457,130 @@ function postProcessScanlines(strength=.5, spacing=6)
 
 /**
  * Static noise over the picture, changing every frame
- * @param {number} [strength] - How bright the static is
- * @param {number} [size] - Size of a speck in pixels
+ * @param {number|string} [strength] - How bright the static is
+ * @param {number|string} [size] - Size of a speck in pixels
  * @return {string}
  * @memberof PostProcess
  */
 function postProcessNoise(strength=.1, size=2)
 {
     return `        // noise
-        vec2 q = fract((floor(p / ${postProcessNumber(size)}) + mod(iTime * 500., 1e3)) * .3197);
-        c.rgb += ${postProcessNumber(strength)} * fract(1. + sin(51. * q.x + 73. * q.y) * 13753.3);`;
+        vec2 _q = fract((floor(p / ${postProcessNumber(size)}) + mod(iTime * 500., 1e3)) * .3197);
+        c.rgb += ${postProcessNumber(strength)} * fract(1. + sin(51. * _q.x + 73. * _q.y) * 13753.3);`;
 }
 
 /**
  * Darken toward the edges and corners
- * @param {number} [strength] - How dark the corners get, 1 is black
- * @param {number} [falloff] - How far in it reaches, low darkens most of the screen, high only the corners
+ * @param {number|string} [strength] - How dark the corners get, 1 is black
+ * @param {number|string} [falloff] - How far in it reaches, low darkens most of the screen, high only the corners
  * @return {string}
  * @memberof PostProcess
  */
 function postProcessVignette(strength=1, falloff=3)
 {
     return `        // vignette
-        vec2 d = uv * 2. - 1.;
-        c.rgb *= 1. - ${postProcessNumber(strength)} * min(1., pow(dot(d, d) / 2., ${postProcessNumber(falloff)}));`;
+        vec2 _d = uv * 2. - 1.;
+        c.rgb *= 1. - ${postProcessNumber(strength)} * min(1., pow(dot(_d, _d) / 2., ${postProcessNumber(falloff)}));`;
 }
 
 /**
  * Bend the picture like the bulged glass of an old TV, black past the corners; put it first
- * @param {number} [strength] - How much it bends
+ * @param {number|string} [strength] - How much it bends
  * @return {string}
  * @memberof PostProcess
  */
 function postProcessCurve(strength=.1)
 {
     return `        // curve
-        vec2 d = uv * 2. - 1.;
-        d *= 1. + ${postProcessNumber(strength)} * dot(d, d);
-        uv = d * .5 + .5;
-        c = all(lessThan(abs(d), vec2(1))) ? texture(iChannel0, uv) : vec4(0, 0, 0, 1);`;
+        vec2 _d = uv * 2. - 1.;
+        _d *= 1. + ${postProcessNumber(strength)} * dot(_d, _d);
+        uv = _d * .5 + .5;
+        c = all(lessThan(abs(_d), vec2(1))) ? texture(iChannel0, uv) : vec4(0, 0, 0, 1);`;
 }
 
 /**
  * Split red and blue apart toward the edges, like a cheap lens; put it before what shades the picture
- * @param {number} [strength] - How far apart at the edge, as a part of the screen
+ * @param {number|string} [strength] - How far apart at the edge, as a part of the screen
  * @return {string}
  * @memberof PostProcess
  */
 function postProcessChromatic(strength=.005)
 {
     return `        // chromatic
-        vec2 d = (uv - .5) * ${postProcessNumber(strength)} * 2.;
-        c.r = texture(iChannel0, uv + d).r;
-        c.b = texture(iChannel0, uv - d).b;`;
+        vec2 _d = (uv - .5) * ${postProcessNumber(strength)} * 2.;
+        c.r = texture(iChannel0, uv + _d).r;
+        c.b = texture(iChannel0, uv - _d).b;`;
+}
+
+// a blur's widest is 32 pixels, past which its 24 taps sit far enough apart to show; a value's is the game's to keep
+const postProcessBlurCheck = (blur)=>
+    ASSERT(typeof blur === 'string' || blur <= 32, 'a blur of more than 32 pixels shows its taps as copies', blur);
+
+// a blur over a disc of radius _r pixels around uv, of 24 taps spread evenly by the golden angle; weight, when given,
+// is GLSL for how much a tap at _puv, _s of the radius out, counts, from 0 to 1
+function postProcessDiscBlur(weight)
+{
+    return `
+        vec3 _sum = vec3(0);
+        float _total = 0.;
+        for (int _k = 0; _k < 24; ++_k)
+        {
+            float _s = sqrt((float(_k) + .5) / 24.), _a = float(_k) * 2.39996;
+            vec2 _puv = uv + vec2(cos(_a), sin(_a)) * _s * _r / iResolution.xy;
+            float _w = ${weight || '1.'};
+            _sum += texture(iChannel0, _puv).rgb * _w;
+            _total += _w;
+        }
+        c.rgb = _total > 0. ? _sum / _total : c.rgb;`;
+}
+
+/**
+ * Keep a band across the screen sharp and blur the picture above and below it, as a tilt shift lens does, which
+ * makes a scene look like a small model; it reads only the screen, so it works in 2D and 3D; put it first
+ * @param {number|string} [focus] - Height of the middle of the sharp band, 0 the bottom of the screen and 1 the top
+ * @param {number|string} [size] - Height of the sharp band, as a part of the screen
+ * @param {number|string} [blur] - Widest blur in pixels, reached half the screen past the band, at most 32
+ * @return {string}
+ * @memberof PostProcess
+ * @example
+ * new PostProcessPlugin(postProcessEffects(postProcessTiltShift(.4, .2, 10), postProcessVignette(.5)));
+ */
+function postProcessTiltShift(focus=.5, size=.25, blur=8)
+{
+    postProcessBlurCheck(blur);
+    const n = postProcessNumber;
+    return `        // tilt shift
+        float _r = ${n(blur)} * smoothstep(0., .5, abs(uv.y - ${n(focus)}) - ${n(size)} * .5);${postProcessDiscBlur()}`;
+}
+
+/**
+ * Keep what is a distance from the camera sharp and blur what is nearer or farther, as a camera lens does; needs
+ * render3D.depthTexture on, and blurs 3D only, 2D draws having no depth; put it first
+ * - What is in focus stays sharp at its edges: a blur in front of or behind it leaves out what is in focus
+ * @param {number|string} [focus] - Distance from the camera, along its view, that is sharpest, in world units
+ * @param {number|string} [range] - How deep the sharp part is; the blur grows over as far again past it
+ * @param {number|string} [blur] - Widest blur in pixels, at most 32
+ * @return {string}
+ * @memberof PostProcess
+ * @example
+ * render3D.depthTexture = true;
+ * new PostProcessPlugin(postProcessEffects(postProcessDepthOfField(10, 4, 8)));
+ */
+function postProcessDepthOfField(focus=10, range=4, blur=8)
+{
+    postProcessBlurCheck(blur);
+    const n = postProcessNumber;
+    const amount = (depth)=> `${n(blur)} * smoothstep(0., ${n(range)}, abs(${depth} - ${n(focus)}) - ${n(range)} * .5)`;
+    // a tap counts as far as its own blur reaches back to here, so a sharp thing in front is not smeared over
+    return `        // depth of field, none where there is no depth, as with render3D.depthTexture off
+        float _r = LJS_HAS_DEPTH ? ${amount('sceneDepth(uv)')} : 0.;${postProcessDiscBlur(`clamp(${amount('sceneDepth(_puv)')} - _s * _r + 1., 0., 1.)`)}`;
 }
 
 /**
  * Draw lines where the 3D depth jumps, around objects and along their creases; needs render3D.depthTexture on
  * @param {Color} [color] - The lines' color, its alpha how strong they are
- * @param {number} [thickness] - How wide the lines are in pixels
- * @param {number} [threshold] - How big a jump makes a line, as a part of the distance, lower draws more
+ * @param {number|string} [thickness] - How wide the lines are in pixels
+ * @param {number|string} [threshold] - How big a jump makes a line, as a part of the distance, lower draws more
  * @return {string}
  * @memberof PostProcess
  */
@@ -459,24 +589,25 @@ function postProcessOutline(color=BLACK, thickness=1, threshold=.02)
     ASSERT(isColor(color), 'outline color must be a Color');
     const n = postProcessNumber;
     return `        // outline
-        vec2 o = ${n(thickness)} / iResolution.xy;
-        float d = sceneDepth(uv);
-        float dx = abs(sceneDepth(uv + vec2(o.x, 0)) + sceneDepth(uv - vec2(o.x, 0)) - 2. * d);
-        float dy = abs(sceneDepth(uv + vec2(0, o.y)) + sceneDepth(uv - vec2(0, o.y)) - 2. * d);
-        vec4 line = vec4(${n(color.r)}, ${n(color.g)}, ${n(color.b)}, ${n(color.a)});
-        c.rgb = mix(c.rgb, line.rgb, line.a * step(${n(threshold)}, max(dx, dy) / d));`;
+        vec2 _o = ${n(thickness)} / iResolution.xy;
+        float _d = sceneDepth(uv);
+        float _dx = abs(sceneDepth(uv + vec2(_o.x, 0)) + sceneDepth(uv - vec2(_o.x, 0)) - 2. * _d);
+        float _dy = abs(sceneDepth(uv + vec2(0, _o.y)) + sceneDepth(uv - vec2(0, _o.y)) - 2. * _d);
+        vec4 _line = vec4(${n(color.r)}, ${n(color.g)}, ${n(color.b)}, ${n(color.a)});
+        if (LJS_HAS_DEPTH)
+            c.rgb = mix(c.rgb, _line.rgb, _line.a * step(${n(threshold)}, max(_dx, _dy) / max(abs(_d), 1e-6)));`;
 }
 
 /**
  * The look of an old TV, as one effect to use alone or join with others: static noise, scan lines, a soft glow and
  * a vignette, and a bulged screen when curve is set; any setting at 0 leaves that part out
  * @param {Object} [settings]
- * @param {number} [settings.noise] - Static noise strength
- * @param {number} [settings.scanlines] - Scan line strength
- * @param {number} [settings.scanlineSpacing] - Pixels from one scan line to the next
- * @param {number} [settings.glow] - Soft glow strength
- * @param {number} [settings.vignette] - Vignette strength
- * @param {number} [settings.curve] - How much the screen bulges, 0 by default for flat
+ * @param {number|string} [settings.noise] - Static noise strength
+ * @param {number|string} [settings.scanlines] - Scan line strength
+ * @param {number|string} [settings.scanlineSpacing] - Pixels from one scan line to the next
+ * @param {number|string} [settings.glow] - Soft glow strength
+ * @param {number|string} [settings.vignette] - Vignette strength
+ * @param {number|string} [settings.curve] - How much the screen bulges, 0 by default for flat
  * @return {string}
  * @example
  * new PostProcessPlugin(postProcessEffects(postProcessTV({scanlines: .4, curve: .1})));

package/plugins/render3d.js

@@ -706,7 +706,8 @@ class Render3DPlugin
         this.streamCount = 0;
         /** @type {TextureInfo|undefined} */
         this.streamTileInfo = undefined;
-        this.streamState = undefined; // captured state the pending batch was drawn under
+        /** @type {Object|undefined} */
+        this.streamState = undefined; // captured state the pending batch was drawn under, render3DCaptureBatchState's
         this.streamUnlit = false;     // the pending batch is drawn unlit whatever that state says, billboards are
         /** @type {Mesh|undefined} */
         this.capture = undefined;     // the mesh a bake is filling
@@ -1671,7 +1672,7 @@ const RENDER3D_VERTEX_SOURCE =
     'gl_Position=viewProj*w;' +
     'P=w.xyz;' +
     'vec3 c0=m0.xyz,c1=m1.xyz,c2=m2.xyz;' +
-    'N=mat3(c0/dot(c0,c0),c1/dot(c1,c1),c2/dot(c2,c2))*n;' +
+    'N=mat3(c0/max(dot(c0,c0),1e-20),c1/max(dot(c1,c1),1e-20),c2/max(dot(c2,c2),1e-20))*n;' +
     'T=uvRect.xy+t*uvRect.zw;' +
     'L=t;' +
     'C=c*tint;' +
@@ -1793,7 +1794,7 @@ function render3DFragmentSource(fragmentCode)
         // shadow does not dim it
         'if(materialParams.z>0.){' +
         'vec3 w=normalize(P-cameraPos),q=reflect(w,n);' +
-        'float f=materialParams.z+(1.-materialParams.z)*pow(1.-max(dot(n,-w),0.),5.);' +
+        'float f=materialParams.z+(1.-materialParams.z)*pow(clamp(1.-dot(n,-w),0.,1.),5.);' +
         'c.rgb=mix(c.rgb,q.y>0.?mix(skyHorizon.rgb,skyTop.rgb,q.y):mix(skyHorizon.rgb,skyBottom.rgb,-q.y),f);' +
         '}}else c.rgb*=e;' + // fully emissive: its own color, or brighter, with no lighting to work out
         // the emissive map adds its light on top, lit or not
@@ -1810,7 +1811,8 @@ function render3DFragmentSource(fragmentCode)
 function render3DShaderProgram(shader)
 {
     ASSERT(shader instanceof Shader, 'render3D.shader must be a Shader, not the snippet itself');
-    return shader.program3D ||= glCreateProgram(RENDER3D_VERTEX_SOURCE, render3DFragmentSource(shader.fragmentCode));
+    const program = shader.program3D ||= glCreateProgram(RENDER3D_VERTEX_SOURCE, render3DFragmentSource(shader.fragmentCode));
+    return glFailedPrograms.has(program) ? render3D.program : program; // one that did not build draws as with none
 }
 
 // make a program current for the pass and send it the pass uniforms: the matrices, the camera and the lights,
@@ -2035,7 +2037,7 @@ function render3DSetMaterialUniforms(state)
 {
     const r = render3D, loaded = (map)=> render3DTextureOf(map)?.glTexture ? map : undefined;
     const normalMap = state.normalScale ? loaded(state.normalMap) : undefined, emissiveMap = loaded(state.emissiveMap);
-    render3DUniform4f('materialParams', normalMap ? state.normalScale : 0, state.shininess, state.reflectivity, 0);
+    render3DUniform4f('materialParams', normalMap ? state.normalScale : 0, max(state.shininess, 1e-3), state.reflectivity, 0);
     const ec = state.emissiveMapColor || WHITE;
     emissiveMap ? render3DUniform4f('emissiveTint', ec.r, ec.g, ec.b, 1) : render3DUniform4f('emissiveTint', 0, 0, 0, 0);
     render3DBindMap(2, normalMap, state);
@@ -2191,7 +2193,7 @@ function render3DSetDrawUniforms(matrix, tileInfo, tint, uvRect, state=render3D)
     // its alpha says whether the ground color is on
     gc ? render3DUniform4f('ambientGround', gc.r, gc.g, gc.b, 1) : render3DUniform4f('ambientGround', 0, 0, 0, 0);
 
-    render3DUniform4f('fogColor', fc.r, fc.g, fc.b, r.fogStart);
+    render3DUniform4f('fogColor', fc.r, fc.g, fc.b, r.fogEnd ? min(r.fogStart, r.fogEnd - 1e-3) : r.fogStart);
     // how the fragment shader finishes: 1 drops see through texels and keeps the draw opaque,
     // 0 blends them away instead, and -1 is additive, which has to fade into fog differently
     const blendMode = state.blend ? (state.additive ? -1 : 0) : 1;

package/plugins/render3dEditor.js

@@ -1261,7 +1261,7 @@ function editor3DPrefabHolds(type, name, depth=0)
         !!level3DPrefabs.get(type)?.objects.some((o)=> editor3DPrefabHolds(o.type, name, depth + 1));
 }
 
-// make the selected objects a prefab of the level's own, about the bottom centre of their box, and put one
+// make the selected objects a prefab of the level's own, about the bottom center of their box, and put one
 // instance of it where they were, as one undo; a name the level's prefabs have replaces that prefab, and every
 // instance of it changes; true, or why not, which the panel shows
 function editor3DMakePrefab(name='')
@@ -1280,7 +1280,7 @@ function editor3DMakePrefab(name='')
     if (selected.some((o)=> editor3DPrefabHolds(o.type, name)))
         return refuse(name + ' can not hold itself');
 
-    // its origin is the bottom centre of the selection, so an instance stands on the ground
+    // its origin is the bottom center of the selection, so an instance stands on the ground
     const low = vec3(Infinity), high = vec3(-Infinity);
     for (const object of selected)
         editor3DWorldBox(object, low, high);
@@ -1489,7 +1489,7 @@ function editor3DPrefabEnter(id)
 // no prefab is open
 function editor3DPrefabBack()
 {
-    const frame = editor3DPrefabStack.pop(), edited = editor3DLevel;
+    const frame = editor3DPrefabStack.pop();
     if (!frame) return false;
     editor3DStrokeEnd();
     editor3DDrag = editor3DHover = undefined;

package/plugins/render3dExtras.js

@@ -1921,7 +1921,11 @@ async function loadOBJ(url, smooth=render3D?.smoothShading)
     const response = await fetch(url);
     if (!response.ok)
         throw new Error('loadOBJ failed: ' + url);
-    return parseOBJ(await response.text(), smooth);
+    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' +
+        (loadIsWebPage(text) ? ', it is a web page, so the path may be wrong' : ''));
+    return mesh;
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2092,8 +2096,22 @@ function render3DCSGNear(polygons, polygonsOther)
     const near = [], far = [];
     const faces = [[vec3(1, 0, 0), hi.x], [vec3(-1, 0, 0), -lo.x], [vec3(0, 1, 0), hi.y],
         [vec3(0, -1, 0), -lo.y], [vec3(0, 0, 1), hi.z], [vec3(0, 0, -1), -lo.z]];
+    const e = RENDER3D_CSG_EPSILON;
     for (const polygon of polygons)
     {
+        // wholly beyond a face, as most of a mesh cut many times is, it is far as it is: splitting it at the faces
+        // before would only cut it into parts that all end up far too
+        let x0 = Infinity, y0 = Infinity, z0 = Infinity, x1 = -Infinity, y1 = -Infinity, z1 = -Infinity;
+        for (const {pos} of polygon.vertices)
+        {
+            x0 = min(x0, pos.x); y0 = min(y0, pos.y); z0 = min(z0, pos.z);
+            x1 = max(x1, pos.x); y1 = max(y1, pos.y); z1 = max(z1, pos.z);
+        }
+        if (x0 > hi.x + e || x1 < lo.x - e || y0 > hi.y + e || y1 < lo.y - e || z0 > hi.z + e || z1 < lo.z - e)
+        {
+            far.push(polygon);
+            continue;
+        }
         let inside = [polygon];
         for (const [normal, w] of faces)
         {
@@ -2249,7 +2267,6 @@ function render3DCSGMesh(polygons)
     };
 
     // each loop with the points along its edges put in, as a fan
-    const flat = (a, b, c)=> b.subtract(a).cross(c.subtract(a)).lengthSquared() < 1e-18;
     for (const loop of loops)
     {
         if (loop.length < 3) continue;

package/plugins/render3dLevel.js

@@ -15,6 +15,16 @@
 
 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
+ *  @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 +43,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
@@ -87,7 +97,7 @@ function level3DAddMesh(name, mesh, tileInfo, color=WHITE)
  *    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
+ *  @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)
@@ -420,7 +430,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 +469,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]},