littlejsengine 1.18.26 → 1.18.27

package/dist/littlejs.d.ts

@@ -514,6 +514,13 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let gamepadDirectionEmulateStick: boolean;
+    /** If true, axes that do not rest near center are ignored on gamepads without
+     *  standard mapping. Steering wheels and flight sticks report pedal and throttle
+     *  axes that rest at full deflection, which otherwise reads as a stick held down.
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let gamepadAxisFilterEnable: boolean;
     /** If true the WASD keys are also routed to the direction keys (for better accessibility)
      *  @type {boolean}
      *  @default
@@ -780,6 +787,10 @@ declare module "littlejsengine" {
      *  @param {boolean} enable
      *  @memberof Settings */
     export function setGamepadDirectionEmulateStick(enable: boolean): void;
+    /** Set if axes that do not rest near center are ignored on non-standard gamepads
+     *  @param {boolean} enable
+     *  @memberof Settings */
+    export function setGamepadAxisFilterEnable(enable: boolean): void;
     /** Set if true the WASD keys are also routed to the direction keys
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -1817,6 +1828,11 @@ declare module "littlejsengine" {
      *  @type {OffscreenCanvasRenderingContext2D}
      *  @memberof Draw */
     export let workReadContext: OffscreenCanvasRenderingContext2D;
+    /** Extra canvas to composite behind the engine canvases when combining canvases
+     *  Set by plugins that render to their own canvas below the LittleJS canvases
+     *  @type {HTMLCanvasElement}
+     *  @memberof Draw */
+    export let backgroundCanvas: HTMLCanvasElement;
     /** The size of the main canvas (and other secondary canvases)
      *  @type {Vector2}
      *  @memberof Draw */
@@ -2050,6 +2066,12 @@ declare module "littlejsengine" {
      *  @param {boolean} [additive]
      *  @memberof Draw */
     export function setAdditiveBlendMode(additive?: boolean): void;
+    /** Set an extra canvas to composite behind the engine canvases when combining
+     *  Plugins that insert their own canvas below the LittleJS canvases should set
+     *  this so it appears in screenshots and video capture
+     *  @param {HTMLCanvasElement} [canvas]
+     *  @memberof Draw */
+    export function setBackgroundCanvas(canvas?: HTMLCanvasElement): void;
     /** Combines LittleJS canvases onto the main canvas
      *  This is necessary for things like screenshots and video
      *  @memberof Draw */

package/dist/littlejs.esm.js

@@ -35,7 +35,7 @@ const engineName = 'LittleJS';
  *  @type {string}
  *  @default
  *  @memberof Engine */
-const engineVersion = '1.18.26';
+const engineVersion = '1.18.27';
 
 /** Frames per second to update
  *  @type {number}
@@ -3037,6 +3037,14 @@ let gamepadsEnable = true;
  *  @memberof Settings */
 let gamepadDirectionEmulateStick = true;
 
+/** If true, axes that do not rest near center are ignored on gamepads without
+ *  standard mapping. Steering wheels and flight sticks report pedal and throttle
+ *  axes that rest at full deflection, which otherwise reads as a stick held down.
+ *  @type {boolean}
+ *  @default
+ *  @memberof Settings */
+let gamepadAxisFilterEnable = true;
+
 /** If true the WASD keys are also routed to the direction keys (for better accessibility)
  *  @type {boolean}
  *  @default
@@ -3375,6 +3383,11 @@ function setGamepadsEnable(enable) { gamepadsEnable = enable; }
  *  @memberof Settings */
 function setGamepadDirectionEmulateStick(enable) { gamepadDirectionEmulateStick = enable; }
 
+/** Set if axes that do not rest near center are ignored on non-standard gamepads
+ *  @param {boolean} enable
+ *  @memberof Settings */
+function setGamepadAxisFilterEnable(enable) { gamepadAxisFilterEnable = enable; }
+
 /** Set if true the WASD keys are also routed to the direction keys
  *  @param {boolean} enable
  *  @memberof Settings */
@@ -4119,6 +4132,12 @@ let workReadCanvas;
  *  @memberof Draw */
 let workReadContext;
 
+/** Extra canvas to composite behind the engine canvases when combining canvases
+ *  Set by plugins that render to their own canvas below the LittleJS canvases
+ *  @type {HTMLCanvasElement}
+ *  @memberof Draw */
+let backgroundCanvas;
+
 /** The size of the main canvas (and other secondary canvases)
  *  @type {Vector2}
  *  @memberof Draw */
@@ -5270,6 +5289,13 @@ function setAdditiveBlendMode(additive=true)
     drawContext.globalCompositeOperation = additive ? 'lighter' : 'source-over';
 }
 
+/** Set an extra canvas to composite behind the engine canvases when combining
+ *  Plugins that insert their own canvas below the LittleJS canvases should set
+ *  this so it appears in screenshots and video capture
+ *  @param {HTMLCanvasElement} [canvas]
+ *  @memberof Draw */
+function setBackgroundCanvas(canvas) { backgroundCanvas = canvas; }
+
 /** Combines LittleJS canvases onto the main canvas
  *  This is necessary for things like screenshots and video
  *  @memberof Draw */
@@ -5282,6 +5308,8 @@ function combineCanvases()
     // leaving workContext.fillStyle transparent can't silently no-op this
     workContext.fillStyle = '#000';
     workContext.fillRect(0,0,w,h);
+    if (backgroundCanvas)
+        workContext.drawImage(backgroundCanvas, 0, 0, w, h);
     glCopyToContext(workContext);
     workContext.drawImage(mainCanvas, 0, 0);
     mainContext.drawImage(workCanvas, 0, 0);
@@ -5680,6 +5708,7 @@ function inputClear()
     touchGamepadStickPointerId.length = 0; // release floating sticks so they re-anchor
     gamepadStickData.length = 0;
     gamepadDpadData.length = 0;
+    gamepadAxisCentered.length = 0;
 }
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5917,6 +5946,11 @@ const inputData = [[]];
 
 // gamepad internal variables
 const gamepadStickData = [], gamepadDpadData = [], gamepadHadInput = [];
+// per gamepad, how many consecutive frames each axis has rested inside the
+// dead zone, used to tell stick axes from axes that rest at full deflection
+const gamepadAxisCentered = [];
+// how long an axis must rest inside the dead zone before it counts as a stick
+const gamepadAxisCenteredFrames = 15;
 
 // touch gamepad internal variables
 const touchGamepadTimer = new Timer, touchGamepadButtons = [], touchGamepadSticks = [];
@@ -6165,7 +6199,7 @@ function inputUpdate()
         // gamepad: any button held or stick moved
         let gamepadActive = false;
         for (let s = gamepadStickCount(); s-- && !gamepadActive;)
-            gamepadActive = gamepadStick(s).lengthSquared() > .04;
+            gamepadActive = gamepadStick(s).lengthSquared() > .2;
         for (let b = 17; b-- && !gamepadActive;)
             gamepadActive = gamepadIsDown(b);
 
@@ -6193,12 +6227,12 @@ function inputUpdate()
     // gamepads are updated by engine every frame automatically
     function gamepadsUpdate()
     {
+        const deadZoneMin=.3, deadZoneMax=.8;
         const applyDeadZones = (v)=>
         {
-            const min=.3, max=.8;
             const deadZone = (v)=>
-                v > min ? percent(v, min, max) :
-                v < -min ? -percent(-v, min, max) : 0;
+                v > deadZoneMin ? percent(v, deadZoneMin, deadZoneMax) :
+                v < -deadZoneMin ? -percent(-v, deadZoneMin, deadZoneMax) : 0;
             return vec2(deadZone(v.x), deadZone(-v.y)).clampLength();
         };
 
@@ -6282,6 +6316,7 @@ function inputUpdate()
                 gamepadStickData[i] = undefined;
                 gamepadDpadData[i] = undefined;
                 gamepadHadInput[i] = undefined;
+                gamepadAxisCentered[i] = undefined;
                 continue;
             }
 
@@ -6290,8 +6325,30 @@ function inputUpdate()
             const dpad = gamepadDpadData[i] ?? (gamepadDpadData[i] = vec2());
 
             // read analog sticks
+            // gamepads without standard mapping (steering wheels, flight sticks)
+            // can report axes that rest at full deflection instead of center,
+            // which would otherwise read as a stick held down forever, so only
+            // trust an axis once it has rested inside the dead zone for a moment
+            const isStandard = gamepad.mapping === 'standard';
+            const centered = gamepadAxisCentered[i] ?? (gamepadAxisCentered[i] = []);
+            const readAxis = (j)=>
+            {
+                const v = gamepad.axes[j];
+                if (isStandard && j < 4)
+                    return v; // spec guarantees axes 0-3 are the two sticks
+                if (!gamepadAxisFilterEnable)
+                    return v;
+
+                // once an axis has proven it rests at center it stays trusted,
+                // otherwise moving it would immediately disqualify it again
+                const frames = centered[j] | 0;
+                if (frames > gamepadAxisCenteredFrames)
+                    return v;
+                centered[j] = abs(v) < deadZoneMin ? frames + 1 : 0;
+                return 0;
+            };
             for (let j = 0; j < gamepad.axes.length-1; j+=2)
-                sticks[j>>1] = applyDeadZones(vec2(gamepad.axes[j],gamepad.axes[j+1]));
+                sticks[j>>1] = applyDeadZones(vec2(readAxis(j), readAxis(j+1)));
 
             // read buttons
             let hadInput = false;
@@ -16808,6 +16865,9 @@ class ThreeJSPlugin
         rootElement.insertBefore(threeCanvas, rootElement.firstChild);
         threeCanvas.style.cssText = mainCanvas.style.cssText;
 
+        // composite the 3D canvas into screenshots and video capture
+        setBackgroundCanvas(threeCanvas);
+
         // render automatically each frame after the engine renders
         engineAddPlugin(undefined, ()=> this.render());
     }
@@ -16992,6 +17052,7 @@ export
     glCircleSides,
     gamepadsEnable,
     gamepadDirectionEmulateStick,
+    gamepadAxisFilterEnable,
     inputWASDEmulateDirection,
     touchInputEnable,
     touchGamepadEnable,
@@ -17048,6 +17109,7 @@ export
     setTouchInputEnable,
     setGamepadsEnable,
     setGamepadDirectionEmulateStick,
+    setGamepadAxisFilterEnable,
     setInputWASDEmulateDirection,
     setTouchGamepadEnable,
     setTouchGamepadPassthrough,
@@ -17163,6 +17225,7 @@ export
     workContext,
     workReadCanvas,
     workReadContext,
+    backgroundCanvas,
     mainCanvasSize,
     textureInfos,
     drawCount,
@@ -17188,6 +17251,7 @@ export
     drawText,
     drawTextScreen,
     setAdditiveBlendMode,
+    setBackgroundCanvas,
     combineCanvases,
     engineImageFont,
     ImageFont,