littlejsengine 1.18.12 → 1.18.17

package/dist/littlejs.d.ts

@@ -291,7 +291,7 @@ declare module "littlejsengine" {
      *  @param {boolean} [screenSpace]
      *  @memberof Debug */
     export function debugOverlap(posA: Vector2, sizeA: Vector2, posB: Vector2, sizeB: Vector2, color?: Color | string, time?: number, screenSpace?: boolean): void;
-    /** Draw a debug axis aligned bounding box in world space
+    /** Draw debug text in world space
      *  @param {string|number} text
      *  @param {Vector2} pos
      *  @param {number} [size]
@@ -358,7 +358,7 @@ declare module "littlejsengine" {
     export let canvasColorTiles: boolean;
     /** Color to clear the canvas to before render, does not clear if alpha is 0
      *  @type {Color}
-     *  @memberof Draw */
+     *  @memberof Settings */
     export let canvasClearColor: Color;
     /** The max size of the canvas, centered if window is larger
      *  @type {Vector2}
@@ -510,30 +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 if overlappng with virtual stick or buttons if they are enabled
+    /** 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 */
@@ -548,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
@@ -717,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 */
@@ -739,6 +805,14 @@ declare module "littlejsengine" {
      *  @param {number} alpha
      *  @memberof Settings */
     export function setTouchGamepadAlpha(alpha: number): void;
+    /** Set how long to display the touch gamepad on screen in seconds, set to 0 to always display
+     *  @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 */
@@ -821,17 +895,17 @@ declare module "littlejsengine" {
      *  @param {number} x
      *  @return {number}
      *  @memberof Math */
-    export const sign: any;
+    export function sign(x: number): number;
     /** Returns hypotenuse of values passed in
      *  @param {...number} values
      *  @return {number}
      *  @memberof Math */
-    export const hypot: any;
+    export function hypot(...values: number[]): number;
     /** Returns log2 of value passed in
      *  @param {number} x
      *  @return {number}
      *  @memberof Math */
-    export const log2: any;
+    export function log2(x: number): number;
     /** Returns sin of value passed in
      *  @param {number} x
      *  @return {number}
@@ -1422,7 +1496,8 @@ declare module "littlejsengine" {
         /** Get how long since elapsed, returns 0 if not set (returns negative if currently active)
          * @return {number} */
         get(): number;
-        /** Get percentage elapsed based on time it was set to, returns 0 if not set
+        /** Get percentage elapsed based on time it was set to, returns 0 if not set.
+         *  Zero-duration timers report 1 (already elapsed).
          * @return {number} */
         getPercent(): number;
         /** Get the time this timer was set to, returns 0 if not set
@@ -1499,9 +1574,9 @@ declare module "littlejsengine" {
     /**
      * Check if object is an array
      * @param {any} a
-     * @return {boolean}
+     * @return {a is Array<any>}
      * @memberof Math */
-    export function isArray(a: any): boolean;
+    export function isArray(a: any): a is any[];
     /** Color - White #ffffff
      *  @type {Color}
      *  @memberof Math */
@@ -1580,8 +1655,8 @@ declare module "littlejsengine" {
          *  @param {Vector2} [pos=vec2()] - Top left corner of tile in pixels
          *  @param {Vector2} [size] - Size of tile in pixels
          *  @param {TextureInfo} [textureInfo] - Texture info to use
-         *  @param {number} [padding] - How many pixels padding around tiles
-         *  @param {number} [bleed] - How many pixels smaller to draw tiles
+         *  @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)
          */
         constructor(pos?: Vector2, size?: Vector2, textureInfo?: TextureInfo, padding?: number, bleed?: number);
         /** @property {Vector2} - Top left corner of tile in pixels */
@@ -1656,7 +1731,7 @@ declare module "littlejsengine" {
      * - Optimized tile sheet sprite rendering using WebGL batching
      * - Primitive drawing for polygons, ellipses, and lines
      * - Tile-based rendering with TileInfo and TextureInfo classes
-     * - Text rendering with custom fonts and FontImage support
+     * - Text rendering with custom fonts and ImageFont support
      * - Color and additive color blending for effects
      * - Rotation, mirroring, and scaling transformations
      * - Camera system with position, scale, and rotation
@@ -1833,9 +1908,9 @@ declare module "littlejsengine" {
      *  @param {Vector2} [size=vec2(1)]
      *  @param {number}  [sides]
      *  @param {Color}   [color=WHITE]
-     *  @param {number}  [angle]
      *  @param {number}  [lineWidth]
      *  @param {Color}   [lineColor=BLACK]
+     *  @param {number}  [angle]
      *  @param {boolean} [useWebGL=glEnable]
      *  @param {boolean} [screenSpace]
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
@@ -1864,13 +1939,29 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
     export function drawCircle(pos: Vector2, size?: number, color?: Color, lineWidth?: number, lineColor?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-    export function drawCircleGradient(pos: any, size: number, colorInner: Color, colorOuter: Color, useWebGL: boolean, screenSpace: boolean, context: any): void;
+    export function drawEllipseGradient(pos: any, size: Vector2, colorInner: Color, colorOuter: Color, angle: number, useWebGL: boolean, screenSpace: boolean, context: any): void;
+    /** Draw a circle filled with a radial gradient from the center to the rim
+     *  - Best when batched with other untextured polys
+     *  - If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
+     *  - Stacking gradients at the exact same position may show a faint vertical artifact
+     *  @param {Vector2} pos
+     *  @param {number}  [size=1] - Diameter
+     *  @param {Color}   [colorInner=WHITE]
+     *  @param {Color}   [colorOuter=CLEAR_WHITE]
+     *  @param {boolean} [useWebGL=glEnable]
+     *  @param {boolean} [screenSpace]
+     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
+     *  @memberof Draw */
+    export function drawCircleGradient(pos: Vector2, size?: number, colorInner?: Color, colorOuter?: Color, useWebGL?: boolean, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
     /**
      * @callback Canvas2DDrawFunction - A function that draws to a 2D canvas context
      * @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
@@ -1922,11 +2013,11 @@ declare module "littlejsengine" {
      *  @memberof Draw */
     export function combineCanvases(): void;
     /** Engine font image, 8x8 font provided by the engine
-     *  @type {FontImage}
+     *  @type {ImageFont}
      *  @memberof Draw */
-    export let engineFontImage: FontImage;
+    export let engineImageFont: ImageFont;
     /**
-     * Font Image Object - Draw text by using tiles in an image
+     * Image Font Object - Draw text by using tiles in an image
      * - 96 characters (from space to tilde) are stored in an image
      * - A 8x8 default engine font is supplied for general use
      * - This system is WebGL enabled for fast text rendering
@@ -1935,12 +2026,12 @@ declare module "littlejsengine" {
      * @memberof Draw
      * @example
      * // use built in font
-     * const font = engineFontImage;
+     * const font = engineImageFont;
      *
      * // draw text
      * font.drawTextScreen('LittleJS\nHello World!', vec2(200, 50));
      */
-    export class FontImage {
+    export class ImageFont {
         /** Create an image font
          *  @param {TileInfo} tileInfo - Tile info of first character in font
          */
@@ -2087,9 +2178,9 @@ declare module "littlejsengine" {
      *  @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;
     /** Add an untextured rect to the gl draw list
-     *  Picks the optimal path: if already in poly mode, emits a tristrip rect
-     *  so it batches with surrounding polys; otherwise uses the instanced path
-     *  with uvs and rgba zeroed so the color falls through the additive slot.
+     *  Zeroes the uvs and rgba so the texture contribution multiplies to 0,
+     *  then carries the real color in the additive slot. Works regardless of
+     *  which texture is currently bound.
      *  @param {number} x
      *  @param {number} y
      *  @param {number} sizeX
@@ -2405,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
@@ -2424,7 +2515,7 @@ declare module "littlejsengine" {
          */
         playNote(semitoneOffset?: number, pos?: Vector2, volume?: number): SoundInstance;
         /** Get how long this sound is in seconds
-         *  @return {number} - How long the sound is in seconds (undefined if loading)
+         *  @return {number} - How long the sound is in seconds (0 if loading)
          */
         getDuration(): number;
         /** Check if sound is loaded, for sounds fetched from a url
@@ -2505,7 +2596,7 @@ declare module "littlejsengine" {
          */
         getCurrentTime(): number;
         /** Get the total duration of this sound
-         *  @return {number} - Total duration in seconds
+         *  @return {number} - Total duration in seconds (0 if loading)
          */
         getDuration(): number;
         /** Get source of this sound instance
@@ -2641,7 +2732,7 @@ declare module "littlejsengine" {
         color: Color;
         /** @property {Color} - Additive color to apply when rendered */
         additiveColor: any;
-        /** @property {boolean} - Should it flip along y axis when rendered */
+        /** @property {boolean} - Should the rendered tile flip along the y axis. Affects rendering and the local→world transform of attached children (a mirrored parent flips its children's localPos.x and localAngle). Does not affect this object's own physics, collision, or localToWorld/worldToLocal. */
         mirror: boolean;
         /** @property {boolean} - Has object been destroyed? */
         destroyed: boolean;
@@ -2693,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;
@@ -2898,20 +2991,6 @@ declare module "littlejsengine" {
         *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context] - Canvas 2D context to draw to
         *  @memberof Draw */
         draw(pos: Vector2, size?: Vector2, color?: Color, angle?: number, mirror?: boolean, additiveColor?: Color, screenSpace?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-        /** Draw a tile onto the layer canvas in world space
-         *  @param {Vector2}  pos
-         *  @param {Vector2}  [size=vec2(1)]
-         *  @param {TileInfo} [tileInfo]
-         *  @param {Color}    [color=WHITE]
-         *  @param {number}   [angle]
-         *  @param {boolean}  [mirror] */
-        drawTile(pos: Vector2, size?: Vector2, tileInfo?: TileInfo, color?: Color, angle?: number, mirror?: boolean): void;
-        /** Draw a rectangle onto the layer canvas in world space
-         *  @param {Vector2} pos
-         *  @param {Vector2} [size=vec2(1)]
-         *  @param {Color}   [color=WHITE]
-         *  @param {number}  [angle] */
-        drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number): void;
         /** Create WebGL texture if necessary and copy layer canvas to it */
         updateWebGL(): void;
         /** Check if this layer is using WebGL
@@ -2982,6 +3061,20 @@ declare module "littlejsengine" {
          *  @param {number} [angle] - Angle to rotate by
          */
         drawLayerRect(pos: Vector2, size: Vector2, color?: Color, angle?: number): void;
+        /** Draw a tile onto the layer canvas in world space
+         *  @param {Vector2}  pos
+         *  @param {Vector2}  [size=vec2(1)]
+         *  @param {TileInfo} [tileInfo]
+         *  @param {Color}    [color=WHITE]
+         *  @param {number}   [angle]
+         *  @param {boolean}  [mirror] */
+        drawTile(pos: Vector2, size?: Vector2, tileInfo?: TileInfo, color?: Color, angle?: number, mirror?: boolean): void;
+        /** Draw a rectangle onto the layer canvas in world space
+         *  @param {Vector2} pos
+         *  @param {Vector2} [size=vec2(1)]
+         *  @param {Color}   [color=WHITE]
+         *  @param {number}  [angle] */
+        drawRect(pos: Vector2, size?: Vector2, color?: Color, angle?: number): void;
         /** Clear a rectangle in layer space
          *  @param {Vector2} pos - position in pixel coordinates
          *  @param {Vector2} size
@@ -2998,8 +3091,8 @@ declare module "littlejsengine" {
         clearData(layerPos: Vector2, redraw?: boolean): void;
         /** Get data at a given position in the array
          *  @param {Vector2} layerPos - Local position in array
-         *  @return {TileLayerData} */
-        getData(layerPos: Vector2): TileLayerData;
+         *  @return {TileLayerData|undefined} */
+        getData(layerPos: Vector2): TileLayerData | undefined;
         /** Called after this layer is redrawn, does nothing by default */
         onRedraw(): void;
         /** @type {[CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D, Vector2, Vector2, number, Color]} */
@@ -3102,13 +3195,13 @@ 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]          - How quick to fade particles at start/end in percent of life
+         *  @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
          *  @param {number} [randomness]    - Apply extra randomness percent
          *  @param {boolean} [collideTiles] - Do particles collide against tiles
          *  @param {boolean} [additive]     - Should particles use additive blend
@@ -3143,13 +3236,13 @@ 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;
-        /** @property {number} - How quick to fade in particles at start/end in percent of life */
+        /** @property {number} - Fraction of life spent fading, split half at start and half at end (e.g. .2 = 10% fade-in + 10% fade-out) */
         fadeRate: number;
         /** @property {number} - Apply extra randomness percent */
         randomness: number;
@@ -3249,6 +3342,21 @@ declare module "littlejsengine" {
      *  @default
      *  @memberof Settings */
     export let medalsPreventUnlock: boolean;
+    /** How long to show medals for in seconds
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let medalDisplayTime: number;
+    /** How quickly to slide on/off medals in seconds
+     *  @type {number}
+     *  @default
+     *  @memberof Settings */
+    export let medalDisplaySlideTime: number;
+    /** Size of medal display
+     *  @type {Vector2}
+     *  @default Vector2(640,80)
+     *  @memberof Settings */
+    export let medalDisplaySize: Vector2;
     /** Initialize medals with a save name used for storage
      *  - Call this after creating all medals
      *  - Checks if medals are unlocked
@@ -3264,6 +3372,25 @@ 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 */
+    export function setMedalDisplayTime(time: number): void;
+    /** Set how quickly to slide on/off medals in seconds
+     *  @param {number} time
+     *  @memberof Settings */
+    export function setMedalDisplaySlideTime(time: number): void;
+    /** Set size of medal display
+     *  @param {Vector2} size
+     *  @memberof Settings */
+    export function setMedalDisplaySize(size: Vector2): void;
+    /** Set to stop medals from being unlockable
+     *  @param {boolean} preventUnlock
+     *  @memberof Settings */
+    export function setMedalsPreventUnlock(preventUnlock: boolean): void;
     /**
      * Medal - Tracks an unlockable medal
      * @memberof Medals
@@ -3309,39 +3436,7 @@ declare module "littlejsengine" {
          *  @param {number} size - Screen space size
          */
         renderIcon(pos: Vector2, size: number): void;
-        storageKey(): string;
     }
-    /** How long to show medals for in seconds
-     *  @type {number}
-     *  @default
-     *  @memberof Settings */
-    export let medalDisplayTime: number;
-    /** How quickly to slide on/off medals in seconds
-     *  @type {number}
-     *  @default
-     *  @memberof Settings */
-    export let medalDisplaySlideTime: number;
-    /** Size of medal display
-     *  @type {Vector2}
-     *  @default Vector2(640,80)
-     *  @memberof Settings */
-    export let medalDisplaySize: Vector2;
-    /** Set how long to show medals for in seconds
-     *  @param {number} time
-     *  @memberof Settings */
-    export function setMedalDisplayTime(time: number): void;
-    /** Set how quickly to slide on/off medals in seconds
-     *  @param {number} time
-     *  @memberof Settings */
-    export function setMedalDisplaySlideTime(time: number): void;
-    /** Set size of medal display
-     *  @param {Vector2} size
-     *  @memberof Settings */
-    export function setMedalDisplaySize(size: Vector2): void;
-    /** Set to stop medals from being unlockable
-     *  @param {boolean} preventUnlock
-     *  @memberof Settings */
-    export function setMedalsPreventUnlock(preventUnlock: boolean): void;
     /**
      * LittleJS Newgrounds Plugin
      * - NewgroundsMedal extends Medal with Newgrounds API functionality
@@ -3380,9 +3475,7 @@ declare module "littlejsengine" {
         host: string;
         /** @property {string|null} - Newgrounds session id from the URL (null when not logged in) */
         session_id: string;
-        /** @property {Array} - Medals fetched from Newgrounds (empty until session is active) */
         medals: any;
-        /** @property {Array} - Scoreboards fetched from Newgrounds */
         scoreboards: any;
         /** Send message to unlock a medal by id
          * @param {number} id - The medal id */
@@ -3449,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
@@ -3498,6 +3670,14 @@ declare module "littlejsengine" {
          */
         playMusic(volume?: number, loop?: boolean): SoundInstance;
     }
+    /** Generate samples for a ZzFM song with given parameters
+     *  @param {Array} instruments - Array of ZzFX sound parameters
+     *  @param {Array} patterns - Array of pattern data
+     *  @param {Array} sequence - Array of pattern indexes
+     *  @param {number} [BPM] - Playback speed of the song in BPM
+     *  @return {Array} - Left and right channel sample data
+     *  @memberof ZzFXM */
+    export function zzfxM(instruments: any[], patterns: any[], sequence: any[], BPM?: number): any[];
     /**
      * LittleJS User Interface Plugin
      * - call new UISystemPlugin() to setup the UI system
@@ -3659,6 +3839,7 @@ declare module "littlejsengine" {
         *  @param {DragAndDropCallback} [onDragLeave] - when a file is dragged off the window
         *  @param {DragAndDropCallback} [onDragOver] - continuously when dragging over */
         setupDragAndDrop(onDrop?: (event: DragEvent) => any, onDragEnter?: (event: DragEvent) => any, onDragLeave?: (event: DragEvent) => any, onDragOver?: (event: DragEvent) => any): void;
+        _dragListeners: any[];
         /** Convert a screen space position to native UI position
          *  @param {Vector2} pos
          *  @return {Vector2} */
@@ -4225,7 +4406,9 @@ declare module "littlejsengine" {
         /** Add a box shape to the body
          *  @param {Vector2} [size]
          *  @param {Vector2} [offset]
-         *  @param {number}  [angle]
+         *  @param {number}  [angle] - LittleJS convention (clockwise positive).
+         *      Negated internally to match Box2D's CCW-positive convention so the
+         *      fixture aligns with the same angle passed to drawRect/drawTile.
          *  @param {number}  [density]
          *  @param {number}  [friction]
          *  @param {number}  [restitution]
@@ -5086,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