littlejsengine 1.18.7 → 1.18.12

package/README.md

@@ -53,7 +53,7 @@ The code is very clean and well documented with many examples to get you started
 
 - Robust arcade physics system with collision handling
 - Fast tilemap collision and raycasting
-- Full Box2D integration for realistic physics
+- Full Box2D integration for realistic physics using [Box2D v2.3.1 wasm](https://github.com/kripken/box2d.js)
 - Grid-based A* pathfinding plugin with optional path smoothing
 
 ### 🚀 Flexibility
@@ -74,7 +74,6 @@ The code is very clean and well documented with many examples to get you started
 
 ## How To Use LittleJS
 
-
 To get started download the latest LittleJS package from GitHub or install via npm: 
 
 ```
@@ -98,8 +97,7 @@ npm run dev
 - [LittleJS Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.md) - A reference sheet to help you get started.
 - [Little JS FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) - Answers to common questions about LittleJS.
 - [JS13k Branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) - For size coding events like JS13k there is a special branch that builds to a 7KB zip.
-- [LittleJS GPT AI](https://chatgpt.com/g/g-67c7c080b5bc81919736bc8815836be6-make-games-with-littlejs) - Use AI to make games without writing any code!
-- [LittleJS AI Info](https://github.com/KilledByAPixel/LittleJS-AI) - Experiments, games, and templates to improve LittleJS + AI workflows.
+- [LittleJS AI Tools](https://github.com/KilledByAPixel/LittleJS-AI) - Experiments, games, and templates to improve LittleJS + AI workflows.
 
 ## Examples
 

package/dist/littlejs.d.ts

@@ -1018,6 +1018,19 @@ declare module "littlejsengine" {
      *  @param {Object} saveData - object containing data to be saved
      *  @memberof Utilities */
     export function writeSaveData(saveName: string, saveData: any): void;
+    /** 1D gradient noise — returns a smooth value in [0, 1] for any real x.
+     *  Integer inputs land on deterministic lattice values; non-integer inputs
+     *  are interpolated with smoothStep for C1 continuity.
+     *  @param {number} x
+     *  @return {number}
+     *  @memberof Utilities */
+    export function noise1D(x: number): number;
+    /** 2D gradient noise — returns a smooth value in [0, 1] for any real (x, y).
+     *  @param {number} x
+     *  @param {number} y
+     *  @return {number}
+     *  @memberof Utilities */
+    export function noise2D(x: number, y: number): number;
     /** Random global functions
      *  @namespace Random */
     /** Returns a random value between the two values passed in
@@ -1368,6 +1381,7 @@ declare module "littlejsengine" {
      * - File saving (text, canvas, data URLs)
      * - Native share dialog support
      * - Local storage save data management
+     * - Gradient noise (1D and 2D)
      * @namespace Utilities
      */
     /**
@@ -1473,13 +1487,15 @@ declare module "littlejsengine" {
      * @memberof Math */
     export function isNumber(n: any): boolean;
     /**
-     * Check if object can be converted to a string (has a toString method)
+     * Check if a value is stringifiable — i.e. it has a toString that returns
+     * a string. Use this for ASSERTs and inputs that will be coerced to text;
+     * use `typeof x === 'string'` inline if you need strict-string semantics.
      * - Returns true for strings, numbers, and most objects
      * - Returns false for null and undefined
      * @param {any} s
      * @return {boolean}
      * @memberof Math */
-    export function isString(s: any): boolean;
+    export function isStringLike(s: any): boolean;
     /**
      * Check if object is an array
      * @param {any} a
@@ -1695,6 +1711,11 @@ declare module "littlejsengine" {
      *  @type {number}
      *  @memberof Draw */
     export let drawCount: number;
+    /** Keeps track of how many primitives were drawn each frame for debugging
+     *  A single draw call can render many primitives (e.g. a WebGL sprite batch).
+     *  @type {number}
+     *  @memberof Draw */
+    export let primitiveCount: number;
     /** Convert from screen to world space coordinates
      *  @param {Vector2} screenPos
      *  @return {Vector2}
@@ -1749,7 +1770,7 @@ declare module "littlejsengine" {
      *  @param {Vector2} pos
      *  @param {Vector2} [size=vec2(1)]
      *  @param {Color}   [colorTop=WHITE]
-     *  @param {Color}   [colorBottom=BLACK]
+     *  @param {Color}   [colorBottom=CLEAR_WHITE]
      *  @param {number}  [angle]
      *  @param {boolean} [useWebGL=glEnable]
      *  @param {boolean} [screenSpace]
@@ -1843,6 +1864,7 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function drawCircle(pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    export function drawCircleGradient(pos: any, size: number, colorInner: Color, colorOuter: Color, useWebGL: boolean, screenSpace: boolean, context: any): void;
     /**
      * @callback Canvas2DDrawFunction - A function that draws to a 2D canvas context
      * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
@@ -2064,6 +2086,18 @@ declare module "littlejsengine" {
      *  @param {number} [rgbaAdditive=0] - black is 0
      *  @memberof WebGL */
     export function glDraw(x: number, y: number, sizeX: number, sizeY: number, angle?: number, uv0X?: number, uv0Y?: number, uv1X?: number, uv1Y?: number, rgba?: number, rgbaAdditive?: number): void;
+    /** Add an untextured rect to the gl draw list
+     *  Picks the optimal path: if already in poly mode, emits a tristrip rect
+     *  so it batches with surrounding polys; otherwise uses the instanced path
+     *  with uvs and rgba zeroed so the color falls through the additive slot.
+     *  @param {number} x
+     *  @param {number} y
+     *  @param {number} sizeX
+     *  @param {number} sizeY
+     *  @param {number} angle
+     *  @param {number} rgba - color as 32-bit integer
+     *  @memberof WebGL */
+    export function glDrawUntextured(x: number, y: number, sizeX: number, sizeY: number, angle: number, rgba: number): void;
     /** Transform and add a polygon to the gl draw list
      *  @param {Array<Vector2>} points - Array of Vector2 points
      *  @param {number} rgba - Color of the polygon as a 32-bit integer
@@ -2301,9 +2335,7 @@ declare module "littlejsengine" {
      * - Web Audio API integration with master gain control
      * @namespace Audio
      */
-    /** Audio context used by the engine. Created lazily in audioInit() to avoid
-     *  browser autoplay warnings about constructing an AudioContext before any
-     *  user gesture.
+    /** Audio context used by the engine
      *  @type {AudioContext}
      *  @memberof Audio */
     export let audioContext: AudioContext;
@@ -2483,13 +2515,13 @@ declare module "littlejsengine" {
     }
     /** Speak text with passed in settings
      *  @param {string} text - The text to speak
-     *  @param {string} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
      *  @param {number} [volume] - How much to scale volume by
      *  @param {number} [rate] - How quickly to speak
      *  @param {number} [pitch] - How much to change the pitch by
+     *  @param {string} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
      *  @return {SpeechSynthesisUtterance} - The utterance that was spoken
      *  @memberof Audio */
-    export function speak(text: string, language?: string, volume?: number, rate?: number, pitch?: number): SpeechSynthesisUtterance;
+    export function speak(text: string, volume?: number, rate?: number, pitch?: number, language?: string): SpeechSynthesisUtterance;
     /** Stop all queued speech
      *  @memberof Audio */
     export function speakStop(): void;
@@ -3264,6 +3296,7 @@ declare module "littlejsengine" {
         icon: string;
         /** @property {boolean} - Is the medal unlocked? */
         unlocked: boolean;
+        /** @property {HTMLImageElement|undefined} - Source image for the medal icon, if any */
         image: HTMLImageElement;
         /** Unlocks a medal if not already unlocked */
         unlock(): void;
@@ -3337,12 +3370,19 @@ declare module "littlejsengine" {
          *  new NewgroundsPlugin(app_id);
          */
         constructor(app_id: string, cipher?: string, cryptoJS?: any);
+        /** @property {string} - The newgrounds App ID */
         app_id: string;
+        /** @property {string|undefined} - AES-128/Base64 encryption key, if any */
         cipher: string;
+        /** @property {Object|undefined} - CryptoJS instance used when cipher is set */
         cryptoJS: any;
+        /** @property {string} - Hostname used when logging views */
         host: string;
+        /** @property {string|null} - Newgrounds session id from the URL (null when not logged in) */
         session_id: string;
+        /** @property {Array} - Medals fetched from Newgrounds (empty until session is active) */
         medals: any;
+        /** @property {Array} - Scoreboards fetched from Newgrounds */
         scoreboards: any;
         /** Send message to unlock a medal by id
          * @param {number} id - The medal id */
@@ -3738,6 +3778,10 @@ declare module "littlejsengine" {
         navigationIndex: any;
         /** @property {boolean} - Should this be auto selected by navigation? Must also have valid navigation index. */
         navigationAutoSelect: boolean;
+        /** @property {Vector2} - Where on parent (or canvas if no parent) this object is anchored.
+         *  Components in [-1, 1]: (0,0)=center, (-1,-1)=top-left, (1,1)=bottom-right.
+         *  Also acts as self-pivot — e.g. (1,-1) puts your top-right corner at the anchor point. */
+        anchor: Vector2;
         /** Add a child UIObject to this object, returns child for chaining
          *  @param {UIObject} child
          *  @return {UIObject} The child object added */
@@ -5070,13 +5114,21 @@ declare module "littlejsengine" {
             useRealTime?: boolean;
             paused?: boolean;
         });
+        /** @property {function(number|Vector2|Color):void} - Called with the interpolated value each frame */
         callback: (arg0: number | Vector2 | Color) => void;
+        /** @property {number|Vector2|Color} - Starting value */
         start: number | Vector2 | Color;
+        /** @property {number|Vector2|Color} - Ending value */
         end: number | Vector2 | Color;
+        /** @property {number} - Total duration in seconds */
         duration: number;
+        /** @property {number} - Remaining time in seconds (counts down from duration to 0) */
         life: number;
+        /** @property {function(number):number} - Easing curve mapping [0,1] -> [0,1] */
         ease: (arg0: number) => number;
+        /** @property {boolean} - If true, advance even when the game is paused */
         useRealTime: boolean;
+        /** @property {boolean} - If true, stop advancing until cleared */
         paused: boolean;
         /** @private completion callback set by then(), loop(), pingPong(). */
         private thenCallback;
@@ -5218,13 +5270,21 @@ declare module "littlejsengine" {
          *  (size and walkability auto-derived) or a Vector2 grid size (user
          *  overrides isWalkable). */
         constructor(source: TileCollisionLayer | Vector2);
+        /** @property {Vector2} - Grid dimensions in tiles */
         size: any;
+        /** @property {TileCollisionLayer|undefined} - Tile layer driving walkability, if any */
         tileLayer: Vector2 | TileCollisionLayer;
+        /** @property {number} - A* heuristic multiplier (1 = admissible, higher = greedier) */
         heuristicWeight: number;
+        /** @property {number} - Maximum A* expansions before giving up */
         maxLoop: number;
+        /** @property {boolean} - If true, post-process paths with two-pass smoothing */
         smoothPath: boolean;
+        /** @property {boolean} - If true, draw debug visualization during findPath */
         debug: boolean;
+        /** @property {number} - Debug primitive lifetime in seconds (0 disables drawing) */
         debugTime: number;
+        /** @property {Array<PathFinderNode>} - Flat row-major array of size.x*size.y nodes */
         nodes: any[];
         collisionScratch: Vector2;
         /** Default walkability: if a tile layer was provided, returns true when the
@@ -5304,6 +5364,14 @@ declare module "littlejsengine" {
          *  @param {PathFinderNode[]} path
          *  @private */
         private smoothPathStringPull;
+        /** Drop any middle node that lies exactly on the line through its two
+         *  neighbors. Backstop for the smoothing passes — the corners pass
+         *  intentionally keeps truly-straight runs, and the string-pulling pass
+         *  checks collinearity against the original path, not the in-progress
+         *  result, so it can leave 3+ collinear nodes in some edge cases.
+         *  @param {PathFinderNode[]} path
+         *  @private */
+        private dropCollinearNodes;
         /** Lookup helper: true when the node at tile coords (x, y) is in-bounds
          *  and clear (walkable, zero-cost). Used by isLineClear's hot path.
          *  @param {number} x