@litecanvas/utils 0.3.2 → 0.5.0

package/dist/grid.js

@@ -0,0 +1,202 @@
+(() => {
+  // src/grid/index.js
+  var Grid = class _Grid {
+    /** @type {number} The grid width */
+    _w;
+    /** @type {number} The grid height */
+    _h;
+    /** @type {any[]} The grid cells */
+    _c;
+    /**
+     * @static
+     * @param {number} width
+     * @param {number} height
+     * @param {any[]} values
+     */
+    static fromArray(width, height, values) {
+      const grid = new _Grid(width, height);
+      for (let i = 0; i < values.length; i++) {
+        grid._c[i] = values[i];
+      }
+      return grid;
+    }
+    /**
+     * @param {number} width The grid width
+     * @param {number} height The grid height
+     */
+    constructor(width, height) {
+      this.width = width;
+      this.height = height;
+      this.clear();
+    }
+    /**
+     * Delete all cell values.
+     */
+    clear() {
+      this._c = Array(this._w * this._h);
+    }
+    /**
+     * @param {number} value
+     */
+    set width(value) {
+      this._w = Math.max(1, ~~value);
+    }
+    get width() {
+      return this._w;
+    }
+    /**
+     * @param {number} value
+     */
+    set height(value) {
+      this._h = Math.max(1, ~~value);
+    }
+    get height() {
+      return this._h;
+    }
+    /**
+     * The the value of a grid's cell.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {any} value
+     */
+    set(x, y, value) {
+      this._c[this.pointToIndex(x, y)] = value;
+    }
+    /**
+     * Returns the value of a grid's cell.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {any}
+     */
+    get(x, y) {
+      return this._c[this.pointToIndex(x, y)];
+    }
+    /**
+     * Returns true if the which cell has any value not equal to `null` or `undefined`.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {boolean}
+     */
+    has(x, y) {
+      return this.get(x, y) != null;
+    }
+    /**
+     * Returns the total of cells.
+     *
+     * @returns {number}
+     */
+    get length() {
+      return this._w * this._h;
+    }
+    /**
+     * Convert a grid point (X, Y) to a index.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {number} The index
+     */
+    pointToIndex(x, y) {
+      return this.clampX(~~x) + this.clampY(~~y) * this._w;
+    }
+    /**
+     * Convert index to a grid point X.
+     *
+     * @param {number} index
+     * @returns {number}
+     */
+    indexToPointX(index) {
+      return index % this._w;
+    }
+    /**
+     * Convert index to a grid point Y.
+     *
+     * @param {number} index
+     * @returns {number}
+     */
+    indexToPointY(index) {
+      return Math.floor(index / this._w);
+    }
+    /**
+     * Loops over all grid cells.
+     *
+     * @callback GridForEachCallback
+     * @param {number} x
+     * @param {number} y
+     * @param {any} value
+     * @param {Grid} grid
+     * @returns {boolean?} returns `false` to stop/break the loop
+     *
+     * @param {GridForEachCallback} handler
+     * @param {boolean} [reverse=false]
+     */
+    forEach(handler, reverse = false) {
+      let i = reverse ? this.length - 1 : 0, limit = reverse ? -1 : this.length, step = reverse ? -1 : 1;
+      while (i !== limit) {
+        const x = this.indexToPointX(i), y = this.indexToPointY(i), cellValue = this._c[i];
+        if (false === handler(x, y, cellValue, this)) break;
+        i += step;
+      }
+    }
+    /**
+     * @param {*} value
+     */
+    fill(value) {
+      this.forEach((x, y) => {
+        this.set(x, y, value);
+      });
+    }
+    /**
+     * @returns {Grid} the cloned grid
+     */
+    clone() {
+      return _Grid.fromArray(this._w, this._h, this._c);
+    }
+    /**
+     * @param {number} y
+     * @returns {number}
+     */
+    clampX(x) {
+      return _clamp(x, 0, this._w - 1);
+    }
+    /**
+     * @param {number} y
+     * @returns {number}
+     */
+    clampY(y) {
+      return _clamp(y, 0, this._h - 1);
+    }
+    /**
+     * Returns the cell values in a single array.
+     *
+     * @returns {any[]}
+     */
+    toArray() {
+      return this._c.slice(0);
+    }
+    /**
+     * @param {string} separator
+     * @param {boolean} format
+     * @returns {string}
+     */
+    toString(separator = " ", format = true) {
+      if (!format) return this._c.join(separator);
+      const rows = [];
+      this.forEach((x, y, value) => {
+        rows[y] = rows[y] || "";
+        rows[y] += value + separator;
+      });
+      return rows.join("\n");
+    }
+  };
+  function _clamp(value, min, max) {
+    if (value < min) return min;
+    if (value > max) return max;
+    return value;
+  }
+
+  // src/grid/_web.js
+  globalThis.utils = Object.assign(globalThis.utils || {}, { Grid });
+})();

package/dist/grid.min.js

@@ -0,0 +1,2 @@
+(()=>{var e=class s{_w;_h;_c;static fromArray(t,i,h){let n=new s(t,i);for(let r=0;r<h.length;r++)n._c[r]=h[r];return n}constructor(t,i){this.width=t,this.height=i,this.clear()}clear(){this._c=Array(this._w*this._h)}set width(t){this._w=Math.max(1,~~t)}get width(){return this._w}set height(t){this._h=Math.max(1,~~t)}get height(){return this._h}set(t,i,h){this._c[this.pointToIndex(t,i)]=h}get(t,i){return this._c[this.pointToIndex(t,i)]}has(t,i){return this.get(t,i)!=null}get length(){return this._w*this._h}pointToIndex(t,i){return this.clampX(~~t)+this.clampY(~~i)*this._w}indexToPointX(t){return t%this._w}indexToPointY(t){return Math.floor(t/this._w)}forEach(t,i=!1){let h=i?this.length-1:0,n=i?-1:this.length,r=i?-1:1;for(;h!==n;){let o=this.indexToPointX(h),c=this.indexToPointY(h),_=this._c[h];if(t(o,c,_,this)===!1)break;h+=r}}fill(t){this.forEach((i,h)=>{this.set(i,h,t)})}clone(){return s.fromArray(this._w,this._h,this._c)}clampX(t){return l(t,0,this._w-1)}clampY(t){return l(t,0,this._h-1)}toArray(){return this._c.slice(0)}toString(t=" ",i=!0){if(!i)return this._c.join(t);let h=[];return this.forEach((n,r,o)=>{h[r]=h[r]||"",h[r]+=o+t}),h.join(`
+`)}};function l(s,t,i){return s<t?t:s>i?i:s}globalThis.utils=Object.assign(globalThis.utils||{},{Grid:e});})();

package/dist/vector.js

@@ -63,7 +63,7 @@
     if (isvector(x)) {
       return veceq(v, x.x, x.y);
     }
-    return v.x === x && v.y === (y || x);
+    return v.x === x && v.y === y;
   };
   var veccopy = (v) => vec(v.x, v.y);
   var vecset = (v, x, y = x) => {

package/dist/vector.min.js

@@ -1 +1 @@
-(()=>{var M=Object.defineProperty;var g=(t,o)=>{for(var s in o)M(t,s,{get:o[s],enumerable:!0})};var i={};g(i,{DOWN:()=>G,LEFT:()=>H,ONE:()=>w,RIGHT:()=>F,UP:()=>D,Vector:()=>n,ZERO:()=>j,isvector:()=>r,vec:()=>c,vecadd:()=>l,vecconfig:()=>x,veccopy:()=>m,veccross:()=>R,vecdir:()=>N,vecdist:()=>E,vecdist2:()=>I,vecdiv:()=>y,vecdot:()=>P,veceq:()=>a,veclerp:()=>U,veclimit:()=>O,vecmag:()=>u,vecmag2:()=>f,vecmult:()=>p,vecnorm:()=>T,vecrand:()=>$,vecrot:()=>q,vecset:()=>d,vecsub:()=>h});var n=class{x;y;constructor(o=0,s=o){this.x=o,this.y=s}toString(){return`Vector (${this.x}, ${this.y})`}},c=(t=0,o=t)=>new n(t,o),a=(t,o,s=o)=>r(o)?a(t,o.x,o.y):t.x===o&&t.y===(s||o),m=t=>c(t.x,t.y),d=(t,o,s=o)=>{r(o)?d(t,o.x,o.y):(t.x=o,t.y=s)},l=(t,o,s=o)=>{r(o)?l(t,o.x,o.y):(t.x+=o,t.y+=s)},h=(t,o,s=o)=>{r(o)?h(t,o.x,o.y):(t.x-=o,t.y-=s)},p=(t,o,s=o)=>{r(o)?p(t,o.x,o.y):(t.x*=o,t.y*=s)},y=(t,o,s=o)=>{r(o)?y(t,o.x,o.y):(t.x/=o,t.y/=s)},q=(t,o)=>{let s=Math.cos(o),e=Math.sin(o);t.x=s*t.x-e*t.y,t.y=e*t.x+s*t.y},u=t=>Math.sqrt(t.x*t.x+t.y*t.y),f=t=>t.x*t.x+t.y*t.y,T=t=>{let o=u(t);o>0&&y(t,o)},O=(t,o)=>{let s=f(t);s>o*o&&(y(t,Math.sqrt(s)),p(t,o))},E=(t,o)=>{let s=t.x-o.x,e=t.y-o.y;return Math.sqrt(s*s+e*e)},I=(t,o)=>{let s=t.x-o.x,e=t.y-o.y;return s*s+e*e},N=t=>Math.atan2(t.y,t.x),P=(t,o)=>t.x*o.x+t.y*o.y,R=(t,o)=>t.x*o.y-t.y*o.x,U=(t,o,s)=>{t.x+=(o.x-t.x)*s||0,t.y+=(o.y-t.y)*s||0},$=(t=1,o=t)=>{let s=x.random()*2*Math.PI,e=x.random()*(o-t)+t;return c(Math.cos(s)*e,Math.sin(s)*e)},r=t=>t instanceof n,x={random:()=>globalThis.rand?rand():Math.random()},j=c(0,0),w=c(1,1),D=c(0,-1),F=c(1,0),G=c(0,1),H=c(-1,0);globalThis.utils=Object.assign(globalThis.utils||{},i);})();
+(()=>{var M=Object.defineProperty;var g=(t,o)=>{for(var s in o)M(t,s,{get:o[s],enumerable:!0})};var i={};g(i,{DOWN:()=>G,LEFT:()=>H,ONE:()=>w,RIGHT:()=>F,UP:()=>D,Vector:()=>n,ZERO:()=>j,isvector:()=>r,vec:()=>c,vecadd:()=>l,vecconfig:()=>y,veccopy:()=>m,veccross:()=>R,vecdir:()=>N,vecdist:()=>E,vecdist2:()=>I,vecdiv:()=>x,vecdot:()=>P,veceq:()=>a,veclerp:()=>U,veclimit:()=>O,vecmag:()=>u,vecmag2:()=>f,vecmult:()=>p,vecnorm:()=>T,vecrand:()=>$,vecrot:()=>q,vecset:()=>d,vecsub:()=>h});var n=class{x;y;constructor(o=0,s=o){this.x=o,this.y=s}toString(){return`Vector (${this.x}, ${this.y})`}},c=(t=0,o=t)=>new n(t,o),a=(t,o,s=o)=>r(o)?a(t,o.x,o.y):t.x===o&&t.y===s,m=t=>c(t.x,t.y),d=(t,o,s=o)=>{r(o)?d(t,o.x,o.y):(t.x=o,t.y=s)},l=(t,o,s=o)=>{r(o)?l(t,o.x,o.y):(t.x+=o,t.y+=s)},h=(t,o,s=o)=>{r(o)?h(t,o.x,o.y):(t.x-=o,t.y-=s)},p=(t,o,s=o)=>{r(o)?p(t,o.x,o.y):(t.x*=o,t.y*=s)},x=(t,o,s=o)=>{r(o)?x(t,o.x,o.y):(t.x/=o,t.y/=s)},q=(t,o)=>{let s=Math.cos(o),e=Math.sin(o);t.x=s*t.x-e*t.y,t.y=e*t.x+s*t.y},u=t=>Math.sqrt(t.x*t.x+t.y*t.y),f=t=>t.x*t.x+t.y*t.y,T=t=>{let o=u(t);o>0&&x(t,o)},O=(t,o)=>{let s=f(t);s>o*o&&(x(t,Math.sqrt(s)),p(t,o))},E=(t,o)=>{let s=t.x-o.x,e=t.y-o.y;return Math.sqrt(s*s+e*e)},I=(t,o)=>{let s=t.x-o.x,e=t.y-o.y;return s*s+e*e},N=t=>Math.atan2(t.y,t.x),P=(t,o)=>t.x*o.x+t.y*o.y,R=(t,o)=>t.x*o.y-t.y*o.x,U=(t,o,s)=>{t.x+=(o.x-t.x)*s||0,t.y+=(o.y-t.y)*s||0},$=(t=1,o=t)=>{let s=y.random()*2*Math.PI,e=y.random()*(o-t)+t;return c(Math.cos(s)*e,Math.sin(s)*e)},r=t=>t instanceof n,y={random:()=>globalThis.rand?rand():Math.random()},j=c(0,0),w=c(1,1),D=c(0,-1),F=c(1,0),G=c(0,1),H=c(-1,0);globalThis.utils=Object.assign(globalThis.utils||{},i);})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litecanvas/utils",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Utilities to help build litecanvas games",
   "author": "Luiz Bills <luizbills@pm.me>",
   "license": "MIT",

package/src/actor/README.md

@@ -0,0 +1,140 @@
+# Actor
+
+**CDN**: https://unpkg.com/@litecanvas/utils/dist/actor.js
+
+## Usage
+
+```js
+import litecanvas from "@litecanvas"
+import { Actor } from "@litecanvas/utils"
+
+let player, mySprite
+
+litecanvas({
+  loop: { init, tapped, draw },
+})
+
+// create a sprite image
+mySprite = paint(3, 3, ["303", "030", "303"], { scale: 10 })
+
+function init() {
+  // create a actor
+  player = new Actor(mySprite)
+}
+
+function tapped(tapx, tapy) {
+  // update the actor position
+  player.x = tapx
+  player.y = tapy
+}
+
+function draw() {
+  cls(0)
+
+  // draw the actor sprite
+  player.draw()
+}
+```
+
+## Actor#x / Actor#y
+
+Set or get the actor position
+
+```js
+player.x = 100
+player.y = 200
+```
+
+## Actor#scale
+
+Set or get the actor scale/size
+
+```js
+// twice bigger
+player.scale.x = 2
+player.scale.y = 2
+```
+
+## Actor#anchor
+
+Set or get the actor anchor (origin). By default, the anchor is a vector `(0, 0)` (meaning anchor Top Left).
+
+```js
+// position the sprite based on their center
+player.anchor.x = 0.5
+player.anchor.y = 0.5
+```
+
+```js
+// alternatively
+import { ANCHOR_CENTER } from "@litecanvas/utils"
+
+player.anchor = ANCHOR_CENTER
+```
+
+> Note:
+> You can import and use the following constants to help you choose an actor anchor: , `ANCHOR_TOP_LEFT` (default), `ANCHOR_TOP_RIGHT`, `ANCHOR_BOT_LEFT`, `ANCHOR_BOT_RIGHT` or `ANCHOR_CENTER`.
+
+## Actor#angle
+
+Set or get the actor angle (in radians).
+
+```js
+player.angle = HALF_PI / 2 // 45 degrees
+
+// or use the litecanvas' `deg2rad()` helper
+player.angle = deg2rad(45)
+```
+
+## Actor#opacity
+
+Set or get the actor opacity (alpha).
+
+```js
+player.opacity = 0.5 // 50% transparent
+```
+
+## Actor#hidden
+
+Set or get the actor hidden (`boolean`) state.
+
+```js
+player.hidden = true // hides the actor image
+player.hidden = false // display the actor image
+```
+
+## Actor#width
+
+Get (not set) the actor current width.
+
+```js
+console.log(player.width) // => 30
+
+player.scale.x = 1.5
+
+console.log(player.width) // => 45
+```
+
+## Actor#height
+
+Get (not set) the actor current height.
+
+```js
+console.log(player.height) // => 30
+
+player.scale.x = 2
+
+console.log(player.height) // => 60
+```
+
+## Actor#sprite
+
+Set or get the actor sprite image. Useful to make animations.
+
+```js
+player.sprite = anotherSprite
+```
+
+> The actor sprite must be a `Image`, `HTMLCanvas` or `OffscreenCanvas`.
+>
+> Remember, you can create a image using the litecanvas' `paint()` built-in helper or [load a image](https://github.com/litecanvas/plugin-asset-loader?tab=readme-ov-file#loading-images) with plugins.

package/src/actor/_web.js

@@ -0,0 +1,3 @@
+import * as actorUtils from "./index.js"
+
+globalThis.utils = Object.assign(globalThis.utils || {}, { actorUtils })

package/src/actor/index.js

@@ -0,0 +1,135 @@
+import { Vector, vec, veccopy } from "../vector/index.js"
+import "litecanvas"
+
+export const ANCHOR_CENTER = vec(0.5, 0.5)
+export const ANCHOR_TOP_LEFT = vec(0, 0)
+export const ANCHOR_TOP_RIGHT = vec(1, 0)
+export const ANCHOR_BOT_LEFT = vec(0, 1)
+export const ANCHOR_BOT_RIGHT = vec(1, 1)
+
+export class Actor {
+  /** @type {Image|HTMLCanvasElement|OffscreenCanvas} */
+  sprite
+
+  /** @type {Vector} The actor position */
+  _p
+
+  /** @type {Vector} The actor anchor (origin) */
+  _o
+
+  /** @type {Vector} The actor scale */
+  _s
+
+  /** @type {number} The actor angle (in radians) */
+  angle = 0
+
+  /** @type {number} The actor opacity */
+  opacity = 1
+
+  /** @type {boolean} If `true` the actor will not be drawn. */
+  hidden = false
+
+  /**
+   * @param {Image|HTMLCanvasElement|OffscreenCanvas} sprite
+   * @param {Vector} position
+   */
+  constructor(sprite, position) {
+    this.sprite = sprite
+    this._p = position || vec(0)
+    this._o = veccopy(ANCHOR_TOP_LEFT)
+    this._s = vec(1, 1)
+  }
+
+  /**
+   * @param {number}
+   */
+  set x(value) {
+    this._p.x = value
+  }
+
+  /**
+   * @returns {number}
+   */
+  get x() {
+    return this._p.x
+  }
+
+  /**
+   * @param {number}
+   */
+  set y(value) {
+    this._p.y = value
+  }
+
+  /**
+   * @returns {number}
+   */
+  get y() {
+    return this._p.y
+  }
+
+  /**
+   * @param {Vector}
+   */
+  set anchor(vec) {
+    this._o.x = vec.x
+    this._o.y = vec.y
+  }
+
+  /**
+   * @returns {Vector}
+   */
+  get anchor() {
+    return this._o
+  }
+
+  /**
+   * @returns {number}
+   */
+  get width() {
+    return this.sprite.width * this._s.y
+  }
+
+  /**
+   * @returns {number}
+   */
+  get height() {
+    return this.sprite.height * this._s.y
+  }
+
+  /**
+   * @retuns {Vector}
+   */
+  get scale() {
+    return this._s
+  }
+
+  /**
+   * Update the transformation matrix, sets the opacity and draw the actor sprite image.
+   *
+   * @param {LitecanvasInstance} [litecanvas]
+   */
+  draw(litecanvas = globalThis) {
+    if (this.hidden || this.opacity <= 0) return
+
+    litecanvas.push()
+
+    this.transform(litecanvas)
+
+    const anchorX = this.sprite.width * this.anchor.x
+    const anchorY = this.sprite.height * this.anchor.y
+    litecanvas.image(-anchorX, -anchorY, this.sprite)
+
+    litecanvas.pop()
+  }
+
+  /**
+   * @param {LitecanvasInstance} litecanvas
+   */
+  transform(litecanvas) {
+    litecanvas.translate(this._p.x, this._p.y)
+    litecanvas.rotate(this.angle)
+    litecanvas.scale(this._s.x, this._s.y)
+    litecanvas.alpha(this.opacity)
+  }
+}

package/src/collision/README.md

@@ -40,6 +40,8 @@ function draw() {
 
 Syntax: `resolve(x1, y1, w1, h1, x2, y2, w2, h2): { direction: string, x: number, y: number }`
 
+> Note: possible values for `direction` is `"top"`, `"botton"`, `"left"`, `"right"` or `""` (empty string, if no collision).
+
 ```js
 import litecanvas from "litecanvas"
 import { resolve } from "@litecanvas/utils"

package/src/grid/README.md

@@ -0,0 +1,47 @@
+# Grid
+
+**CDN**: https://unpkg.com/@litecanvas/utils/dist/grid.js
+
+## Usage
+
+Lets build an arena with [ASCII graphics](https://en.wikipedia.org/wiki/ASCII_art) like in classic roguelikes.
+
+```js
+import { Grid } from "@litecanvas/utils"
+
+// make a grid 13x13
+let grid = new Grid(13, 13)
+
+// fill the entire grid with "."
+grid.fill(".")
+
+// put a '@' in the middle
+grid.set(grid.width / 2, grid.height / 2, "@")
+
+// put '#' around the grid
+grid.forEach((x, y, cellValue) => {
+  if (x === 0 || y === 0 || x === grid.width - 1 || y === grid.height - 1) {
+    grid.set(x, y, "#")
+  }
+})
+
+document.body.innerHTML = "<pre>" + grid.toString() + "</pre>"
+```
+
+The result:
+
+```
+# # # # # # # # # # # # #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . @ . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# . . . . . . . . . . . #
+# # # # # # # # # # # # #
+```

package/src/grid/_web.js

@@ -0,0 +1,3 @@
+import Grid from "./index.js"
+
+globalThis.utils = Object.assign(globalThis.utils || {}, { Grid })