littlejsengine 1.9.6 → 1.9.8

package/LICENSE

@@ -19,3 +19,25 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+-------------------------------------------------------------------------------
+
+This project uses the Box2D physics engine, which is licensed under the zlib license.
+Copyright (c) 2006 Erin Catto (Box2D)
+Copyright (c) 2011 The box2d.js contributors
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.

package/README.md

@@ -86,14 +86,15 @@ Learn how to make a simple game from scratch with [The Breakout Tutorial.](https
 
 Join our vibrant community on [Discord](https://discord.gg/zb7hcGkyZe) to get help, share your projects, and collaborate with others!
 
-## Demos
+## Examples
 
-These examples are for both learning and using as starter projects to create your own games.
+These demos are for both learning and using as starter projects to create your own games.
 
 - [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 level data from [Tiled Editor](https://github.com/mapeditor/tiled)
+- [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
 
@@ -194,16 +195,20 @@ Debug builds of LittleJS have a special menu that can be opened by pressing the
 
 Here are a few of the amazing games people made using LittleJS...
 
-- [Space Huggers](https://www.newgrounds.com/portal/view/819609) - Run and gun platformer with procedural levels
-- [Undergrowth](https://undergrowth.squidband.uk/) - An interactive music videogame for the band Squid
-- [Space Huggers - JS13K Edition](https://github.com/KilledByAPixel/SpaceHuggers) - Original js13k game with source code
-- [Isletopia](https://store.steampowered.com/app/1861260/Isletopia) - Relaxing strategy game of greenifying barren islands
+- [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)
 - [Dead Again](https://js13kgames.com/entries/dead-again) - Top down survial horror by [sanojian & repsej](https://github.com/sanojian/js13k_2022)
 - [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)
-- [Boxing up Bamboo](https://patrickgh3.itch.io/boxing-up-bamboo) - A challenging puzzle game by [Patrick Traynor](https://cwpat.me/about)
-- [Samurai Sam](https://dev.js13kgames.com/2023/games/samurai-sam) - A Fruit Ninja inspired game by [John Edvard](https://reitgames.com)
+- [Boxing up Bamboo](https://patrickgh3.itch.io/boxing-up-bamboo) - Challenging puzzle game by [Patrick Traynor](https://cwpat.me/about)
+- [Samurai Sam](https://dev.js13kgames.com/2023/games/samurai-sam) - Fruit Ninja inspired rhythm game by [John Edvard](https://reitgames.com)
+- [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)
 
 ![LittleJS Logo](examples/favicon.png)
 

package/dist/littlejs.d.ts

@@ -123,6 +123,15 @@ declare module "littlejsengine" {
      *  @param {Boolean} [fill]
      *  @memberof Debug */
     export function debugRect(pos: Vector2, size?: Vector2, color?: string, time?: number, angle?: number, fill?: boolean): void;
+    /** Draw a debug poly in world space
+     *  @param {Vector2} pos
+     *  @param {Array}   points
+     *  @param {String}  [color]
+     *  @param {Number}  [time]
+     *  @param {Number}  [angle]
+     *  @param {Boolean} [fill]
+     *  @memberof Debug */
+    export function debugPoly(pos: Vector2, points: any[], color?: string, time?: number, angle?: number, fill?: boolean): void;
     /** Draw a debug circle in world space
      *  @param {Vector2} pos
      *  @param {Number}  [radius]
@@ -146,14 +155,14 @@ declare module "littlejsengine" {
      *  @param {Number}  [time]
      *  @memberof Debug */
     export function debugLine(posA: Vector2, posB: Vector2, color?: string, thickness?: number, time?: number): void;
-    /** Draw a debug axis aligned bounding box in world space
+    /** Draw a debug combined axis aligned bounding box in world space
      *  @param {Vector2} pA - position A
      *  @param {Vector2} sA - size A
      *  @param {Vector2} pB - position B
      *  @param {Vector2} sB - size B
      *  @param {String}  [color]
      *  @memberof Debug */
-    export function debugAABB(pA: Vector2, sA: Vector2, pB: Vector2, sB: Vector2, color?: string): void;
+    export function debugOverlap(pA: Vector2, sA: Vector2, pB: Vector2, sB: Vector2, color?: string): void;
     /** Draw a debug axis aligned bounding box in world space
      *  @param {String}  text
      *  @param {Vector2} pos
@@ -173,6 +182,17 @@ declare module "littlejsengine" {
      *  @param {String}            [type]
      *  @memberof Debug */
     export function debugSaveCanvas(canvas: HTMLCanvasElement, filename?: string, type?: string): void;
+    /** Save a text file to disk
+     *  @param {String}     text
+     *  @param {String}     [filename]
+     *  @param {String}     [type]
+     *  @memberof Debug */
+    export function debugSaveText(text: string, filename?: string, type?: string): void;
+    /** Save a data url to disk
+     *  @param {String}     dataURL
+     *  @param {String}     filename
+     *  @memberof Debug */
+    export function debugSaveDataURL(dataURL: string, filename: string): void;
     /**
      * LittleJS Engine Settings
      * - All settings for the engine are here
@@ -190,7 +210,7 @@ declare module "littlejsengine" {
     export let cameraScale: number;
     /** The max size of the canvas, centered if window is larger
      *  @type {Vector2}
-     *  @default Vector2(1920,1200)
+     *  @default Vector2(1920,1080)
      *  @memberof Settings */
     export let canvasMaxSize: Vector2;
     /** Fixed size of the canvas, if enabled canvas size never changes
@@ -731,6 +751,11 @@ declare module "littlejsengine" {
         x: number;
         /** @property {Number} - Y axis location */
         y: number;
+        /** Sets values of this vector and returns self
+         *  @param {Number} [x] - X axis location
+         *  @param {Number} [y] - Y axis location
+         *  @return {Vector2} */
+        set(x?: number, y?: number): Vector2;
         /** Returns a new vector that is a copy of this
          *  @return {Vector2} */
         copy(): Vector2;
@@ -850,6 +875,13 @@ declare module "littlejsengine" {
         b: number;
         /** @property {Number} - Alpha */
         a: number;
+        /** Sets values of this color and returns self
+         *  @param {Number} [r] - red
+         *  @param {Number} [g] - green
+         *  @param {Number} [b] - blue
+         *  @param {Number} [a] - alpha
+         *  @return {Color} */
+        set(r?: number, g?: number, b?: number, a?: number): Color;
         /** Returns a new color that is a copy of this
          * @return {Color} */
         copy(): Color;
@@ -897,7 +929,7 @@ declare module "littlejsengine" {
          * @param {Number} [alphaAmount]
          * @return {Color} */
         mutate(amount?: number, alphaAmount?: number): Color;
-        /** Returns this color expressed as a rgb color code
+        /** Returns this color expressed as a hex color code
          * @param {Boolean} [useAlpha] - if alpha should be included in result
          * @return {String} */
         toString(useAlpha?: boolean): string;
@@ -1224,6 +1256,10 @@ declare module "littlejsengine" {
     /** Toggle fullsceen mode
      *  @memberof Draw */
     export function toggleFullscreen(): void;
+    /** Get the camera's visible area in world space
+     *  @return {Vector2}
+     *  @memberof Draw */
+    export function getCameraSize(): Vector2;
     /**
      * LittleJS WebGL Interface
      * - All webgl used by the engine is wrapped up here
@@ -1265,11 +1301,6 @@ declare module "littlejsengine" {
      *  @return {WebGLTexture}
      *  @memberof WebGL */
     export function glCreateTexture(image: HTMLImageElement): WebGLTexture;
-    /** Set up a post processing shader
-     *  @param {String} shaderCode
-     *  @param {Boolean} includeOverlay
-     *  @memberof WebGL */
-    export function glInitPostProcess(shaderCode: string, includeOverlay?: boolean): void;
     /**
      * LittleJS Input System
      * - Tracks keyboard down, pressed, and released
@@ -1381,16 +1412,6 @@ declare module "littlejsengine" {
     /** True if a touch device has been detected
      *  @memberof Input */
     export const isTouchDevice: boolean;
-    /**
-     * LittleJS Audio System
-     * - <a href=https://killedbyapixel.github.io/ZzFX/>ZzFX Sound Effects</a> - ZzFX Sound Effect Generator
-     * - <a href=https://keithclark.github.io/ZzFXM/>ZzFXM Music</a> - ZzFXM Music System
-     * - Caches sounds and music for fast playback
-     * - Can attenuate and apply stereo panning to sounds
-     * - Ability to play mp3, ogg, and wave files
-     * - Speech synthesis functions
-     * @namespace Audio
-     */
     /**
      * Sound Object - Stores a sound for later use and can be played positionally
      *
@@ -1426,7 +1447,12 @@ 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
+         */
+        setVolume(volume?: number): void;
         /** Stop the last instance of this sound that was played */
         stop(): void;
         /** Get source of most recent instance of this sound that was played
@@ -1465,9 +1491,9 @@ declare module "littlejsengine" {
          *  @param {Number} [randomness] - How much to randomize frequency each time sound plays
          *  @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 {Function} [onloadCallback] - callback function to call when sound is loaded
          */
-        constructor(filename: string, randomness?: number, range?: number, taper?: number);
-        randomness: number;
+        constructor(filename: string, randomness?: number, range?: number, taper?: number, onloadCallback?: Function);
     }
     /**
      * Music Object - Stores a zzfx music track for later use
@@ -1516,9 +1542,9 @@ declare module "littlejsengine" {
      *  @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
+     *  @return {SoundWave} - The sound object for this file
      *  @memberof Audio */
-    export function playAudioFile(filename: string, volume?: number, loop?: boolean): HTMLAudioElement;
+    export function playAudioFile(filename: string, volume?: number, loop?: boolean): SoundWave;
     /** 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)
@@ -1537,20 +1563,31 @@ declare module "littlejsengine" {
      *  @return {Number} - The frequency of the note
      *  @memberof Audio */
     export function getNoteFrequency(semitoneOffset: number, rootFrequency?: number): number;
+    /**
+     * LittleJS Audio System
+     * - <a href=https://killedbyapixel.github.io/ZzFX/>ZzFX Sound Effects</a> - ZzFX Sound Effect Generator
+     * - <a href=https://keithclark.github.io/ZzFXM/>ZzFXM Music</a> - ZzFXM Music System
+     * - Caches sounds and music for fast playback
+     * - Can attenuate and apply stereo panning to sounds
+     * - Ability to play mp3, ogg, and wave files
+     * - Speech synthesis functions
+     * @namespace Audio
+     */
     /** Audio context used by the engine
      *  @type {AudioContext}
      *  @memberof Audio */
     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
-     *  @param {Number}  [rate] - The playback rate to use
-     *  @param {Number}  [pan] - How much to apply stereo panning
-     *  @param {Boolean} [loop] - True if the sound should loop when it reaches the end
-     *  @param {Number}  [sampleRate=44100] - Sample rate for the sound
+     *  @param {Array}    sampleChannels - Array of arrays of samples to play (for stereo playback)
+     *  @param {Number}   [volume] - How much to scale volume by
+     *  @param {Number}   [rate] - The playback rate to use
+     *  @param {Number}   [pan] - How much to apply stereo panning
+     *  @param {Boolean}  [loop] - True if the sound should loop when it reaches the end
+     *  @param {Number}   [sampleRate=44100] - Sample rate for the sound
+     *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing
      *  @return {AudioBufferSourceNode} - The audio node of the sound played
      *  @memberof Audio */
-    export function playSamples(sampleChannels: any[], volume?: number, rate?: number, pan?: number, loop?: boolean, sampleRate?: number): AudioBufferSourceNode;
+    export function playSamples(sampleChannels: any[], volume?: number, rate?: number, pan?: number, loop?: boolean, sampleRate?: number, gainNode?: GainNode): AudioBufferSourceNode;
     /** Generate and play a ZzFX sound
      *
      *  <a href=https://killedbyapixel.github.io/ZzFX/>Create sounds using the ZzFX Sound Designer.</a>
@@ -1634,6 +1671,8 @@ declare module "littlejsengine" {
         spawnTime: number;
         /** @property {Array}   - List of children of this object */
         children: any[];
+        /** @property {Boolean}  - Limit object speed using linear or circular math */
+        clampSpeedLinear: boolean;
         /** @property {EngineObject} - Parent of object if in local space  */
         parent: any;
         /** @property {Vector2}      - Local position if child */
@@ -1658,6 +1697,18 @@ declare module "littlejsengine" {
         /** Destroy this object, destroy it's children, detach it's parent, and mark it for removal */
         destroy(): void;
         destroyed: number;
+        /** Convert from local space to world space
+         *  @param {Vector2} pos - local space point */
+        localToWorld(pos: Vector2): Vector2;
+        /** Convert from world space to local space
+         *  @param {Vector2} pos - world space point */
+        worldToLocal(pos: Vector2): Vector2;
+        /** Convert from local space to world space for a vector (rotation only)
+         *  @param {Vector2} vec - local space vector */
+        localToWorldVector(vec: Vector2): Vector2;
+        /** Convert from world space to local space for a vector (rotation only)
+         *  @param {Vector2} vec - world space vector */
+        worldToLocalVector(vec: Vector2): Vector2;
         /** Called to check if a tile collision should be resolved
          *  @param {Number}  tileData - the value of the tile at the position
          *  @param {Vector2} pos      - tile where the collision occured
@@ -1697,6 +1748,8 @@ declare module "littlejsengine" {
         /** Returns string containg info about this object for debugging
          *  @return {String} */
         toString(): string;
+        /** Render debug info for this object  */
+        renderDebugInfo(): void;
     }
     /**
      * LittleJS Tile Layer System
@@ -2005,9 +2058,9 @@ declare module "littlejsengine" {
      * @namespace Medals
      */
     /** List of all medals
-     *  @type {Array}
+     *  @type {Object}
      *  @memberof Medals */
-    export const medals: any[];
+    export const medals: any;
     /** Set to stop medals from being unlockable (like if cheats are enabled)
      *  @type {Boolean}
      *  @default
@@ -2019,12 +2072,6 @@ declare module "littlejsengine" {
      *  @param {String} saveName
      *  @memberof Medals */
     export function medalsInit(saveName: string): void;
-    /** This can used to enable Newgrounds functionality
-     *  @param {Number} app_id   - The newgrounds App ID
-     *  @param {String} [cipher] - The encryption Key (AES-128/Base64)
-     *  @param {Object} [cryptoJS] - An instance of CryptoJS, if there is a cipher
-     *  @memberof Medals */
-    export function newgroundsInit(app_id: number, cipher?: string, cryptoJS?: any): void;
     /**
      * Medal - Tracks an unlockable medal
      * @example
@@ -2065,50 +2112,4 @@ declare module "littlejsengine" {
         renderIcon(pos: Vector2, size?: number): void;
         storageKey(): string;
     }
-    /**
-     * Newgrounds API wrapper object
-     * @example
-     * // create a newgrounds object, replace the app id with your own
-     * const app_id = '53123:1ZuSTQ9l';
-     * newgrounds = new Newgrounds(app_id);
-     */
-    export class Newgrounds {
-        /** Create a newgrounds object
-         *  @param {Number} app_id   - The newgrounds App ID
-         *  @param {String} [cipher] - The encryption Key (AES-128/Base64)
-         *  @param {Object} [cryptoJS] - An instance of CryptoJS, if there is a cipher */
-        constructor(app_id: number, cipher?: string, cryptoJS?: any);
-        app_id: number;
-        cipher: string;
-        cryptoJS: any;
-        host: string;
-        session_id: string;
-        medals: any;
-        scoreboards: any;
-        /** Send message to unlock a medal by id
-         * @param {Number} id - The medal id */
-        unlockMedal(id: number): any;
-        /** Send message to post score
-         * @param {Number} id    - The scoreboard id
-         * @param {Number} value - The score value */
-        postScore(id: number, value: number): any;
-        /** Get scores from a scoreboard
-         * @param {Number} id       - The scoreboard id
-         * @param {String} [user]   - A user's id or name
-         * @param {Number} [social] - If true, only social scores will be loaded
-         * @param {Number} [skip]   - Number of scores to skip before start
-         * @param {Number} [limit]  - Number of scores to include in the list
-         * @return {Object}         - The response JSON object
-         */
-        getScores(id: number, user?: string, social?: number, skip?: number, limit?: number): any;
-        /** Send message to log a view */
-        logView(): any;
-        /** Send a message to call a component of the Newgrounds API
-         * @param {String}  component    - Name of the component
-         * @param {Object}  [parameters] - Parameters to use for call
-         * @param {Boolean} [async]      - If true, don't wait for response before continuing
-         * @return {Object}              - The response JSON object
-         */
-        call(component: string, parameters?: any, async?: boolean): any;
-    }
 }