litecanvas 0.95.1 → 0.97.0

package/src/index.js

@@ -23,6 +23,8 @@ export default function litecanvas(settings = {}) {
             elem.addEventListener(evt, callback, false)
             _browserEventListeners.push(() => elem.removeEventListener(evt, callback, false))
         },
+        /** @type {(str: string) => string} */
+        lowerCase = (str) => str.toLowerCase(),
         /** @type {(ev: Event) => void} */
         preventDefault = (ev) => ev.preventDefault(),
         /** @type {(c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void} */
@@ -34,13 +36,11 @@ export default function litecanvas(settings = {}) {
             width: null,
             height: null,
             autoscale: true,
-            pixelart: true,
             canvas: null,
             global: true,
             loop: null,
             tapEvents: true,
             keyboardEvents: true,
-            animate: true,
         }
 
     // setup the settings default values
@@ -75,7 +75,9 @@ export default function litecanvas(settings = {}) {
         /** @type {number} */
         _rngSeed = Date.now(),
         /** @type {string[]} */
-        _colors = defaultPalette,
+        _currentPalette,
+        /** @type {string[]} */
+        _colors,
         /** @type {number[]} */
         _defaultSound = [0.5, 0, 1750, , , 0.3, 1, , , , 600, 0.1],
         /** @type {string} */
@@ -178,7 +180,7 @@ export default function litecanvas(settings = {}) {
         round: (n, precision = 0) => {
             DEV: assert(isNumber(n), '[litecanvas] round() 1st param must be a number')
             DEV: assert(
-                null == precision || (isNumber(precision) && precision >= 0),
+                isNumber(precision) && precision >= 0,
                 '[litecanvas] round() 2nd param must be a positive number or zero'
             )
             if (!precision) {
@@ -602,15 +604,15 @@ export default function litecanvas(settings = {}) {
         },
 
         /**
-         * Sets the thickness of lines
+         * Sets the thickness of the lines
          *
          * @param {number} value
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineWidth
          */
         linewidth(value) {
             DEV: assert(
-                isNumber(value) && ~~value > 0,
-                '[litecanvas] linewidth() 1st param must be a positive number'
+                isNumber(value) && value >= 0,
+                '[litecanvas] linewidth() 1st param must be a positive number or zero'
             )
 
             _ctx.lineWidth = ~~value
@@ -728,19 +730,46 @@ export default function litecanvas(settings = {}) {
             _ctx.drawImage(source, ~~x, ~~y)
         },
 
+        /**
+         * Draw a sprite pxiel by pixel represented by a string. Each pixel must be a base 36 number (0-9 or a-z) or a dot.
+         *
+         * @param {number} x
+         * @param {number} y
+         * @param {number} width
+         * @param {number} height
+         * @param {string} pixels
+         */
+        spr(x, y, width, height, pixels) {
+            DEV: assert(isNumber(x), '[litecanvas] spr() 1st param must be a number')
+            DEV: assert(isNumber(y), '[litecanvas] spr() 2nd param must be a number')
+            DEV: assert(isNumber(width), '[litecanvas] spr() 3rd param must be a number')
+            DEV: assert(isNumber(height), '[litecanvas] spr() 4th param must be a number')
+            DEV: assert('string' === typeof pixels, '[litecanvas] spr() 5th param must be a string')
+
+            const chars = pixels.replace(/\s/g, '')
+            for (let gridx = 0; gridx < width; gridx++) {
+                for (let gridy = 0; gridy < height; gridy++) {
+                    const char = chars[height * gridy + gridx] || '.'
+                    if (char !== '.') {
+                        instance.rectfill(x + gridx, y + gridy, 1, 1, parseInt(char, 16) || 0)
+                    }
+                }
+            }
+        },
+
         /**
          * Draw in an OffscreenCanvas and returns its image.
          *
          * @param {number} width
          * @param {number} height
-         * @param {string[]|drawCallback} drawing
+         * @param {drawCallback} callback
          * @param {object} [options]
          * @param {number} [options.scale=1]
          * @param {OffscreenCanvas} [options.canvas]
          * @returns {ImageBitmap}
          * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
          */
-        paint(width, height, drawing, options = {}) {
+        paint(width, height, callback, options = {}) {
             DEV: assert(
                 isNumber(width) && width >= 1,
                 '[litecanvas] paint() 1st param must be a positive number'
@@ -750,7 +779,7 @@ export default function litecanvas(settings = {}) {
                 '[litecanvas] paint() 2nd param must be a positive number'
             )
             DEV: assert(
-                'function' === typeof drawing || Array.isArray(drawing),
+                'function' === typeof callback,
                 '[litecanvas] paint() 3rd param must be a function or array'
             )
             DEV: assert(
@@ -765,37 +794,16 @@ export default function litecanvas(settings = {}) {
             const /** @type {OffscreenCanvas} */
                 canvas = options.canvas || new OffscreenCanvas(1, 1),
                 scale = options.scale || 1,
-                contextOriginal = _ctx
+                currentContext = _ctx // context backup
 
             canvas.width = width * scale
             canvas.height = height * scale
 
             _ctx = canvas.getContext('2d')
             _ctx.scale(scale, scale)
+            callback(_ctx)
 
-            // draw pixel art if `draw` is a array
-            if (Array.isArray(drawing)) {
-                let x = 0,
-                    y = 0
-
-                _ctx.imageSmoothingEnabled = false
-
-                for (const str of drawing) {
-                    for (const color of str) {
-                        if (' ' !== color && '.' !== color) {
-                            // support for 16-color palette using hex (from 0 to f)
-                            instance.rectfill(x, y, 1, 1, parseInt(color, 16))
-                        }
-                        x++
-                    }
-                    y++
-                    x = 0
-                }
-            } else {
-                drawing(_ctx)
-            }
-
-            _ctx = contextOriginal // restore the context
+            _ctx = currentContext // restore the context
 
             return canvas.transferToImageBitmap()
         },
@@ -820,14 +828,18 @@ export default function litecanvas(settings = {}) {
          *
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
          */
-        push: () => _ctx.save(),
+        push() {
+            _ctx.save()
+        },
 
         /**
          * restores the drawing style settings and transformations
          *
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/restore
          */
-        pop: () => _ctx.restore(),
+        pop() {
+            _ctx.restore()
+        },
 
         /**
          * Adds a translation to the transformation matrix.
@@ -835,11 +847,11 @@ export default function litecanvas(settings = {}) {
          * @param {number} x
          * @param {number} y
          */
-        translate: (x, y) => {
+        translate(x, y) {
             DEV: assert(isNumber(x), '[litecanvas] translate() 1st param must be a number')
             DEV: assert(isNumber(y), '[litecanvas] translate() 2nd param must be a number')
 
-            return _ctx.translate(~~x, ~~y)
+            _ctx.translate(~~x, ~~y)
         },
 
         /**
@@ -848,11 +860,11 @@ export default function litecanvas(settings = {}) {
          * @param {number} x
          * @param {number} [y]
          */
-        scale: (x, y) => {
+        scale(x, y) {
             DEV: assert(isNumber(x), '[litecanvas] scale() 1st param must be a number')
             DEV: assert(null == y || isNumber(y), '[litecanvas] scale() 2nd param must be a number')
 
-            return _ctx.scale(x, y || x)
+            _ctx.scale(x, y || x)
         },
 
         /**
@@ -860,10 +872,10 @@ export default function litecanvas(settings = {}) {
          *
          * @param {number} radians
          */
-        rotate: (radians) => {
+        rotate(radians) {
             DEV: assert(isNumber(radians), '[litecanvas] rotate() 1st param must be a number')
 
-            return _ctx.rotate(radians)
+            _ctx.rotate(radians)
         },
 
         /**
@@ -1030,7 +1042,7 @@ export default function litecanvas(settings = {}) {
                 '[litecanvas] listen() 2nd param must be a function'
             )
 
-            eventName = eventName.toLowerCase()
+            eventName = lowerCase(eventName)
 
             _eventListeners[eventName] = _eventListeners[eventName] || new Set()
             _eventListeners[eventName].add(callback)
@@ -1054,7 +1066,7 @@ export default function litecanvas(settings = {}) {
                 '[litecanvas] emit() 1st param must be a string'
             )
             if (_initialized) {
-                eventName = eventName.toLowerCase()
+                eventName = lowerCase(eventName)
 
                 triggerEvent('before:' + eventName, arg1, arg2, arg3, arg4)
                 triggerEvent(eventName, arg1, arg2, arg3, arg4)
@@ -1063,7 +1075,7 @@ export default function litecanvas(settings = {}) {
         },
 
         /**
-         * Set or reset the color palette
+         * Set or reset the color palette.
          *
          * @param {string[]} [colors]
          */
@@ -1073,6 +1085,31 @@ export default function litecanvas(settings = {}) {
                 '[litecanvas] pal() 1st param must be a array of strings'
             )
             _colors = colors
+            _currentPalette = [...colors]
+        },
+
+        /**
+         * Swap two colors of the current palette.
+         *
+         * If called without arguments, reset the current palette.
+         *
+         * @param {number?} a
+         * @param {number?} b
+         */
+        palc(a, b) {
+            DEV: assert(
+                null == a || (isNumber(a) && a >= 0),
+                '[litecanvas] palc() 1st param must be a positive number'
+            )
+            DEV: assert(
+                isNumber(a) ? isNumber(b) && b >= 0 : null == b,
+                '[litecanvas] palc() 2nd param must be a positive number'
+            )
+            if (a == null) {
+                _colors = [..._currentPalette]
+            } else {
+                ;[_colors[a], _colors[b]] = [_colors[b], _colors[a]]
+            }
         },
 
         /**
@@ -1128,13 +1165,16 @@ export default function litecanvas(settings = {}) {
         /**
          * Returns information about that engine instance.
          *
-         * @param {number} n
+         * @param {number|string} index
          * @returns {any}
          */
-        stat(n) {
-            DEV: assert(isNumber(n) && n >= 0, '[litecanvas] stat() 1st param must be a number')
+        stat(index) {
+            DEV: assert(
+                isNumber(index) || 'string' === typeof index,
+                '[litecanvas] stat() 1st param must be a number or string'
+            )
 
-            const list = [
+            const internals = [
                 // 0
                 settings,
                 // 1
@@ -1161,9 +1201,9 @@ export default function litecanvas(settings = {}) {
                 _fontFamily,
             ]
 
-            const data = { index: n, value: list[n] }
+            const data = { index, value: internals[index] }
 
-            // plugins can modify or create stat values
+            // plugins can modify or create new stats
             instance.emit('stat', data)
 
             return data.value
@@ -1447,7 +1487,7 @@ export default function litecanvas(settings = {}) {
              * @returns {boolean}
              */
             const keyCheck = (keySet, key = '') => {
-                key = key.toLowerCase()
+                key = lowerCase(key)
                 return !key ? keySet.size > 0 : keySet.has('space' === key ? ' ' : key)
             }
 
@@ -1455,7 +1495,7 @@ export default function litecanvas(settings = {}) {
             let _lastKey = ''
 
             on(root, 'keydown', (/** @type {KeyboardEvent} */ event) => {
-                const key = event.key.toLowerCase()
+                const key = lowerCase(event.key)
                 if (!_keysDown.has(key)) {
                     _keysDown.add(key)
                     _keysPress.add(key)
@@ -1464,7 +1504,7 @@ export default function litecanvas(settings = {}) {
             })
 
             on(root, 'keyup', (/** @type {KeyboardEvent} */ event) => {
-                _keysDown.delete(event.key.toLowerCase())
+                _keysDown.delete(lowerCase(event.key))
             })
 
             on(root, 'blur', () => _keysDown.clear())
@@ -1516,9 +1556,8 @@ export default function litecanvas(settings = {}) {
     }
 
     function drawFrame() {
-        if (!settings.animate) {
-            return instance.emit('draw', _ctx)
-        }
+        // request the next frame
+        _rafid = raf(drawFrame)
 
         let now = Date.now()
         let updated = 0
@@ -1548,9 +1587,6 @@ export default function litecanvas(settings = {}) {
                 )
             }
         }
-
-        // request the next frame
-        _rafid = raf(drawFrame)
     }
 
     function setupCanvas() {
@@ -1575,15 +1611,13 @@ export default function litecanvas(settings = {}) {
 
         on(_canvas, 'click', () => focus())
 
-        /** @ts-ignore */
-        _canvas.style = ''
-
         resizeCanvas()
 
         if (!_canvas.parentNode) {
             document.body.appendChild(_canvas)
         }
 
+        _canvas.style.imageRendering = 'pixelated'
         _canvas.oncontextmenu = () => false
     }
 
@@ -1625,10 +1659,7 @@ export default function litecanvas(settings = {}) {
         }
 
         // set canvas image rendering properties
-        if (settings.pixelart) {
-            _ctx.imageSmoothingEnabled = false
-            _canvas.style.imageRendering = 'pixelated'
-        }
+        _ctx.imageSmoothingEnabled = false
 
         // set the default text align and baseline
         instance.textalign('start', 'top')
@@ -1636,11 +1667,6 @@ export default function litecanvas(settings = {}) {
         // trigger "resized" event
         // note: not triggered before the "init" event
         instance.emit('resized', _scale)
-
-        // force redraw when the canvas is not animated
-        if (!settings.animate) {
-            raf(drawFrame)
-        }
     }
 
     /**
@@ -1687,6 +1713,9 @@ export default function litecanvas(settings = {}) {
 
     setupCanvas()
 
+    // init the color palette
+    instance.pal()
+
     if ('loading' === document.readyState) {
         on(root, 'DOMContentLoaded', () => raf(init))
     } else {

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.95.1'
+export const version = '0.97.0'

package/types/global.d.ts

@@ -356,7 +356,7 @@ declare global {
      */
     function textalign(align: CanvasTextAlign, baseline: CanvasTextBaseline): void
 
-    /** IMAGE GRAPHICS API */
+    /** BASIC GRAPHICS API */
     /**
      * Draw an image
      *
@@ -365,19 +365,33 @@ declare global {
      * @param source
      */
     function image(x: number, y: number, source: CanvasImageSource): void
+    /**
+     * Draw a sprite pxiel by pixel represented by a string. Each pixel must be a base 36 number or a dot:
+     *
+     * - A base 36 number (`0-9` or `a-z`) represent a pixel color (supporting color palettes with max 36 colors).
+     * - A dot (`.`) represent a transparent pixel.
+     * - Spaces and lines breaks are ignored and can be used to improve the visualization.
+     *
+     * @param x the position X of the first pixel
+     * @param y the position Y of the first pixel
+     * @param width the width of the sprite
+     * @param height the height of the sprite
+     * @param pixels
+     */
+    function spr(x: number, y: number, width: number, height: number, pixels: string): void
     /**
      * Draw in an OffscreenCanvas and returns its image.
      *
      * @param width
      * @param height
-     * @param drawing
+     * @param callback
      * @param [options]
      * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
      */
     function paint(
         width: number,
         height: number,
-        drawing: string[] | drawCallback,
+        callback: drawCallback,
         options?: {
             scale?: number
             canvas?: OffscreenCanvas
@@ -531,11 +545,22 @@ declare global {
      */
     function emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): void
     /**
-     * Set or reset the color palette
+     * Set or reset the color palette.
      *
      * @param [colors]
      */
     function pal(colors?: string[]): void
+    /**
+     * Swap two colors of the current palette.
+     *
+     * If called without arguments, reset the current palette.
+     *
+     * Note: `palc()` don't affect drawings made with `image()`.
+     *
+     * @param a
+     * @param b
+     */
+    function palc(a?: number, b?: number): void
     /**
      * Define or update a instance property
      *

package/types/types.d.ts

@@ -350,7 +350,7 @@ type LitecanvasInstance = {
      */
     textalign(align: CanvasTextAlign, baseline: CanvasTextBaseline): void
 
-    /** IMAGE GRAPHICS API */
+    /** BASIC GRAPHICS API */
     /**
      * Draw an image
      *
@@ -359,19 +359,33 @@ type LitecanvasInstance = {
      * @param source
      */
     image(x: number, y: number, source: CanvasImageSource): void
+    /**
+     * Draw a sprite pxiel by pixel represented by a string. Each pixel must be a base 36 number or a dot:
+     *
+     * - A base 36 number (`0-9` or `a-z`) represent a pixel color (supporting color palettes with max 36 colors).
+     * - A dot (`.`) represent a transparent pixel.
+     * - Spaces and lines breaks are ignored and can be used to improve the visualization.
+     *
+     * @param x the position X of the first pixel
+     * @param y the position Y of the first pixel
+     * @param width the width of the sprite
+     * @param height the height of the sprite
+     * @param pixels
+     */
+    spr(x: number, y: number, width: number, height: number, pixels: string): void
     /**
      * Draw in an OffscreenCanvas and returns its image.
      *
      * @param width
      * @param height
-     * @param drawing
+     * @param callback
      * @param [options]
      * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
      */
     paint(
         width: number,
         height: number,
-        drawing: string[] | drawCallback,
+        callback: drawCallback,
         options?: {
             scale?: number
             canvas?: OffscreenCanvas
@@ -528,11 +542,22 @@ type LitecanvasInstance = {
      */
     def(key: string, value: any): void
     /**
-     * Set or reset the color palette
+     * Set or reset the color palette.
      *
      * @param [colors]
      */
     pal(colors?: string[]): void
+    /**
+     * Swap two colors of the current palette.
+     *
+     * If called without arguments, reset the current palette.
+     *
+     * Note: `palc()` don't affect drawings made with `image()`.
+     *
+     * @param a
+     * @param b
+     */
+    palc(a?: number, b?: 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.
@@ -605,13 +630,6 @@ type LitecanvasOptions = {
      * Note: Only works if the option "width" was specified.
      */
     autoscale?: boolean | number
-    /**
-     * If `true`, the pixel art images won't look blurry.
-     * Also, disables canvas built-in antialias.
-     *
-     * Default: `true`
-     */
-    pixelart?: boolean
     /**
      * If `true` (default), all methods and properties of the engine will be exposed to the global scope (window).
      */
@@ -646,12 +664,6 @@ type LitecanvasOptions = {
      * Useful when you want to implement your keyboard handler.
      */
     keyboardEvents?: boolean
-    /**
-     * default: `true`
-     *
-     * if `false` stops the code in `update()` and `draw()` from running repeatedly. By default, tries to run these functions 60 times per second.
-     */
-    animate?: boolean
 }
 
 type LitecanvasGameLoop = {