littlejsengine 1.19.3 → 1.21.0

package/src/engineRelease.js

@@ -1,45 +1,79 @@
-/**
- * LittleJS - Release Mode
- * - Replaces engineDebug.js in production builds
- * - All debug functions are stubbed out as no-ops
- * - Removes ASSERT and LOG calls to reduce file size
- * - Disables debug overlay, watermark, and visualizations
- * - Improves performance by eliminating debug overhead
- * - Significantly reduces final bundle size
- */
-
-'use strict';
-
-let debugWatermark = 0;
-let debugKey = '';
-const debug = 0;
-const debugOverlay = 0;
-const debugPhysics = 0;
-const debugParticles = 0;
-const debugRaycast = 0;
-const debugGamepads = 0;
-const debugSound = 0;
-const debugPointSize = .5;
-
-// debug commands are automatically removed from the final build
-function ASSERT          (){}
-function LOG             (){}
-function debugInit       (){}
-function debugUpdate     (){}
-function debugRender     (){}
-function debugRenderPost (){}
-function debugRect       (){}
-function debugPoly       (){}
-function debugCircle     (){}
-function debugPoint      (){}
-function debugLine       (){}
-function debugOverlap    (){}
-function debugText       (){}
-function debugClear      (){}
-function debugScreenshot (){}
-function debugShowErrors(){}
-function debugVideoCaptureIsActive(){ return false; }
-function debugVideoCaptureStart (){}
-function debugVideoCaptureStop  (){}
-function debugVideoCaptureUpdate(){}
-function debugProtectConstant(o){ return o; }
+/**
+ * LittleJS - Release Mode
+ * - Replaces engineDebug.js in production builds
+ * - All debug functions are stubbed out as no-ops
+ * - Removes ASSERT and LOG calls to reduce file size
+ * - Disables debug overlay, watermark, and visualizations
+ * - Improves performance by eliminating debug overhead
+ * - Significantly reduces final bundle size
+ */
+
+'use strict';
+
+let debugWatermark = 0;
+let debugKey = '';
+let debugKeysAlways = false;
+let debugTweakables = false;
+let debugClearCount = 0;
+const debug = 0;
+const debugOverlay = 0;
+const debugPhysics = 0;
+const debugParticles = 0;
+const debugRaycast = 0;
+const debugGamepads = 0;
+const debugSound = 0;
+const debugPointSize = .5;
+
+// debug commands are automatically removed from the final build
+function ASSERT          (){}
+function LOG             (){}
+function debugInit       (){}
+function debugUpdate     (){}
+function debugRender     (){}
+function debugRenderPost (){}
+function debugRect       (){}
+function debugPoly       (){}
+function debugCircle     (){}
+function debugPoint      (){}
+function debugLine       (){}
+function debugOverlap    (){}
+function debugText       (){}
+function debugClear      (){}
+function debugScreenshot (){}
+function debugShowErrors(){}
+function setDebugOverlay(){}
+function debugVideoCaptureIsActive(){ return false; }
+function debugVideoCaptureStart (){}
+function debugVideoCaptureStop  (){}
+function debugProtectConstant(o){ return o; }
+
+// the tweakables and the level editor are debug only
+function tweak(){}
+function tweakButton(){}
+function tweakDivider(){}
+function tweakEngineDefaults(){}
+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

@@ -32,7 +32,7 @@ let cameraScale = 32;
 
 /** Scale applied to engine time, can be used for slow motion or fast forward
  *  - 1 is normal speed, 2 is double speed, 0.5 is half speed
- *  - 0 freezes the simulation without setting the paused flag
+ *  - 0 freezes the game like a pause without setting the paused flag, gameUpdatePost and input still run
  *  - Should be >= 0; stacks multiplicatively with the debug +/- shortcut
  *  @type {number}
  *  @default
@@ -76,7 +76,6 @@ let canvasMinAspect = 0;
 let canvasMaxAspect = 0;
 
 /** Fixed size of the canvas in css pixels, if enabled canvas size never changes
- * - you may also need to set mainCanvasSize if using screen space coords in startup
  * - canvasPixelRatio still applies, it only scales the backing store
  *  @type {Vector2}
  *  @default Vector2()
@@ -92,7 +91,8 @@ let canvasPixelated = false;
 
 /** Disables texture filtering for crisper pixel art
  *  - Leave true for pixel art so sprites stay sharp when scaled (uses NEAREST filtering)
- *  - Set false for smooth/high-resolution art to enable bilinear filtering and mipmaps
+ *  - Set false for smooth/high-resolution art to enable bilinear filtering and mipmaps; those textures upload
+ *    premultiplied, so filtering does not pull dark from see through texels into the edges
  *  @type {boolean}
  *  @default
  *  @memberof Settings */
@@ -116,13 +116,20 @@ let canvasPixelRatio = 1;
  *  @memberof Settings */
 let fontDefault = 'arial';
 
-/** Enable to show the LittleJS splash screen on startup
+/** Enable to show the LittleJS splash screen on startup, must be set before engineInit
  *  @type {boolean}
  *  @default
  *  @memberof Settings */
 let showSplashScreen = false;
 
-/** Disables all rendering, audio, and input for servers
+/** 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
  *  @memberof Settings */
@@ -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
 
@@ -144,6 +160,17 @@ let engineManualStep = false;
  *  @memberof Settings */
 let glEnable = true;
 
+/** Draw in screen space by default: what the screenSpace parameter of the draw and debug functions defaults to, so a
+ *  heads up display, or a 3D game that only draws 2D on the screen, can turn it on and leave the flag out
+ *  - The engine says its own space when it draws, so objects, tile layers and particles stay in world space, but a
+ *    game's own draws follow it, a render() override included: turn it on around the hud, or pass false there
+ *  - Sizes and widths keep their defaults, which are world sized, so pass them in pixels
+ *  - drawText has no screenSpace and stays in world space, drawTextScreen is the one for the screen
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let drawScreenSpace = false;
+
 /** How many sided poly to use when drawing circles and ellipses with WebGL
  *  @type {number}
  *  @default
@@ -174,7 +201,7 @@ let tileDefaultBleed = 0;
 ///////////////////////////////////////////////////////////////////////////////
 // Object settings
 
-/** Enable physics solver for collisions between objects
+/** Enable physics solver for collisions, between objects and with tiles
  *  @type {boolean}
  *  @default
  *  @memberof Settings */
@@ -186,13 +213,13 @@ let enablePhysicsSolver = true;
  *  @memberof Settings */
 let objectDefaultMass = 1;
 
-/** How much to slow velocity by each frame (0-1)
+/** Fraction of velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @type {number}
  *  @default
  *  @memberof Settings */
 let objectDefaultDamping = 1;
 
-/** How much to slow angular velocity each frame (0-1)
+/** Fraction of angular velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @type {number}
  *  @default
  *  @memberof Settings */
@@ -204,19 +231,20 @@ let objectDefaultAngleDamping = 1;
  *  @memberof Settings */
 let objectDefaultRestitution = 0;
 
-/** How much to slow when touching (0-1)
+/** Fraction of sliding speed objects keep each frame on the ground, 1 is no friction, 0 stops at once
+ *  - The more slippery of an object and its ground is used
  *  @type {number}
  *  @default
  *  @memberof Settings */
 let objectDefaultFriction = .8;
 
-/** Clamp max speed to avoid fast objects missing collisions
+/** Clamp max speed to avoid fast objects missing collisions, in world units per frame on each axis
  *  @type {number}
  *  @default
  *  @memberof Settings */
 let objectMaxSpeed = 1;
 
-/** How much gravity to apply to objects, negative Y is down
+/** How much gravity to apply to objects, negative Y is down, in world units per frame per frame
  *  @type {Vector2}
  *  @default
  *  @memberof Settings */
@@ -252,6 +280,7 @@ let gamepadDirectionEmulateStick = true;
 let gamepadAxisFilterEnable = true;
 
 /** If true the WASD keys are also routed to the direction keys (for better accessibility)
+ *  - Turn it off for a game with two players on one keyboard, one on WASD and one on the arrows
  *  @type {boolean}
  *  @default
  *  @memberof Settings */
@@ -266,9 +295,10 @@ let touchInputEnable = true;
 
 /** True if touch gamepad should appear on mobile devices
  *  - Supports left analog stick, 4 face buttons and start button (button 9)
- *  - setTouchGamepadButtonCount(1) to use face buttons as right analog stick
+ *  - setTouchGamepadRightStick(true) for a right analog stick in place of the face buttons
  *  - Analog stick buttons 10 and 11 are also activated when virtual sticks are touched
  *  - Rendered as a full-viewport HTML/SVG overlay, so controls may sit outside the game canvas
+ *  - It is gamepad 0 once touched; a real gamepad being used takes over and hides it until the screen is touched again
  *  @type {boolean}
  *  @default
  *  @memberof Settings */
@@ -425,9 +455,14 @@ function setCameraAngle(angle) { cameraAngle = angle; }
 function setCameraScale(scale) { cameraScale = scale; }
 
 /** Set scale applied to engine time
- *  @param {number} scale
+ *  - 0 freezes the game like a pause, gameUpdatePost and input still run so the game can set it back
+ *  @param {number} scale - 0 or more
  *  @memberof Settings */
-function setTimeScale(scale) { timeScale = scale; }
+function setTimeScale(scale)
+{
+    ASSERT(scale >= 0, 'time scale must be 0 or more');
+    timeScale = max(0, scale); // a negative scale would build a debt of time the game then waits out
+}
 
 /** Set if tiles should be colorized when using canvas2d
  *  This can be slower but results should look nearly identical to WebGL rendering
@@ -476,6 +511,7 @@ function setCanvasPixelated(pixelated)
 
 /** Disables texture filtering for crisper pixel art
  *  - Leave true for pixel art; set false for smooth/high-resolution art
+ *  - Set it before engineInit, a texture already loaded keeps the filtering it was made with
  *  @param {boolean} pixelated
  *  @memberof Settings */
 function setTilesPixelated(pixelated) { tilesPixelated = pixelated; }
@@ -505,21 +541,62 @@ function getCanvasPixelRatio() { return canvasPixelRatio ?? (devicePixelRatio ||
  *  @memberof Settings */
 function setFontDefault(font) { fontDefault = font; }
 
-/** Set if the LittleJS splash screen should be shown on startup
+/** Set if the LittleJS splash screen should be shown on startup, must be set before engineInit
  *  @param {boolean} show
  *  @memberof Settings */
 function setShowSplashScreen(show) { showSplashScreen = show; }
 
-/** Set to disable rendering, audio, and input for servers
+/** 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 */
 function setHeadlessMode(headless) { headlessMode = headless; }
 
 /** Set if the engine only advances when engineStep is called
- *  Must be set before engineInit
+ *  Set before engineInit for a test or a server; turned on in a running game it stops the loop, and turned off
+ *  again it starts the loop from real time
  *  @param {boolean} [enable]
  *  @memberof Settings */
-function setEngineManualStep(enable=true) { engineManualStep = enable; }
+function setEngineManualStep(enable=true)
+{
+    const resume = engineManualStep && !enable;
+    if (enable && !engineManualStep)
+        frameTimeBufferMS = -.5e3 / frameRate; // half a frame short, so each engineStep frame runs one update,
+                                               // not one more from time the last real frame left over
+    engineManualStep = enable;
+    if (resume && engineUpdateInternal)
+    {
+        // engineStep may have run the clock ahead of real time, start from now so that is not waited out
+        frameTimeLastMS = performance.now();
+        engineScheduleFrame();
+    }
+}
+
+/** 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 */
+function setDrawScreenSpace(screenSpace) { drawScreenSpace = screenSpace; }
 
 /** Set if WebGL rendering is enabled
  *  @param {boolean} enable
@@ -556,7 +633,7 @@ function setTileDefaultPadding(padding) { tileDefaultPadding = padding; }
  *  @memberof Settings */
 function setTileDefaultBleed(bleed) { tileDefaultBleed = bleed; }
 
-/** Set if collisions between objects are enabled
+/** Set if collisions are enabled, between objects and with tiles
  *  @param {boolean} enable
  *  @memberof Settings */
 function setEnablePhysicsSolver(enable) { enablePhysicsSolver = enable; }
@@ -566,12 +643,12 @@ function setEnablePhysicsSolver(enable) { enablePhysicsSolver = enable; }
  *  @memberof Settings */
 function setObjectDefaultMass(mass) { objectDefaultMass = mass; }
 
-/** Set how much to slow velocity by each frame
+/** Set the fraction of velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @param {number} damp
  *  @memberof Settings */
 function setObjectDefaultDamping(damp) { objectDefaultDamping = damp; }
 
-/** Set how much to slow angular velocity each frame
+/** Set the fraction of angular velocity objects keep each frame, 1 keeps all of it, 0 stops at once
  *  @param {number} damp
  *  @memberof Settings */
 function setObjectDefaultAngleDamping(damp) { objectDefaultAngleDamping = damp; }
@@ -581,7 +658,7 @@ function setObjectDefaultAngleDamping(damp) { objectDefaultAngleDamping = damp;
  *  @memberof Settings */
 function setObjectDefaultRestitution(restitution) { objectDefaultRestitution = restitution; }
 
-/** Set how much to slow when touching
+/** Set the fraction of sliding speed objects keep each frame on the ground, 1 is no friction, 0 stops at once
  *  @param {number} friction
  *  @memberof Settings */
 function setObjectDefaultFriction(friction) { objectDefaultFriction = friction; }
@@ -596,7 +673,7 @@ function setObjectMaxSpeed(speed) { objectMaxSpeed = speed; }
  *  @memberof Settings */
 function setGravity(newGravity) { gravity = newGravity.copy(); }
 
-/** Set to scales emit rate of particles
+/** Set the scale for the emit rate of particles, 0 disables particle emitters
  *  @param {number} scale
  *  @memberof Settings */
 function setParticleEmitRateScale(scale) { particleEmitRateScale = scale; }
@@ -616,7 +693,7 @@ function setGamepadDirectionEmulateStick(enable) { gamepadDirectionEmulateStick
  *  @memberof Settings */
 function setGamepadAxisFilterEnable(enable) { gamepadAxisFilterEnable = enable; }
 
-/** Set if true the WASD keys are also routed to the direction keys
+/** Set if the WASD keys are also routed to the direction keys
  *  @param {boolean} enable
  *  @memberof Settings */
 function setInputWASDEmulateDirection(enable) { inputWASDEmulateDirection = enable; }
@@ -694,7 +771,7 @@ function setTouchGamepadAnalog(analog) { touchGamepadAnalog = analog; }
  *  @memberof Settings */
 function setTouchGamepadFloating(floating) { touchGamepadFloating = floating; }
 
-/** Set size of virtual gamepad for touch devices in pixels
+/** Set size of virtual gamepad for touch devices in viewport CSS pixels
  *  @param {number} size
  *  @memberof Settings */
 function setTouchGamepadSize(size) { touchGamepadSize = size; }
@@ -719,7 +796,7 @@ function setTouchGamepadVibration(ms) { touchGamepadVibration = ms; }
  *  @memberof Settings */
 function setVibrateEnable(enable) { vibrateEnable = enable; }
 
-/** Set to disable all audio code
+/** Set if audio is enabled, false turns all sound off
  *  @param {boolean} enable
  *  @memberof Settings */
 function setSoundEnable(enable) { soundEnable = enable; }
@@ -730,8 +807,7 @@ function setSoundEnable(enable) { soundEnable = enable; }
 function setSoundVolume(volume)
 {
     soundVolume = volume;
-    if (soundEnable && !headlessMode && audioMasterGain)
-        audioMasterGain.gain.value = volume; // update gain immediately
+    audioUpdateVolume(); // update gain immediately, sound off or not
 }
 
 /** Set default range where sound no longer plays
@@ -757,4 +833,14 @@ function setDebugWatermark(show) { debugWatermark = show; }
 /** Set key code used to toggle debug mode, Esc by default
  *  @param {string} key
  *  @memberof Debug */
-function setDebugKey(key) { debugKey = key; }
+function setDebugKey(key) { debugKey = key; }
+
+/** Set if the debug keys work while the overlay is closed, the number keys and the +/- time keys
+ *  @param {boolean} [enable]
+ *  @memberof Debug */
+function setDebugKeysAlways(enable=true) { debugKeysAlways = enable; }
+
+/** Set if the tweakables panel is shown, as 9 does while the debug overlay is open
+ *  @param {boolean} [show]
+ *  @memberof Debug */
+function setDebugTweakables(show=true) { debugTweakables = show; }