littlejsengine 1.18.19 → 1.18.22

package/README.md

@@ -38,6 +38,7 @@ The code is very clean and well documented with many examples to get you started
 - Blazing fast WebGL2 + Canvas2D hybrid rendering system
 - Apply [Shadertoy](https://www.shadertoy.com) style shaders for post-processing effects
 - Robust particle effect system and [effect design tool](https://killedbyapixel.github.io/LittleJS/examples/particles/)
+- Optional 3D rendering with the [Three.js](https://threejs.org) plugin
 
 ### 🔊 Audio
 
@@ -73,6 +74,18 @@ The code is very clean and well documented with many examples to get you started
 - Medal tracking system with [Newgrounds](https://www.newgrounds.com/) support
 - Node.js build system
 
+### 🤖 AI Friendly
+
+- The entire API is small and well documented so LLMs can produce high quality results
+- [LittleJS AI Tools](https://github.com/KilledByAPixel/LittleJS-AI) - Templates, examples, and prompts tuned for AI + LittleJS workflows
+- [LittleJS GPT](https://chatgpt.com/g/g-67c7c080b5bc81919736bc8815836be6-littlejs-game-maker) - Build LittleJS games right inside ChatGPT
+
+### 🧊 3D with Three.js
+
+- Optional [Three.js](https://threejs.org) plugin renders a 3D scene behind the LittleJS canvas
+- 2D camera and 3D camera stay aligned so sprites and meshes share the same world space
+- LittleJS physics drive Three.js meshes with `ThreeJSObject`
+
 ## How To Use LittleJS
 
 To get started download the latest LittleJS package from GitHub or install via npm: 
@@ -113,7 +126,6 @@ engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
 - [LittleJS Quick Reference Sheet](https://github.com/KilledByAPixel/LittleJS/blob/main/REFERENCE.md) - A reference sheet to help you get started.
 - [Little JS FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) - Answers to common questions about LittleJS.
 - [JS13k Branch](https://github.com/KilledByAPixel/LittleJS/tree/js13k) - For size coding events like JS13k there is a special branch that builds to a 7KB zip.
-- [LittleJS AI Tools](https://github.com/KilledByAPixel/LittleJS-AI) - Experiments, games, and templates to improve LittleJS + AI workflows.
 
 ## Examples
 
@@ -126,6 +138,8 @@ LittleJS comes with several demos both for learning and using as starter project
 - [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 demo that loads level data
 - [Box2D Demo](https://killedbyapixel.github.io/LittleJS/examples/box2d/) - Box2D plugin demonstration and testbed
+- [Three.js Side Scroller](https://killedbyapixel.github.io/LittleJS/examples/threejs/sideScroller/) - 3D rendering with Three.js behind the 2D canvas
+- [Three.js Platformer](https://killedbyapixel.github.io/LittleJS/examples/threejs/platformer/) - 3D platformer with LittleJS gameplay and Three.js rendering
 - [Stress Test](https://killedbyapixel.github.io/LittleJS/examples/stress/) - Sprite rendering benchmark and music system demo
 - [Particle System Designer](https://killedbyapixel.github.io/LittleJS/examples/particles/) - Particle system editor and visualizer
 

package/dist/littlejs.d.ts

@@ -606,6 +606,7 @@ declare module "littlejsengine" {
      *  @memberof Settings */
     export let soundEnable: boolean;
     /** Volume scale to apply to all sound, music and speech
+     *  Use setSoundVolume to also update the audio master gain immediately
      *  @type {number}
      *  @default
      *  @memberof Settings */
@@ -1481,7 +1482,7 @@ declare module "littlejsengine" {
      */
     export class Timer {
         /** Create a timer object set time passed in
-         *  @param {number} [timeLeft] - How much time left before the timer
+         *  @param {number} [timeLeft] - How much time left before the timer is elapsed in seconds (undefined = unset)
          *  @param {boolean} [useRealTime] - Should the timer keep running even when the game is paused? (useful for UI) */
         constructor(timeLeft?: number, useRealTime?: boolean);
         useRealTime: boolean;
@@ -1668,8 +1669,9 @@ declare module "littlejsengine" {
          *  @param {TextureInfo} [textureInfo] - Texture info to use
          *  @param {number} [padding] - How many pixels padding around all sides of each tile (increases grid size, does not affect tile size)
          *  @param {number} [bleed] - How many pixels smaller to shrink UVS of tiles (does not affect grid size, only UVs)
+         *  @param {number} [columns] - How many frames per row for frame(), 0 to keep frames on a single row
          */
-        constructor(pos?: Vector2, size?: Vector2, textureInfo?: TextureInfo, padding?: number, bleed?: number);
+        constructor(pos?: Vector2, size?: Vector2, textureInfo?: TextureInfo, padding?: number, bleed?: number, columns?: number);
         /** @property {Vector2} - Top left corner of tile in pixels */
         pos: Vector2;
         /** @property {Vector2} - Size of tile in pixels */
@@ -1680,28 +1682,36 @@ declare module "littlejsengine" {
         textureInfo: TextureInfo;
         /** @property {number} - Shrinks tile by this many pixels to prevent neighbors bleeding */
         bleed: number;
+        /** @property {number} - How many frames per row for frame(), 0 to keep frames on a single row */
+        columns: number;
         /** Returns a copy of this tile offset by a vector
         *  @param {Vector2} offset - Offset to apply in pixels
         *  @return {TileInfo}
         */
         offset(offset: Vector2): TileInfo;
         /** Returns a copy of this tile offset by a number of animation frames
+        *  Frames wrap down to the next row if columns is set
         *  @param {number} frame - Offset to apply in animation frames
         *  @return {TileInfo}
         */
         frame(frame: number): TileInfo;
+        /** Set how many frames per row this tile uses, so frame() can wrap
+        *  @param {number} [columns] - Frames per row, 0 to keep frames on a single row
+        *  @return {TileInfo}
+        */
+        setColumns(columns?: number): TileInfo;
         /**
-         * Set this tile to use a full image in a texture info
-         * @param {TextureInfo} [textureInfo]
+         * Returns a tile info for an index using this tile as reference
+         * @param {Vector2|number} [index=0]
          * @return {TileInfo}
          */
-        setFullImage(textureInfo?: TextureInfo): TileInfo;
+        index(index?: Vector2 | number): TileInfo;
         /**
-         * Returns a tile info for an index using this tile as reference
-         * @param {Vector2|number} [index=0]
+         * Set this tile to use a full image in a texture info
+         * @param {TextureInfo} [textureInfo]
          * @return {TileInfo}
          */
-        tile(index?: Vector2 | number): TileInfo;
+        setFullImage(textureInfo?: TextureInfo): TileInfo;
     }
     /**
      * Tile Info - Stores info about each texture
@@ -2660,9 +2670,9 @@ declare module "littlejsengine" {
      *  @param {number} [rate] - How quickly to speak
      *  @param {number} [pitch] - How much to change the pitch by
      *  @param {string} [language] - The language/accent to use (examples: en, it, ru, ja, zh)
-     *  @return {SpeechSynthesisUtterance} - The utterance that was spoken
+     *  @return {SpeechSynthesisUtterance|undefined} - The utterance that was spoken, or undefined if speech is unavailable
      *  @memberof Audio */
-    export function speak(text: string, volume?: number, rate?: number, pitch?: number, language?: string): SpeechSynthesisUtterance;
+    export function speak(text: string, volume?: number, rate?: number, pitch?: number, language?: string): SpeechSynthesisUtterance | undefined;
     /** Stop all queued speech
      *  @memberof Audio */
     export function speakStop(): void;
@@ -2684,7 +2694,7 @@ declare module "littlejsengine" {
      *  @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
+     *  @param {GainNode} [gainNode] - Optional gain node for volume control while playing (disconnected when the sound ends)
      *  @param {number}   [offset] - Offset in seconds to start playback from
      *  @param {AudioEndedCallback} [onended] - Callback for when the sound ends
      *  @return {AudioBufferSourceNode} - The source node of the sound played, may be undefined if play fails
@@ -3068,7 +3078,7 @@ declare module "littlejsengine" {
         *  @param {boolean}  [useWebGL] - Should this layer use WebGL for rendering
         */
         constructor(pos: Vector2, size: Vector2, tileInfo?: TileInfo, renderOrder?: number, useWebGL?: boolean);
-        /** @property {Array<TileLayerData>} - Default tile info for layer */
+        /** @property {Array<TileLayerData>} - Array of tile data for the layer */
         data: TileLayerData[];
         /** @property {boolean} - Is this layer using a webgl texture? */
         isUsingWebGL: boolean;
@@ -3225,8 +3235,8 @@ declare module "littlejsengine" {
      *     rgb(1,1,1,1), rgb(0,0,0,1), // colorStartA, colorStartB
      *     rgb(1,1,1,0), rgb(0,0,0,0), // colorEndA, colorEndB
      *     1, .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
+     *     .99, 1, 1, PI, .05,  // damping, angleDamping, gravityScale, particleCone, fadeRate
+     *     .5, 1                // randomness, collide
      * );
      */
     export class ParticleEmitter extends EngineObject {
@@ -3572,7 +3582,7 @@ declare module "littlejsengine" {
      *  @memberof PostProcess */
     export let postProcess: PostProcessPlugin;
     /**
-     * UI System Global Object
+     * Post Process Plugin - Applies a full screen shader to the rendered output
      * @memberof PostProcess
      */
     export class PostProcessPlugin {
@@ -3910,8 +3920,8 @@ declare module "littlejsengine" {
          *  @return {number} */
         getNavigationDirection(): number;
         /** Get other axis navigation direction from gamepad or keyboard
-         *  @return {Vector2} */
-        getNavigationOtherDirection(): Vector2;
+         *  @return {number} */
+        getNavigationOtherDirection(): number;
         /** Get if navigation button was pressed from gamepad or keyboard
          *  @return {boolean} */
         getNavigationWasPressed(): boolean;
@@ -4111,7 +4121,7 @@ declare module "littlejsengine" {
         maxLength: number;
         text: string;
         click(): void;
-        /** Stop editing the text edited */
+        /** Stop editing the text */
         stopEditing(): void;
         /** Key down event handler if this object is being edited
          *  @param {KeyboardEvent} [e] */
@@ -4170,7 +4180,7 @@ declare module "littlejsengine" {
          *  @param {Color}   [color=uiSystem.defaultButtonColor]
          */
         constructor(pos?: Vector2, size?: Vector2, checked?: boolean, text?: string, color?: Color);
-        /** @property {boolean} - Current percentage value of this slider 0-1 */
+        /** @property {boolean} - Is the checkbox currently checked? */
         checked: boolean;
         text: string;
         click(): void;
@@ -4390,7 +4400,7 @@ declare module "littlejsengine" {
          *  @param {number} [lineWidth]
          *  @param {boolean} [useWebGL=glEnable]
          *  @param {CanvasRenderingContext2D} [context] */
-        drawFixture(fixture: any, pos: Vector2, angle: number, color?: Color, lineColor?: Color, lineWidth?: number, useWebgl: any, context?: CanvasRenderingContext2D): void;
+        drawFixture(fixture: any, pos: Vector2, angle: number, color?: Color, lineColor?: Color, lineWidth?: number, useWebGL?: boolean, context?: CanvasRenderingContext2D): void;
         /** converts a box2d vec2 to a Vector2
          *  @param {Object} v */
         vec2From(v: any): Vector2;
@@ -5707,4 +5717,189 @@ declare module "littlejsengine" {
         /** True if walkable and not blocked by cost. */
         isClear(): boolean;
     }
+    /**
+     * LittleJS Three.js Plugin
+     * - Renders a three.js scene on a canvas behind the LittleJS canvases
+     * - The three.js module is passed in by the user, nothing is bundled
+     * - Keep canvasClearColor transparent so the 3D scene shows through
+     * - Aligned camera mode locks the 3D camera to the LittleJS 2D camera
+     * - ThreeJSObject lets LittleJS physics drive a three.js mesh
+     * - Call new ThreeJSPlugin(THREE) in gameInit to set up
+     * @namespace ThreeJS
+     */
+    /** Global ThreeJS plugin object
+     *  @type {ThreeJSPlugin}
+     *  @memberof ThreeJS */
+    export let threeJS: ThreeJSPlugin;
+    /**
+     * ThreeJS Plugin - Renders a three.js scene behind the LittleJS canvas
+     * @example
+     * // in gameInit, with three.js loaded by the user
+     * new ThreeJSPlugin(THREE);
+     * threeJS.scene.add(new THREE.AmbientLight);
+     * @memberof ThreeJS
+     */
+    export class ThreeJSPlugin {
+        /** Set up the three.js rendering layer, call in gameInit
+         *  @param {Object} THREE - The three.js module, supplied by the user
+         *  @param {number} [cameraFOV] - Vertical field of view in degrees */
+        constructor(THREE: any, cameraFOV?: number);
+        /** @property {Object} - The three.js module passed into the constructor */
+        THREE: any;
+        /** @property {Object} - The three.js renderer */
+        renderer: any;
+        /** @property {Object} - The three.js scene, add lights and meshes here */
+        scene: any;
+        /** @property {Object} - The three.js perspective camera */
+        camera: any;
+        /** @property {boolean} - Lock the camera to the LittleJS 2D camera so the z=0 plane matches world space */
+        cameraAlign2D: boolean;
+        /** Position the camera so the z=0 plane exactly matches LittleJS world space,
+         *  called automatically when cameraAlign2D is set */
+        alignCamera2D(): void;
+        /** Sync the canvas layout and render the scene, called automatically each frame */
+        render(): void;
+    }
+    /**
+     * ThreeJS Object - EngineObject that drives a three.js mesh
+     * - LittleJS physics moves the object and the mesh follows automatically
+     * - Destroying the object removes the mesh from the scene
+     * @extends EngineObject
+     * @memberof ThreeJS
+     */
+    export class ThreeJSObject extends EngineObject {
+        /** Create an engine object that drives a three.js mesh
+         *  @param {Vector2} [pos] - World space position
+         *  @param {Vector2} [size] - World space size
+         *  @param {Object} [mesh] - The three.js object3d to drive
+         *  @param {number} [z] - Mesh height above the 2D plane */
+        constructor(pos?: Vector2, size?: Vector2, mesh?: any, z?: number);
+        /** @property {Object} - The three.js object3d this object drives */
+        mesh: any;
+        /** @property {number} - Mesh height above the 2D plane */
+        z: number;
+        /** Copy this object's transform to the mesh */
+        syncMesh(): void;
+    }
+    /**
+     * LittleJS Texture Sheet Plugin
+     * - Packs images into texture sheets as they are loaded
+     * - Sprites are placed automatically, callers get a TileInfo
+     * - Sheets are created and filled as needed
+     * - Sheets fill in call order, images decode in parallel
+     * - Animation frames keep layout and wrap across rows as needed
+     * - WebGL textures upload once per batch of loads
+     * - loadAtlas imports pre-packed atlases (TexturePacker and Aseprite json)
+     * @namespace TextureSheets
+     */
+    /** Width and height in pixels of texture sheets created by loadSprite
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let textureSheetSize: number;
+    /** Default padding pixels around each frame packed by loadSprite
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let textureSheetPadding: number;
+    /** Set width and height in pixels of texture sheets created by loadSprite
+     *  @param {number} size
+     *  @memberof Settings */
+    export function setTextureSheetSize(size: number): void;
+    /** Set default padding pixels around each frame packed by loadSprite
+     *  @param {number} padding
+     *  @memberof Settings */
+    export function setTextureSheetPadding(padding: number): void;
+    /** Array of texture sheets created by loadSprite
+     *  @type {Array<TextureSheet>}
+     *  @memberof TextureSheets */
+    export let textureSheets: Array<TextureSheet>;
+    /**
+     * Texture Sheet - A texture that images are packed into as they load
+     * Uses shelf packing, images are placed left to right then wrap to a new row
+     * @memberof TextureSheets
+     */
+    export class TextureSheet {
+        /** Create a texture sheet, called automatically by loadSprite
+         *  @param {number} [size] - Width and height of the sheet in pixels */
+        constructor(size?: number);
+        /** @property {number} - Width and height of the sheet in pixels */
+        size: number;
+        /** @property {OffscreenCanvas} - Canvas holding the packed images */
+        canvas: OffscreenCanvas;
+        /** @property {OffscreenCanvasRenderingContext2D} - 2d context for the canvas */
+        context: OffscreenCanvasRenderingContext2D;
+        /** @property {TextureInfo} - The texture info for this sheet */
+        textureInfo: TextureInfo;
+        /** @property {Vector2} - Where the next image will be packed */
+        cursor: Vector2;
+        /** @property {number} - Height of the row being packed */
+        rowHeight: number;
+        /** @property {boolean} - Has the canvas changed since the last webgl upload? */
+        glDirty: boolean;
+        /** Find a spot for an image on this sheet without drawing it
+         *  @param {Vector2} imageSize - Size of the source image in pixels
+         *  @param {Vector2} [frameSize] - Size of each frame, or the whole image if not passed
+         *  @param {number} [padding] - How many pixels padding around each frame
+         *  @return {TileInfo} Tile for the packed image, or undefined if the sheet is full */
+        tryAdd(imageSize: Vector2, frameSize?: Vector2, padding?: number): TileInfo;
+        /** Draw an image into this sheet at a tile returned by tryAdd
+         *  @param {HTMLImageElement} image - Source image to copy from
+         *  @param {TileInfo} tileInfo - Where to put it, from tryAdd
+         *  @param {boolean} [update] - Upload to webgl now, pass false when batching */
+        drawImage(image: HTMLImageElement, tileInfo: TileInfo, update?: boolean): void;
+        /** Upload the canvas to webgl if it has changed since the last upload
+         *  Only needed after batching, drawImage uploads automatically by default */
+        updateTexture(): void;
+    }
+    /** Load an image and pack it into a texture sheet
+     *  - Returns a TileInfo immediately which is filled in when the image loads
+     *  - Nothing is visible until it loads, use spritesReady to wait for it
+     *  - Pass frameSize for animations, then step through them with TileInfo.frame
+     *  - Grid images keep their layout and frames wrap down to the next row
+     *  @param {string} src - Image source path
+     *  @param {Vector2|number} [frameSize] - Size of each animation frame in pixels
+     *  @param {number} [padding] - How many pixels padding around each frame
+     *  @return {TileInfo}
+     *  @example
+     *  const playerTile = loadSprite('player.png');     // a single sprite
+     *  const runTile = loadSprite('run.png', vec2(16)); // a 16x16 frame animation
+     *  @memberof TextureSheets */
+    export function loadSprite(src: string, frameSize?: Vector2 | number, padding?: number): TileInfo;
+    /** Load a pre-packed texture atlas and repack it onto texture sheets
+     *  - Supports TexturePacker json (hash and array) and Aseprite json
+     *  - Returns an empty object which is filled with TileInfos when loaded
+     *  - Frames are named by the json, animations are grouped automatically
+     *  - Aseprite frame tags become animations, so do names like run_0, run_1
+     *  - Trimmed frames are restored to their full source size when packed
+     *  - Rotated frames are rotated back upright when packed
+     *  @param {string} imageSrc - Atlas image path
+     *  @param {string|Object} jsonSrc - Atlas json path, or already parsed json data
+     *  @param {number} [padding] - How many pixels padding around each frame
+     *  @return {Object} Object mapping frame and animation names to TileInfos
+     *  @example
+     *  const atlas = loadAtlas('sprites.png', 'sprites.json');
+     *  await spritesReady();
+     *  drawTile(pos, size, atlas.player);          // a single frame
+     *  drawTile(pos, size, atlas.run.frame(2));    // frame 2 of the run animation
+     *  @memberof TextureSheets */
+    export function loadAtlas(imageSrc: string, jsonSrc: string | any, padding?: number): any;
+    /** Parse atlas json into a list of named frame groups, used by loadAtlas
+     *  - Accepts TexturePacker json (hash and array) and Aseprite json
+     *  - Frames tagged in Aseprite or named like run_0, run_1 group into animations
+     *  @param {Object} data - Parsed atlas json data
+     *  @return {Array<Object>} List of {name, frames} groups in atlas order
+     *  @memberof TextureSheets */
+    export function parseAtlas(data: any): Array<any>;
+    /** Wait for everything started by loadSprite and loadAtlas to finish packing
+     *  @return {Promise}
+     *  @example
+     *  async function gameInit()
+     *  {
+     *      playerTile = loadSprite('player.png');
+     *      runTile = loadSprite('run.png', vec2(16));
+     *      await spritesReady();
+     *  }
+     *  @memberof TextureSheets */
+    export function spritesReady(): Promise<any>;
 }