v0.99

* add `stat(12)`
* internal code improvements

Author: luizbills

package.json

@@ -1,6 +1,6 @@
 {
     "name": "litecanvas",
-    "version": "0.98.4",
+    "version": "0.99.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/fullscreen/fullscreen.js

@@ -6,10 +6,9 @@ litecanvas({
 let fullscreen
 
 function resized() {
-    // fix: HTML canvas reset the text align and baseline
-    // when the canvas resizes
+    // the canvas resets the text align
+    // and baseline when the canvas resizes
     textalign('start', 'top')
-    console.log('resized')
 }
 
 function update() {

src/index.js

@@ -48,6 +48,8 @@ export default function litecanvas(settings = {}) {
 
     let /** @type {boolean} */
         _initialized = false,
+        /** @type {boolean} */
+        _paused = true,
         /** @type {HTMLCanvasElement} _canvas */
         _canvas,
         /** @type {number} */
@@ -1056,6 +1058,7 @@ export default function litecanvas(settings = {}) {
                 'string' === typeof eventName,
                 '[litecanvas] emit() 1st param must be a string'
             )
+
             if (_initialized) {
                 eventName = lowerCase(eventName)
 
@@ -1156,7 +1159,7 @@ export default function litecanvas(settings = {}) {
         },
 
         /**
-         * Returns information about that engine instance.
+         * Returns information about the engine instance.
          *
          * @param {number|string} index
          * @returns {any}
@@ -1190,8 +1193,10 @@ export default function litecanvas(settings = {}) {
                 _rngSeed,
                 // 10
                 _fontSize,
-                //  11
+                // 11
                 _fontFamily,
+                // 12
+                _colorPaletteState,
             ]
 
             const data = { index, value: internals[index] }
@@ -1202,49 +1207,24 @@ export default function litecanvas(settings = {}) {
             return data.value
         },
 
-        /**
-         * Stops the litecanvas instance and remove all event listeners.
-         */
-        quit() {
-            // stop the game loop (update & draw)
-            instance.pause()
-
-            // emit "quit" event to manual clean ups
-            instance.emit('quit')
-
-            // clear all engine event listeners
-            _eventListeners = {}
-
-            // clear all browser event listeners
-            for (const removeListener of _browserEventListeners) {
-                removeListener()
-            }
-
-            // maybe clear global context
-            if (settings.global) {
-                for (const key in instance) {
-                    delete root[key]
-                }
-                delete root.ENGINE
-            }
-
-            // unset that flag
-            _initialized = false
-        },
-
         /**
          * Pauses the engine loop (update & draw).
          */
         pause() {
+            _paused = true
             cancelAnimationFrame(_rafid)
-            _rafid = 0
         },
 
         /**
          * Resumes (if paused) the engine loop.
          */
         resume() {
-            if (_initialized && !_rafid) {
+            DEV: assert(
+                _initialized,
+                '[litecanvas] resume() cannot be called before the "init" event and neither after the quit() function'
+            )
+            if (_initialized && _paused) {
+                _paused = false
                 _accumulated = _fpsInterval
                 _lastFrameTime = Date.now()
                 _rafid = raf(drawFrame)
@@ -1257,7 +1237,37 @@ export default function litecanvas(settings = {}) {
          * @returns {boolean}
          */
         paused() {
-            return !_rafid
+            return _paused
+        },
+
+        /**
+         * Shutdown the litecanvas instance and remove all event listeners.
+         */
+        quit() {
+            // emit "quit" event to manual clean ups
+            instance.emit('quit')
+
+            // stop the game loop (update & draw)
+            instance.pause()
+
+            // deinitialize the engine
+            _initialized = false
+
+            // clear all engine event listeners
+            _eventListeners = {}
+
+            // clear all browser event listeners
+            for (const removeListener of _browserEventListeners) {
+                removeListener()
+            }
+
+            // maybe clear global context
+            if (settings.global) {
+                for (const key in instance) {
+                    delete root[key]
+                }
+                delete root.ENGINE
+            }
         },
     }
 
@@ -1655,6 +1665,8 @@ export default function litecanvas(settings = {}) {
         // trigger "resized" event
         // note: not triggered before the "init" event
         instance.emit('resized', _scale)
+
+        DEV: console.warn('[litecanvas] quit() terminated a Litecanvas instance.')
     }
 
     /**
@@ -1711,9 +1723,11 @@ export default function litecanvas(settings = {}) {
     setupCanvas()
 
     if ('loading' === document.readyState) {
-        on(root, 'DOMContentLoaded', () => raf(init))
+        on(root, 'DOMContentLoaded', () => {
+            raf(init)
+        })
     } else {
-        raf(init)
+        _rafid = raf(init)
     }
 
     return instance

src/version.js

@@ -7,9 +7,7 @@ import * as sinon from 'sinon'
 let /** @type {LitecanvasInstance} */
     local,
     /** @type {sinon.SinonSpiedInstance<CanvasRenderingContext2D>} */
-    contextSpy,
-    /** @type {sinon.SinonSpiedInstance<Console>} */
-    consoleSpy
+    contextSpy
 
 test.before(() => {
     setupDOM()

tests/cls.js

@@ -36,16 +36,17 @@ test('remove all engine event listeners', async (t) => {
             global: false,
         })
 
-        local.listen('draw', () => {
-            t.fail()
-        })
-
         local.listen('update', () => {
+            resolve()
+
             // "update" runs before the "draw" event
-            // so destroy lets destroy that engine instance
+            // so lets destroy that engine instance
             // and the "draw" event will never happens
             local.quit()
-            resolve()
+        })
+
+        local.listen('draw', () => {
+            t.fail()
         })
     })
 

tests/quit.js

@@ -211,6 +211,28 @@ test('stat(11) returns the current font family', async (t) => {
     }
 })
 
+test('stat(12) returns the current color palette state modified by palc()', (t) => {
+    {
+        const expected = [] // initial value (default)
+        const actual = local.stat(12)
+        t.deepEqual(actual, expected)
+    }
+
+    {
+        // prettier-ignore
+        const expected = [3, , , 5,]
+
+        local.palc(0, 3)
+        local.palc(3, 5)
+
+        const actual = local.stat(12)
+
+        t.deepEqual(actual, expected)
+
+        local.palc() // reset
+    }
+})
+
 test('stat modified via event', async (t) => {
     const expected = 'BAR'
 

tests/stat.js

@@ -583,9 +583,9 @@ declare global {
      */
     function framerate(fps: number): void
     /**
-     * Returns information about that engine instance.
+     * Returns information about the engine instance.
      *
-     * - n = 0: the settings passed to that instance
+     * - n = 0: the settings passed to this instance
      * - n = 1: returns true if the "init" event has already been emitted
      * - n = 2: the current delta time (dt)
      * - n = 3: the current canvas element scale (not the context 2D scale)
@@ -597,15 +597,12 @@ declare global {
      * - n = 9: the current RNG state
      * - n = 10: the current font size
      * - n = 11: the current font family
+     * - n = 12: the current state of the color palette
      * - n = *any other value*: probably returns undefined
      *
-     * @param n
+     * @param index
      */
-    function stat(n: number): any
-    /**
-     * Shutdown the litecanvas instance and remove all event listeners.
-     */
-    function quit(): void
+    function stat(index: number | string): any
     /**
      * Pauses the engine loop (update & draw).
      */
@@ -618,4 +615,8 @@ declare global {
      * Returns `true` if the engine loop is paused.
      */
     function paused(): boolean
+    /**
+     * Shutdown the litecanvas instance and remove all event listeners.
+     */
+    function quit(): void
 }

types/global.d.ts

@@ -573,9 +573,9 @@ type LitecanvasInstance = {
      */
     framerate(fps: number): void
     /**
-     * Returns information about that engine instance.
+     * Returns information about the engine instance.
      *
-     * - n = 0: the settings passed to that instance
+     * - n = 0: the settings passed to this instance
      * - n = 1: returns true if the "init" event has already been emitted
      * - n = 2: the current delta time (dt)
      * - n = 3: the current canvas element scale (not the context 2D scale)
@@ -587,15 +587,12 @@ type LitecanvasInstance = {
      * - n = 9: the current RNG state
      * - n = 10: the current font size
      * - n = 11: the current font family
+     * - n = 12: the current state of the color palette
      * - n = *any other value*: probably returns undefined
      *
-     * @param n
+     * @param index
      */
-    stat(n: number): any
-    /**
-     * Stops the litecanvas instance and remove all event listeners.
-     */
-    quit(): void
+    stat(index: number | string): any
     /**
      * Pauses the engine loop (update & draw).
      */
@@ -608,6 +605,10 @@ type LitecanvasInstance = {
      * Returns `true` if the engine loop is paused.
      */
     paused(): boolean
+    /**
+     * Shutdown the litecanvas instance and remove all event listeners.
+     */
+    quit(): void
 }
 
 type LitecanvasOptions = {