littlejsengine 1.6.92 → 1.7.1

package/README.md

@@ -6,66 +6,72 @@
 [![DeepScan][deepscan]][deepscan-url]
 [![Discord][discord]][discord-url]
 
-## All aboard!
+## 🚂 All aboard!
+
+LittleJS is a lightweight open source HTML5 game engine designed for modern web development.
+It's small footprint is packed with a comprehensive feature set, including hybrid rendering, physics, particles, sound effects, music, input handling, and debug tools.
+The code is very clean and well documented with a several examples to get you started. Choo-Choo! 🚂
 
-LittleJS is a super lightweight JavaScript game engine designed for modern web development. With its fast hybrid rendering system, it offers a comprehensive suite of game development tools from rendering to sound effects. The code is very clean and well documented with a variety of examples to get you started. Choo-Choo! 🚂
 <div align="center">
-  
+
 ## [Demo](https://killedbyapixel.github.io/LittleJS/examples/starter/) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe) | [Tutorial](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial)
+
 </div>
 
 ![LittleJS Screenshot](examples/screenshot.jpg)
 
-## Demos
-
-### [Starter Project](https://killedbyapixel.github.io/LittleJS/examples/starter/) - Clean example with only a few things to get you started
-### [Puzzle Game](https://killedbyapixel.github.io/LittleJS/examples/puzzle/) - Match 3 puzzle game with HD rendering and high score tracking
-### [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Platformer/shooter with procedural generation and destruction
-### [Breakout](https://killedbyapixel.github.io/LittleJS/examples/breakout/) - Breakout game with post processing effect
-### [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Max sprite/object test and music system demo
-### [Particle System Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Particle system editor and visualizer
-
 ## About LittleJS
 
 LittleJS is a small but powerful game engine with many features and no depenencies.
 
-### Graphics
+### ✨ Graphics
 
 - Super fast sprite and tile map rendering engine with WebGL
 - Update and render 10,000+ objects at 60fps, often many times more
+- Particle effect system and [design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
 - Apply [Shadertoy](https://www.shadertoy.com) compatible shaders for post processinge effects
 
-### Audio
+### 🔊 Audio
 
 - Positional sound effects with [ZzFX](https://killedbyapixel.github.io/ZzFX/) sound effect generator
 - Music with [ZzFXM](https://keithclark.github.io/ZzFXM/), mp3, or wav audio
 
-### Input
+### 🎮 Input
 
 - Input processing system for keyboard, mouse, gamepad, and touch
 - On screen touch gamepad for mobile devices
 
-### Physics
+### 💥 Physics
 
 - 2D physics engine with collision handling for axis aligned boxes
 - Very fast collision handling and raycasting for tile maps
 
-### Flexability
+### 🚀 Flexability
 
 - Designed to work with all modern web bowsers and mobile devices
-- Compatible with TypeScript and includes [an example TS project](https://killedbyapixel.github.io/LittleJS/examples/typescript)
+- Compatible with TypeScript and Modules with example projects for both
 - For size coding competitions like [js13kGames](https://js13kgames.com/), [a special example project builds to a 7KB zip file](https://killedbyapixel.github.io/LittleJS/examples/js13k)
-- Builds to a Windows executable with [Electron](https://www.electronjs.org/) for distribution on platforms like Steam
-- Open Source with the [MIT license](https://github.com/KilledByAPixel/LittleJS/blob/main/LICENSE) so it can be used for anything you want
+- Builds to a Windows executable with [Electron](https://www.electronjs.org/) for distribution on PC platforms like Steam
+- Open Source with the [MIT license](https://github.com/KilledByAPixel/LittleJS/blob/main/LICENSE) so it can be used for anything you want forever
 
-### And more...
+### 🛠️ And more...
 
 - Node.js build system
-- Debug primitives rendering system
+- 2D vector math library
+- Debug primitive rendering system
 - Particle effects system and design tool
 - Bitmap font rendering and includes a built in engine font
 - Medal system tracks and displays achievements with Newgrounds integration
 
+## Demos
+
+### [Starter Project](https://killedbyapixel.github.io/LittleJS/examples/starter/) - Clean example with only a few things to get you started
+### [Puzzle Game](https://killedbyapixel.github.io/LittleJS/examples/puzzle/) - Match 3 puzzle game with HD rendering and high score tracking
+### [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Platformer/shooter with procedural generation and destruction
+### [Breakout](https://killedbyapixel.github.io/LittleJS/examples/breakout/) - Breakout game with post processing effect
+### [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Max sprite/object test and music system demo
+### [Particle System Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Particle system editor and visualizer
+
 ## How to use LittleJS
 
 To use LittleJS download the latest package from GitHub or call ```npm install littlejsengine```. This package contains the engine and several small examples.
@@ -95,7 +101,8 @@ The starter example project also includes a node js file [build.js](https://gith
 
 ## Engine Source Code
 
-This engine is made with simplicity in mind using clean easy to read code. There are only a few files used by the entire engine.
+This engine is made with simplicity in mind using clean easy to read code.
+There are only a few core files used by the entire engine.
 
 - [engine.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engine.js) - Top level engine init, update, and render
 - [engineSettings.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineSettings.js) - Global engine settings
@@ -105,7 +112,7 @@ This engine is made with simplicity in mind using clean easy to read code. There
 - [engineInput.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineInput.js) - Input for keyboard, mouse, touch, and gamepad
 - [engineUtilities.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineUtilities.js) - Vector2, Color, and Timer clases and math functions
 
-Optional Components, these components are built to synergize with the rest of the engine but are not necessary.
+Optional Components, these components are built to synergize with the rest of the engine but are not required.
 
 - [engineTileLayer.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineTileLayer.js) - Tile layer rendering and collision
 - [engineParticles.js](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineParticles.js) - Particle system with fast rendering and collision

package/build/littlejs.d.ts

@@ -1,7 +1,7 @@
 declare module "littlejs.esm" {
     /**
      * LittleJS Module Export
-     * - Export engine as a module with extra functions where necessary
+     * - Export engine as a module with functions where necessary
      */
     /** Set position of camera in world space
      *  @param {Vector2} pos
@@ -404,8 +404,9 @@ declare module "littlejs.esm" {
     /** Save a canvas to disk
      *  @param {HTMLCanvasElement} canvas
      *  @param {String}            [filename]
+     *  @param {String}            [type='image/png']
      *  @memberof Debug */
-    export function debugSaveCanvas(canvas: HTMLCanvasElement, filename?: string): void;
+    export function debugSaveCanvas(canvas: HTMLCanvasElement, filename?: string, type?: string): void;
     /** A shortcut to get Math.PI
      *  @type {Number}
      *  @default Math.PI
@@ -446,20 +447,48 @@ declare module "littlejs.esm" {
      *  @return {Number}
      *  @memberof Utilities */
     export function clamp(value: number, min?: number, max?: number): number;
-    /** Returns what percentage the value is between max and min
+    /** Returns what percentage the value is between valueA and valueB
      *  @param {Number} value
-     *  @param {Number} [min=0]
-     *  @param {Number} [max=1]
+     *  @param {Number} valueA
+     *  @param {Number} valueB
      *  @return {Number}
      *  @memberof Utilities */
-    export function percent(value: number, min?: number, max?: number): number;
-    /** Linearly interpolates the percent value between max and min
+    export function percent(value: number, valueA: number, valueB: number): number;
+    /** Returns signed wrapped distance between the two values passed in
+     *  @param {Number} valueA
+     *  @param {Number} valueB
+     *  @param {Number} [wrapSize=1]
+     *  @returns {Number}
+     *  @memberof Utilities */
+    export function distanceWrap(valueA: number, valueB: number, wrapSize?: number): number;
+    /** Linearly interpolates between values passed in with wrappping
      *  @param {Number} percent
-     *  @param {Number} [min=0]
-     *  @param {Number} [max=1]
+     *  @param {Number} valueA
+     *  @param {Number} valueB
+     *  @param {Number} [wrapSize=1]
+     *  @returns {Number}
+     *  @memberof Utilities */
+    export function lerpWrap(percent: number, valueA: number, valueB: number, wrapSize?: number): number;
+    /** Returns signed wrapped distance between the two angles passed in
+     *  @param {Number} angleA
+     *  @param {Number} angleB
+     *  @returns {Number}
+     *  @memberof Utilities */
+    export function distanceAngle(angleA: number, angleB: number): number;
+    /** Linearly interpolates between the angles passed in with wrappping
+     *  @param {Number} percent
+     *  @param {Number} angleA
+     *  @param {Number} angleB
+     *  @returns {Number}
+     *  @memberof Utilities */
+    export function lerpAngle(percent: number, angleA: number, angleB: number): number;
+    /** Linearly interpolates between values passed in using percent
+     *  @param {Number} percent
+     *  @param {Number} valueA
+     *  @param {Number} valueB
      *  @return {Number}
      *  @memberof Utilities */
-    export function lerp(percent: number, min?: number, max?: number): number;
+    export function lerp(percent: number, valueA: number, valueB: number): number;
     /** Applies smoothstep function to the percentage value
      *  @param {Number} percent
      *  @return {Number}
@@ -499,11 +528,11 @@ declare module "littlejs.esm" {
      *  @memberof Random */
     export function rand(valueA?: number, valueB?: number): number;
     /** Returns a floored random value the two values passed in
-     *  @param {Number} [valueA=1]
+     *  @param {Number} valueA
      *  @param {Number} [valueB=0]
      *  @return {Number}
      *  @memberof Random */
-    export function randInt(valueA?: number, valueB?: number): number;
+    export function randInt(valueA: number, valueB?: number): number;
     /** Randomly returns either -1 or 1
      *  @return {Number}
      *  @memberof Random */
@@ -526,21 +555,36 @@ declare module "littlejs.esm" {
      *  @return {Color}
      *  @memberof Random */
     export function randColor(colorA?: Color, colorB?: Color, linear?: boolean): Color;
-    /** Seed used by the randSeeded function
-     *  @type {Number}
-     *  @default
-     *  @memberof Random */
-    export let randSeed: number;
-    /** Set seed used by the randSeeded function, should not be 0
-     *  @param {Number} seed
-     *  @memberof Random */
-    export function setRandSeed(seed: number): void;
-    /** Returns a seeded random value between the two values passed in using randSeed
-     *  @param {Number} [valueA=1]
-     *  @param {Number} [valueB=0]
-     *  @return {Number}
-     *  @memberof Random */
-    export function randSeeded(valueA?: number, valueB?: number): number;
+    /**
+     * Seeded random number generator
+     * - Can be used to create a deterministic random number sequence
+     * @example
+     * let r = new RandomGenerator(123); // random number generator with seed 123
+     * let a = r.rand();                 // random value between 0 and 1
+     * let b = r.randInt(10);            // random integer between 0 and 9
+     * r.seed = 123;                     // reset the seed
+     * let c = r.rand();                 // the same value as a
+     */
+    export class RandomGenerator {
+        /** Create a random number generator with the seed passed in
+         *  @param {Number} seed - Starting seed */
+        constructor(seed: number);
+        /** @property {Number} - random seed */
+        seed: number;
+        /** Returns a seeded random value between the two values passed in
+        *  @param {Number} [valueA=1]
+        *  @param {Number} [valueB=0]
+        *  @return {Number} */
+        float(valueA?: number, valueB?: number): number;
+        /** Returns a floored seeded random value the two values passed in
+        *  @param {Number} valueA
+        *  @param {Number} [valueB=0]
+        *  @return {Number} */
+        int(valueA: number, valueB?: number): number;
+        /** Randomly returns either -1 or 1 deterministically
+        *  @return {Number} */
+        sign(): number;
+    }
     /**
      * 2D Vector object with vector math library
      * - Functions do not change this so they can be chained together
@@ -810,12 +854,12 @@ declare module "littlejs.esm" {
     export function hsl(h?: number, s?: number, l?: number, a?: number): Color;
     /**
      * LittleJS Object Base Object Class
-     * - Base object class used by the engine
+     * - Top level object class used by the engine
      * - Automatically adds self to object list
      * - Will be updated and rendered each frame
      * - Renders as a sprite from a tilesheet by default
      * - Can have color and addtive color applied
-     * - 2d Physics and collision system
+     * - 2D Physics and collision system
      * - Sorted by renderOrder
      * - Objects can have children attached
      * - Parents are updated before children, and set child transform
@@ -956,13 +1000,11 @@ declare module "littlejs.esm" {
      *  @memberof Draw */
     export let mainCanvasSize: Vector2;
     /** Convert from screen to world space coordinates
-     *  - if calling outside of render, you may need to manually set mainCanvasSize
      *  @param {Vector2} screenPos
      *  @return {Vector2}
      *  @memberof Draw */
     export function screenToWorld(screenPos: Vector2): Vector2;
     /** Convert from world to screen space coordinates
-     *  - if calling outside of render, you may need to manually set mainCanvasSize
      *  @param {Vector2} worldPos
      *  @return {Vector2}
      *  @memberof Draw */
@@ -977,42 +1019,25 @@ declare module "littlejs.esm" {
      *  @param {Boolean} [mirror=0]                     - If true image is flipped along the Y axis
      *  @param {Color}   [additiveColor=Color(0,0,0,0)] - Additive color to be applied
      *  @param {Boolean} [useWebGL=glEnable]            - Use accelerated WebGL rendering
+     *  @param {Boolean} [screenSpace=0]                - If true the pos and size are in screen space
      *  @memberof Draw */
-    export function drawTile(pos: Vector2, size?: Vector2, tileIndex?: number, tileSize?: Vector2, color?: Color, angle?: number, mirror?: boolean, additiveColor?: Color, useWebGL?: boolean): void;
+    export function drawTile(pos: Vector2, size?: Vector2, tileIndex?: number, tileSize?: Vector2, color?: Color, angle?: number, mirror?: boolean, additiveColor?: Color, useWebGL?: boolean, screenSpace?: boolean): void;
     /** Draw colored rect centered on pos
      *  @param {Vector2} pos
      *  @param {Vector2} [size=Vector2(1,1)]
      *  @param {Color}   [color=Color()]
      *  @param {Number}  [angle=0]
      *  @param {Boolean} [useWebGL=glEnable]
+     *  @param {Boolean} [screenSpace=0]
      *  @memberof Draw */
-    export function drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number, useWebGL?: boolean): void;
-    /** Draw textured tile centered on pos in screen space
-     *  @param {Vector2} pos                        - Center of the tile
-     *  @param {Vector2} [size=Vector2(1,1)]    - Size of the tile
-     *  @param {Number}  [tileIndex=-1]             - Tile index to use, negative is untextured
-     *  @param {Vector2} [tileSize=tileSizeDefault] - Tile size in source pixels
-     *  @param {Color}   [color=Color()]
-     *  @param {Number}  [angle=0]
-     *  @param {Boolean} [mirror=0]
-     *  @param {Color}   [additiveColor=Color(0,0,0,0)]
-     *  @param {Boolean} [useWebGL=glEnable]
-     *  @memberof Draw */
-    export function drawTileScreenSpace(pos: Vector2, size?: Vector2, tileIndex?: number, tileSize?: Vector2, color?: Color, angle?: number, mirror?: boolean, additiveColor?: Color, useWebGL?: boolean): void;
-    /** Draw colored rectangle in screen space
-     *  @param {Vector2} pos
-     *  @param {Vector2} [size=Vector2(1,1)]
-     *  @param {Color}   [color=Color()]
-     *  @param {Number}  [angle=0]
-     *  @param {Boolean} [useWebGL=glEnable]
-     *  @memberof Draw */
-    export function drawRectScreenSpace(pos: Vector2, size?: Vector2, color?: Color, angle?: number, useWebGL?: boolean): void;
+    export function drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number, useWebGL?: boolean, screenSpace?: boolean): void;
     /** Draw colored line between two points
      *  @param {Vector2} posA
      *  @param {Vector2} posB
      *  @param {Number}  [thickness=.1]
      *  @param {Color}   [color=Color()]
      *  @param {Boolean} [useWebGL=glEnable]
+     *  @param {Boolean} [screenSpace=0]
      *  @memberof Draw */
     export function drawLine(posA: Vector2, posB: Vector2, thickness?: number, color?: Color, useWebGL?: boolean): void;
     /** Draw directly to a 2d canvas context in world space
@@ -1022,8 +1047,9 @@ declare module "littlejs.esm" {
      *  @param {Boolean}  mirror
      *  @param {Function} drawFunction
      *  @param {CanvasRenderingContext2D} [context=mainContext]
+     *  @param {Boolean} [screenSpace=0]
      *  @memberof Draw */
-    export function drawCanvas2D(pos: Vector2, size: Vector2, angle: number, mirror: boolean, drawFunction: Function, context?: CanvasRenderingContext2D): void;
+    export function drawCanvas2D(pos: Vector2, size: Vector2, angle: number, mirror: boolean, drawFunction: Function, context?: CanvasRenderingContext2D, screenSpace?: boolean): void;
     /** Enable normal or additive blend mode
      *  @param {Boolean} [additive=0]
      *  @param {Boolean} [useWebGL=glEnable]
@@ -1082,20 +1108,20 @@ declare module "littlejs.esm" {
         paddingSize: Vector2;
         startTileIndex: number;
         context: CanvasRenderingContext2D;
-        /** Draw text in screen space using the image font
+        /** Draw text in world space using the image font
          *  @param {String}  text
          *  @param {Vector2} pos
-         *  @param {Number}  [scale=4]
+         *  @param {Number}  [scale=.25]
          *  @param {Boolean} [center]
          */
-        drawTextScreen(text: string, pos: Vector2, scale?: number, center?: boolean): void;
-        /** Draw text in world space using the image font
+        drawText(text: string, pos: Vector2, scale?: number, center?: boolean): void;
+        /** Draw text in screen space using the image font
          *  @param {String}  text
          *  @param {Vector2} pos
-         *  @param {Number}  [scale=.25]
+         *  @param {Number}  [scale=4]
          *  @param {Boolean} [center]
          */
-        drawText(text: string, pos: Vector2, scale?: number, center?: boolean): void;
+        drawTextScreen(text: string, pos: Vector2, scale?: number, center?: boolean): void;
     }
     /** Returns true if fullscreen mode is active
      *  @return {Boolean}
@@ -1221,6 +1247,7 @@ declare module "littlejs.esm" {
         range: number;
         /** @property {Number} - At what percentage of range should it start tapering off */
         taper: number;
+        /** @property {Number} - How much to randomize frequency each time sound plays */
         randomness: any;
         cachedSamples: any[];
         /** Play the sound