litecanvas 0.80.0 → 0.81.0

package/README.md

@@ -55,8 +55,8 @@ function init() {
     bg = 0
     color = 3
     radius = 32
-    posx = CENTERX
-    posy = CENTERY
+    posx = CX // center X or (canvas width / 2)
+    posy = CY // center Y or (canvas width / 2)
 }
 
 // this function detect taps/clicks

package/dist/dist.dev.js

@@ -50,39 +50,33 @@
       animate: true
     };
     settings = Object.assign(defaults, settings);
-    let _initialized = false, _plugins = [], _canvas, _scale = 1, _ctx, _outline_fix = 0.5, _timeScale = 1, _lastFrameTime, _deltaTime = 1 / 60, _accumulated = 0, _rafid, _fontFamily = "sans-serif", _fontSize = 20, _rng_seed = Date.now(), _colors = defaultPalette, _events = {
-      init: false,
-      update: false,
-      draw: false,
-      resized: false,
-      tap: false,
-      untap: false,
-      tapping: false,
-      tapped: false
-    }, _helpers = {
-      settings: Object.assign({}, settings)
+    let _initialized = false, _plugins = [], _canvas, _scale = 1, _ctx, _outline_fix = 0.5, _timeScale = 1, _lastFrameTime, _deltaTime = 1 / 60, _accumulated = 0, _rafid, _fontFamily = "sans-serif", _fontSize = 20, _rng_seed = Date.now(), _colors = defaultPalette, _default_sound = [0.5, 0, 1750, , , 0.3, 1, , , , 600, 0.1], _events = {
+      init: null,
+      update: null,
+      draw: null,
+      resized: null,
+      tap: null,
+      untap: null,
+      tapping: null,
+      tapped: null
     };
     const instance = {
+      /** @type {HTMLCanvasElement} */
+      CANVAS: null,
       /** @type {number} */
-      WIDTH: 0,
+      W: 0,
       /** @type {number} */
-      HEIGHT: 0,
-      /** @type {HTMLCanvasElement} */
-      CANVAS: false,
+      H: 0,
       /** @type {number} */
-      ELAPSED: 0,
+      T: 0,
       /** @type {number} */
-      CENTERX: 0,
+      CX: 0,
       /** @type {number} */
-      CENTERY: 0,
+      CY: 0,
       /** @type {number} */
-      MOUSEX: -1,
+      MX: -1,
       /** @type {number} */
-      MOUSEY: -1,
-      /** @type {number[]} */
-      DEFAULT_SFX: [0.5, 0, 1750, , , 0.3, 1, , , , 600, 0.1],
-      /** @type {string[]} */
-      COLORS: _colors,
+      MY: -1,
       /** MATH API */
       /**
        * Twice the value of the mathematical constant PI (π).
@@ -235,6 +229,15 @@
         DEV: assert(isNumber(stop), "norm: 3rd param must be a number");
         return instance.map(value, start, stop, 0, 1);
       },
+      /**
+       * Interpolate between 2 values using a periodic function.
+       *
+       * @param {number} from - the lower bound
+       * @param {number} to - the higher bound
+       * @param {number} t - the amount
+       * @param {(n: number) => number} fn - the periodic function (which default to `Math.sin`)
+       */
+      wave: (from, to, t, fn = Math.sin) => from + (fn(t) + 1) / 2 * (to - from),
       /** RNG API */
       /**
        * Generates a pseudorandom float between min (inclusive) and max (exclusive)
@@ -274,18 +277,18 @@
         return math.floor(instance.rand(min, max + 1));
       },
       /**
-       * If a value is passed, initializes the random number generator with an explicit seed value.
-       * Otherwise, returns the current seed state.
+       * Initializes the random number generator with an explicit seed value.
+       *
+       * Note: The seed should be a integer number greater than or equal to zero.
        *
        * @param {number} value
-       * @returns {number} the seed state
        */
-      seed: (value) => {
+      rseed(value) {
         DEV: assert(
           null == value || isNumber(value) && value >= 0,
-          "seed: 1st param must be a positive number or zero"
+          "rseed: 1st param must be a positive number or zero"
         );
-        return null == value ? _rng_seed : _rng_seed = ~~value;
+        _rng_seed = ~~value;
       },
       /** BASIC GRAPHICS API */
       /**
@@ -521,7 +524,7 @@
           "text: 5th param must be a string"
         );
         _ctx.font = `${fontStyle} ${_fontSize}px ${_fontFamily}`;
-        _ctx.fillStyle = instance.getcolor(color);
+        _ctx.fillStyle = _colors[~~color % _colors.length];
         _ctx.fillText(message, ~~x, ~~y);
       },
       /**
@@ -548,15 +551,15 @@
       /**
        * 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 {CanvasTextAlign} align the horizontal alignment. Possible values: "left", "right", "center", "start" or "end"
+       * @param {CanvasTextBaseline} 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
        */
       textalign(align, baseline) {
         DEV: assert(
           null == align || ["left", "right", "center", "start", "end"].includes(align),
-          "textalign: 1st param must be null or one of the following values: center, left, right, start or end."
+          "textalign: 1st param must be null or one of the following strings: center, left, right, start or end."
         );
         DEV: assert(
           null == baseline || [
@@ -567,7 +570,7 @@
             "alphabetic",
             "ideographic"
           ].includes(baseline),
-          "textalign: 2nd param must be null or one of the following values: middle, top, bottom, hanging, alphabetic or ideographic."
+          "textalign: 2nd param must be null or one of the following strings: middle, top, bottom, hanging, alphabetic or ideographic."
         );
         if (align) _ctx.textAlign = align;
         if (baseline) _ctx.textBaseline = baseline;
@@ -593,7 +596,7 @@
        * @param {string[]|drawCallback} drawing
        * @param {object} [options]
        * @param {number} [options.scale=1]
-       * @param {OffscreenCanvas | HTMLCanvasElement} [options.canvas]
+       * @param {OffscreenCanvas} [options.canvas]
        * @returns {ImageBitmap}
        * @see https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
        */
@@ -733,7 +736,7 @@
           null == path || path instanceof Path2D,
           "fill: 2nd param must be a Path2D instance"
         );
-        _ctx.fillStyle = instance.getcolor(color);
+        _ctx.fillStyle = _colors[~~color % _colors.length];
         if (path) {
           _ctx.fill(path);
         } else {
@@ -755,7 +758,7 @@
           null == path || path instanceof Path2D,
           "stroke: 2nd param must be a Path2D instance"
         );
-        _ctx.strokeStyle = instance.getcolor(color);
+        _ctx.strokeStyle = _colors[~~color % _colors.length];
         if (path) {
           _ctx.stroke(path);
         } else {
@@ -800,7 +803,7 @@
         if (root.zzfxV <= 0 || navigator.userActivation && !navigator.userActivation.hasBeenActive) {
           return false;
         }
-        zzfxParams = zzfxParams || instance.DEFAULT_SFX;
+        zzfxParams = zzfxParams || _default_sound;
         if (pitchSlide !== 0 || volumeFactor !== 1) {
           zzfxParams = zzfxParams.slice();
           zzfxParams[0] = volumeFactor * (zzfxParams[0] || 1);
@@ -887,34 +890,22 @@
           "pal: 1st param must be a array of strings"
         );
         _colors = colors;
-        instance.setvar("COLORS", _colors);
       },
       /**
-       * Get a color by index
-       *
-       * @param {number} [index=0] The color number
-       * @returns {string} the color code
-       */
-      getcolor: (index) => {
-        DEV: assert(
-          null == index || isNumber(index) && index >= 0,
-          "getcolor: 1st param must be a number"
-        );
-        return _colors[~~index % _colors.length];
-      },
-      /**
-       * Create or update a instance variable
+       * Define or update a instance property.
        *
        * @param {string} key
        * @param {*} value
        */
-      setvar(key, value) {
+      def(key, value) {
         DEV: assert(
           "string" === typeof key,
-          "setvar: 1st param must be a string"
+          "def: 1st param must be a string"
         );
-        if (null == value) {
-          console.warn(`setvar: key "${key}" was defined as ${value}`);
+        DEV: if (null == value) {
+          console.warn(
+            `def: key "${key}" was defined as ${value} but now is null`
+          );
         }
         instance[key] = value;
         if (settings.global) {
@@ -930,33 +921,81 @@
        */
       timescale(value) {
         DEV: assert(
-          isNumber(value),
-          "timescale: 1st param must be a number"
+          isNumber(value) && value >= 0,
+          "timescale: 1st param must be a positive number or zero"
         );
         _timeScale = value;
       },
       /**
-       * Set the target FPS at runtime.
+       * Set the target FPS (frames per second).
        *
        * @param {number} value
        */
-      setfps(value) {
+      framerate(value) {
         DEV: assert(
           isNumber(value) && value >= 1,
-          "setfps: 1st param must be a positive number"
+          "framerate: 1st param must be a positive number"
         );
         _deltaTime = 1 / ~~value;
       },
+      /**
+       * Returns information about that engine instance.
+       *
+       * n = 0: the settings passed to that instance
+       * n = 1: returns true if the "init" event has already been emitted
+       * n = 2: the current ID returned by last requestAnimationFrame
+       * n = 3: the current canvas element scale (not the context 2D scale)
+       * n = 4: the attached event callbacks
+       * n = 5: the current color palette
+       * n = 6: the default sound used by `sfx()`
+       * n = 7: the current time scale
+       * n = 8: the current volume used by ZzFX
+       * n = 9: the current RNG state
+       *
+       * n = any other value: returns undefined
+       *
+       * @param {number} n
+       * @returns {any}
+       */
+      stat(n) {
+        DEV: assert(
+          isNumber(n) && n >= 0,
+          "stat: 1st param must be a positive number"
+        );
+        const list = [
+          // 0
+          settings,
+          // 1
+          _initialized,
+          // 2
+          _rafid,
+          // 3
+          _scale,
+          // 4
+          _events,
+          // 5
+          _colors,
+          // 6
+          _default_sound,
+          // 7
+          _timeScale,
+          // 8
+          root.zzfxV || 1,
+          // 9
+          _rng_seed
+        ];
+        return list[n];
+      },
       /**
        * Stops the litecanvas instance and remove all event listeners.
        */
       quit() {
         cancelAnimationFrame(_rafid);
         instance.emit("quit");
-        _events = [];
         for (const removeListener of _browserEventListeners) {
           removeListener();
         }
+        _events = {};
         if (settings.global) {
           for (const key in instance) {
             delete root[key];
@@ -969,7 +1008,6 @@
       instance[k] = math[k];
     }
     function init() {
-      _initialized = true;
       const source = settings.loop ? settings.loop : root;
       for (const event in _events) {
         if (source[event]) instance.listen(event, source[event]);
@@ -1001,55 +1039,90 @@
           tap.y = y;
         }, _checkTapped = (tap) => tap && performance.now() - tap.ts <= 300, preventDefault = (ev) => ev.preventDefault();
         let _pressingMouse = false;
-        on(_canvas, "mousedown", (ev) => {
-          if (ev.button === 0) {
+        on(
+          _canvas,
+          "mousedown",
+          /**
+           * @param {MouseEvent} ev
+           */
+          (ev) => {
+            if (ev.button === 0) {
+              preventDefault(ev);
+              const [x, y] = _getXY(ev.pageX, ev.pageY);
+              instance.emit("tap", x, y, 0);
+              _registerTap(0, x, y);
+              _pressingMouse = true;
+            }
+          }
+        );
+        on(
+          _canvas,
+          "mouseup",
+          /**
+           * @param {MouseEvent} ev
+           */
+          (ev) => {
+            if (ev.button === 0) {
+              preventDefault(ev);
+              const tap = _taps.get(0);
+              const [x, y] = _getXY(ev.pageX, ev.pageY);
+              if (_checkTapped(tap)) {
+                instance.emit("tapped", tap.startX, tap.startY, 0);
+              }
+              instance.emit("untap", x, y, 0);
+              _taps.delete(0);
+              _pressingMouse = false;
+            }
+          }
+        );
+        on(
+          _canvas,
+          "mousemove",
+          /**
+           * @param {MouseEvent} ev
+           */
+          (ev) => {
             preventDefault(ev);
             const [x, y] = _getXY(ev.pageX, ev.pageY);
-            instance.emit("tap", x, y, 0);
-            _registerTap(0, x, y);
-            _pressingMouse = true;
+            instance.def("MX", x);
+            instance.def("MY", y);
+            if (!_pressingMouse) return;
+            instance.emit("tapping", x, y, 0);
+            _updateTap(0, x, y);
           }
-        });
-        on(_canvas, "mouseup", (ev) => {
-          if (ev.button === 0) {
+        );
+        on(
+          _canvas,
+          "touchstart",
+          /**
+           * @param {TouchEvent} ev
+           */
+          (ev) => {
             preventDefault(ev);
-            const tap = _taps.get(0);
-            const [x, y] = _getXY(ev.pageX, ev.pageY);
-            if (_checkTapped(tap)) {
-              instance.emit("tapped", tap.startX, tap.startY, 0);
+            const touches = ev.changedTouches;
+            for (const touch of touches) {
+              const [x, y] = _getXY(touch.pageX, touch.pageY);
+              instance.emit("tap", x, y, touch.identifier + 1);
+              _registerTap(touch.identifier + 1, x, y);
             }
-            instance.emit("untap", x, y, 0);
-            _taps.delete(0);
-            _pressingMouse = false;
-          }
-        });
-        on(_canvas, "mousemove", (ev) => {
-          preventDefault(ev);
-          const [x, y] = _getXY(ev.pageX, ev.pageY);
-          instance.setvar("MOUSEX", x);
-          instance.setvar("MOUSEY", y);
-          if (!_pressingMouse) return;
-          instance.emit("tapping", x, y, 0);
-          _updateTap(0, x, y);
-        });
-        on(_canvas, "touchstart", (ev) => {
-          preventDefault(ev);
-          const touches = ev.changedTouches;
-          for (const touch of touches) {
-            const [x, y] = _getXY(touch.pageX, touch.pageY);
-            instance.emit("tap", x, y, touch.identifier + 1);
-            _registerTap(touch.identifier + 1, x, y);
           }
-        });
-        on(_canvas, "touchmove", (ev) => {
-          preventDefault(ev);
-          const touches = ev.changedTouches;
-          for (const touch of touches) {
-            const [x, y] = _getXY(touch.pageX, touch.pageY);
-            instance.emit("tapping", x, y, touch.identifier + 1);
-            _updateTap(touch.identifier + 1, x, y);
+        );
+        on(
+          _canvas,
+          "touchmove",
+          /**
+           * @param {TouchEvent} ev
+           */
+          (ev) => {
+            preventDefault(ev);
+            const touches = ev.changedTouches;
+            for (const touch of touches) {
+              const [x, y] = _getXY(touch.pageX, touch.pageY);
+              instance.emit("tapping", x, y, touch.identifier + 1);
+              _updateTap(touch.identifier + 1, x, y);
+            }
           }
-        });
+        );
         const _touchEndHandler = (ev) => {
           preventDefault(ev);
           const existing = [];
@@ -1097,7 +1170,7 @@
         });
         on(root, "blur", () => _keysDown.clear());
         instance.listen("after:draw", () => _keysPress.clear());
-        instance.setvar(
+        instance.def(
           "iskeydown",
           /**
            * Checks if a which key is pressed (down) on the keyboard.
@@ -1114,7 +1187,7 @@
             return keyCheck(_keysDown, key);
           }
         );
-        instance.setvar(
+        instance.def(
           "iskeypressed",
           /**
            * Checks if a which key just got pressed on the keyboard.
@@ -1143,6 +1216,7 @@
           }
         });
       }
+      _initialized = true;
       instance.emit("init", instance);
       _lastFrameTime = performance.now();
       _rafid = raf(drawFrame);
@@ -1158,10 +1232,7 @@
         _accumulated += frameTime;
         while (_accumulated >= _deltaTime) {
           instance.emit("update", _deltaTime * _timeScale);
-          instance.setvar(
-            "ELAPSED",
-            instance.ELAPSED + _deltaTime * _timeScale
-          );
+          instance.def("T", instance.T + _deltaTime * _timeScale);
           updated++;
           _accumulated -= _deltaTime;
         }
@@ -1174,18 +1245,23 @@
       }
     }
     function setupCanvas() {
-      _canvas = settings.canvas || document.createElement("canvas");
-      _canvas = "string" === typeof _canvas ? document.querySelector(_canvas) : _canvas;
+      if ("string" === typeof settings.canvas) {
+        _canvas = document.querySelector(settings.canvas);
+      } else {
+        _canvas = settings.canvas || document.createElement("canvas");
+      }
       DEV: assert(
         _canvas && _canvas.tagName === "CANVAS",
         "Invalid canvas element"
       );
-      instance.setvar("CANVAS", _canvas);
+      instance.def("CANVAS", _canvas);
       _ctx = _canvas.getContext("2d");
       on(_canvas, "click", () => root.focus());
       _canvas.style = "";
       resizeCanvas();
-      if (!_canvas.parentNode) document.body.appendChild(_canvas);
+      if (!_canvas.parentNode) {
+        document.body.appendChild(_canvas);
+      }
     }
     function resizeCanvas() {
       DEV: assert(
@@ -1201,28 +1277,29 @@
         `Litecanvas' option "width" is required when the option "height" is defined`
       );
       const width = settings.width || root.innerWidth, height = settings.height || settings.width || root.innerHeight;
-      instance.setvar("WIDTH", _canvas.width = width);
-      instance.setvar("HEIGHT", _canvas.height = height);
-      instance.setvar("CENTERX", instance.WIDTH / 2);
-      instance.setvar("CENTERY", instance.HEIGHT / 2);
+      instance.def("W", _canvas.width = width);
+      instance.def("H", _canvas.height = height);
+      instance.def("CX", instance.W / 2);
+      instance.def("CY", instance.H / 2);
       if (settings.autoscale) {
         if (!_canvas.style.display) {
           _canvas.style.display = "block";
           _canvas.style.margin = "auto";
         }
         _scale = math.min(
-          root.innerWidth / instance.WIDTH,
-          root.innerHeight / instance.HEIGHT
+          root.innerWidth / instance.W,
+          root.innerHeight / instance.H
         );
         _scale = (settings.pixelart ? ~~_scale : _scale) || 1;
-        _canvas.style.width = instance.WIDTH * _scale + "px";
-        _canvas.style.height = instance.HEIGHT * _scale + "px";
+        _canvas.style.width = instance.W * _scale + "px";
+        _canvas.style.height = instance.H * _scale + "px";
       }
       if (!settings.antialias || settings.pixelart) {
         _ctx.imageSmoothingEnabled = false;
         _canvas.style.imageRendering = "pixelated";
       }
       instance.emit("resized", _scale);
+      instance.cls(0);
       if (!settings.animate) {
         raf(drawFrame);
       }
@@ -1234,13 +1311,13 @@
       }
     }
     function loadPlugin(callback, config) {
-      const pluginData = callback(instance, _helpers, config);
+      const pluginData = callback(instance, config);
       DEV: assert(
         null == pluginData || "object" === typeof pluginData,
         "Litecanvas plugins should return an object or nothing"
       );
       for (const key in pluginData) {
-        instance.setvar(key, pluginData[key]);
+        instance.def(key, pluginData[key]);
       }
     }
     if (settings.global) {