littlejsengine 1.20.0 → 1.22.0

package/src/engineParticles.js

@@ -165,6 +165,13 @@ class ParticleEmitter extends EngineObject
         this.localSpace        = localSpace;
         /** @property {number} - If non zero the particle is drawn as a trail, stretched in the direction of velocity */
         this.trailScale        = 0;
+        /** @property {number} - Grows the whole effect as each particle is born: the spawn area, the particles' sizes,
+         *  speed and fall, so it looks the same only bigger; 1 is as made, and a particle keeps the scale it was born
+         *  with, so a change never moves the ones already out */
+        this.scale             = 1;
+        /** @property {number} - The effect's own fall, added to each particle's velocity y every frame, on top of the
+         *  world's gravity times gravityScale; an effect that sets its own looks the same in any game */
+        this.gravity           = 0;
         /** @property {ParticleCallback|undefined} - Callback when particle is created
          *  @type {ParticleCallback|undefined} */
         this.particleCreateCallback = undefined;
@@ -251,9 +258,9 @@ class ParticleEmitter extends EngineObject
         {
             // show emitter bounds
             if (this.emitCircle)
-                debugCircle(this.pos, this.emitSize.x, '#0f0', 0, false, false);
+                debugCircle(this.pos, this.emitSize.x * this.scale, '#0f0', 0, false, false);
             else
-                debugRect(this.pos, this.emitSize, '#0f0', 0, this.angle, false, false);
+                debugRect(this.pos, this.emitSize.scale(this.scale), '#0f0', 0, this.angle, false, false);
         }
     }
 
@@ -262,10 +269,11 @@ class ParticleEmitter extends EngineObject
     emitParticle()
     {
         // spawn a particle
+        const scale = this.scale; // grows the spawn area, the sizes and the speed of each particle born
         let pos = this.emitCircle ?            // check if circle emitter
-            randInCircle(this.emitSize.x/2)    // circle emitter
-            : vec2(rand(-.5,.5), rand(-.5,.5)) // box emitter
-                .multiply(this.emitSize);
+            randInCircle(this.emitSize.x/2 * scale) // circle emitter
+            : vec2(rand(-.5,.5) * this.emitSize.x * scale, // box emitter, one vector made
+                rand(-.5,.5) * this.emitSize.y * scale);
         let angle = rand(this.particleConeAngle, -this.particleConeAngle);
         if (!this.localSpace)
         {
@@ -282,9 +290,9 @@ class ParticleEmitter extends EngineObject
 
         // randomize particle settings
         const particleTime  = randomizeScale(this.particleTime);
-        const sizeStart     = randomizeScale(this.sizeStart);
-        const sizeEnd       = randomizeScale(this.sizeEnd);
-        const speed         = randomizeScale(this.speed);
+        const sizeStart     = randomizeScale(this.sizeStart) * scale;
+        const sizeEnd       = randomizeScale(this.sizeEnd) * scale;
+        const speed         = randomizeScale(this.speed) * scale;
         const angleSpeed    = randomizeScale(this.angleSpeed) * randSign();
         const coneAngle     = rand(this.emitConeAngle, -this.emitConeAngle);
         const colorStart    = randColor(this.colorStartA, this.colorStartB, this.randomColorLinear);
@@ -318,9 +326,13 @@ class ParticleEmitter extends EngineObject
     render()
     {
         // render all particles, the blend switched once for them all, not around each one
+        // and the tile's draw worked out once for them all, fresh each frame so a tile changed in place draws changed
         this.additive && setAdditiveBlendMode();
+        particleTile = null; // none yet, undefined is the untextured tile
+        particleTileBatch = true;
         for (const particle of this.particles)
             particle.render();
+        particleTileBatch = false;
         this.additive && setAdditiveBlendMode(false);
     }
 
@@ -347,6 +359,39 @@ class ParticleEmitter extends EngineObject
 // scratch vectors reused by Particle.render and the tile collision to avoid per-frame allocations
 const particleDrawPos = new Vector2, particleDrawSize = new Vector2, particleCollidePos = new Vector2;
 
+// the WebGL draw of the tile particles draw with, what drawTile works out for each sprite: kept while an emitter
+// renders its particles, so each one only writes its own values into the batch
+let particleTile, particleTileBatch = false, particleTileTextured = false, particleTileEmpty = false;
+let particleTileU0 = 0, particleTileV0 = 0, particleTileU1 = 0, particleTileV1 = 0;
+function particleTileSet(tileInfo)
+{
+    particleTile = tileInfo;
+    const textureInfo = tileInfo?.textureInfo;
+    particleTileTextured = !!textureInfo;
+    particleTileEmpty = !!textureInfo && !(tileInfo.size.x && tileInfo.size.y); // like a sprite still loading
+    if (!textureInfo || particleTileEmpty) return;
+
+    ASSERT(!!textureInfo.glTexture, 'texture has no WebGL texture, draw it with useWebGL false');
+    glSetTexture(textureInfo.glTexture); // bound, and its mipmaps brought up to date, once for the emitter
+    const sizeInverse = textureInfo.sizeInverse, bleed = tileInfo.bleed;
+    const x = tileInfo.pos.x * sizeInverse.x;
+    const y = tileInfo.pos.y * sizeInverse.y;
+    const w = tileInfo.size.x * sizeInverse.x;
+    const h = tileInfo.size.y * sizeInverse.y;
+    if (bleed)
+    {
+        const bleedX = sizeInverse.x*bleed;
+        const bleedY = sizeInverse.y*bleed;
+        particleTileU0 = x + bleedX;     particleTileV0 = y + bleedY;
+        particleTileU1 = x - bleedX + w; particleTileV1 = y - bleedY + h;
+    }
+    else
+    {
+        particleTileU0 = x;     particleTileV0 = y;
+        particleTileU1 = x + w; particleTileV1 = y + h;
+    }
+}
+
 // tests if a particle collides with tiles at x, y, through its emitter's collide callback if it has one
 function particleCollideTest(particle, collideCallback, x, y)
 {
@@ -382,6 +427,8 @@ class Particle
     {
         /** @property {ParticleEmitter} - The emitter this particle came from */
         this.emitter = emitter;
+        /** @property {number} - The emitter's scale when it was made, which grows its fall */
+        this.scale = emitter.scale ?? 1; // a hand made emitter-like object may have none
         /** @property {Vector2} - Position, world space or local to the emitter when localSpace is set */
         this.pos = pos;
         /** @property {number} - Angle in radians */
@@ -444,7 +491,10 @@ class Particle
         // apply physics; only the tile collision needs where the particle was
         const solve = enablePhysicsSolver && collideLevel;
         const oldX = this.pos.x, oldY = this.pos.y;
-        let gravityX = gravity.x * gravityScale, gravityY = gravity.y * gravityScale;
+        // the world's gravity times gravityScale plus the emitter's own, grown by the particle's scale
+        const fall = this.scale;
+        let gravityX = gravity.x * gravityScale * fall;
+        let gravityY = (gravity.y * gravityScale + (emitter.gravity || 0)) * fall;
         if (emitter.localSpace && emitter.angle)
         {
             // world gravity turned into the emitter's space, the render turns it back
@@ -498,7 +548,9 @@ class Particle
                 }
                 if (isBlockedY || !isBlockedX)
                 {
-                    const wasFalling = this.velocity.y < 0 && gravity.y < 0 || this.velocity.y > 0 && gravity.y > 0;
+                    // down is the world's gravity, or the emitter's own fall in a world with none
+                    const down = gravity.y || emitter.gravity || 0;
+                    const wasFalling = this.velocity.y < 0 && down < 0 || this.velocity.y > 0 && down > 0;
                     if (wasFalling)
                         this.groundObject = hitLayer;
 
@@ -577,7 +629,24 @@ class Particle
                 angle = atan2(velocity.x, velocity.y);
             }
         }
-        drawTile(pos, size, this.tileInfo, this.color, angle, this.mirror, undefined, glEnable, false);
+        if (glEnable && !headlessMode)
+        {
+            // straight into the batch, the tile's draw worked out once for the emitter's particles
+            const tileInfo = this.tileInfo;
+            if (!particleTileBatch || tileInfo !== particleTile)
+                particleTileSet(tileInfo);
+            if (!particleTileTextured)
+                glDrawUntextured(pos.x, pos.y, size.x, size.y, angle, this.color.rgbaInt());
+            else if (!particleTileEmpty)
+            {
+                const texture = tileInfo.textureInfo.glTexture;
+                glActiveTexture === texture || glSetTexture(texture); // bound again only if a draw between changed it
+                glDraw(pos.x, pos.y, this.mirror ? -size.x : size.x, size.y, angle,
+                    particleTileU0, particleTileV0, particleTileU1, particleTileV1, this.color.rgbaInt());
+            }
+        }
+        else
+            drawTile(pos, size, this.tileInfo, this.color, angle, this.mirror, undefined, false, false);
         additive && setAdditiveBlendMode(false);
         debugParticles && debugRect(pos, size, '#f005', 0, angle, false, false);
     }

package/src/engineRelease.js

@@ -52,16 +52,28 @@ function tweak(){}
 function tweakButton(){}
 function tweakDivider(){}
 function tweakEngineDefaults(){}
-const levelEditor = {isOpen: false, open(){}, close(){}, onTile: undefined, onRestart: undefined, onPlayFrom: undefined};
+const levelEditor = {isOpen: false, open(){}, close(){}, onTile: undefined, onRestart: undefined, onPlayFrom: undefined,
+    paletteTiles: undefined, use3D: undefined};
 function editorMapRestore(map){ return map; }
 function editorMapLoaded(){}
 function editorJSONFetched(){}
 function editorPreRender(){}
 function editorObjectMade(){}
 
+// the input capture of the free camera and the 3D editor
+function inputCaptureHides(){ return false; }
+function inputCaptureMouse(){}
+function inputLockExit(){}
+
 // the 3D debug draws are debug only too
 function debugBox3D(){}
 function debugSphere3D(){}
 function debugLine3D(){}
 function debugPoint3D(){}
 function render3DRenderDebug(){}
+
+// the free camera and the 3D level editor are debug only
+function editor3DCameraBegin(){}
+function editor3DCameraEnd(){}
+function editor3DLevelLoaded(){}
+function editor3DObjectMade(){}

package/src/engineSettings.js

@@ -122,6 +122,13 @@ let fontDefault = 'arial';
  *  @memberof Settings */
 let showSplashScreen = false;
 
+/** The loading screen, drawn after the splash while the images, gameInit and what they load are loading, once that
+ *  takes more than half a second: a function given the part done, 0 to 1, or undefined for none, which leaves the
+ *  screen blank; the default says Loading over a bar
+ *  @type {LoadingScreenCallback|undefined}
+ *  @memberof Settings */
+let loadingScreen = drawLoadingScreen;
+
 /** Disables all rendering, audio, and input for servers, must be set before engineInit
  *  @type {boolean}
  *  @default
@@ -135,6 +142,15 @@ let headlessMode = false;
  *  @memberof Settings */
 let engineManualStep = false;
 
+/** Run one update per display frame with timeDelta the time it covers, in place of fixed updates at frameRate
+ *  - Per-frame values are not scaled: velocity, gravity, damping and particle speeds act once per update, so a
+ *    game that turns this on scales its own movement by timeDelta
+ *  - Values in seconds follow real time as they are: time, timers, particle emit rate and life, animation, Box2D
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let engineVariableStep = false;
+
 ///////////////////////////////////////////////////////////////////////////////
 // WebGL settings
 
@@ -530,6 +546,11 @@ function setFontDefault(font) { fontDefault = font; }
  *  @memberof Settings */
 function setShowSplashScreen(show) { showSplashScreen = show; }
 
+/** Set the loading screen, drawn after the splash while the game loads, once that takes more than half a second
+ *  @param {LoadingScreenCallback} [callback] - Draws on mainContext given the part done, 0 to 1; undefined for none
+ *  @memberof Settings */
+function setLoadingScreen(callback) { loadingScreen = callback; }
+
 /** Set to disable rendering, audio, and input for servers, must be set before engineInit
  *  @param {boolean} headless
  *  @memberof Settings */
@@ -555,6 +576,23 @@ function setEngineManualStep(enable=true)
     }
 }
 
+/** Set if the engine runs one update per display frame with timeDelta the time it covers
+ *  Can be set before engineInit or while running; turned off it goes back to fixed updates at frameRate
+ *  @param {boolean} [enable]
+ *  @memberof Settings */
+function setEngineVariableStep(enable=true)
+{
+    if (engineVariableStep && !enable)
+    {
+        // fixed time goes on one fixed step after the last update, if one ran, and timeDelta is the fixed step again
+        timeFixedStart = frame ? time + 1 / frameRate : time;
+        frameFixedStart = frame;
+        timeDelta = 1 / frameRate;
+        frameTimeBufferMS = engineManualStep ? -.5e3 / frameRate : 0;
+    }
+    engineVariableStep = enable;
+}
+
 /** Set whether the draw and debug functions draw in screen space when a call leaves screenSpace out
  *  @param {boolean} screenSpace
  *  @memberof Settings */

package/src/engineWebGL.js

@@ -26,6 +26,19 @@ let glCanvas;
  *  @memberof WebGL */
 let glContext;
 
+/** The largest texture this device makes, in pixels across, 0 until WebGL starts; at least 2048 with WebGL2
+ *  @type {number}
+ *  @memberof WebGL */
+let glMaxTextureSize = 0;
+
+/** A texture size this device can make: the size asked for, or the largest it supports when that is smaller
+ *  - The engine sizes the textures it makes itself through this, the shadow maps and the like, so a size a device
+ *    does not have falls back instead of failing
+ *  @param {number} size - Pixels across
+ *  @return {number}
+ *  @memberof WebGL */
+function glClampTextureSize(size) { return glMaxTextureSize ? min(size, glMaxTextureSize) : size; }
+
 /** Should WebGL be setup with anti-aliasing? must be set before calling engineInit
  *  @type {boolean}
  *  @memberof WebGL */
@@ -115,7 +128,7 @@ function glInit(rootElement)
     // startup webgl, and make the textures of any texture infos made before it
     initWebGL();
     for (const info of glTextureInfos)
-        info.glTexture ||= glCreateTexture(info.image, info.wrap);
+        info.glTexture ||= glCreateTexture(info.image, info.wrap, info.pixelated);
 
     // setup context lost and restore handlers
     glCanvas.addEventListener('webglcontextlost', (e)=>
@@ -155,7 +168,7 @@ function glInit(rootElement)
         glPremultipliedTextures = new WeakSet; // the tile layers draw into their new textures again below
         initWebGL();
         for (const info of glTextureInfos)
-            info.glTexture = glCreateTexture(info.image, info.wrap);
+            info.glTexture = glCreateTexture(info.image, info.wrap, info.pixelated);
         pluginList.forEach(plugin=>plugin.glContextRestored?.());
 
         // a tile layer drawn on the GPU only had its tiles in the lost texture, it draws them again
@@ -165,6 +178,8 @@ function glInit(rootElement)
 
     function initWebGL()
     {
+        glMaxTextureSize = glContext.getParameter(glContext.MAX_TEXTURE_SIZE) | 0;
+
         // setup instanced rendering shader program
         glShader = glCreateProgram(gl_VERTEX_SOURCE,
             '#version 300 es\n' +     // specify GLSL ES version
@@ -488,9 +503,10 @@ function glShaderProgram(shader)
  *  Restores the active texture when done
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} [image]
  *  @param {boolean|Array<number>} [wrap] - true for REPEAT, false for CLAMP_TO_EDGE, or the WebGL modes across and down
+ *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
  *  @return {WebGLTexture}
  *  @memberof WebGL */
-function glCreateTexture(image, wrap=false)
+function glCreateTexture(image, wrap=false, pixelated=tilesPixelated)
 {
     if (!glContext) return;
 
@@ -499,10 +515,10 @@ function glCreateTexture(image, wrap=false)
     let mipMap = false;
     if (image?.width)
     {
-        glSetTextureData(texture, image);
+        glSetTextureData(texture, image, pixelated);
         glContext.bindTexture(glContext.TEXTURE_2D, texture);
         // WebGL2 makes mipmaps at any size, a texture that becomes a render target keeps them only at powers of two
-        mipMap = !tilesPixelated;
+        mipMap = !pixelated;
         if (mipMap && !(isPowerOfTwo(image.width) && isPowerOfTwo(image.height)))
             glMipmapsUntilTarget.add(texture);
     }
@@ -515,7 +531,7 @@ function glCreateTexture(image, wrap=false)
     }
 
     // set texture filtering
-    const magFilter = tilesPixelated ? glContext.NEAREST : glContext.LINEAR;
+    const magFilter = pixelated ? glContext.NEAREST : glContext.LINEAR;
     const minFilter = mipMap ? glContext.LINEAR_MIPMAP_LINEAR : magFilter;
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MAG_FILTER, magFilter);
     glContext.texParameteri(glContext.TEXTURE_2D, glContext.TEXTURE_MIN_FILTER, minFilter);
@@ -546,8 +562,9 @@ function glDeleteTexture(texture)
 /** Set WebGL texture data from an image, restores the active texture when done
  *  @param {WebGLTexture} texture
  *  @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image
+ *  @param {boolean} [pixelated] - Hard edged or smooth, undefined follows tilesPixelated
  *  @memberof WebGL */
-function glSetTextureData(texture, image)
+function glSetTextureData(texture, image, pixelated=tilesPixelated)
 {
     if (!glContext) return;
 
@@ -565,7 +582,7 @@ function glSetTextureData(texture, image)
     }
     // smooth filtering mixes a texel with its see through neighbors, right only for premultiplied color, or the
     // edges go dark; pixel art is sampled a texel at a time, and uploads straight color as it always has
-    const premultiply = !tilesPixelated;
+    const premultiply = !pixelated;
     glContext.pixelStorei(glContext.UNPACK_PREMULTIPLY_ALPHA_WEBGL, premultiply);
     glContext.texImage2D(glContext.TEXTURE_2D, 0, glContext.RGBA, glContext.RGBA, glContext.UNSIGNED_BYTE, image);
     glContext.pixelStorei(glContext.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
@@ -596,9 +613,9 @@ function glRegisterTextureInfo(textureInfo)
 
     // create or set the texture data
     if (textureInfo.glTexture)
-        glSetTextureData(textureInfo.glTexture, textureInfo.image);
+        glSetTextureData(textureInfo.glTexture, textureInfo.image, textureInfo.pixelated);
     else
-        textureInfo.glTexture = glCreateTexture(textureInfo.image, textureInfo.wrap);
+        textureInfo.glTexture = glCreateTexture(textureInfo.image, textureInfo.wrap, textureInfo.pixelated);
 }
 
 /** Internal: tells WebGL to destroy the glTexture and stop tracking it, TextureInfo calls it