littlejsengine 1.18.15 → 1.18.17

package/README.md

@@ -19,13 +19,13 @@ LittleJS is a fast, lightweight, and fully open source HTML5 game engine designe
 Its small footprint is packed with a comprehensive feature set including rendering, physics, particles, sound, and input handling.
 The code is very clean and well documented with many examples to get you started quickly.
 
-### 🚀 Join the LittleJS Game Jam
+### 🚀 [Join the LittleJS Game Jam](https://itch.io/jam/littlejs-jam)
 
-*The Third Annual LittleJS Game Jam will take place From Oct 2 to Nov 2! Unleash your creativity and develop amazing games using the LittleJS game engine. 🕹️🎮 [Sign up today and get more info about the jam on itch.io!](https://itch.io/jam/littlejs-jam)*
+*The Third Annual LittleJS Game Jam will take place From Oct 2 to Nov 2! Unleash your creativity and develop amazing games using the LittleJS game engine.*
 
 <div align='center' markdown='1'>
 
-## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [Reference](https://github.com/KilledByAPixel/LittleJS/blob/main/REFERENCE.md) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe)
+## [Demos](https://killedbyapixel.github.io/LittleJS/examples) | [Arcade](https://killedbyapixel.github.io/LittleJSArcade) | [Docs](https://killedbyapixel.github.io/LittleJS/docs) | [FAQ](https://github.com/KilledByAPixel/LittleJS/blob/main/FAQ.md) | [Trailer](https://youtu.be/chuBzGjv7Ms) | [Discord](https://discord.gg/zb7hcGkyZe)
 
 </div>
 
@@ -120,6 +120,7 @@ engineInit(gameInit, gameUpdate, gameUpdatePost, gameRender, gameRenderPost);
 LittleJS comes with several demos both for learning and using as starter projects to create new games.
 
 - [Example Browser](https://killedbyapixel.github.io/LittleJS/examples/) - Live example browser with all examples and editable source
+- [LittleJS Arcade](https://killedbyapixel.github.io/LittleJSArcade/) - Over 50 example games you can use as starter projects
 - [Short Examples](https://github.com/KilledByAPixel/LittleJS/tree/main/examples/shorts) - 60+ single-file demos showing off individual engine features
 - [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
@@ -157,7 +158,6 @@ Here are a few of the many amazing games created with LittleJS...
 - [Tetrimals](https://nixn.itch.io/tetrimals) - A puzzle game mixing Tetris with animals. by [nixn](https://nixn.itch.io/)
 - [Bug&Bee](https://itch.io/jam/littlejs-game-jam-2025/results) - Low fi shoot em up with co-op gameplay. LittleJS Jam 1st place! by [eoinmcg](https://eoinmcg.itch.io/)
 - [Little Platformer](https://psemo.itch.io/little-platformer) - Platformer with many mechanics. LittleJS Jam 2st place! by [PSEMO](https://psemo.itch.io/), [Solita666](https://itch.io/profile/solita666), [GabrielRG](https://gabrielrg.itch.io/), [Nate](https://natesassoon.itch.io/)
-- [Rogue Pong](https://itch.io/jam/littlejs-game-jam-2025/rate/4004165) - Roguelike crossed with classic pong gameplay. LittleJS Jam 3rd place! by [webdevbrian](https://webdevbrian.itch.io/)
 - [Alien Escape Pinball](https://focaccai.itch.io/alien-pinball) - Pinball game with physics and aliens. by [Focaccai](https://www.focaccai.com/)
 - [LittleJS Jam 2024 Results](https://itch.io/jam/littlejs-jam-2024/results) - All the games from the first LittleJS Game Jam.
 - [LittleJS Jam 2025 Results](https://itch.io/jam/littlejs-game-jam-2025/results) - All the games from the second LittleJS Game Jam.

package/dist/littlejs.d.ts

@@ -510,31 +510,69 @@ declare module "littlejsengine" {
      *  - Supports left analog stick, 4 face buttons and start button (button 9)
      *  - setTouchGamepadButtonCount(1) to use face buttons as right analog stick
      *  - Analog stick buttons 10 and 11 are also activated when virtual sticks are touched
-    
+     *  - Rendered as a full-viewport HTML/SVG overlay, so controls may sit outside the game canvas
      *  @type {boolean}
      *  @default
      *  @memberof Settings */
     export let touchGamepadEnable: boolean;
-    /** True if touch gamepad should have start button in the center
-     *  - Prevents activating within 2*touchGamepadSize of the virtual stick or face buttons
-     *    (one radius for the visible control + one radius of buffer beyond its edge)
+    /** True if touches outside the gamepad controls should still drive mouse/touch input
+     *  - When false (the default), enabling the touch gamepad suppresses touch-to-mouse input entirely
+     *  - Set true to also pass touches outside the controls through to the game as mouse/touch input
+     *  - Touches on the gamepad controls never drive the mouse regardless of this setting
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadPassthrough: boolean;
+    /** Size of center button if touch gamepad should have start button in the center
+     *  - Prevents activating when pressed near virtual stick or face buttons
      *  - When the game is paused, any touch will press the button
-     *  - Set size to enable the center button
+     *  - Measured in viewport CSS pixels
      *  @type {number}
      *  @default
      *  @memberof Settings */
     export let touchGamepadCenterButtonSize: number;
-    /** Number of buttons on touch gamepad (0-4), if 1 also acts as right analog stick
+    /** Number of buttons on the right side of the touch gamepad (0-4), using gamepad buttons 0-3
+     *  - A count of 1 is a single large button (the size of a stick)
+     *  - Ignored when touchGamepadRightStick is set (the right side is a stick instead)
      *  @type {number}
      *  @default
      *  @memberof Settings */
     export let touchGamepadButtonCount: number;
+    /** True if the touch gamepad should have a left analog stick (or dpad)
+     *  - When false, the left side is face buttons (touchGamepadLeftButtonCount) or nothing
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadLeftStick: boolean;
+    /** Number of buttons on the left side of the touch gamepad (0-4), using gamepad buttons 4-7
+     *  - Only used when touchGamepadLeftStick is false (otherwise the left side is a stick)
+     *  - A count of 1 is a single large button (the size of a stick)
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadLeftButtonCount: number;
+    /** True if the touch gamepad right side should be an analog stick (or dpad) instead of face buttons
+     *  - When set, touchGamepadButtonCount is ignored and the right side is a stick
+     *  - Uses an analog stick when touchGamepadAnalog is true, otherwise an 8 way dpad
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadRightStick: boolean;
     /** True if touch gamepad should be analog stick or false to use if 8 way dpad
      *  @type {boolean}
      *  @default
      *  @memberof Settings */
     export let touchGamepadAnalog: boolean;
-    /** Size of virtual gamepad for touch devices in pixels
+    /** True if touch gamepad directional controls should float to where you press
+     *  - Only affects analog sticks and dpads, not face buttons
+     *  - Directional controls re-anchor to where you press within the bottom ~60% of their screen half; the top ~40% passes through to the game
+     *  - The right side floats only when it acts as the right analog stick (touchGamepadRightStick is set)
+     *  - A center button (touchGamepadCenterButtonSize) still works since it ignores touches near the sticks
+     *  @type {boolean}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadFloating: boolean;
+    /** Size of virtual gamepad for touch devices in viewport CSS pixels
      *  @type {number}
      *  @default
      *  @memberof Settings */
@@ -549,6 +587,12 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let touchGamepadDisplayTime: number;
+    /** Duration in ms to vibrate when a touch gamepad face button or start button is pressed
+     *  - Set to 0 to disable, also requires vibrateEnable and hardware support (ignored on iOS)
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let touchGamepadVibration: number;
     /** Allow vibration hardware if it exists
      *  @type {boolean}
      *  @default
@@ -718,20 +762,41 @@ declare module "littlejsengine" {
      *  @param {boolean} enable
      *  @memberof Settings */
     export function setTouchGamepadEnable(enable: boolean): void;
+    /** Set if touches outside the gamepad controls should still drive mouse/touch input
+     *  @param {boolean} passthrough
+     *  @memberof Settings */
+    export function setTouchGamepadPassthrough(passthrough: boolean): void;
     /** Set if touch gamepad should have start button in the center
      *  - Set size to enable the center button
      *  - When the game is paused, any touch will press the button
      *  @param {number} size
      *  @memberof Settings */
     export function setTouchGamepadCenterButtonSize(size: number): void;
-    /** Set number of buttons on touch gamepad (0-4), if 1 also acts as right analog stick
+    /** Set number of buttons on the right side of the touch gamepad (0-4, gamepad buttons 0-3)
      *  @param {number} count
      *  @memberof Settings */
     export function setTouchGamepadButtonCount(count: number): void;
+    /** Set if the touch gamepad should have a left analog stick (or dpad)
+     *  @param {boolean} enable
+     *  @memberof Settings */
+    export function setTouchGamepadLeftStick(enable: boolean): void;
+    /** Set number of buttons on the left side of the touch gamepad (0-4, gamepad buttons 4-7)
+     *  - Only used when touchGamepadLeftStick is false
+     *  @param {number} count
+     *  @memberof Settings */
+    export function setTouchGamepadLeftButtonCount(count: number): void;
+    /** Set if the touch gamepad right side is an analog stick (or dpad) instead of face buttons
+     *  @param {boolean} rightStick
+     *  @memberof Settings */
+    export function setTouchGamepadRightStick(rightStick: boolean): void;
     /** Set if touch gamepad should be analog stick or 8 way dpad
      *  @param {boolean} analog
      *  @memberof Settings */
     export function setTouchGamepadAnalog(analog: boolean): void;
+    /** Set if touch gamepad directional controls should float to where you press
+     *  @param {boolean} floating
+     *  @memberof Settings */
+    export function setTouchGamepadFloating(floating: boolean): void;
     /** Set size of virtual gamepad for touch devices in pixels
      *  @param {number} size
      *  @memberof Settings */
@@ -744,6 +809,10 @@ declare module "littlejsengine" {
      *  @param {number} time
      *  @memberof Settings */
     export function setTouchGamepadDisplayTime(time: number): void;
+    /** Set duration in ms to vibrate when a touch gamepad face or start button is pressed (0 disables)
+     *  @param {number} ms
+     *  @memberof Settings */
+    export function setTouchGamepadVibration(ms: number): void;
     /** Set to allow vibration hardware if it exists
      *  @param {boolean} enable
      *  @memberof Settings */
@@ -1889,7 +1958,10 @@ declare module "littlejsengine" {
      * @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} context
      * @memberof Draw
      */
-    /** Draw directly to a 2d canvas context in world space
+    /** Draw directly to a 2d canvas context in world space.
+     *  The Y axis is flipped so world-Y-up coordinates render right-side up
+     *  (matches the WebGL path). Callers whose drawing depends on Y direction
+     *  (e.g. linear gradients) should flip their own Y endpoints accordingly.
      *  @param {Vector2}  pos
      *  @param {Vector2}  size
      *  @param {number}   angle
@@ -2424,7 +2496,7 @@ declare module "littlejsengine" {
          *  @param {number}  [randomnessScale] - How much to scale pitch randomness
          *  @param {boolean} [loop] - Should the sound loop?
          *  @param {boolean} [paused] - Should the sound start paused
-         *  @return {SoundInstance} - The audio source node
+         *  @return {SoundInstance} - The sound instance, or undefined if sound is disabled, not loaded, or running in headless mode
          */
         play(pos?: Vector2, volume?: number, pitch?: number, randomnessScale?: number, loop?: boolean, paused?: boolean): SoundInstance;
         /** Play a music track that loops by default
@@ -2712,6 +2784,8 @@ declare module "littlejsengine" {
         update(): void;
         /** Render the object, draws a tile by default, automatically called each frame, sorted by renderOrder */
         render(): void;
+        /** Optional hook called during the light system plugin's lightmap pass to draw this object's lightmap contribution. Does nothing by default. */
+        renderLight(): void;
         /** Destroy this object, destroy its children, detach its parent, and mark it for removal
          *  @param {boolean} [immediate] - should attached effects be allowed to die off? */
         destroy(immediate?: boolean): void;
@@ -3121,10 +3195,10 @@ declare module "littlejsengine" {
          *  @param {number} [particleTime]      - How long particles live
          *  @param {number} [sizeStart]         - How big are particles at start
          *  @param {number} [sizeEnd]           - How big are particles at end
-         *  @param {number} [speed]             - How fast are particles when spawned
-         *  @param {number} [angleSpeed]        - How fast are particles rotating
-         *  @param {number} [damping]           - How much to dampen particle speed
-         *  @param {number} [angleDamping]      - How much to dampen particle angular speed
+         *  @param {number} [speed]             - How fast are particles when spawned, in world units per frame (at 60fps, so multiply units/sec by 1/60)
+         *  @param {number} [angleSpeed]        - How fast are particles rotating, in radians per frame (at 60fps)
+         *  @param {number} [damping]           - How much to dampen particle speed, per-frame velocity multiplier (1 = no damping, .9 = lose 10% speed each frame)
+         *  @param {number} [angleDamping]      - How much to dampen particle angular speed, per-frame multiplier (1 = no damping)
          *  @param {number} [gravityScale]      - How much gravity effect particles
          *  @param {number} [particleConeAngle] - Cone for start particle angle
          *  @param {number} [fadeRate]          - Fraction of life spent fading: half at fade-in (start), half at fade-out (end). e.g. .2 = 10% fade-in, 80% full opacity, 10% fade-out
@@ -3162,9 +3236,9 @@ declare module "littlejsengine" {
         sizeStart: number;
         /** @property {number} - How big are particles at end */
         sizeEnd: number;
-        /** @property {number} - How fast are particles when spawned */
+        /** @property {number} - Particle speed when spawned, in world units per frame (at 60fps) */
         speed: number;
-        /** @property {number} - How fast are particles rotating */
+        /** @property {number} - Particle angular speed when spawned, in radians per frame (at 60fps) */
         angleSpeed: number;
         /** @property {number} - Cone for start particle angle */
         particleConeAngle: number;
@@ -3298,6 +3372,9 @@ declare module "littlejsengine" {
      *  @param {MedalCallbackFunction} callback
      *  @memberof Medals */
     export function medalsForEach(callback: MedalCallbackFunction): void;
+    /** Reset all medals to locked and persist the cleared catalog
+     *  @memberof Medals */
+    export function medalsReset(): void;
     /** Set how long to show medals for in seconds
      *  @param {number} time
      *  @memberof Settings */
@@ -3359,7 +3436,6 @@ declare module "littlejsengine" {
          *  @param {number} size - Screen space size
          */
         renderIcon(pos: Vector2, size: number): void;
-        storageKey(): string;
     }
     /**
      * LittleJS Newgrounds Plugin
@@ -3466,6 +3542,85 @@ declare module "littlejsengine" {
         /** @property {WebGLVertexArrayObject} - Vertex array object */
         vao: any;
     }
+    /**
+     * LittleJS Light System Plugin
+     * - Adds 2D dynamic lighting to the scene
+     * - Lights are first-class EngineObjects (the Light class)
+     * - Each Light draws a soft falloff blob of its color into a shared lightmap
+     * - Lights accumulate ADDITIVELY in the lightmap (red + blue = magenta)
+     * - The lightmap is then MULTIPLIED with the scene during composite, so unlit
+     *   areas go to the ambient color and lit areas show the scene tinted by the
+     *   accumulated light color
+     * - Draw the world at full brightness — the lightmap does the darkening
+     * - Any EngineObject may override renderLight() to additively contribute to the
+     *   lightmap (e.g. emissive lava tiles, weapon flashes, glowing crystals)
+     * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
+     * @namespace LightSystem
+     */
+    /** Global Light System plugin object
+     *  @type {LightSystemPlugin}
+     *  @memberof LightSystem */
+    export let lightSystem: LightSystemPlugin;
+    /**
+     * LightSystemPlugin
+     * - Owns the offscreen lightmap texture, falloff/composite shaders, and the
+     *   per-frame render pass that multiplies the lightmap onto the WebGL scene
+     * - The composite is MULTIPLICATIVE: unlit areas get the ambient color, lit
+     *   areas show the scene tinted by the accumulated light color. So you should
+     *   draw your world at full brightness — the lightmap handles the darkening.
+     * @memberof LightSystem
+     */
+    export class LightSystemPlugin {
+        /** Create the global light system plugin.
+         *  @param {Vector2} [textureSize]  - Size of the lightmap texture (defaults to mainCanvasSize)
+         *  @param {Color}   [ambientColor] - Color applied to unlit areas of the scene (defaults to BLACK = pitch dark). Set a small RGB like rgb(0.1,0.1,0.15) for a faint "moonlight" baseline so unlit areas aren't fully black.
+         *  @example
+         *  // simplest usage
+         *  new LightSystemPlugin();
+         */
+        constructor(textureSize?: Vector2, ambientColor?: Color);
+        /** @property {boolean} - When false, the render pass is skipped entirely */
+        enabled: boolean;
+        /** @property {Color} - Baseline color applied to unlit areas of the scene. Defaults to BLACK (pitch dark). Set to a small RGB for a faint ambient. The lightmap is cleared to this color each frame, then lights add on top, then the result multiplies the scene. */
+        ambientColor: Color;
+        /** @property {Vector2} - Size of the lightmap texture (set at construction; falls back to mainCanvasSize at init time) */
+        textureSize: Vector2;
+        /** @property {WebGLTexture} - The lightmap texture */
+        texture: any;
+        /** @property {WebGLProgram} - Shader for drawing per-Light falloff blobs into the lightmap */
+        lightShader: any;
+        /** @property {WebGLProgram} - Shader for compositing the lightmap over the main scene */
+        compositeShader: any;
+        /** @property {WebGLVertexArrayObject} - Vertex array object for the light shader */
+        lightVAO: any;
+        /** @property {WebGLVertexArrayObject} - Vertex array object for the composite shader */
+        compositeVAO: any;
+        /** Draw a single Light's falloff blob into the currently bound lightmap.
+         *  Called by Light.renderLight() during the plugin's render pass.
+         *  @param {Light} light */
+        drawLight(light: Light): void;
+    }
+    /**
+     * A Light is an EngineObject that contributes a soft additive blob of color
+     * to the LightSystem plugin's lightmap.
+     * @extends EngineObject
+     * @memberof LightSystem
+     * @example
+     * new Light(vec2(5, 5), 4, rgb(1, 0.5, 0));        // orange light, full soft blob
+     * new Light(vec2(0, 0), 8, rgb(1, 1, 1), 2);       // white core with 2-unit soft halo
+     */
+    export class Light extends EngineObject {
+        /** Create a light object and add it to the engine object list
+         *  @param {Vector2} pos - World space position
+         *  @param {number} radius - Total extent of the light in world units
+         *  @param {Color} [color] - Color of the light; alpha modulates intensity
+         *  @param {number} [fadeRange] - Width of the soft edge in world units (defaults to radius) */
+        constructor(pos: Vector2, radius: number, color?: Color, fadeRange?: number);
+        /** @property {number} - Total extent of the light in world units */
+        radius: number;
+        /** @property {number} - Width of the soft edge in world units */
+        fadeRange: number;
+    }
     /**
      * LittleJS ZzFXM Plugin
      * @namespace ZzFXM
@@ -5114,6 +5269,32 @@ declare module "littlejsengine" {
      *  @param {number} [angle] - Angle to rotate by
      *  @memberof DrawUtilities */
     export function drawThreeSliceScreen(pos: Vector2, size: Vector2, startTile: TileInfo, borderSize?: number, extraSpace?: number, angle?: number): void;
+    /** Draw a crescent / moon-phase shape built from a polygon
+     *  Routes through drawPoly, so it supports WebGL, screen space, color, and outlines
+     *  @param {Vector2} pos - Center position
+     *  @param {number}  [size] - Diameter
+     *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
+     *  @param {Color}   [color] - Fill color
+     *  @param {number}  [angle] - Angle to rotate by
+     *  @param {boolean} [invert] - Flip which side is illuminated
+     *  @param {number}  [lineWidth] - Outline width, 0 for no outline
+     *  @param {Color}   [lineColor] - Outline color
+     *  @param {boolean} [useWebGL=glEnable] - Use WebGL for rendering
+     *  @param {boolean} [screenSpace] - Use screen space coordinates
+     *  @param {CanvasRenderingContext2D} [context] - Canvas context to use
+     *  @memberof DrawUtilities */
+    export function drawCrescent(pos: Vector2, size?: number, percent?: number, color?: Color, angle?: number, invert?: boolean, lineWidth?: number, lineColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D): void;
+    /** Get the list of points that make up a crescent / moon-phase shape
+     *  Returns world-space points with pos and angle baked in, ready for drawPoly or other use
+     *  @param {Vector2} pos - Center position
+     *  @param {number}  [size] - Diameter
+     *  @param {number}  [percent] - Moon phase over a full cycle (0=new, .25=first quarter, .5=full, .75=last quarter), wraps
+     *  @param {number}  [angle] - Angle to rotate by
+     *  @param {boolean} [invert] - Flip which side is illuminated
+     *  @param {number}  [sides=glCircleSides] - Number of sides for a full circle (halved per arc)
+     *  @return {Array<Vector2>} - List of points making up the crescent
+     *  @memberof DrawUtilities */
+    export function getCrescentPoints(pos: Vector2, size?: number, percent?: number, angle?: number, invert?: boolean, sides?: number): Array<Vector2>;
     /** A numeric tween: drives a callback with a value interpolated between
      *  `start` and `end` over `duration` seconds. Pauses with the game by default.
      *  @memberof TweenSystem