littlejsengine 1.10.2 → 1.10.7

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
 
@@ -24,13 +24,13 @@ 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) | [Quick Reference](https://github.com/KilledByAPixel/LittleJS/blob/main/reference.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) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md)
 
 </div>
 
 ![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/)
 
@@ -83,13 +83,11 @@ To get started download the latest LittleJS package from GitHub or install via n
 
 This is because web browsers just have protection from loading local files. You may see a console error like "The image element contains cross-origin data." Don't panic, it's easy to fix! If you are using [Visual Studio Code](https://code.visualstudio.com/) there is a [Live Preview Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) that will handle this for you automatically. Another option is to setup a simple local web server like [http-server](https://www.npmjs.com/package/http-server) via npm.
 
-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!
+- 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!
+- [Check out The Little JS FAQ for more help getting started](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md), and let us know if there's anything you'd like to see added.
 
 ## Examples
 
@@ -102,6 +100,7 @@ These demos are for both learning and using as starter projects to create your o
 - [Box2D Demo](https://killedbyapixel.github.io/LittleJS/examples/box2d/) - Box2D plugin demonstration and testbed
 - [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
+- [All Examples](https://killedbyapixel.github.io/LittleJS/examples/) - Links to all the example projects on one page
 
 ## Builds
 
@@ -117,93 +116,18 @@ 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.
 
-- Esc: Debug Overlay
-- 1: Debug Physics
-- 2: Debug Particles
-- 3: Debug Gamepads
-- 4: Debug Raycasts
-- 5: Save Screenshot
-
 ## Games Made With LittleJS
 
 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)
@@ -212,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=['tiles.png']] - 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;
@@ -700,7 +700,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 +876,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 +969,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 +1116,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;
@@ -1245,6 +1252,37 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function drawLine(posA: Vector2, posB: Vector2, thickness?: number, color?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    /** Draw colored polygon using passed in points
+     *  @param {Array}   points - Array of Vector2 points
+     *  @param {Color}   [color=(1,1,1,1)]
+     *  @param {Number}  [lineWidth=0]
+     *  @param {Color}   [lineColor=(0,0,0,1)]
+     *  @param {Boolean} [screenSpace=false]
+     *  @param {CanvasRenderingContext2D} [context=mainContext]
+     *  @memberof Draw */
+    export function drawPoly(points: any[], color?: Color, lineWidth?: number, lineColor?: Color, screenSpace?: boolean, context?: CanvasRenderingContext2D): void;
+    /** Draw colored ellipse using passed in point
+     *  @param {Vector2} pos
+     *  @param {Number}  [width=1]
+     *  @param {Number}  [height=1]
+     *  @param {Number}  [angle=0]
+     *  @param {Color}   [color=(1,1,1,1)]
+     *  @param {Number}  [lineWidth=0]
+     *  @param {Color}   [lineColor=(0,0,0,1)]
+     *  @param {Boolean} [screenSpace=false]
+     *  @param {CanvasRenderingContext2D} [context=mainContext]
+     *  @memberof Draw */
+    export function drawEllipse(pos: Vector2, width?: number, height?: number, angle?: number, color?: Color, lineWidth?: number, lineColor?: Color, screenSpace?: boolean, context?: CanvasRenderingContext2D): void;
+    /** Draw colored circle using passed in point
+     *  @param {Vector2} pos
+     *  @param {Number}  [radius=1]
+     *  @param {Color}   [color=(1,1,1,1)]
+     *  @param {Number}  [lineWidth=0]
+     *  @param {Color}   [lineColor=(0,0,0,1)]
+     *  @param {Boolean} [screenSpace=false]
+     *  @param {CanvasRenderingContext2D} [context=mainContext]
+     *  @memberof Draw */
+    export function drawCircle(pos: Vector2, radius?: number, color?: Color, lineWidth?: number, lineColor?: Color, screenSpace?: boolean, context?: CanvasRenderingContext2D): void;
     /** Draw directly to a 2d canvas context in world space
      *  @param {Vector2}  pos
      *  @param {Vector2}  size
@@ -1403,6 +1441,23 @@ declare module "littlejsengine" {
      *  @param {WebGLTexture} texture
      *  @memberof WebGL */
     export function glSetTexture(texture: WebGLTexture): void;
+    /** Set antialiasing for webgl canvas
+     *  @param {Boolean} [antialias]
+     *  @memberof WebGL */
+    export function glSetAntialias(antialias?: boolean): void;
+    /** Shoule webgl be setup with antialiasing, must be set before calling engineInit
+     *  @type {Boolean}
+     *  @memberof WebGL */
+    export let glAntialias: boolean;
+    export let glShader: any;
+    export let glActiveTexture: any;
+    export let glArrayBuffer: any;
+    export let glGeometryBuffer: any;
+    export let glPositionData: any;
+    export let glColorData: any;
+    export let glInstanceCount: any;
+    export let glAdditive: any;
+    export let glBatchAdditive: any;
     /**
      * LittleJS Input System
      * - Tracks keyboard down, pressed, and released
@@ -1540,6 +1595,8 @@ declare module "littlejsengine" {
         taper: number;
         /** @property {Number} - How much to randomize frequency each time sound plays */
         randomness: any;
+        /** @property {GainNode} - Gain node for this sound */
+        gainNode: GainNode;
         sampleChannels: any[][];
         sampleRate: number;
         /** Play the sound
@@ -1551,7 +1608,6 @@ declare module "littlejsengine" {
          *  @return {AudioBufferSourceNode} - The audio source node
          */
         play(pos?: Vector2, volume?: number, pitch?: number, randomnessScale?: number, loop?: boolean): AudioBufferSourceNode;
-        gainNode: GainNode;
         source: AudioBufferSourceNode;
         /** Set the sound volume
          *  @param {Number}  [volume] - How much to scale volume by
@@ -1866,24 +1922,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 */
@@ -1895,7 +1951,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]
@@ -2197,14 +2254,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
          */