add spr()

luizbills · luizbills · commit 6cab6f0a2a22 · 2025-08-07T13:36:14.000-03:00
* spr() draws pixel by pixel
* paint() now only accepts a callback
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "litecanvas",
-    "version": "0.96.0",
+    "version": "0.97.0",
     "description": "Lightweight HTML5 canvas 2D game engine suitable for small projects and creative coding. Inspired by PICO-8 and P5/Processing.",
     "license": "MIT",
     "author": "Luiz Bills <luizbills@pm.me>",
diff --git a/samples/bench/bench.js b/samples/bench/bench.js
@@ -18,20 +18,28 @@ function init() {
     state.sprite = paint(
         12,
         12,
-        [
-            '....4444....',
-            '....4aa4....',
-            '..004aa400..',
-            '..02444420..',
-            '777733335555',
-            '766731135bb5',
-            '766731135bb5',
-            '777733335555',
-            '..02999920..',
-            '..00988900..',
-            '....9889....',
-            '....9999....',
-        ],
+        () => {
+            spr(
+                0,
+                0,
+                12,
+                12,
+                [
+                    '....4444....',
+                    '....4aa4....',
+                    '..004aa400..',
+                    '..02444420..',
+                    '777733335555',
+                    '766731135bb5',
+                    '766731135bb5',
+                    '777733335555',
+                    '..02999920..',
+                    '..00988900..',
+                    '....9889....',
+                    '....9999....',
+                ].join('')
+            )
+        },
         {
             scale: 3,
         }
diff --git a/samples/custom-palette/custom-palette.js b/samples/custom-palette/custom-palette.js
@@ -23,19 +23,21 @@ function init() {
         '#FF77A8',
         '#FFCCAA',
     ])
-
-    // create a PICO-8 logo image
-    pico8logo = paint(5, 5, [
-        // prettier-ignore
-        '..8..',
-        '.97f.',
-        'a777e',
-        '.b7d.',
-        '..c..',
-    ])
 }
 
 function draw() {
+    console.log('drawing...')
     cls(0)
-    image(0, 0, pico8logo)
+    spr(
+        0,
+        0,
+        5,
+        5,
+        `
+        ..8..
+        .97f.
+        a777e
+        .b7d.
+        ..c..`
+    )
 }
diff --git a/samples/logo/logo.js b/samples/logo/logo.js
@@ -12,24 +12,32 @@ let scale = floor(size / minsize)
 logo = paint(
     minsize,
     minsize,
-    [
-        '................',
-        '................',
-        '......4444......',
-        '......4aa4......',
-        '....004aa400....',
-        '....02444420....',
-        '..777733335555..',
-        '..766731135bb5..',
-        '..766731135bb5..',
-        '..777733335555..',
-        '....02999920....',
-        '....00988900....',
-        '......9889......',
-        '......9999......',
-        '................',
-        '................',
-    ],
+    () => {
+        spr(
+            0,
+            0,
+            minsize,
+            minsize,
+            [
+                '................',
+                '................',
+                '......4444......',
+                '......4aa4......',
+                '....004aa400....',
+                '....02444420....',
+                '..777733335555..',
+                '..766731135bb5..',
+                '..766731135bb5..',
+                '..777733335555..',
+                '....02999920....',
+                '....00988900....',
+                '......9889......',
+                '......9999......',
+                '................',
+                '................',
+            ].join('')
+        )
+    },
     {
         scale,
     }
diff --git a/samples/pixelart/pixelart.js b/samples/pixelart/pixelart.js
@@ -4,28 +4,51 @@ litecanvas({
     autoscale: 4, // auto scale by until 4x
 })
 
-const art = paint(
-    8, // the pixel art width
-    8, // the pixelart height
-    [
-        // the pixelart pixels:
-        // each number is a pixel color
-        // note: use space or dots to make a pixel 100% transparent
-        '  0000  ',
-        ' 055550 ',
-        '05505050',
-        '05555550',
-        '05500050',
-        '05555550',
-        '.055550.',
-        '..0000..',
-    ],
-    {
-        scale: 2, // this pixelart is twice bigger
+const smile = `
+    ..0000..
+    .055550.
+    05505050
+    05555550
+    05500050
+    05555550
+    .055550.
+    ..0000..`
+
+// https://lospec.com/palette-list/kulepu
+const palKulepu = [
+    '#180c10',
+    '#3d4249',
+    '#798890',
+    '#a6cbc4',
+    '#43a6c7',
+    '#2d488c',
+    '#8f74e8',
+    '#e7aac7',
+    '#f0f5dc',
+    '#f0b886',
+    '#d87f5c',
+    '#8b3e34',
+    '#f0933b',
+    '#f1cc46',
+    '#89ab3e',
+    '#306645',
+]
+
+let usingAltPal = false
+
+function tapped() {
+    if (usingAltPal) {
+        pal()
+    } else {
+        pal(palKulepu)
     }
-)
+    usingAltPal = !usingAltPal
+}
 
 function draw() {
     cls(3)
-    image(0, 0, art)
+    push()
+    scale(2)
+    spr(0, 0, 8, 8, smile)
+    pop()
 }
diff --git a/src/index.js b/src/index.js
@@ -728,19 +728,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 +777,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 +792,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()
         },
diff --git a/src/version.js b/src/version.js
diff --git a/types/global.d.ts b/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
diff --git a/types/types.d.ts b/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

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "litecanvas",`
`3`		`- "version": "0.96.0",`
	`3`	`+ "version": "0.97.0",`
`4`	`4`	`"description": "Lightweight HTML5 canvas 2D game engine suitable for small projects and creative coding. Inspired by PICO-8 and P5/Processing.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"author": "Luiz Bills <luizbills@pm.me>",`