littlejsengine 1.18.15 → 1.18.18

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

@@ -390,6 +390,8 @@ declare module "littlejsengine" {
      *  @memberof Settings */
     export let canvasPixelated: boolean;
     /** Disables texture filtering for crisper pixel art
+     *  - Leave true for pixel art so sprites stay sharp when scaled (uses NEAREST filtering)
+     *  - Set false for smooth/high-resolution art to enable bilinear filtering and mipmaps
      *  @type {boolean}
      *  @default
      *  @memberof Settings */
@@ -510,31 +512,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 +589,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
@@ -622,6 +668,7 @@ declare module "littlejsengine" {
      *  @memberof Settings */
     export function setCanvasPixelated(pixelated: boolean): void;
     /** Disables texture filtering for crisper pixel art
+     *  - Leave true for pixel art; set false for smooth/high-resolution art
      *  @param {boolean} pixelated
      *  @memberof Settings */
     export function setTilesPixelated(pixelated: boolean): void;
@@ -718,20 +765,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 +812,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 */
@@ -1316,9 +1388,17 @@ declare module "littlejsengine" {
          * @param {Color} c - other color
          * @return {Color} */
         setFrom(c: Color): Color;
+        /** Sets the alpha of this color and returns self
+         *  @param {number} [a] - alpha
+         *  @return {Color} */
+        setAlpha(a?: number): Color;
         /** Returns a new color that is a copy of this
          * @return {Color} */
         copy(): Color;
+        /** Returns a copy of this color with the alpha set
+         *  @param {number} [a] - alpha
+         *  @return {Color} */
+        withAlpha(a?: number): Color;
         /** Returns a copy of this color plus the color passed in
          * @param {Color} c - other color
          * @return {Color} */
@@ -1889,7 +1969,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
@@ -1931,11 +2014,10 @@ declare module "littlejsengine" {
      *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context=drawContext]
      *  @memberof Draw */
     export function drawTextScreen(text: string | number, pos: Vector2, size: number, color?: Color, lineWidth?: number, lineColor?: Color, textAlign?: CanvasTextAlign, font?: string, fontStyle?: string, maxWidth?: number, angle?: number, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
-    /** Enable normal or additive blend mode
+    /** Enable additive blending
      *  @param {boolean} [additive]
-     *  @param {CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D} [context]
      *  @memberof Draw */
-    export function setBlendMode(additive?: boolean, context?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D): void;
+    export function setAdditiveBlendMode(additive?: boolean): void;
     /** Combines LittleJS canvases onto the main canvas
      *  This is necessary for things like screenshots and video
      *  @memberof Draw */
@@ -2002,6 +2084,19 @@ declare module "littlejsengine" {
      *  @return {Vector2}
      *  @memberof Draw */
     export function getCameraSize(): Vector2;
+    /** Fit the camera to a rectangle in world space by setting cameraPos and cameraScale
+     *  - worldMargin pads the content rectangle in world units, so the gap scales with the content on resize
+     *  - screenInset reserves space in screen pixels on each viewport edge (for example a HUD band) and
+     *    re-centers the content away from that edge, so the reserved band stays a fixed pixel size on resize
+     *  - worldMargin and screenInset may each be a number for all sides, a Vector2 (x=left/right, y=top/bottom),
+     *    or an object with any of {top, right, bottom, left}
+     *  @param {Vector2} center - Center of the rectangle in world space
+     *  @param {Vector2} size - Size of the rectangle in world space
+     *  @param {number|Vector2|Object} [worldMargin] - World space padding added around the content rectangle
+     *  @param {number|Vector2|Object} [screenInset] - Screen space padding in pixels reserved on each viewport edge
+     *  @return {number} - The new camera scale
+     *  @memberof Draw */
+    export function cameraFit(center: Vector2, size: Vector2, worldMargin?: number | Vector2 | any, screenInset?: number | Vector2 | any): number;
     /** Check if a box, point, or circle is on screen with a circle test
      *  If size is a Vector2, uses the length as diameter
      *  This can be used to cull offscreen objects from render or update
@@ -2253,10 +2348,27 @@ declare module "littlejsengine" {
      *  @type {boolean}
      *  @memberof Input */
     export let mouseInWindow: boolean;
-    /** Returns true if user is using gamepad (has more recently pressed a gamepad button)
+    /** True if a gamepad is the most recently used input device.
+     *  Equivalent to usingGamepadInput(); derived from lastInputDevice each frame.
      *  @type {boolean}
      *  @memberof Input */
     export let isUsingGamepad: boolean;
+    /** The most recently used input device: 'mouse' | 'keyboard' | 'gamepad'.
+     *  Sticky: it holds its value while every device is idle, so a mouse-follow
+     *  control (e.g. paddle = mousePos) won't snap back the instant the stick/keys
+     *  are released. With several devices in play at once (e.g. keyboard to move +
+     *  mouse to aim) it tracks whichever was touched last each frame, so it may
+     *  alternate — that's intended; use it to pick which control drives a shared
+     *  action. Updated every frame by inputUpdate().
+     *  @type {string}
+     *  @memberof Input */
+    export let lastInputDevice: string;
+    /** Screen-pixel mouse movement per frame that counts as "using the mouse"
+     *  (so sub-pixel hand jitter doesn't steal focus from the keyboard/gamepad).
+     *  @type {number}
+     *  @default
+     *  @memberof Input */
+    export let inputMouseMoveThreshold: number;
     /** Prevents input continuing to the default browser handling (true by default)
      *  @type {boolean}
      *  @memberof Input */
@@ -2273,6 +2385,16 @@ declare module "littlejsengine" {
      *  @param {boolean} preventDefault
      *  @memberof Input */
     export function setInputPreventDefault(preventDefault?: boolean): void;
+    /** Set the screen-pixel mouse movement per frame that counts as using the mouse
+     *  @param {number} threshold
+     *  @memberof Input */
+    export function setInputMouseMoveThreshold(threshold: number): void;
+    /** @return {boolean} - Is the mouse the most recently used input device?    @memberof Input */
+    export function usingMouseInput(): boolean;
+    /** @return {boolean} - Is the keyboard the most recently used input device? @memberof Input */
+    export function usingKeyboardInput(): boolean;
+    /** @return {boolean} - Is a gamepad the most recently used input device?    @memberof Input */
+    export function usingGamepadInput(): boolean;
     /** Returns true if gamepad button is down
      *  @param {number} button
      *  @param {number} [gamepad]
@@ -2424,7 +2546,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 +2834,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 +3245,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 +3286,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 +3422,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 +3486,6 @@ declare module "littlejsengine" {
          *  @param {number} size - Screen space size
          */
         renderIcon(pos: Vector2, size: number): void;
-        storageKey(): string;
     }
     /**
      * LittleJS Newgrounds Plugin
@@ -3466,6 +3592,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
@@ -3730,10 +3935,15 @@ declare module "littlejsengine" {
          *  @param {Vector2}  [size=vec2(1)]
          */
         constructor(pos?: Vector2, size?: Vector2);
-        /** @property {Vector2} - Local position of the object */
+        /** @property {Vector2} - Position you set: an offset from this object's
+         *  anchor point (the parent box, or the canvas for roots). This is the
+         *  input that controls placement — set this, not nativePos. */
         localPos: Vector2;
-        /** @property {Vector2} - Screen space position of the object */
-        pos: Vector2;
+        /** @property {Vector2} - Resolved position in native UI space, recomputed
+         *  every frame from localPos + anchor (and nativeHeight, if set). This is a
+         *  derived output used for drawing and hit-testing; assigning to it has no
+         *  effect since it is overwritten each frame. Set localPos instead. */
+        nativePos: Vector2;
         /** @property {Vector2} - Screen space size of the object */
         size: Vector2;
         /** @property {Color} - Color of the object */
@@ -5060,11 +5270,16 @@ declare module "littlejsengine" {
     }
     /** Draw a scalable nine-slice UI element in world space
      *  This function can apply color and additive color if WebGL is enabled
+     *  The nine-slice samples a 3x3 block of tiles from the tilesheet, it does not
+     *  subdivide a single tile. Pass the top-left tile of that block as startTile;
+     *  the other 8 tiles (edges, corners, and center) are taken automatically from
+     *  the 3x3 grid of tiles extending right and down from it. borderSize only sets
+     *  the rendered thickness of the edges and corners, not how the texture is cut.
      *  @param {Vector2} pos - World space position
      *  @param {Vector2} size - World space size
-     *  @param {TileInfo} startTile - Starting tile for the nine-slice pattern
+     *  @param {TileInfo} startTile - Top-left tile of the 3x3 block to sample the nine-slice from
      *  @param {Color} [color] - Color to modulate with
-     *  @param {number} [borderSize] - Width of the border sections
+     *  @param {number} [borderSize] - Rendered thickness of the border sections
      *  @param {Color} [additiveColor] - Additive color
      *  @param {number} [extraSpace] - Extra spacing adjustment
      *  @param {number} [angle] - Angle to rotate by
@@ -5083,19 +5298,23 @@ declare module "littlejsengine" {
      *  This function can not apply color because it draws using the 2d context
      *  @param {Vector2} pos - Screen space position
      *  @param {Vector2} size - Screen space size
-     *  @param {TileInfo} startTile - Starting tile for the nine-slice pattern
-     *  @param {number} [borderSize] - Width of the border sections
+     *  @param {TileInfo} startTile - Top-left tile of the 3x3 block to sample (see drawNineSlice)
+     *  @param {number} [borderSize] - Rendered thickness of the border sections
      *  @param {number} [extraSpace] - Extra spacing adjustment
      *  @param {number} [angle] - Angle to rotate by
      *  @memberof DrawUtilities */
     export function drawNineSliceScreen(pos: Vector2, size: Vector2, startTile: TileInfo, borderSize?: number, extraSpace?: number, angle?: number): void;
     /** Draw a scalable three-slice UI element in world space
      *  This function can apply color and additive color if WebGL is enabled
+     *  The three-slice samples 3 consecutive tiles from the tilesheet, it does not
+     *  subdivide a single tile. Pass the first tile as startTile; the three tiles
+     *  are used in order as corner, side, and center, then rotated and mirrored to
+     *  build all four edges and corners. borderSize only sets the rendered thickness.
      *  @param {Vector2} pos - World space position
      *  @param {Vector2} size - World space size
-     *  @param {TileInfo} startTile - Starting tile for the three-slice pattern
+     *  @param {TileInfo} startTile - First of 3 consecutive tiles (corner, side, center) for the three-slice
      *  @param {Color} [color] - Color to modulate with
-     *  @param {number} [borderSize] - Width of the border sections
+     *  @param {number} [borderSize] - Rendered thickness of the border sections
      *  @param {Color} [additiveColor] - Additive color
      *  @param {number} [extraSpace] - Extra spacing adjustment
      *  @param {number} [angle] - Angle to rotate by
@@ -5108,12 +5327,38 @@ declare module "littlejsengine" {
      *  This function can not apply color because it draws using the 2d context
      *  @param {Vector2} pos - Screen space position
      *  @param {Vector2} size - Screen space size
-     *  @param {TileInfo} startTile - Starting tile for the three-slice pattern
-     *  @param {number} [borderSize] - Width of the border sections
+     *  @param {TileInfo} startTile - First of 3 consecutive tiles: corner, side, center (see drawThreeSlice)
+     *  @param {number} [borderSize] - Rendered thickness of the border sections
      *  @param {number} [extraSpace] - Extra spacing adjustment
      *  @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