littlejsengine 1.9.9 → 1.10.2

package/README.md

@@ -56,6 +56,7 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 - Robust arcade physics system with collision handling
 - Very fast collision and raycasting for tile maps
+- Full Box2d support using [super fast wasm build of box2d.js](https://github.com/kripken/box2d.js/)
 
 ### 🚀 Flexibility
 
@@ -78,6 +79,10 @@ LittleJS is a small but powerful game engine with many features and no dependenc
 
 To get started download the latest LittleJS package from GitHub or install via npm: ```npm install littlejsengine```
 
+*You will need to run a local web server to run LittleJS games!*
+
+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.
@@ -209,6 +214,7 @@ Here are a few of the amazing games people made using LittleJS...
 - [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

@@ -70,8 +70,9 @@ declare module "littlejsengine" {
      *  @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 {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[]): void;
+    export function engineInit(gameInit: Function, 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;
@@ -85,6 +86,13 @@ declare module "littlejsengine" {
      *  @param {Array} [objects=engineObjects] - List of objects to check
      *  @memberof Engine */
     export function engineObjectsCallback(pos?: Vector2, size?: number | Vector2, callbackFunction?: Function, objects?: any[]): void;
+    /** Return a list of objects intersecting a ray
+     *  @param {Vector2} start
+     *  @param {Vector2} end
+     *  @param {Array} [objects=engineObjects] - List of objects to check
+     *  @return {Array} - List of objects hit
+     *  @memberof Engine */
+    export function engineObjectsRaycast(start: Vector2, end: Vector2, objects?: any[]): any[];
     /** Add a new update function for a plugin
      *  @param {Function} [updateFunction]
      *  @param {Function} [renderFunction]
@@ -664,6 +672,14 @@ declare module "littlejsengine" {
      *  @return {Boolean}              - True if overlapping
      *  @memberof Utilities */
     export function isOverlapping(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB?: Vector2): boolean;
+    /** Returns true if a line segment is intersecting an axis aligned box
+     *  @param {Vector2} start - Start of raycast
+     *  @param {Vector2} end   - End of raycast
+     *  @param {Vector2} pos   - Center of box
+     *  @param {Vector2} size  - Size of box
+     *  @return {Boolean}      - True if intersecting
+     *  @memberof Utilities */
+    export function isIntersecting(start: Vector2, end: Vector2, pos: Vector2, size: 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
@@ -1025,17 +1041,69 @@ declare module "littlejsengine" {
      * @memberof Utilities
      */
     export function hsl(h?: number, s?: number, l?: number, a?: number): Color;
+    /**
+     * Check if object is a valid Color
+     * @param {any} c
+     * @return {Boolean}
+     * @memberof Utilities
+     */
+    export function isColor(c: any): boolean;
+    /** Color - White
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const WHITE: Color;
+    /** Color - Black
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const BLACK: Color;
+    /** Color - Gray
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const GRAY: Color;
+    /** Color - Red
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const RED: Color;
+    /** Color - Orange
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const ORANGE: Color;
+    /** Color - Yellow
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const YELLOW: Color;
+    /** Color - Green
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const GREEN: Color;
+    /** Color - Cyan
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const CYAN: Color;
+    /** Color - Blue
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const BLUE: Color;
+    /** Color - Purple
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const PURPLE: Color;
+    /** Color - Magenta
+     *  @type {Color}
+     *  @memberof Utilities */
+    export const MAGENTA: Color;
     /** Array containing texture info for batch rendering system
      *  @type {Array}
      *  @memberof Draw */
     export let textureInfos: any[];
     /**
-     * Create a tile info object
+     * Create a tile info object using a grid based system
      * - This can take vecs or floats for easier use and conversion
      * - If an index is passed in, the tile size and index will determine the position
-     * @param {(Number|Vector2)} [pos=(0,0)]            - Top left corner of tile in pixels or index
+     * @param {(Number|Vector2)} [pos=0]                - Index of tile in sheet
      * @param {(Number|Vector2)} [size=tileSizeDefault] - Size of tile in pixels
      * @param {Number} [textureIndex]                   - Texture index to use
+     * @param {Number} [padding]                        - How many pixels padding around tiles
      * @return {TileInfo}
      * @example
      * tile(2)                       // a tile at index 2 using the default tile size of 16
@@ -1044,7 +1112,7 @@ declare module "littlejsengine" {
      * tile(vec2(4,8), vec2(30,10))  // a tile at pixel location (4,8) with a size of (30,10)
      * @memberof Draw
      */
-    export function tile(pos?: (number | Vector2), size?: (number | Vector2), textureIndex?: number): TileInfo;
+    export function tile(pos?: (number | Vector2), size?: (number | Vector2), textureIndex?: number, padding?: number): TileInfo;
     /**
      * Tile Info - Stores info about how to draw a tile
      */
@@ -1053,14 +1121,17 @@ declare module "littlejsengine" {
          *  @param {Vector2} [pos=(0,0)]            - Top left corner of tile in pixels
          *  @param {Vector2} [size=tileSizeDefault] - Size of tile in pixels
          *  @param {Number}  [textureIndex]         - Texture index to use
+         *  @param {Number}  [padding]              - How many pixels padding around tiles
          */
-        constructor(pos?: Vector2, size?: Vector2, textureIndex?: number);
+        constructor(pos?: Vector2, size?: Vector2, textureIndex?: number, padding?: number);
         /** @property {Vector2} - Top left corner of tile in pixels */
         pos: Vector2;
         /** @property {Vector2} - Size of tile in pixels */
         size: Vector2;
         /** @property {Number} - Texture index to use */
         textureIndex: number;
+        /** @property {Number} - How many pixels padding around tiles */
+        padding: number;
         /** Returns a copy of this tile offset by a vector
         *  @param {Vector2} offset - Offset to apply in pixels
         *  @return {TileInfo}
@@ -1089,8 +1160,6 @@ declare module "littlejsengine" {
         size: Vector2;
         /** @property {WebGLTexture} - webgl texture */
         glTexture: WebGLTexture;
-        /** @property {Vector2} - size to adjust tile to fix bleeding */
-        fixBleedSize: Vector2;
     }
     /**
      * LittleJS Drawing System
@@ -1203,8 +1272,9 @@ declare module "littlejsengine" {
      *  @param {CanvasTextAlign}  [textAlign]
      *  @param {String}  [font=fontDefault]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=overlayContext]
+     *  @param {Number}  [maxWidth]
      *  @memberof Draw */
-    export function drawTextScreen(text: string, pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    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;
     /** Draw text on overlay canvas in world space
      *  Automatically splits new lines into rows
      *  @param {String}  text
@@ -1216,8 +1286,9 @@ declare module "littlejsengine" {
      *  @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): void;
+    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 let engineFontImage: any;
     /**
      * Font Image Object - Draw text on a 2D canvas by using characters in an image
@@ -1288,17 +1359,17 @@ declare module "littlejsengine" {
      *  @type {WebGL2RenderingContext}
      *  @memberof WebGL */
     export let glContext: WebGL2RenderingContext;
-    /** Set the WebGl texture, called automatically if using multiple textures
-     *  - This may also flush the gl buffer resulting in more draw calls and worse performance
-     *  @param {WebGLTexture} texture
-     *  @memberof WebGL */
-    export function glSetTexture(texture: WebGLTexture): void;
     /** Compile WebGL shader of the given type, will throw errors if in debug mode
      *  @param {String} source
      *  @param {Number} type
      *  @return {WebGLShader}
      *  @memberof WebGL */
     export function glCompileShader(source: string, type: number): WebGLShader;
+    /** Draw any sprites still in the buffer, copy to main canvas and clear
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
+     *  @param {Boolean} [forceDraw]
+     *  @memberof WebGL */
+    export function glCopyToContext(context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, forceDraw?: boolean): void;
     /** Create WebGL program with given shaders
      *  @param {String} vsSource
      *  @param {String} fsSource
@@ -1310,6 +1381,28 @@ declare module "littlejsengine" {
      *  @return {WebGLTexture}
      *  @memberof WebGL */
     export function glCreateTexture(image: HTMLImageElement): WebGLTexture;
+    /** Add a sprite to the gl draw list, used by all gl draw functions
+     *  @param {Number} x
+     *  @param {Number} y
+     *  @param {Number} sizeX
+     *  @param {Number} sizeY
+     *  @param {Number} angle
+     *  @param {Number} uv0X
+     *  @param {Number} uv0Y
+     *  @param {Number} uv1X
+     *  @param {Number} uv1Y
+     *  @param {Number} rgba
+     *  @param {Number} [rgbaAdditive=0]
+     *  @memberof WebGL */
+    export function glDraw(x: number, y: number, sizeX: number, sizeY: number, angle: number, uv0X: number, uv0Y: number, uv1X: number, uv1Y: number, rgba: number, rgbaAdditive?: number): void;
+    /** Draw all sprites and clear out the buffer, called automatically by the system whenever necessary
+     *  @memberof WebGL */
+    export function glFlush(): void;
+    /** Set the WebGl texture, called automatically if using multiple textures
+     *  - This may also flush the gl buffer resulting in more draw calls and worse performance
+     *  @param {WebGLTexture} texture
+     *  @memberof WebGL */
+    export function glSetTexture(texture: WebGLTexture): void;
     /**
      * LittleJS Input System
      * - Tracks keyboard down, pressed, and released