v0.209

package.json

@@ -1,6 +1,6 @@
 {
     "name": "litecanvas",
-    "version": "0.208.0",
+    "version": "0.209.0",
     "description": "Lightweight HTML5 canvas 2D game engine suitable for small projects and creative coding. Inspired by PICO-8 and p5.js/Processing.",
     "license": "MIT",
     "author": "Luiz Bills <luizbills@pm.me>",

samples/bench/bench.js

@@ -38,7 +38,7 @@ function init() {
             `
             ),
         {
-            scale: 3,
+            scale: 4,
         }
     )
     state.size = state.sprite.width
@@ -63,7 +63,7 @@ function init() {
 
 function draw() {
     // Clear the canvas
-    cls(0)
+    cls(3)
 
     // Particle animation
     const particles = state.particles

src/index.js

@@ -776,7 +776,11 @@ export default function litecanvas(settings = {}) {
         },
 
         /**
-         * Draw a sprite pixel by pixel represented by a string. Each pixel must be a base 36 number (0-9 or a-z) or a dot.
+         * Draw a sprite, using a string of rows and columns representing a bitmask.
+         * - Each colored pixel must be a base 36 number (0-9 or a-z).
+         * - Use "." (dot) for transparent pixels.
+         * - Any other characters (like symbols) are ignored.
+         * - empty lines are ignored
          *
          * @param {number} x
          * @param {number} y
@@ -787,14 +791,15 @@ export default function litecanvas(settings = {}) {
             DEV: assert(isNumber(y), 'spr() 2nd parameter must be a number')
             DEV: assert('string' === typeof pixels, 'spr() 3rd parameter must be a string')
 
-            const rows = pixels.trim().split('\n')
+            const rows = pixels
+                .replace(/[^\w.\n]/g, '')
+                .split('\n')
+                .filter((s) => s)
 
-            for (let row = 0; row < rows.length; row++) {
-                const chars = rows[row].trim()
-                for (let col = 0; col < chars.length; col++) {
-                    const char = chars[col]
-                    if (char !== '.' && char !== ' ') {
-                        instance.rectfill(x + col, y + row, 1, 1, parseInt(char, 36) || 0)
+            for (let i = 0; i < rows.length; i++) {
+                for (let j = 0; j < rows[i].length; j++) {
+                    if (rows[i][j] !== '.') {
+                        instance.rectfill(x + j, y + i, 1, 1, parseInt(rows[i][j], 36) || 0)
                     }
                 }
             }

types/global.d.ts

@@ -401,15 +401,32 @@ declare global {
      */
     function image(x: number, y: number, source: CanvasImageSource): void
     /**
-     * Draw a sprite pixel by pixel represented by a string. Each pixel must be a base 36 number or a dot:
+     * Draw a sprite, using a string of rows and columns representing a bitmask.
+     * - Each colored pixel must be a base 36 number (0-9 or a-z).
+     * - Use "." (dot) for transparent pixels.
+     * - Any other characters (like symbols) are ignored.
+     * - empty lines are ignored
      *
-     * - 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 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 x
+     * @param y
      * @param pixels
+     * @see https://litecanvas.js.org/tools/pixel-art-editor.html
+     * @example
+     * function draw() {
+     *   // a little white key 8x8 sprite
+     *   const littleKeySprite = `
+     *     ........
+     *     .3......
+     *     323.....
+     *     3.333333
+     *     3.322323
+     *     232..2.2
+     *     .2......
+     *     ........
+     *   `
+     *   // draw the sprite pixels at position x=10, y=10
+     *   spr(10, 10, littleKeySprite)
+     * }
      */
     function spr(x: number, y: number, pixels: string): void
     /**

types/types.d.ts

@@ -389,15 +389,32 @@ type LitecanvasInstance = {
      */
     image(x: number, y: number, source: CanvasImageSource): void
     /**
-     * Draw a sprite pixel by pixel represented by a string. Each pixel must be a base 36 number or a dot:
+     * Draw a sprite, using a string of rows and columns representing a bitmask.
+     * - Each colored pixel must be a base 36 number (0-9 or a-z).
+     * - Use "." (dot) for transparent pixels.
+     * - Any other characters (like symbols) are ignored.
+     * - empty lines are ignored
      *
-     * - 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 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 x
+     * @param y
      * @param pixels
+     * @see https://litecanvas.js.org/tools/pixel-art-editor.html
+     * @example
+     * function draw() {
+     *   // a little white key 8x8 sprite
+     *   const littleKeySprite = `
+     *     ........
+     *     .3......
+     *     323.....
+     *     3.333333
+     *     3.322323
+     *     232..2.2
+     *     .2......
+     *     ........
+     *   `
+     *   // draw the sprite pixels at position x=10, y=10
+     *   spr(10, 10, littleKeySprite)
+     * }
      */
     spr(x: number, y: number, pixels: string): void
     /**