littlejsengine 1.18.17 → 1.18.18

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 */
@@ -666,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;
@@ -1385,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} */
@@ -2003,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 */
@@ -2074,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
@@ -2325,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 */
@@ -2345,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]
@@ -3885,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 */
@@ -5215,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
@@ -5238,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
@@ -5263,8 +5327,8 @@ 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 */