litecanvas 0.63.0 → 0.65.0

package/types/types.d.ts

@@ -42,55 +42,55 @@ type LitecanvasInstance = {
     /**
      * Calculates a linear (interpolation) value over t%.
      *
-     * @param {number} start
-     * @param {number} end
-     * @param {number} t The progress in percentage, where 0 = 0% and 1 = 100%.
-     * @returns {number} The unterpolated value
+     * @param start
+     * @param end
+     * @param t The progress in percentage, where 0 = 0% and 1 = 100%.
+     * @returns The unterpolated value
      * @tutorial https://gamedev.net/tutorials/programming/general-and-gameplay-programming/a-brief-introduction-to-lerp-r4954/
      */
     lerp(start: number, end: number, t: number): number
     /**
      * Convert degrees to radians
      *
-     * @param {number} degs
-     * @returns {number} the value in radians
+     * @param degs
+     * @returns the value in radians
      */
     deg2rad(degs: number): number
     /**
      * Convert radians to degrees
      *
-     * @param {number} rads
-     * @returns {number} the value in degrees
+     * @param rads
+     * @returns the value in degrees
      */
     rad2deg(rads: number): number
     /**
      * Constrains a number between `min` and `max`.
      *
-     * @param {number} value
-     * @param {number} min
-     * @param {number} max
-     * @returns {number}
+     * @param value
+     * @param min
+     * @param max
+     * @returns
      */
     clamp(value: number, min: number, max: number): number
     /**
      * Wraps a number between `min` (inclusive) and `max` (exclusive).
      *
-     * @param {number} value
-     * @param {number} min
-     * @param {number} max
-     * @returns {number}
+     * @param value
+     * @param min
+     * @param max
+     * @returns
      */
     wrap(value: number, min: number, max: number): number
     /**
      * Re-maps a number from one range to another.
      *
-     * @param {number} value  the value to be remapped.
-     * @param {number} min1 lower bound of the value's current range.
-     * @param {number} max1  upper bound of the value's current range.
-     * @param {number} min2 lower bound of the value's target range.
-     * @param {number} max2  upper bound of the value's target range.
-     * @param {boolean} [withinBounds=false] constrain the value to the newly mapped range
-     * @returns {number} the remapped number
+     * @param value  the value to be remapped.
+     * @param min1 lower bound of the value's current range.
+     * @param max1  upper bound of the value's current range.
+     * @param min2 lower bound of the value's target range.
+     * @param max2  upper bound of the value's target range.
+     * @param [withinBounds=false] constrain the value to the newly mapped range
+     * @returns the remapped number
      */
     map(
         value: number,
@@ -105,10 +105,10 @@ type LitecanvasInstance = {
      * Identical to `map(value, min, max, 0, 1)`.
      * Note: Numbers outside the range are not clamped to 0 and 1.
      *
-     * @param {number} value
-     * @param {number} min
-     * @param {number} max
-     * @returns {number} the normalized number.
+     * @param value
+     * @param min
+     * @param max
+     * @returns the normalized number.
      */
     norm(value: number, min: number, max: number): number
     /**
@@ -181,42 +181,37 @@ type LitecanvasInstance = {
     /**
      * Generates a pseudorandom float between min (inclusive) and max (exclusive)
      *
-     * @param {number} [min=0.0]
-     * @param {number} [max=1.0]
-     * @returns {number} the random number
+     * @param [min=0.0]
+     * @param [max=1.0]
+     * @returns the random number
      */
     rand(min?: number, max?: number): number
     /**
      * Generates a pseudorandom integer between min (inclusive) and max (inclusive)
      *
-     * @param {number} [min=0]
-     * @param {number} [max=1]
-     * @returns {number} the random number
+     * @param [min=0]
+     * @param [max=1]
+     * @returns the random number
      */
     randi(min?: number, max?: number): number
-    /**
-     * Returns the fractional part of a number
-     *
-     * @param {number} value The number
-     * @returns {number}
-     */
 
     /** BASIC GRAPHICS API */
     /**
      * Clear the game screen
      *
-     * @param {number|null} color The background color (from 0 to 7) or null
+     * @param color The background color index or `null`
      */
     cls(color: number | null): void
+
     /**
      * Draw a rectangle outline
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
-     * @param {number} [color=0] the color index (generally from 0 to 7)
-     * @param {number|number[]} [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
+     * @param x
+     * @param y
+     * @param width
+     * @param height
+     * @param [color=0] the color index
+     * @param [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
      */
     rect(
         x: number,
@@ -229,12 +224,12 @@ type LitecanvasInstance = {
     /**
      * Draw a color-filled rectangle
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
-     * @param {number} [color=0] the color index (generally from 0 to 7)
-     * @param {number|number[]} [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
+     * @param x
+     * @param y
+     * @param width
+     * @param height
+     * @param [color=0] the color index
+     * @param [radii] A number or list specifying the radii used to draw a rounded-borders rectangle
      */
     rectfill(
         x: number,
@@ -247,81 +242,81 @@ type LitecanvasInstance = {
     /**
      * Draw a circle outline
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} radius
-     * @param {number} [color=0] the color index (generally from 0 to 7)
+     * @param x
+     * @param y
+     * @param radius
+     * @param [color=0] the color index
      */
     circ(x: number, y: number, radius: number, color?: number): void
     /**
      * Draw a color-filled circle
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} radius
-     * @param {number} [color=0] the color index (generally from 0 to 7)
+     * @param x
+     * @param y
+     * @param radius
+     * @param [color=0] the color index
      */
     circfill(x: number, y: number, radius: number, color?: number): void
     /**
      * Draw a line
      *
-     * @param {number} x1
-     * @param {number} y1
-     * @param {number} x2
-     * @param {number} y2
-     * @param {number} [color=0] the color index (generally from 0 to 7)
+     * @param x1
+     * @param y1
+     * @param x2
+     * @param y2
+     * @param [color=0] the color index
      */
     line(x1: number, y1: number, x2: number, y2: number, color?: number): void
     /**
      * Sets the thickness of lines
      *
-     * @param {number} value
+     * @param value
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineWidth
      */
     linewidth(value: number): void
     /**
      * Sets the line dash pattern used when drawing lines
      *
-     * @param {number|number[]} segments the line dash pattern
-     * @param {number} [offset=0] the line dash offset, or "phase".
+     * @param segments the line dash pattern
+     * @param [offset=0] the line dash offset, or "phase".
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
      */
-    linedash(segments: number | number[], offset?: number): void
+    linedash(segments: number[], offset?: number): void
 
     /** TEXT RENDERING API */
     /**
      * Draw text
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {string} text the text message
-     * @param {number} [color=3] the color index (generally from 0 to 7)
+     * @param x
+     * @param y
+     * @param text the text message
+     * @param [color=3] the color index
      */
     text(x: number, y: number, text: string, color?: number): void
     /**
      * Set the font family
      *
-     * @param {string} fontFamily
+     * @param fontFamily
      */
     textfont(fontFamily: string): void
     /**
      * Set the font size
      *
-     * @param {string} size
+     * @param size
      */
     textsize(size: string): void
     /**
      * Sets whether a font should be styled with a normal, italic, or bold.
      *
-     * @param {string} style
+     * @param style
      */
     textstyle(style: string): void
     /**
      * Sets the alignment used when drawing texts
      *
-     * @param {string} align the horizontal alignment. Possible values: "left", "right", "center", "start" or "end"
-     * @param {string} baseline the vertical alignment. Possible values: "top", "bottom", "middle", "hanging" or "ideographic"
+     * @param align the horizontal alignment. Possible values: "left", "right", "center", "start" or "end"
+     * @param baseline the vertical alignment. Possible values: "top", "bottom", "middle", "hanging" or "ideographic"
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign
      */
@@ -329,9 +324,8 @@ type LitecanvasInstance = {
     /**
      * Returns a TextMetrics object that contains information about the measured text (such as its width, for example)
      *
-     * @param {string} text
-     * @param {number} [size]
-     * @returns {TextMetrics}
+     * @param text
+     * @param [size]
      * @see https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics
      */
     textmetrics(text: string, size?: number): TextMetrics
@@ -340,9 +334,9 @@ type LitecanvasInstance = {
     /**
      * Draw an image
      *
-     * @param {number} x
-     * @param {number} y
-     * @param {OffscreenCanvas|HTMLImageElement|HTMLCanvasElement} image
+     * @param x
+     * @param y
+     * @param image
      */
     image(
         x: number,
@@ -352,11 +346,10 @@ type LitecanvasInstance = {
     /**
      * Creates a offscreen canvas to draw on it
      *
-     * @param {number} width
-     * @param {number} height
-     * @param {string[]|drawCallback} draw
-     * @param {{scale?:number}} [options]
-     * @returns {OffscreenCanvas}
+     * @param width
+     * @param height
+     * @param draw
+     * @param [options]
      * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
      */
     paint(
@@ -372,9 +365,12 @@ type LitecanvasInstance = {
     /** ADVANCED GRAPHICS API */
     /**
      * Get or set the canvas context 2D
+     *
+     * @param [context] an new canvas context
+     * @returns the current canvas context
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D
      */
-    ctx(value?: CanvasRenderingContext2D): CanvasRenderingContext2D
+    ctx(context?: CanvasRenderingContext2D): CanvasRenderingContext2D
     /**
      * saves the current drawing style settings and transformations
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
@@ -388,31 +384,31 @@ type LitecanvasInstance = {
     /**
      * Adds a translation transformation to the current matrix
      *
-     * @param {number} x
-     * @param {number} y
+     * @param x
+     * @param y
      */
     translate(x: number, y: number): void
     /**
      * Adds a scaling transformation to the canvas units horizontally and/or vertically.
      *
-     * @param {number} x
-     * @param {number} [y]
+     * @param x
+     * @param [y]
      */
     scale(x: number, y?: number): void
     /**
      * Adds a rotation to the transformation matrix
      *
-     * @param {number} radians
+     * @param radians
      */
     rotate(radians: number): void
     /**
-     * @param {number} a
-     * @param {number} b
-     * @param {number} c
-     * @param {number} d
-     * @param {number} e
-     * @param {number} f
-     * @param {boolean} [resetFirst=true] `false` to use _ctx.transform(); by default use _ctx.setTransform()
+     * @param a
+     * @param b
+     * @param c
+     * @param d
+     * @param e
+     * @param f
+     * @param [resetFirst=true] `false` to use _ctx.transform(); by default use _ctx.setTransform()
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setTransform
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/transform
@@ -429,7 +425,7 @@ type LitecanvasInstance = {
     /**
      * Sets the alpha (transparency) value to apply when drawing new shapes and images
      *
-     * @param {number} alpha float from 0 to 1 (e.g: 0.5 = 50% transparent)
+     * @param alpha float from 0 to 1 (e.g: 0.5 = 50% transparent)
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalAlpha
      */
     alpha(alpha: number): void
@@ -438,61 +434,40 @@ type LitecanvasInstance = {
      * path as an argument (creates a copy), or optionally with a string
      * consisting of SVG path data.
      *
-     * @param {Path2D|string} [arg]
-     * @returns Path2D
+     * @param [arg]
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
      */
     path(arg?: Path2D | string): Path2D
     /**
      * Fills the current or given path with a given color.
      *
-     * @param {number} color
-     * @param {Path2D} [path]
+     * @param color
+     * @param [path]
      */
     fill(color: number, path?: Path2D): void
     /**
      * Outlines the current or given path with a given color.
      *
-     * @param {number} color
-     * @param {Path2D} [path]
+     * @param color
+     * @param [path]
      */
     stroke(color: number, path?: Path2D): void
     /**
-     * Create a retangular clipping region.
-     *
-     * Note: Clip paths cannot be reverted directly. You must save your
-     * canvas state using push() before calling cliprect(), and restore it
-     * once you have finished drawing in the clipped area using pop().
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} width
-     * @param {number} height
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/clip
-     */
-    cliprect(x: number, y: number, width: number, height: number): void
-    /**
-     * Create a circular clipping region.
+     * Turn given path into a clipping region.
      *
-     * Note: Clip paths cannot be reverted directly. You must save your
-     * canvas state using push() before calling clipcirc(), and restore it
-     * once you have finished drawing in the clipped area using pop().
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} radius
+     * @param path
      * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/clip
      */
-    clipcirc(x: number, y: number, radius: number): void
+    clip(path: Path2D): void
 
     /** SOUND API */
     /**
      * Play a sound effects using ZzFX library.
      * If the first argument is omitted, plays an default sound.
      *
-     * @param {number|number[]} [zzfxParams] a ZzFX array of params
-     * @param {number} [pitchSlide] a value to increment/decrement the pitch
-     * @param {number} [volumeFactor] the volume factor
+     * @param [zzfxParams] a ZzFX array of params
+     * @param [pitchSlide=0] a value to increment/decrement the pitch
+     * @param [volumeFactor=1] the volume factor
      * @returns The sound that was played or `false`
      *
      * @see https://github.com/KilledByAPixel/ZzFX
@@ -506,14 +481,13 @@ type LitecanvasInstance = {
      * Set the ZzFX's global volume factor.
      * Note: use 0 to mute all sound effects.
      *
-     * @param {number} value
+     * @param value
      */
     volume(value: number): void
 
     /** UTILS API */
     /**
      * Checks if a key is currently pressed in your keyboard.
-     *
      * Notes:
      * - to check the space key use `iskeydown(" ")`.
      * - you can check if any key is pressed using `iskeydown("any")`.
@@ -525,15 +499,14 @@ type LitecanvasInstance = {
     /**
      * Check a collision between two rectangles
      *
-     * @param {number} x1 first rectangle position X
-     * @param {number} y1 first rectangle position Y
-     * @param {number} w1 first rectangle width
-     * @param {number} h1 first rectangle height
-     * @param {number} x2 second rectangle position X
-     * @param {number} y2 second rectangle position Y
-     * @param {number} w2 second rectangle width
-     * @param {number} h2 second rectangle height
-     * @returns {boolean}
+     * @param x1 first rectangle position X
+     * @param y1 first rectangle position Y
+     * @param w1 first rectangle width
+     * @param h1 first rectangle height
+     * @param x2 second rectangle position X
+     * @param y2 second rectangle position Y
+     * @param w2 second rectangle width
+     * @param h2 second rectangle height
      */
     colrect(
         x1: number,
@@ -548,13 +521,12 @@ type LitecanvasInstance = {
     /**
      * Check a collision between two circles
      *
-     * @param {number} x1 first circle position X
-     * @param {number} y1 first circle position Y
-     * @param {number} r1 first circle position radius
-     * @param {number} x2 second circle position X
-     * @param {number} y2 second circle position Y
-     * @param {number} r2 second circle position radius
-     * @returns {boolean}
+     * @param x1 first circle position X
+     * @param y1 first circle position Y
+     * @param r1 first circle position radius
+     * @param x2 second circle position X
+     * @param y2 second circle position Y
+     * @param r2 second circle position radius
      */
     colcirc(
         x1: number,
@@ -564,61 +536,67 @@ type LitecanvasInstance = {
         y2: number,
         r2: number
     ): boolean
-    /**
-     * The scale of the game's delta time (dt).
-     * Values higher than 1 increase the speed of time, while values smaller than 1 decrease it.
-     * A value of 0 freezes time and is effectively equivalent to pausing.
-     *
-     * @param {number} value
-     */
-    timescale(value: number): void
 
     /** PLUGINS API */
     /**
      * Prepares a plugin to be loaded
      *
-     * @param {pluginCallback} callback
+     * @param callback
      */
     use(callback: pluginCallback): void
     /**
      * Add a game loop event listener
      *
-     * @param {string} event The game event type
-     * @param {function} callback the function that is called when the event occurs
-     * @returns {function?} a function to remove the listener
+     * @param event The game event type
+     * @param callback the function that is called when the event occurs
+     * @returns a function to remove the listener
      */
     listen(event: string, callback: Function): Function | null
     /**
      * Call all listeners attached to a game event
      *
      * @param event The game event type
-     * @param arg1 any data to be passed over the listeners
-     * @param arg2 any data to be passed over the listeners
-     * @param arg3 any data to be passed over the listeners
-     * @param arg4 any data to be passed over the listeners
+     * @param [arg1] any data to be passed over the listeners
+     * @param [arg2] any data to be passed over the listeners
+     * @param [arg3] any data to be passed over the listeners
+     * @param [arg4] any data to be passed over the listeners
      */
-    emit(event: string, arg1: any, arg2: any, arg3: any, arg4: any): void
+    emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): void
     /**
      * Get the color value
      *
-     * @param {number} index The color number
-     * @returns {string} the color value
+     * @param index The color number
+     * @returns the color value
      */
     getcolor(index: number): string
     /**
      * Create or update a instance variable
      *
-     * @param {string} key
-     * @param {any} value
+     * @param key
+     * @param value
      */
     setvar(key: string, value: any): void
     /**
      * Resizes the game canvas and emit the "resized" event
      *
-     * @param {number} width
-     * @param {number} height
+     * @param width
+     * @param height
      */
     resize(width: number, height: number): void
+    /**
+     * The scale of the game's delta time (dt).
+     * Values higher than 1 increase the speed of time, while values smaller than 1 decrease it.
+     * A value of 0 freezes time and is effectively equivalent to pausing.
+     *
+     * @param value
+     */
+    timescale(value: number): void
+    /**
+     * Set the target FPS at runtime.
+     *
+     * @param fps
+     */
+    setfps(fps: number): void
 }
 
 type LitecanvasOptions = {