littlejsengine 1.9.1 → 1.9.3

package/README.md

@@ -15,7 +15,7 @@
 ## 🚂 All aboard!
 
 LittleJS is a fast lightweight open source HTML5 game engine for modern web development.
-It's small footprint is packed with a comprehensive feature set including hybrid rendering, physics, particles, sound effects, music, and input handling.
+Its small footprint is packed with a comprehensive feature set including hybrid rendering, physics, particles, sound effects, music, and input handling.
 The code is very clean and well documented with some fun examples to get you started. Choo-Choo!
 
 ### 🚀 Join the First Ever LittleJS Game Jam
@@ -24,7 +24,7 @@ The code is very clean and well documented with some fun examples to get you sta
 
 <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/blob/main/examples/breakoutTutorial/README.md)
+## [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/blob/main/examples/breakoutTutorial/README.md) | [Quick Reference](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.md)
 
 </div>
 
@@ -54,7 +54,7 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 ### 💥 Physics
 
-- Robust 2D physics engine with collision handling for axis aligned boxes
+- Robust arcade physics system with collision handling
 - Very fast collision and raycasting for tile maps
 
 ### 🚀 Flexibility
@@ -80,6 +80,8 @@ To get started download the latest LittleJS package from GitHub or install via n
 
 Learn how to make a simple game from scratch with [The Breakout Tutorial.](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/breakoutTutorial)
 
+[LittleJS Engine Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.md) - This cheat sheet can help you get started.
+
 [Watch this GitNation talk](https://youtu.be/_dXKU0WgAj8?si=ZDXLYAFDWp54hrGT) to hear more about LittleJS works and get some tips on how to use it.
 
 Join our vibrant community on [Discord](https://discord.gg/zb7hcGkyZe) to get help, share your projects, and collaborate with others!
@@ -91,7 +93,7 @@ These examples are for both learning and using as starter projects to create you
 - [Starter Project](https://killedbyapixel.github.io/LittleJS/examples/starter/) - Clean example with only a few things to get you started
 - [Breakout](https://killedbyapixel.github.io/LittleJS/examples/breakout/) - Block breaking game with post-processing effects
 - [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
+- [Platformer](https://killedbyapixel.github.io/LittleJS/examples/platformer/) - Platformer/shooter with level data from [Tiled Editor](https://github.com/mapeditor/tiled)
 - [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
 
@@ -99,11 +101,11 @@ These examples are for both learning and using as starter projects to create you
 
 To easily include LittleJS in your game, you can use one of the pre-built js files.
 
-- [littlejs.js](https://github.com/KilledByAPixel/LittleJS/blob/main/build/littlejs.js) - The full game engine with debug mode available
-- [littlejs.release.js](https://github.com/KilledByAPixel/LittleJS/blob/main/build/littlejs.release.js) - The engine optimized for release builds
-- [littlejs.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/build/littlejs.min.js) - The engine in release mode and minified
-- [littlejs.esm.js](https://github.com/KilledByAPixel/LittleJS/blob/main/build/littlejs.esm.js) - The engine exported as a module with debug mode available
-- [littlejs.esm.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/build/littlejs.esm.min.js) - The engine exported as a minified module in release mode
+- [littlejs.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.js) - The full game engine with debug mode available
+- [littlejs.release.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.release.js) - The engine optimized for release builds
+- [littlejs.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.min.js) - The engine in release mode and minified
+- [littlejs.esm.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.js) - The engine exported as a module with debug mode available
+- [littlejs.esm.min.js](https://github.com/KilledByAPixel/LittleJS/blob/main/dist/littlejs.esm.min.js) - The engine exported as a minified module in release mode
 
 To rebuild the engine you must first run ```npm install``` to setup the necessary npm dependencies. Then call ```npm run build``` to build the engine.
 

package/{build → dist}/littlejs.d.ts

@@ -1,6 +1,6 @@
 declare module "littlejs.esm" {
     /**
-     * LittleJS - The Tiny JavaScript Game Engine That Can!
+     * LittleJS - The Tiny Fast JavaScript Game Engine
      * MIT License - Copyright 2021 Frank Force
      *
      * Engine Features
@@ -28,7 +28,7 @@ declare module "littlejs.esm" {
      *  @default
      *  @memberof Engine */
     export const engineVersion: string;
-    /** Frames per second to update objects
+    /** Frames per second to update
      *  @type {Number}
      *  @default
      *  @memberof Engine */
@@ -46,7 +46,7 @@ declare module "littlejs.esm" {
      *  @type {Number}
      *  @memberof Engine */
     export let frame: number;
-    /** Current engine time since start in seconds, derived from frame
+    /** Current engine time since start in seconds
      *  @type {Number}
      *  @memberof Engine */
     export let time: number;
@@ -63,12 +63,12 @@ declare module "littlejs.esm" {
      *  @param {Boolean} isPaused
      *  @memberof Engine */
     export function setPaused(isPaused: boolean): void;
-    /** Start up LittleJS engine with your callback functions
-     *  @param {Function} gameInit        - Called once after the engine starts up, setup the game
-     *  @param {Function} gameUpdate      - Called every frame at 60 frames per second, handle input and update the game state
-     *  @param {Function} gameUpdatePost  - Called after physics and objects are updated, setup camera and prepare for render
-     *  @param {Function} gameRender      - Called before objects are rendered, draw any background effects that appear behind objects
-     *  @param {Function} gameRenderPost  - Called after objects are rendered, draw effects or hud that appear above all objects
+    /** Startup LittleJS engine with your callback functions
+     *  @param {Function} gameInit       - Called once after the engine starts up, setup the game
+     *  @param {Function} gameUpdate     - Called every frame at 60 frames per second, handle input and update the game state
+     *  @param {Function} gameUpdatePost - Called after physics and objects are updated, setup camera and prepare for render
+     *  @param {Function} gameRender     - Called before objects are rendered, draw any background effects that appear behind objects
+     *  @param {Function} gameRenderPost - Called after objects are rendered, draw effects or hud that appear above all objects
      *  @param {Array} [imageSources=['tiles.png']] - Image to load
      *  @memberof Engine */
     export function engineInit(gameInit: Function, gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: any[]): void;
@@ -109,11 +109,11 @@ declare module "littlejs.esm" {
      *  @default
      *  @memberof Debug */
     export let showWatermark: boolean;
-    /** Asserts if the experssion is false, does not do anything in release builds
+    /** Asserts if the expression is false, does not do anything in release builds
      *  @param {Boolean} assert
-     *  @param {Object} output
+     *  @param {Object} [output]
      *  @memberof Debug */
-    export function ASSERT(assert: boolean, output: any): void;
+    export function ASSERT(assert: boolean, output?: any): void;
     /** Draw a debug rectangle in world space
      *  @param {Vector2} pos
      *  @param {Vector2} [size=Vector2()]
@@ -229,7 +229,7 @@ declare module "littlejs.esm" {
      *  @default
      *  @memberof Settings */
     export let enablePhysicsSolver: boolean;
-    /** Default object mass for collison calcuations (how heavy objects are)
+    /** Default object mass for collision calcuations (how heavy objects are)
      *  @type {Number}
      *  @default
      *  @memberof Settings */
@@ -306,7 +306,7 @@ declare module "littlejs.esm" {
      *  @default
      *  @memberof Settings */
     export let touchGamepadAnalog: boolean;
-    /** Size of virutal gamepad for touch devices in pixels
+    /** Size of virtual gamepad for touch devices in pixels
      *  @type {Number}
      *  @default
      *  @memberof Settings */
@@ -548,7 +548,7 @@ declare module "littlejs.esm" {
      *  @return {Number}
      *  @memberof Utilities */
     export function max(valueA: number, valueB: number): number;
-    /** Returns the sign of value passed in (also returns 1 if 0)
+    /** Returns the sign of value passed in
      *  @param {Number} value
      *  @return {Number}
      *  @memberof Utilities */
@@ -580,7 +580,7 @@ declare module "littlejs.esm" {
      *  @returns {Number}
      *  @memberof Utilities */
     export function distanceWrap(valueA: number, valueB: number, wrapSize?: number): number;
-    /** Linearly interpolates between values passed in with wrappping
+    /** Linearly interpolates between values passed in with wrapping
      *  @param {Number} percent
      *  @param {Number} valueA
      *  @param {Number} valueB
@@ -594,7 +594,7 @@ declare module "littlejs.esm" {
      *  @returns {Number}
      *  @memberof Utilities */
     export function distanceAngle(angleA: number, angleB: number): number;
-    /** Linearly interpolates between the angles passed in with wrappping
+    /** Linearly interpolates between the angles passed in with wrapping
      *  @param {Number} percent
      *  @param {Number} angleA
      *  @param {Number} angleB
@@ -619,13 +619,13 @@ declare module "littlejs.esm" {
      *  @memberof Utilities */
     export function nearestPowerOfTwo(value: number): number;
     /** Returns true if two axis aligned bounding boxes are overlapping
-     *  @param {Vector2} pointA - Center of box A
-     *  @param {Vector2} sizeA  - Size of box A
-     *  @param {Vector2} pointB - Center of box B
-     *  @param {Vector2} sizeB  - Size of box B
-     *  @return {Boolean}       - True if overlapping
+     *  @param {Vector2} pointA         - Center of box A
+     *  @param {Vector2} sizeA          - Size of box A
+     *  @param {Vector2} pointB         - Center of box B
+     *  @param {Vector2} [sizeB=(0,0)]  - Size of box B, a point if undefined
+     *  @return {Boolean}               - True if overlapping
      *  @memberof Utilities */
-    export function isOverlapping(pointA: Vector2, sizeA: Vector2, pointB: Vector2, sizeB: Vector2): boolean;
+    export function isOverlapping(pointA: Vector2, sizeA: Vector2, pointB: Vector2, sizeB?: Vector2): boolean;
     /** 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
@@ -668,8 +668,8 @@ declare module "littlejs.esm" {
      *  @memberof Random */
     export function randVector(length?: number): Vector2;
     /** Returns a random color between the two passed in colors, combine components if linear
-     *  @param {Color}   [colorA=Color()]
-     *  @param {Color}   [colorB=Color(0,0,0,1)]
+     *  @param {Color}   [colorA=(1,1,1,1)]
+     *  @param {Color}   [colorB=(0,0,0,1)]
      *  @param {Boolean} [linear]
      *  @return {Color}
      *  @memberof Random */
@@ -787,6 +787,10 @@ declare module "littlejs.esm" {
          * @param {Number} angle
          * @return {Vector2} */
         rotate(angle: number): Vector2;
+        /** Set the integer direction of this vector, corrosponding to multiples of 90 degree rotation (0-3)
+         * @param {Number} [direction]
+         * @param {Number} [length] */
+        setDirection(direction?: number, length?: number): Vector2;
         /** Returns the integer direction of this vector, corrosponding to multiples of 90 degree rotation (0-3)
          * @return {Number} */
         direction(): number;
@@ -819,8 +823,8 @@ declare module "littlejs.esm" {
      * let a = new Color;              // white
      * let b = new Color(1, 0, 0);     // red
      * let c = new Color(0, 0, 0, 0);  // transparent black
-     * let d = RGB(0, 0, 1);           // blue using rgb color
-     * let e = HSL(.3, 1, .5);         // green using hsl color
+     * let d = rgb(0, 0, 1);           // blue using rgb color
+     * let e = hsl(.3, 1, .5);         // green using hsl color
      */
     export class Color {
         /** Create a color with the rgba components passed in, white by default
@@ -952,7 +956,7 @@ declare module "littlejs.esm" {
      */
     export function vec2(x?: (number | Vector2), y?: number): Vector2;
     /**
-     * Create a color object with RGBA values
+     * Create a color object with RGBA values, white by default
      * @param {Number} [r=1] - red
      * @param {Number} [g=1] - green
      * @param {Number} [b=1] - blue
@@ -962,7 +966,7 @@ declare module "littlejs.esm" {
      */
     export function rgb(r?: number, g?: number, b?: number, a?: number): Color;
     /**
-     * Create a color object with HSLA values
+     * Create a color object with HSLA values, white by default
      * @param {Number} [h=0] - hue
      * @param {Number} [s=0] - saturation
      * @param {Number} [l=1] - lightness
@@ -1374,7 +1378,7 @@ declare module "littlejs.esm" {
      * @namespace Audio
      */
     /**
-     * Sound Object - Stores a zzfx sound for later use and can be played positionally
+     * Sound Object - Stores a sound for later use and can be played positionally
      *
      * <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
      * @example
@@ -1388,7 +1392,7 @@ declare module "littlejs.esm" {
         /** Create a sound object and cache the zzfx samples for later use
          *  @param {Array}  zzfxSound - Array of zzfx parameters, ex. [.5,.5]
          *  @param {Number} [range=soundDefaultRange] - World space max range of sound, will not play if camera is farther away
-         *  @param {Number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering off
+         *  @param {Number} [taper=soundDefaultTaper] - At what percentage of range should it start tapering
          */
         constructor(zzfxSound: any[], range?: number, taper?: number);
         /** @property {Number} - World space max range of sound, will not play if camera is farther away */
@@ -1489,18 +1493,18 @@ declare module "littlejs.esm" {
         sampleChannels: any[];
         /** Play the music
          *  @param {Number}  [volume=1] - How much to scale volume by
-         *  @param {Boolean} [loop=1] - True if the music should loop
+         *  @param {Boolean} [loop] - True if the music should loop
          *  @return {AudioBufferSourceNode} - The audio source node
          */
         playMusic(volume?: number, loop?: boolean): AudioBufferSourceNode;
     }
     /** Play an mp3, ogg, or wav audio from a local file or url
-     *  @param {String}  url - Location of sound file to play
+     *  @param {String}  filename - Location of sound file to play
      *  @param {Number}  [volume] - How much to scale volume by
      *  @param {Boolean} [loop] - True if the music should loop
      *  @return {HTMLAudioElement} - The audio element for this sound
      *  @memberof Audio */
-    export function playAudioFile(url: string, volume?: number, loop?: boolean): HTMLAudioElement;
+    export function playAudioFile(filename: string, volume?: number, loop?: boolean): HTMLAudioElement;
     /** 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)
@@ -1520,8 +1524,9 @@ declare module "littlejs.esm" {
      *  @memberof Audio */
     export function getNoteFrequency(semitoneOffset: number, rootFrequency?: number): number;
     /** Audio context used by the engine
+     *  @type {AudioContext}
      *  @memberof Audio */
-    export let audioContext: any;
+    export let audioContext: AudioContext;
     /** Play cached audio samples with given settings
      *  @param {Array}   sampleChannels - Array of arrays of samples to play (for stereo playback)
      *  @param {Number}  [volume] - How much to scale volume by
@@ -1548,7 +1553,7 @@ declare module "littlejs.esm" {
      * - 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
+     * - Can have color and additive color applied
      * - 2D Physics and collision system
      * - Sorted by renderOrder
      * - Objects can have children attached
@@ -1682,7 +1687,7 @@ declare module "littlejs.esm" {
     /**
      * LittleJS Tile Layer System
      * - Caches arrays of tiles to off screen canvas for fast rendering
-     * - Unlimted numbers of layers, allocates canvases as needed
+     * - Unlimited numbers of layers, allocates canvases as needed
      * - Interfaces with EngineObject for collision
      * - Collision layer is separate from visible layers
      * - It is recommended to have a visible layer that matches the collision
@@ -1714,7 +1719,7 @@ declare module "littlejs.esm" {
     export function getTileCollisionData(pos: Vector2): number;
     /** Check if collision with another object should occur
      *  @param {Vector2}      pos
-     *  @param {Vector2}      [size=(1,1)]
+     *  @param {Vector2}      [size=(0,0)]
      *  @param {EngineObject} [object]
      *  @return {Boolean}
      *  @memberof TileCollision */
@@ -1842,12 +1847,12 @@ declare module "littlejs.esm" {
      * @example
      * // create a particle emitter
      * let pos = vec2(2,3);
-     * let particleEmiter = new ParticleEmitter
+     * let particleEmitter = new ParticleEmitter
      * (
-     *     pos, 0, 1, 0, 500, PI,  // pos, angle, emitSize, emitTime, emitRate, emiteCone
-     *     tile(0, 16),            // tileInfo
-     *     new Color(1,1,1),   new Color(0,0,0),   // colorStartA, colorStartB
-     *     new Color(1,1,1,0), new Color(0,0,0,0), // colorEndA, colorEndB
+     *     pos, 0, 1, 0, 500, PI,      // pos, angle, emitSize, emitTime, emitRate, emiteCone
+     *     tile(0, 16),                // tileInfo
+     *     rgb(1,1,1),   rgb(0,0,0),   // colorStartA, colorStartB
+     *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
      *     2, .2, .2, .1, .05,  // particleTime, sizeStart, sizeEnd, particleSpeed, particleAngleSpeed
      *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate,
      *     .5, 1                // randomness, collide, additive, randomColorLinear, renderOrder