littlejsengine 1.10.4 → 1.11.1

package/README.md

@@ -14,9 +14,9 @@
 
 ## 🚂 All aboard!
 
-LittleJS is a fast lightweight open source HTML5 game engine for modern web development.
-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!
+LittleJS is a fast, lightweight, and fully open source HTML5 game engine designed for simplicity and performance.
+Its small footprint is packed with a comprehensive feature set including hybrid rendering, physics, particles, sound, and input handling.
+The code is clean and well documented with some fun examples to get you started right away. Choo-Choo!
 
 ### 🚀 Join the First Ever LittleJS Game Jam
 
@@ -30,7 +30,7 @@ The code is very clean and well documented with some fun examples to get you sta
 
 ![LittleJS Screenshot](examples/screenshot.jpg)
 
-## About LittleJS
+## About LittleJS Engine
 
 LittleJS is a small but powerful game engine with many features and no dependencies.
 
@@ -43,7 +43,7 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 ### 🔊 Audio
 
-- Positional sound effects with wave files or ZzFX
+- Positional sound effects with wave files, mp3s, or ZzFX
 - Use [ZzFX](https://killedbyapixel.github.io/ZzFX/) sound effect generator to play sounds without asset files
 - Music with mp3, ogg, wave, or [ZzFXM](https://keithclark.github.io/ZzFXM/)
 
@@ -116,76 +116,6 @@ To rebuild the engine you must first run ```npm install``` to setup the necessar
 
 The starter example project includes a node js file [build.js](https://github.com/KilledByAPixel/LittleJS/blob/main/examples/starter/build.js) that compresses everything into a tiny zip file using Google Closure, UglifyJS, and ECT Zip.
 
-## LittleJS Setup
-
-To start LittleJS, you need to create these 5 functions and pass them to engineInit.
-
-```javascript
-function gameInit()
-{
-    // called once after the engine starts up
-    // setup the game
-}
-
-function gameUpdate()
-{
-    // called every frame at 60 frames per second
-    // handle input and update the game state
-}
-
-function gameUpdatePost()
-{
-    // called after physics and objects are updated
-    // setup camera and prepare for render
-}
-
-function gameRender()
-{
-    // called before objects are rendered
-    // draw any background effects that appear behind objects
-}
-
-function gameRenderPost()
-{
-    // called after objects are rendered
-    // draw effects or hud that appear above all objects
-}
-
-// Startup LittleJS Engine
-engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
-```
-
-## LittleJS Objects
-
-LittleJS can be used as an object oriented system by extending the base class [EngineObject](https://github.com/KilledByAPixel/LittleJS/blob/main/src/engineObject.js) with your own. This lightweight class provides many useful features including physics, collision, parent/child system, and sorted rendering. These objects are added to the global list of objects where they will automatically be updated and rendered until destroyed. 
-
-Here is a template you can use to make objects that behave however you want. See the examples for a complete demonstration.
-
-```javascript
-class MyObject extends EngineObject 
-{
-    constructor(pos, size, tileInfo, angle)
-    {
-        super(pos, size, tileInfo, angle);
-        // setup object
-    }
-
-    update()
-    {
-        // update object physics and position
-        super.update(); 
-    }
-
-    render()
-    {
-        // draw object as a sprite
-        super.render();
-    }
-}
-```
-
-## Debugging
-
 Debug builds of LittleJS have a special menu that can be opened by pressing the Esc key.
 
 ## Games Made With LittleJS
@@ -194,8 +124,10 @@ Here are a few of the amazing games people made using LittleJS...
 
 - [Space Huggers](https://github.com/KilledByAPixel/SpaceHuggers) - Original js13k game with source code by [KilledByAPixel](https://frankforce.com/)
 - [Undergrowth](https://undergrowth.squidband.uk/) - An interactive music videogame for the band Squid by [KilledByAPixel](https://frankforce.com/)
-- [Isletopia](https://store.steampowered.com/app/1861260/Isletopia) - Relaxing strategy game of greenifying barren islands by [Gamex Studio](https://x.com/gamesgamex)
+- [The Way of the Dodo](https://js13kgames.com/2024/games/the-way-of-the-dodo) - Single button platformer by [repsej](https://github.com/repsej)
+- [Wendol Village](https://js13kgames.com/2024/games/wendol-village) - Warcraft-like RTS game by [sanojian](https://github.com/sanojian)
 - [Dead Again](https://js13kgames.com/entries/dead-again) - Top down survial horror by [sanojian & repsej](https://github.com/sanojian/js13k_2022)
+- [Isletopia](https://store.steampowered.com/app/1861260/Isletopia) - Relaxing strategy game of greenifying barren islands by [Gamex Studio](https://x.com/gamesgamex)
 - [Hel's Trial](https://js13kgames.com/entries/hels-trial) - Turn based RPG by [Sebastian Dorn](https://github.com/sebadorn/js13k-2022-death)
 - [Bit Butcher](https://js13kgames.com/entries/bit-butcher) - Survival crafting game by [Deathray Games](https://github.com/deathraygames/bit-butcher)
 - [Necrotic Commander](https://js13kgames.com/entries/necrotic-commander) - Tower defense game by [Daniel Jeffery](https://github.com/d-jeffery/NecroticCommander)
@@ -204,8 +136,6 @@ Here are a few of the amazing games people made using LittleJS...
 - [brrr!](https://snowfrog.itch.io/brrr) - Base defense and shooting game by [Snowfrog](https://www.snowfrog.dev/)
 - [Wands of Triskaidekai](https://js13kgames.com/2024/games/wands-of-triskaidekai) - Platformer with experimental gameplay by [gregwoodsfrontier](https://github.com/gregwoodsfrontier)
 - [Data Warrior: 13kb limit](https://js13kgames.com/2024/games/data-warrior-13kb-limit) - Vampire Survivors-like game by [rndD](https://github.com/rndD)
-- [The Way of the Dodo](https://js13kgames.com/2024/games/the-way-of-the-dodo) - Single button platformer by [repsej](https://github.com/repsej)
-- [Wendol Village](https://js13kgames.com/2024/games/wendol-village) - Warcraft-like RTS game by [sanojian](https://github.com/sanojian)
 - [Unblock](https://js13kgames.com/games/unblock) - Retro style space shooter by [Isaac Benitez](https://github.com/isacben)
 
 ![LittleJS Logo](examples/favicon.png)

package/dist/littlejs.d.ts

@@ -64,15 +64,15 @@ declare module "littlejsengine" {
      *  @memberof Engine */
     export function setPaused(isPaused: boolean): void;
     /** 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=[]] - Image to load
+     *  @param {Function|function():Promise} gameInit - Called once after the engine starts up
+     *  @param {Function} gameUpdate - Called every frame before objects are updated
+     *  @param {Function} gameUpdatePost - Called after physics and objects are updated, even when paused
+     *  @param {Function} gameRender - Called before objects are rendered, for drawing the background
+     *  @param {Function} gameRenderPost - Called after objects are rendered, useful for drawing UI
+     *  @param {Array} [imageSources=[]] - List of images to load
      *  @param {HTMLElement} [rootElement] - Root element to attach to, the document body by default
      *  @memberof Engine */
-    export function engineInit(gameInit: Function, gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: any[], rootElement?: HTMLElement): void;
+    export function engineInit(gameInit: Function | (() => Promise<any>), gameUpdate: Function, gameUpdatePost: Function, gameRender: Function, gameRenderPost: Function, imageSources?: any[], rootElement?: HTMLElement): void;
     /** Update each engine object, remove destroyed objects, and update time
      *  @memberof Engine */
     export function engineObjectsUpdate(): void;
@@ -232,11 +232,16 @@ declare module "littlejsengine" {
      *  @default Vector2()
      *  @memberof Settings */
     export let canvasFixedSize: Vector2;
-    /** Disables filtering for crisper pixel art if true
+    /** Use nearest neighbor scaling algorithm for canvas for more pixelated look
      *  @type {Boolean}
      *  @default
      *  @memberof Settings */
     export let canvasPixelated: boolean;
+    /** Disables texture filtering for crisper pixel art
+     *  @type {Boolean}
+     *  @default
+     *  @memberof Settings */
+    export let tilesPixelated: boolean;
     /** Default font used for text rendering
      *  @type {String}
      *  @default
@@ -415,10 +420,14 @@ declare module "littlejsengine" {
      *  @param {Vector2} size
      *  @memberof Settings */
     export function setCanvasFixedSize(size: Vector2): void;
-    /** Disables anti aliasing for pixel art if true
+    /** Use nearest neighbor scaling algorithm for canvas for more pixelated look
      *  @param {Boolean} pixelated
      *  @memberof Settings */
     export function setCanvasPixelated(pixelated: boolean): void;
+    /** Disables texture filtering for crisper pixel art
+     *  @param {Boolean} pixelated
+     *  @memberof Settings */
+    export function setTilesPixelated(pixelated: boolean): void;
     /** Set default font used for text rendering
      *  @param {String} font
      *  @memberof Settings */
@@ -700,7 +709,8 @@ declare module "littlejsengine" {
      *  @return {Number}
      *  @memberof Random */
     export function rand(valueA?: number, valueB?: number): number;
-    /** Returns a floored random value the two values passed in
+    /** Returns a floored random value between the two values passed in
+     *  The upper bound is exclusive. (If 2 is passed in, result will be 0 or 1)
      *  @param {Number} valueA
      *  @param {Number} [valueB]
      *  @return {Number}
@@ -875,6 +885,9 @@ declare module "littlejsengine" {
          * @param {Number} digits - precision to display
          * @return {String} */
         toString(digits?: number): string;
+        /** Checks if this is a valid vector
+         * @return {Boolean} */
+        isValid(): boolean;
     }
     /**
      * Color object (red, green, blue, alpha) with some helpful functions
@@ -965,6 +978,9 @@ declare module "littlejsengine" {
         /** Returns this color expressed as 32 bit RGBA value
          * @return {Number} */
         rgbaInt(): number;
+        /** Checks if this is a valid color
+         * @return {Boolean} */
+        isValid(): boolean;
     }
     /**
      * Timer object tracks how long has passed since it was set
@@ -1109,7 +1125,7 @@ declare module "littlejsengine" {
      * tile(2)                       // a tile at index 2 using the default tile size of 16
      * tile(5, 8)                    // a tile at index 5 using a tile size of 8
      * tile(1, 16, 3)                // a tile at index 1 of size 16 on texture 3
-     * tile(vec2(4,8), vec2(30,10))  // a tile at pixel location (4,8) with a size of (30,10)
+     * tile(vec2(4,8), vec2(30,10))  // a tile at index (4,8) with a size of (30,10)
      * @memberof Draw
      */
     export function tile(pos?: (number | Vector2), size?: (number | Vector2), textureIndex?: number, padding?: number): TileInfo;
@@ -1292,7 +1308,7 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=mainContext]
      *  @memberof Draw */
     export function setBlendMode(additive?: boolean, useWebGL?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-    /** Draw text on overlay canvas in screen space
+    /** Draw text on main canvas in world space
      *  Automatically splits new lines into rows
      *  @param {String}  text
      *  @param {Vector2} pos
@@ -1300,12 +1316,12 @@ declare module "littlejsengine" {
      *  @param {Color}   [color=(1,1,1,1)]
      *  @param {Number}  [lineWidth]
      *  @param {Color}   [lineColor=(0,0,0,1)]
-     *  @param {CanvasTextAlign}  [textAlign]
+     *  @param {CanvasTextAlign}  [textAlign='center']
      *  @param {String}  [font=fontDefault]
-     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
      *  @param {Number}  [maxWidth]
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=mainContext]
      *  @memberof Draw */
-    export function drawTextScreen(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, maxWidth?: number): void;
+    export function drawText(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, maxWidth?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     /** Draw text on overlay canvas in world space
      *  Automatically splits new lines into rows
      *  @param {String}  text
@@ -1316,10 +1332,23 @@ declare module "littlejsengine" {
      *  @param {Color}   [lineColor=(0,0,0,1)]
      *  @param {CanvasTextAlign}  [textAlign='center']
      *  @param {String}  [font=fontDefault]
-     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
      *  @param {Number}  [maxWidth]
      *  @memberof Draw */
-    export function drawText(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, maxWidth?: number): void;
+    export function drawTextOverlay(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, maxWidth?: number): void;
+    /** Draw text on overlay canvas in screen space
+     *  Automatically splits new lines into rows
+     *  @param {String}  text
+     *  @param {Vector2} pos
+     *  @param {Number}  [size]
+     *  @param {Color}   [color=(1,1,1,1)]
+     *  @param {Number}  [lineWidth]
+     *  @param {Color}   [lineColor=(0,0,0,1)]
+     *  @param {CanvasTextAlign}  [textAlign]
+     *  @param {String}  [font=fontDefault]
+     *  @param {Number}  [maxWidth]
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
+     *  @memberof Draw */
+    export function drawTextScreen(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, maxWidth?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     export let engineFontImage: any;
     /**
      * Font Image Object - Draw text on a 2D canvas by using characters in an image
@@ -1601,7 +1630,7 @@ declare module "littlejsengine" {
         play(pos?: Vector2, volume?: number, pitch?: number, randomnessScale?: number, loop?: boolean): AudioBufferSourceNode;
         gainNode: GainNode;
         source: AudioBufferSourceNode;
-        /** Set the sound volume
+        /** Set the sound volume of the most recently played instance of this sound
          *  @param {Number}  [volume] - How much to scale volume by
          */
         setVolume(volume?: number): void;
@@ -1914,24 +1943,24 @@ declare module "littlejsengine" {
      * - Drawn directly to the main canvas without using WebGL
      * @namespace TileCollision
      */
-    /** The tile collision layer array, use setTileCollisionData and getTileCollisionData to access
+    /** The tile collision layer grid, use setTileCollisionData and getTileCollisionData to access
      *  @type {Array}
      *  @memberof TileCollision */
     export let tileCollision: any[];
-    /** Size of the tile collision layer
+    /** Size of the tile collision layer 2d grid
      *  @type {Vector2}
      *  @memberof TileCollision */
     export let tileCollisionSize: Vector2;
     /** Clear and initialize tile collision
-     *  @param {Vector2} size
+     *  @param {Vector2} size - width and height of tile collision 2d grid
      *  @memberof TileCollision */
     export function initTileCollision(size: Vector2): void;
-    /** Set tile collision data
+    /** Set tile collision data for a given cell in the grid
      *  @param {Vector2} pos
      *  @param {Number}  [data]
      *  @memberof TileCollision */
     export function setTileCollisionData(pos: Vector2, data?: number): void;
-    /** Get tile collision data
+    /** Get tile collision data for a given cell in the grid
      *  @param {Vector2} pos
      *  @return {Number}
      *  @memberof TileCollision */
@@ -1943,7 +1972,8 @@ declare module "littlejsengine" {
      *  @return {Boolean}
      *  @memberof TileCollision */
     export function tileCollisionTest(pos: Vector2, size?: Vector2, object?: EngineObject): boolean;
-    /** Return the center of first tile hit (does not return the exact intersection)
+    /** Return the center of first tile hit, undefined if nothing was hit.
+     *  This does not return the exact intersection, but the center of the tile hit.
      *  @param {Vector2}      posStart
      *  @param {Vector2}      posEnd
      *  @param {EngineObject} [object]
@@ -2245,14 +2275,19 @@ declare module "littlejsengine" {
          *  @param {String} [src]         - Image location for the medal
          */
         constructor(id: number, name: string, description?: string, icon?: string, src?: string);
+        /** @property {Number} - The unique identifier of the medal */
         id: number;
+        /** @property {String} - Name of the medal */
         name: string;
+        /** @property {String} - Description of the medal */
         description: string;
+        /** @property {String} - Icon for the medal */
         icon: string;
+        /** @property {Boolean} - Is the medal unlocked? */
+        unlocked: boolean;
         image: HTMLImageElement;
         /** Unlocks a medal if not already unlocked */
         unlock(): void;
-        unlocked: number;
         /** Render a medal
          *  @param {Number} [hidePercent] - How much to slide the medal off screen
          */