littlejsengine 1.18.1 → 1.18.4

package/.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+      - run: npm install
+      - run: npm run build
+      - run: npm test

package/AI.md

@@ -141,6 +141,7 @@ drawEllipse(pos, size, color)           // filled ellipse
 
 ## Common pitfalls
 
+- **New public APIs must be added to `src/engineExport.js`** - Variables and functions added to engine source files are accessible in script-tag builds automatically, but the ESM build (`littlejs.esm.js`) and TypeScript definitions (`littlejs.d.ts`) only include what's listed in `engineExport.js`. Plugin exports go in `plugins/pluginExport.js`. Forgetting this means ESM/TS users can't access the new API.
 - **ASSERT and LOG are stripped in release builds** - Don't rely on side effects
 - **Don't modify constant colors** - `WHITE`, `BLACK`, `RED`, etc. are frozen; use `.copy()` first
 - **Time variables are global** - `time`, `frame` update automatically each frame
@@ -155,6 +156,16 @@ drawEllipse(pos, size, color)           // filled ellipse
 npm run build
 ```
 
+### Testing
+```bash
+npm test
+```
+
+- Tests target `dist/littlejs.esm.js` — rebuild with `npm run build` after changing source.
+- [test/setup.mjs](test/setup.mjs) stubs minimal DOM and enables headless mode. Tests shouldn't call `engineInit`, `render()`, or assume `time` advances.
+- Zero test dependencies — uses Node's built-in `node --test`. Match the style in [test/](test/) when adding new ones.
+- CI runs build + test on every push/PR ([.github/workflows/test.yml](.github/workflows/test.yml)).
+
 ### Debug features
 - Press `Esc` to toggle debug overlay
 - Number keys toggle visualizations

package/LICENSE

@@ -1,4 +1,4 @@
-LittleJS Engine License (MIT License)
+The MIT License
 
 Copyright (c) 2021 Frank Force http://www.frankforce.com
 
@@ -9,35 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
--------------------------------------------------------------------------------
-
-Box2D License
-
-Copyright (c) 2006-2013 Erin Catto http://www.gphysics.com
-
-This software is provided 'as-is', without any express or implied
-warranty.  In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-1. The origin of this software must not be misrepresented; you must not
-claim that you wrote the original software. If you use this software
-in a product, an acknowledgment in the product documentation would be
-appreciated but is not required.
-2. Altered source versions must be plainly marked as such, and must not be
-misrepresented as being the original software.
-3. This notice may not be removed or altered from any source distribution.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # LittleJS - The Tiny Fast JavaScript Game Engine
 
-<div align='center'>
+<div align='center' markdown='1'>
     
 ![LittleJS Logo](examples/logo.png)
 
@@ -22,7 +22,7 @@ The code is very clean and well documented with many examples to get you started
 
 *The Third Annual LittleJS Game Jam will take place From Oct 2 to Nov 2! Unleash your creativity and develop amazing games using the LittleJS game engine. 🕹️🎮 [Sign up today and get more info about the jam on itch.io!](https://itch.io/jam/littlejs-jam)*
 
-<div align='center'>
+<div align='center' markdown='1'>
 
 ## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md)
 

package/dist/littlejs.d.ts

@@ -96,7 +96,7 @@ declare module "littlejsengine" {
      *  @type {number}
      *  @memberof Engine */
     export let time: number;
-    /** Actual clock time since start in seconds (not affected by pause or frame rate clamping)
+    /** Actual clock time since start in seconds (not affected by pause, timescale, or frame rate clamping)
      *  @type {number}
      *  @memberof Engine */
     export let timeReal: number;
@@ -333,6 +333,14 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let cameraScale: number;
+    /** 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
+     *  - Should be >= 0; stacks multiplicatively with the debug +/- shortcut
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let timeScale: number;
     /** Enable applying color to tiles when using canvas2d
      *  - This is slower but should be the same as WebGL rendering
      *  @type {boolean}
@@ -480,17 +488,21 @@ declare module "littlejsengine" {
     export let inputWASDEmulateDirection: boolean;
     /** 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
+     *  - Analog stick buttons 10 and 11 are also activated when virtual sticks are touched
+    
      *  @type {boolean}
      *  @default
      *  @memberof Settings */
     export let touchGamepadEnable: boolean;
     /** True if touch gamepad should have start button in the center
+     *  - Prevents activating if overlappng with virtual stick or buttons if they are enabled
      *  - When the game is paused, any touch will press the button
-     *  - This can function as a way to pause/unpause the game
-     *  @type {boolean}
+     *  - Set size to enable the center button
+     *  @type {number}
      *  @default
      *  @memberof Settings */
-    export let touchGamepadCenterButton: boolean;
+    export let touchGamepadCenterButtonSize: number;
     /** True if touch gamepad should be analog stick or false to use if 8 way dpad
      *  @type {boolean}
      *  @default
@@ -563,6 +575,10 @@ declare module "littlejsengine" {
      *  @param {number} scale
      *  @memberof Settings */
     export function setCameraScale(scale: number): void;
+    /** Set scale applied to engine time
+     *  @param {number} scale
+     *  @memberof Settings */
+    export function setTimeScale(scale: number): void;
     /** Set if tiles should be colorized when using canvas2d
      *  This can be slower but results should look nearly identical to WebGL rendering
      *  It can be enabled/disabled at any time
@@ -687,11 +703,12 @@ declare module "littlejsengine" {
      *  @param {boolean} enable
      *  @memberof Settings */
     export function setTouchGamepadEnable(enable: boolean): void;
-    /** True if touch gamepad should have start button in the center
-     *  - This can function as a way to pause/unpause the game
-     *  @param {boolean} enable
+    /** Set if touch gamepad should have start button in the center
+     *  - Set size to enable the center button
+     *  - When the game is paused, any touch will press the button
+     *  @param {number} size
      *  @memberof Settings */
-    export function setTouchGamepadCenterButton(enable: boolean): void;
+    export function setTouchGamepadCenterButtonSize(size: number): void;
     /** Set number of buttons on touch gamepad (0-4), if 1 also acts as right analog stick
      *  @param {number} count
      *  @memberof Settings */
@@ -893,6 +910,16 @@ declare module "littlejsengine" {
      *  @return {number}
      *  @memberof Math */
     export function lerp(valueA: number, valueB: number, percent: number): number;
+    /** Gets percent between percentA and percentB and linearly interpolates between lerpA and lerpB
+     *  A shortcut for lerp(lerpA, lerpB, percent(value, percentA, percentB))
+     *  @param {number} value
+     *  @param {number} percentA
+     *  @param {number} percentB
+     *  @param {number} lerpA
+     *  @param {number} lerpB
+     *  @return {number}
+     *  @memberof Math */
+    export function percentLerp(value: number, percentA: number, percentB: number, lerpA: number, lerpB: number): number;
     /** Applies smoothstep function to the percentage value
      *  @param {number} percent
      *  @return {number}
@@ -920,6 +947,20 @@ declare module "littlejsengine" {
      *  @return {boolean}      - True if intersecting
      *  @memberof Math */
     export function isIntersecting(start: Vector2, end: Vector2, pos: Vector2, size: Vector2): boolean;
+    /**
+     * @callback LineTestFunction - Checks if a position is colliding
+     * @param {Vector2} pos
+     * @memberof Draw
+     */
+    /**
+     * Casts a ray and returns position of the first collision found, or undefined if none are found
+     * @param {Vector2} posStart
+     * @param {Vector2} posEnd
+     * @param {LineTestFunction} testFunction - Check if colliding
+     * @param {Vector2} [normal] - Optional vector to store the normal
+     * @return {Vector2|undefined} - Position of the collision or undefined if none found
+     * @memberof Math */
+    export function lineTest(posStart: Vector2, posEnd: Vector2, testFunction: LineTestFunction, normal?: Vector2): Vector2 | undefined;
     /** Returns an oscillating wave between 0 and amplitude with frequency of 1 Hz by default
      *  @param {number} [frequency] - Frequency of the wave in Hz
      *  @param {number} [amplitude] - Amplitude (max height) of the wave
@@ -1704,6 +1745,21 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function drawRectGradient(pos: Vector2, size?: Vector2, colorTop?: Color, colorBottom?: Color, angle?: number, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    /** Draw a texture tiled (wrapped) across a rectangle in world space.
+     *  Useful for backgrounds, repeating patterns, and seamless fills.
+     *  The whole texture is tiled — sub-region (TileInfo) wrapping is not supported.
+     *  @param {Vector2}  pos          - Center of the rect in world space
+     *  @param {Vector2}  size         - Size of the rect in world space
+     *  @param {Vector2}  wrapCount    - How many times the texture repeats (x, y)
+     *  @param {TextureInfo|number} [texture=0] - TextureInfo or texture index into textureInfos
+     *  @param {Color}    [color=WHITE] - Color to modulate with
+     *  @param {number}   [angle=0] - Angle to rotate by
+     *  @param {Color}    [additiveColor] - Additive color to be applied if any
+     *  @param {boolean}  [useWebGL=glEnable] - Use accelerated WebGL rendering?
+     *  @param {boolean}  [screenSpace=false] - Are pos and size in screen space?
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
+     *  @memberof Draw */
+    export function drawTextureWrapped(pos: Vector2, size: Vector2, wrapCount: Vector2, texture?: TextureInfo | number, color?: Color, angle?: number, additiveColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     /** Draw connected lines between a series of points
      *  @param {Array<Vector2>} points
      *  @param {number}  [width]
@@ -1914,9 +1970,8 @@ declare module "littlejsengine" {
     /** Set the WebGL texture, called automatically if using multiple textures
      *  - This may also flush the gl buffer resulting in more draw calls and worse performance
      *  @param {WebGLTexture} texture
-     *  @param {boolean} [wrap] - Should the texture wrap or clamp
      *  @memberof WebGL */
-    export function glSetTexture(texture: WebGLTexture, wrap?: boolean): void;
+    export function glSetTexture(texture: WebGLTexture): void;
     /** Compile WebGL shader of the given type, will throw errors if in debug mode
      *  @param {string} source
      *  @param {number} type
@@ -2160,6 +2215,18 @@ declare module "littlejsengine" {
      *  @return {boolean}
      *  @memberof Input */
     export function gamepadConnected(gamepad?: number): boolean;
+    /** Pulse a gamepad's vibration hardware using the dual-rumble effect if it exists
+     *  Strong magnitude is usually the left side motor, weak magnitude is usually the right side motor
+     *  @param {number} [gamepad] - gamepad index
+     *  @param {number} [duration] - effect duration in ms
+     *  @param {number} [strongMagnitude] - strong (left) motor intensity, 0 to 1
+     *  @param {number} [weakMagnitude] - weak (right) motor intensity, 0 to 1
+     *  @param {number} [startDelay] - delay in ms before the effect starts
+     *  @memberof Input */
+    export function gamepadVibrate(gamepad?: number, duration?: number, strongMagnitude?: number, weakMagnitude?: number, startDelay?: number): void;
+    /** Stop vibration on a gamepad
+     *  @memberof Input */
+    export function gamepadVibrateStop(gamepad?: number): void;
     /** Pulse the vibration hardware if it exists
      *  @param {number|Array} [pattern] - single value in ms or vibration interval array
      *  @memberof Input */
@@ -4844,4 +4911,164 @@ declare module "littlejsengine" {
      *  @param {number} [angle] - Angle to rotate by
      *  @memberof DrawUtilities */
     export function drawThreeSliceScreen(pos: Vector2, size: Vector2, startTile: TileInfo, borderSize?: number, extraSpace?: number, angle?: number): void;
+    /** A numeric tween: drives a callback with a value interpolated between
+     *  `start` and `end` over `duration` seconds. Pauses with the game by default.
+     *  @memberof TweenSystem
+     *  @example
+     *  // Animate a fade-out over 2 seconds with an ease-out sine curve.
+     *  new Tween((v) => obj.alpha = v, 1, 0, 2, { ease: Ease.OUT(Ease.SINE) });
+     */
+    export class Tween {
+        /** Create a new tween. The callback fires immediately with `start` so the
+         *  target snaps to the start value on the same frame the tween is created.
+         *
+         *  `start` and `end` may be numbers, Vector2 instances, Color instances, or
+         *  any object exposing a `lerp(other, percent) => sameType` method. The
+         *  callback receives the interpolated value (a number, or a fresh instance
+         *  for lerp-able types). Both endpoints must be the same type.
+         *  @param {function(number|Vector2|Color):void} callback - Called with the interpolated value each frame
+         *  @param {number|Vector2|Color} [start=0] - Starting value
+         *  @param {number|Vector2|Color} [end=1] - Ending value
+         *  @param {number} [duration=1] - Duration in seconds
+         *  @param {Object} [options]
+         *  @param {function(number):number} [options.ease] - Easing function (defaults to LINEAR)
+         *  @param {boolean} [options.useRealTime=false] - Advance even when the game is paused (matches Timer's useRealTime)
+         *  @param {boolean} [options.paused=false] - Start in paused state */
+        constructor(callback: (arg0: number | Vector2 | Color) => void, start?: number | Vector2 | Color, end?: number | Vector2 | Color, duration?: number, options?: {
+            ease?: (arg0: number) => number;
+            useRealTime?: boolean;
+            paused?: boolean;
+        });
+        callback: (arg0: number | Vector2 | Color) => void;
+        start: number | Vector2 | Color;
+        end: number | Vector2 | Color;
+        duration: number;
+        life: number;
+        ease: (arg0: number) => number;
+        useRealTime: boolean;
+        paused: boolean;
+        /** @private completion callback set by then(), loop(), pingPong(). */
+        private thenCallback;
+        /** @private remaining iterations including the current run (loop/pingPong only). */
+        private loopRemaining;
+        /** Set the easing curve and return this for chaining.
+         *  @param {function(number):number} easeFn
+         *  @returns {Tween}
+         *  @memberof TweenSystem */
+        setEase(easeFn: (arg0: number) => number): Tween;
+        /** Set a single completion callback. Calling `then` again replaces the
+         *  previous callback. Returns this for chaining.
+         *
+         *  Calling `then` after `loop` or `pingPong` overrides the loop chain
+         *  (last call wins).
+         *  @param {function():void} callback
+         *  @returns {Tween}
+         *  @memberof TweenSystem */
+        then(callback: () => void): Tween;
+        /** Repeat this tween `n` total times. After each iteration finishes, a
+         *  fresh tween with the same parameters takes over via the `then` slot.
+         *  `loop()` with no argument loops forever.
+         *
+         *  Mutually exclusive with `pingPong`; calling either replaces the other,
+         *  and calling `then` after either clears the loop (last call wins).
+         *  @param {number} [count=Infinity]
+         *  @returns {Tween}
+         *  @memberof TweenSystem */
+        loop(count?: number): Tween;
+        /** Like `loop`, but swap `start` and `end` between iterations so the value
+         *  bounces back and forth. `pingPong()` with no argument bounces forever.
+         *
+         *  Mutually exclusive with `loop`; calling either replaces the other, and
+         *  calling `then` after either clears the loop (last call wins).
+         *  @param {number} [count=Infinity]
+         *  @returns {Tween}
+         *  @memberof TweenSystem */
+        pingPong(count?: number): Tween;
+        /** Pause this tween. While paused, tweenUpdate skips it.
+         *  @memberof TweenSystem */
+        pause(): void;
+        /** Resume a paused tween.
+         *  @memberof TweenSystem */
+        resume(): void;
+        /** Reset this tween to the start: life back to duration, pause cleared,
+         *  re-added to the active list if previously stopped, and the callback
+         *  re-fired with the start value.
+         *  @memberof TweenSystem */
+        restart(): void;
+        /** True if this tween is in the active list and not paused.
+         *  @returns {boolean}
+         *  @memberof TweenSystem */
+        isActive(): boolean;
+        /** Get how far this tween has progressed, from 0 (just started) to 1
+         *  (completed). Clamped — overshoot past completion still reads 1.
+         *  @returns {number}
+         *  @memberof TweenSystem */
+        getPercent(): number;
+        /** Get the current interpolated value (the value most recently passed to
+         *  the callback). Returns a number, Vector2, or Color depending on the
+         *  tween's start/end types.
+         *  @returns {number|Vector2|Color}
+         *  @memberof TweenSystem */
+        getValue(): number | Vector2 | Color;
+        /** Compute the interpolated value at the given remaining `life`.
+         *  At life === duration the result is `start`; at life === 0 it is `end`.
+         *  @param {number} life
+         *  @returns {number}
+         *  @memberof TweenSystem */
+        interp(life: number): number;
+        /** Remove this tween from the active list and prevent any pending then-callback.
+         *  @memberof TweenSystem */
+        stop(): void;
+    }
+    /** Tween a property on an object by dot-path. Returns the underlying Tween
+     *  so all chaining methods (`setEase`, `then`, `loop`, `pingPong`, etc.)
+     *  remain available.
+     *
+     *  `start` and `end` may be numbers, Vector2 instances, Color instances, or
+     *  any object with a `lerp(other, percent) => sameType` method.
+     *  @param {Object} target - The object whose property is being animated
+     *  @param {string} propertyPath - Dot-separated path, e.g. `'pos.x'` or `'color'`
+     *  @param {number|Vector2|Color} start - Starting value
+     *  @param {number|Vector2|Color} end - Ending value
+     *  @param {number} [duration=1] - Duration in seconds
+     *  @param {Object} [options] - Same options as the Tween constructor
+     *  @returns {Tween}
+     *  @memberof TweenSystem
+     *  @example
+     *  // Numeric: slide an object's x with an ease-out sine curve
+     *  tweenProperty(player, 'pos.x', 0, 10, 2).setEase(Ease.OUT(Ease.SINE));
+     *  // Vector2: animate a position diagonally
+     *  tweenProperty(player, 'pos', vec2(-5, 0), vec2(5, 3), 2);
+     *  // Color: pulse between two colors
+     *  tweenProperty(sprite, 'color', RED, BLUE, 1).pingPong();
+     */
+    export function tweenProperty(target: any, propertyPath: string, start: number | Vector2 | Color, end: number | Vector2 | Color, duration?: number, options?: any): Tween;
+    /** Stop every active tween and clear their then-callbacks. Useful for resets
+     *  on level transitions or when changing scenes.
+     *  @memberof TweenSystem */
+    export function tweenStopAll(): void;
+    /** Engine plugin hook: advance every active tween by the appropriate delta.
+     *  Called once per render frame by the engine (no arguments). May also be
+     *  called explicitly with `(gameDelta, realDelta)` to drive tweens manually
+     *  — useful for headless tests or custom replay/scrubbing systems.
+     *  @param {number} [gameDelta] - Game-time delta in seconds; default: time - lastTime
+     *  @param {number} [realDelta] - Real-time delta in seconds; default: timeReal - lastTimeReal
+     *  @memberof TweenSystem */
+    export function tweenUpdate(gameDelta?: number, realDelta?: number): void;
+    export namespace Ease {
+        function LINEAR(x: number): number;
+        function POWER(n: number): (arg0: number) => number;
+        function SINE(x: number): number;
+        function CIRC(x: number): number;
+        function EXPO(x: number): number;
+        function BACK(x: number): number;
+        function ELASTIC(x: number): number;
+        function SPRING(x: number): number;
+        function BOUNCE(x: number): number;
+        function IN(f: (arg0: number) => number): (arg0: number) => number;
+        function OUT(f: (arg0: number) => number): (arg0: number) => number;
+        function IN_OUT(f: (arg0: number) => number): (arg0: number) => number;
+        function PIECEWISE(...fns: ((arg0: number) => number)[]): (arg0: number) => number;
+        function BEZIER(x1: number, y1: number, x2: number, y2: number): (arg0: number) => number;
+    }
 }