litecanvas 0.202.0 → 0.204.0

package/dist/dist.dev.js

@@ -115,7 +115,7 @@
   var assert = (condition, message = "Assertion failed") => {
     if (!condition) throw new Error("[litecanvas] " + message);
   };
-  var version = "0.202.0";
+  var version = "0.204.0";
   function litecanvas(settings = {}) {
     const root = window,
       math = Math,
@@ -192,11 +192,11 @@
         return start + t * (end - start);
       },
       deg2rad: (degs) => {
-        DEV: assert(isNumber(degs), "deg2rad: 1st param must be a number");
+        DEV: assert(isNumber(degs), "deg2rad() 1st param must be a number");
         return (math.PI / 180) * degs;
       },
       rad2deg: (rads) => {
-        DEV: assert(isNumber(rads), "rad2deg: 1st param must be a number");
+        DEV: assert(isNumber(rads), "rad2deg() 1st param must be a number");
         return (180 / math.PI) * rads;
       },
       round: (n, precision = 0) => {
@@ -646,6 +646,10 @@
         }
       },
       textgap(value) {
+        DEV: assert(
+          isNumber(value),
+          loggerPrefix + "textgap() 1st param must be a number",
+        );
         _fontLineHeight = value;
       },
       textfont(family) {
@@ -740,8 +744,10 @@
           loggerPrefix + "paint() 3rd param must be a function",
         );
         DEV: assert(
-          (options && null == options.scale) || isNumber(options.scale),
-          loggerPrefix + "paint() 4th param (options.scale) must be a number",
+          (options && null == options.scale) ||
+            (isNumber(options.scale) && options.scale > 0),
+          loggerPrefix +
+            "paint() 4th param (options.scale) must be a positive number",
         );
         DEV: assert(
           (options && null == options.canvas) ||
@@ -761,6 +767,13 @@
         return canvas.transferToImageBitmap();
       },
       ctx(context) {
+        DEV: assert(
+          null == context ||
+            context instanceof CanvasRenderingContext2D ||
+            context instanceof OffscreenCanvasRenderingContext2D,
+          loggerPrefix +
+            "ctx() 1st param must be an [Offscreen]CanvasRenderingContext2D",
+        );
         if (context) {
           _ctx = context;
         }
@@ -783,16 +796,16 @@
         );
         _ctx.translate(~~x, ~~y);
       },
-      scale(x, y) {
+      scale(x, y = x) {
         DEV: assert(
           isNumber(x),
           loggerPrefix + "scale() 1st param must be a number",
         );
         DEV: assert(
-          null == y || isNumber(y),
+          isNumber(y),
           loggerPrefix + "scale() 2nd param must be a number",
         );
-        _ctx.scale(x, y || x);
+        _ctx.scale(x, y);
       },
       rotate(radians) {
         DEV: assert(
@@ -827,7 +840,7 @@
       clip(callback) {
         DEV: assert(
           "function" === typeof callback,
-          loggerPrefix + "clip() 1st param must be a function",
+          loggerPrefix + "clip() 1st param must be a function (ctx) => void",
         );
         beginPath(_ctx);
         callback(_ctx);
@@ -872,7 +885,8 @@
       use(callback, config = {}) {
         DEV: assert(
           "function" === typeof callback,
-          loggerPrefix + "use() 1st param must be a function",
+          loggerPrefix +
+            "use() 1st param must be a function (instance, config) => any",
         );
         DEV: assert(
           "object" === typeof config,
@@ -921,6 +935,7 @@
           triggerEvent(eventName, arg1, arg2, arg3, arg4);
           triggerEvent("after:" + eventName, arg1, arg2, arg3, arg4);
         }
+        return arg1;
       },
       pal(colors, textColor = 3) {
         DEV: assert(
@@ -1011,8 +1026,11 @@
         return internals[index];
       },
       pause() {
-        _paused = true;
-        cancelAnimationFrame(_rafid);
+        if (!_paused) {
+          _paused = true;
+          cancelAnimationFrame(_rafid);
+          instance.emit("paused");
+        }
       },
       resume() {
         DEV: assert(
@@ -1025,13 +1043,14 @@
           _accumulated = _fpsInterval;
           _lastFrameTime = perf.now();
           _rafid = raf(drawFrame);
+          instance.emit("resumed");
         }
       },
-      paused() {
+      ispaused() {
         return _paused;
       },
       quit() {
-        instance.emit("quit");
+        instance.emit("shutdown");
         instance.pause();
         _initialized = false;
         _eventListeners = {};
@@ -1327,11 +1346,7 @@
           instance.listen(eventName, settings.loop[eventName]);
       }
     }
-    if ("loading" === document.readyState) {
-      on(root, "DOMContentLoaded", () => raf(init));
-    } else {
-      _rafid = raf(init);
-    }
+    _rafid = raf(init);
     return instance;
   }
   window.litecanvas = litecanvas;

package/dist/dist.js

@@ -363,8 +363,8 @@
       translate(x, y) {
         _ctx.translate(~~x, ~~y);
       },
-      scale(x, y) {
-        _ctx.scale(x, y || x);
+      scale(x, y = x) {
+        _ctx.scale(x, y);
       },
       rotate(radians) {
         _ctx.rotate(radians);
@@ -429,6 +429,7 @@
           triggerEvent(eventName, arg1, arg2, arg3, arg4);
           triggerEvent("after:" + eventName, arg1, arg2, arg3, arg4);
         }
+        return arg1;
       },
       pal(colors, textColor = 3) {
         _colorPalette = colors || defaultPalette;
@@ -474,8 +475,11 @@
         return internals[index];
       },
       pause() {
-        _paused = true;
-        cancelAnimationFrame(_rafid);
+        if (!_paused) {
+          _paused = true;
+          cancelAnimationFrame(_rafid);
+          instance.emit("paused");
+        }
       },
       resume() {
         if (_initialized && _paused) {
@@ -483,13 +487,14 @@
           _accumulated = _fpsInterval;
           _lastFrameTime = perf.now();
           _rafid = raf(drawFrame);
+          instance.emit("resumed");
         }
       },
-      paused() {
+      ispaused() {
         return _paused;
       },
       quit() {
-        instance.emit("quit");
+        instance.emit("shutdown");
         instance.pause();
         _initialized = false;
         _eventListeners = {};
@@ -732,11 +737,7 @@
           instance.listen(eventName, settings.loop[eventName]);
       }
     }
-    if ("loading" === document.readyState) {
-      on(root, "DOMContentLoaded", () => raf(init));
-    } else {
-      _rafid = raf(init);
-    }
+    _rafid = raf(init);
     return instance;
   }
   window.litecanvas = litecanvas;

package/dist/dist.min.js

@@ -1 +1 @@
-(()=>{var e=["#211e20","#555568","#a0a08b","#e9efec"];window.litecanvas=function(t={}){let a,l=window,n=Math,i=performance,o=2*n.PI,r=requestAnimationFrame,s=[],f=(e,t,a)=>{e.addEventListener(t,a,!1),s.push(()=>e.removeEventListener(t,a,!1))},d=(a=new AudioContext,l.zzfxV=1,(e=1,t=.05,n=220,i=0,o=0,r=.1,s=0,f=1,d=0,c=0,p=0,u=0,h=0,g=0,m=0,w=0,v=0,x=1,y=0,b=0,k=0)=>{let E=Math,P=2*E.PI,T=d*=500*P/44100/44100,z=n*=(1-t+2*t*E.random(t=[]))*P/44100,C=0,I=0,L=0,D=1,S=0,A=0,M=0,H=k<0?-1:1,N=P*H*k*2/44100,W=E.cos(N),q=E.sin,B=q(N)/4,O=1+B,V=-2*W/O,R=(1-B)/O,F=(1+H*W)/2/O,G=-(H+W)/O,X=0,Y=0,$=0,j=0;for(i=44100*i+9,y*=44100,o*=44100,r*=44100,v*=44100,c*=500*P/85766121e6,m*=P/44100,p*=P/44100,u*=44100,h=44100*h|0,e*=.3*l.zzfxV,H=i+y+o+r+v|0;L<H;t[L++]=M*e)++A%(100*w|0)||(M=s?1<s?2<s?3<s?q(C*C):E.max(E.min(E.tan(C),1),-1):1-(2*C/P%2+2)%2:1-4*E.abs(E.round(C/P)-C/P):q(C),M=(h?1-b+b*q(P*L/h):1)*(M<0?-1:1)*E.abs(M)**f*(L<i?L/i:L<i+y?1-(L-i)/y*(1-x):L<i+y+o?x:L<H-v?(H-L-v)/r*x:0),M=v?M/2+(v>L?0:(L<H-v?1:(H-L)/v)*t[L-v|0]/2/e):M,k&&(M=j=F*X+G*(X=Y)+F*(Y=M)-R*$-V*($=j))),C+=(N=(n+=d+=c)*E.cos(m*I++))+N*g*q(L**5),D&&++D>u&&(n+=p,z+=p,D=0),!h||++S%h||(n=z,d=T,D=D||1);(e=a.createBuffer(1,H,44100)).getChannelData(0).set(t),(n=a.createBufferSource()).buffer=e,n.connect(a.destination),n.start()});t=Object.assign({width:null,height:null,autoscale:!0,canvas:null,global:!0,loop:null,tapEvents:!0,keyboardEvents:!0},t);let c=!1,p=!0,u,h=1,g,m=.5,w=1,v,x=1e3/60,y,b,k=3,E="sans-serif",P=20,T=1.2,z=Date.now(),C=e,I=[],L=[.5,0,1750,,,.3,1,,,,600,.1],D={},S={W:0,H:0,T:0,MX:-1,MY:-1,TWO_PI:o,HALF_PI:o/4,lerp:(e,t,a)=>e+a*(t-e),deg2rad:e=>n.PI/180*e,rad2deg:e=>180/n.PI*e,round:(e,t=0)=>{if(!t)return n.round(e);let a=10**t;return n.round(e*a)/a},clamp:(e,t,a)=>e<t?t:e>a?a:e,dist:(e,t,a,l)=>n.hypot(a-e,l-t),wrap:(e,t,a)=>e-(a-t)*n.floor((e-t)/(a-t)),map(e,t,a,l,n,i){let o=(e-t)/(a-t)*(n-l)+l;return i?S.clamp(o,l,n):o},norm:(e,t,a)=>S.map(e,t,a,0,1),rand:(e=0,t=1)=>(z=(1664525*z+0x3c6ef35f)%0x100000000)/0x100000000*(t-e)+e,randi:(e=0,t=1)=>~~S.rand(e,t+1),rseed(e){z=~~e},cls(e){null==e?g.clearRect(0,0,S.W,S.H):S.rectfill(0,0,S.W,S.H,e)},rect(e,t,a,l,n,i){g.beginPath(),g[i?"roundRect":"rect"](~~e-m,~~t-m,~~a+2*m,~~l+2*m,i),S.stroke(n)},rectfill(e,t,a,l,n,i){g.beginPath(),g[i?"roundRect":"rect"](~~e,~~t,~~a,~~l,i),S.fill(n)},circ(e,t,a,l){g.beginPath(),g.arc(~~e,~~t,~~a,0,o),S.stroke(l)},circfill(e,t,a,l){g.beginPath(),g.arc(~~e,~~t,~~a,0,o),S.fill(l)},oval(e,t,a,l,n){g.beginPath(),g.ellipse(~~e,~~t,~~a,~~l,0,0,o),S.stroke(n)},ovalfill(e,t,a,l,n){g.beginPath(),g.ellipse(~~e,~~t,~~a,~~l,0,0,o),S.fill(n)},shape(e){g.beginPath();for(let t=0;t<e.length;t+=2)0===t?g.moveTo(~~e[t],~~e[t+1]):g.lineTo(~~e[t],~~e[t+1]);g.lineTo(~~e[0],~~e[1])},line(e,t,a,l,n){g.beginPath();let i=.5*(0!==m&&~~e==~~a),o=.5*(0!==m&&~~t==~~l);g.moveTo(~~e+i,~~t+o),g.lineTo(~~a+i,~~l+o),S.stroke(n)},linewidth(e){g.lineWidth=~~e,m=.5*(0!=~~e%2)},linedash(e,t=0){g.setLineDash(e),g.lineDashOffset=t},text(e,t,a,l=k,n="normal"){g.font=`${n} ${P}px ${E}`,g.fillStyle=W(l);let i=(""+a).split("\n");for(let a=0;a<i.length;a++)g.fillText(i[a],~~e,~~t+P*T*a)},textgap(e){T=e},textfont(e){E=e},textsize(e){P=e},textalign(e,t){e&&(g.textAlign=e),t&&(g.textBaseline=t)},image(e,t,a){g.drawImage(a,~~e,~~t)},spr(e,t,a){let l=a.trim().split("\n");for(let a=0;a<l.length;a++){let n=l[a].trim();for(let l=0;l<n.length;l++){let i=n[l];"."!==i&&" "!==i&&S.rectfill(e+l,t+a,1,1,parseInt(i,36)||0)}}},paint(e,t,a,l={}){let n=l.canvas||new OffscreenCanvas(1,1),i=l.scale||1,o=g;return n.width=e*i,n.height=t*i,(g=n.getContext("2d")).scale(i,i),a(g),g=o,n.transferToImageBitmap()},ctx:e=>(e&&(g=e),g),push(){g.save()},pop(){g.restore()},translate(e,t){g.translate(~~e,~~t)},scale(e,t){g.scale(e,t||e)},rotate(e){g.rotate(e)},alpha(e){g.globalAlpha=S.clamp(e,0,1)},fill(e){g.fillStyle=W(e),g.fill()},stroke(e){g.strokeStyle=W(e),g.stroke()},clip(e){g.beginPath(),e(g),g.clip()},sfx:(e,t=0,a=1)=>!!l.zzfxV&&(!navigator.userActivation||!!navigator.userActivation.hasBeenActive)&&(e=e||L,(0!==t||1!==a)&&((e=e.slice())[0]=a*(e[0]||1),e[10]=~~e[10]+t),d.apply(0,e),e),volume(e){l.zzfxV=e},canvas:()=>u,use(e,t={}){var a=e,l=t;let n=a(S,l);for(let e in n)S.def(e,n[e])},listen:(e,t)=>{D[e=e.toLowerCase()]=D[e]||new Set,D[e].add(t)},unlisten:(e,t)=>{D[e=e.toLowerCase()]&&D[e].delete(t)},emit(e,a,n,i,o){c&&(N("before:"+(e=e.toLowerCase()),a,n,i,o),t.loop||"function"!=typeof l[e]||l[e](a,n,i,o),N(e,a,n,i,o),N("after:"+e,a,n,i,o))},pal(t,a=3){C=t||e,I=[],k=a},palc(e,t){null==e?I=[]:I[e]=t},def(e,a){S[e]=a,t.global&&(l[e]=a)},timescale(e){w=e},framerate(e){x=1e3/~~e},stat:e=>[t,c,x/1e3,h,D,C,L,w,l.zzfxV,z,P,E,I,T][e],pause(){p=!0,cancelAnimationFrame(b)},resume(){c&&p&&(p=!1,y=x,v=i.now(),b=r(M))},paused:()=>p,quit(){for(let e of(S.emit("quit"),S.pause(),c=!1,D={},s))e();if(t.global){for(let e in S)delete l[e];delete l.ENGINE}}};for(let e of"PI,sin,cos,atan2,hypot,tan,abs,ceil,floor,trunc,min,max,pow,sqrt,sign,exp".split(","))S[e]=n[e];function A(){if(t.autoscale&&f(l,"resize",H),t.tapEvents){let e=e=>[(e.pageX-u.offsetLeft)/h,(e.pageY-u.offsetTop)/h],t=new Map,a=(e,a,l)=>{let n={x:a,y:l,xi:a,yi:l,t:i.now()};return t.set(e,n),n},n=(e,l,n)=>{let i=t.get(e)||a(e);i.x=l,i.y=n},o=e=>e&&i.now()-e.t<=300,r=!1;f(u,"mousedown",t=>{if(0===t.button){t.preventDefault();let[l,n]=e(t);S.emit("tap",l,n,0),a(0,l,n),r=!0}}),f(u,"mouseup",a=>{if(0===a.button){a.preventDefault();let l=t.get(0),[n,i]=e(a);o(l)&&S.emit("tapped",l.xi,l.yi,0),S.emit("untap",n,i,0),t.delete(0),r=!1}}),f(l,"mousemove",t=>{t.preventDefault();let[a,l]=e(t);S.def("MX",a),S.def("MY",l),r&&(S.emit("tapping",a,l,0),n(0,a,l))}),f(u,"touchstart",t=>{for(let l of(t.preventDefault(),t.changedTouches)){let[t,n]=e(l);S.emit("tap",t,n,l.identifier+1),a(l.identifier+1,t,n)}}),f(u,"touchmove",t=>{for(let a of(t.preventDefault(),t.changedTouches)){let[t,l]=e(a);S.emit("tapping",t,l,a.identifier+1),n(a.identifier+1,t,l)}});let s=e=>{e.preventDefault();let a=[];if(e.targetTouches.length>0)for(let t of e.targetTouches)a.push(t.identifier+1);for(let[e,l]of t)a.includes(e)||(o(l)&&S.emit("tapped",l.xi,l.yi,e),S.emit("untap",l.x,l.y,e),t.delete(e))};f(u,"touchend",s),f(u,"touchcancel",s),f(l,"blur",()=>{for(let[e,a]of(r=!1,t))S.emit("untap",a.x,a.y,e),t.delete(e)})}if(t.keyboardEvents){let e=new Set,t=new Set,a=(e,t="")=>(t=t.toLowerCase())?e.has("space"===t?" ":t):e.size>0,n="";f(l,"keydown",a=>{let l=a.key.toLowerCase();e.has(l)||(e.add(l),t.add(l),n=" "===l?"space":l)}),f(l,"keyup",t=>{e.delete(t.key.toLowerCase())}),f(l,"blur",()=>e.clear()),S.listen("after:update",()=>t.clear()),S.def("iskeydown",t=>a(e,t)),S.def("iskeypressed",e=>a(t,e)),S.def("lastkey",()=>n)}c=!0,S.resume(),S.emit("init",S)}function M(){b=r(M);let e=i.now(),t=0,a=e-v;for(v=e,y+=a<100?a:x;y>=x;){t++,y-=x;let e=x/1e3*w;S.emit("update",e,t),S.def("T",S.T+e)}t&&(S.emit("draw",g),t>1&&(y=0))}function H(){let e=t.width>0?t.width:innerWidth,a=t.width>0?t.height||t.width:innerHeight;if(S.def("W",e),S.def("H",a),u.width=e,u.height=a,t.autoscale){let l=+t.autoscale;u.style.display||(u.style.display="block",u.style.margin="auto"),h=n.min(innerWidth/e,innerHeight/a),h=l>1&&h>l?l:h,u.style.width=e*h+"px",u.style.height=a*h+"px"}g.imageSmoothingEnabled=!1,S.textalign("start","top"),S.emit("resized",h)}function N(e,t,a,l,n){if(D[e])for(let i of D[e])i(t,a,l,n)}function W(e){return C[~~(I[e]??e)%C.length]}if(t.global){if(l.ENGINE)throw Error("only one global litecanvas is allowed");Object.assign(l,S),l.ENGINE=S}if(g=(u=(u="string"==typeof t.canvas?document.querySelector(t.canvas):t.canvas)||document.createElement("canvas")).getContext("2d"),f(u,"click",()=>focus()),H(),u.parentNode||document.body.appendChild(u),u.style.imageRendering="pixelated",u.oncontextmenu=()=>!1,t.loop)for(let e in t.loop)t.loop[e]&&S.listen(e,t.loop[e]);return"loading"===document.readyState?f(l,"DOMContentLoaded",()=>r(A)):b=r(A),S}})();
+(()=>{var e=["#211e20","#555568","#a0a08b","#e9efec"];window.litecanvas=function(t={}){let l,a=window,n=Math,i=performance,o=2*n.PI,r=requestAnimationFrame,s=[],f=(e,t,l)=>{e.addEventListener(t,l,!1),s.push(()=>e.removeEventListener(t,l,!1))},d=(l=new AudioContext,a.zzfxV=1,(e=1,t=.05,n=220,i=0,o=0,r=.1,s=0,f=1,d=0,c=0,p=0,u=0,h=0,m=0,g=0,w=0,v=0,x=1,y=0,b=0,k=0)=>{let E=Math,P=2*E.PI,T=d*=500*P/44100/44100,z=n*=(1-t+2*t*E.random(t=[]))*P/44100,C=0,I=0,L=0,D=1,A=0,S=0,H=0,M=k<0?-1:1,N=P*M*k*2/44100,W=E.cos(N),B=E.sin,V=B(N)/4,q=1+V,O=-2*W/q,R=(1-V)/q,F=(1+M*W)/2/q,G=-(M+W)/q,X=0,Y=0,$=0,j=0;for(i=44100*i+9,y*=44100,o*=44100,r*=44100,v*=44100,c*=500*P/85766121e6,g*=P/44100,p*=P/44100,u*=44100,h=44100*h|0,e*=.3*a.zzfxV,M=i+y+o+r+v|0;L<M;t[L++]=H*e)++S%(100*w|0)||(H=s?1<s?2<s?3<s?B(C*C):E.max(E.min(E.tan(C),1),-1):1-(2*C/P%2+2)%2:1-4*E.abs(E.round(C/P)-C/P):B(C),H=(h?1-b+b*B(P*L/h):1)*(H<0?-1:1)*E.abs(H)**f*(L<i?L/i:L<i+y?1-(L-i)/y*(1-x):L<i+y+o?x:L<M-v?(M-L-v)/r*x:0),H=v?H/2+(v>L?0:(L<M-v?1:(M-L)/v)*t[L-v|0]/2/e):H,k&&(H=j=F*X+G*(X=Y)+F*(Y=H)-R*$-O*($=j))),C+=(N=(n+=d+=c)*E.cos(g*I++))+N*m*B(L**5),D&&++D>u&&(n+=p,z+=p,D=0),!h||++A%h||(n=z,d=T,D=D||1);(e=l.createBuffer(1,M,44100)).getChannelData(0).set(t),(n=l.createBufferSource()).buffer=e,n.connect(l.destination),n.start()});t=Object.assign({width:null,height:null,autoscale:!0,canvas:null,global:!0,loop:null,tapEvents:!0,keyboardEvents:!0},t);let c=!1,p=!0,u,h=1,m,g=.5,w=1,v,x=1e3/60,y,b,k=3,E="sans-serif",P=20,T=1.2,z=Date.now(),C=e,I=[],L=[.5,0,1750,,,.3,1,,,,600,.1],D={},A={W:0,H:0,T:0,MX:-1,MY:-1,TWO_PI:o,HALF_PI:o/4,lerp:(e,t,l)=>e+l*(t-e),deg2rad:e=>n.PI/180*e,rad2deg:e=>180/n.PI*e,round:(e,t=0)=>{if(!t)return n.round(e);let l=10**t;return n.round(e*l)/l},clamp:(e,t,l)=>e<t?t:e>l?l:e,dist:(e,t,l,a)=>n.hypot(l-e,a-t),wrap:(e,t,l)=>e-(l-t)*n.floor((e-t)/(l-t)),map(e,t,l,a,n,i){let o=(e-t)/(l-t)*(n-a)+a;return i?A.clamp(o,a,n):o},norm:(e,t,l)=>A.map(e,t,l,0,1),rand:(e=0,t=1)=>(z=(1664525*z+0x3c6ef35f)%0x100000000)/0x100000000*(t-e)+e,randi:(e=0,t=1)=>~~A.rand(e,t+1),rseed(e){z=~~e},cls(e){null==e?m.clearRect(0,0,A.W,A.H):A.rectfill(0,0,A.W,A.H,e)},rect(e,t,l,a,n,i){m.beginPath(),m[i?"roundRect":"rect"](~~e-g,~~t-g,~~l+2*g,~~a+2*g,i),A.stroke(n)},rectfill(e,t,l,a,n,i){m.beginPath(),m[i?"roundRect":"rect"](~~e,~~t,~~l,~~a,i),A.fill(n)},circ(e,t,l,a){m.beginPath(),m.arc(~~e,~~t,~~l,0,o),A.stroke(a)},circfill(e,t,l,a){m.beginPath(),m.arc(~~e,~~t,~~l,0,o),A.fill(a)},oval(e,t,l,a,n){m.beginPath(),m.ellipse(~~e,~~t,~~l,~~a,0,0,o),A.stroke(n)},ovalfill(e,t,l,a,n){m.beginPath(),m.ellipse(~~e,~~t,~~l,~~a,0,0,o),A.fill(n)},shape(e){m.beginPath();for(let t=0;t<e.length;t+=2)0===t?m.moveTo(~~e[t],~~e[t+1]):m.lineTo(~~e[t],~~e[t+1]);m.lineTo(~~e[0],~~e[1])},line(e,t,l,a,n){m.beginPath();let i=.5*(0!==g&&~~e==~~l),o=.5*(0!==g&&~~t==~~a);m.moveTo(~~e+i,~~t+o),m.lineTo(~~l+i,~~a+o),A.stroke(n)},linewidth(e){m.lineWidth=~~e,g=.5*(0!=~~e%2)},linedash(e,t=0){m.setLineDash(e),m.lineDashOffset=t},text(e,t,l,a=k,n="normal"){m.font=`${n} ${P}px ${E}`,m.fillStyle=N(a);let i=(""+l).split("\n");for(let l=0;l<i.length;l++)m.fillText(i[l],~~e,~~t+P*T*l)},textgap(e){T=e},textfont(e){E=e},textsize(e){P=e},textalign(e,t){e&&(m.textAlign=e),t&&(m.textBaseline=t)},image(e,t,l){m.drawImage(l,~~e,~~t)},spr(e,t,l){let a=l.trim().split("\n");for(let l=0;l<a.length;l++){let n=a[l].trim();for(let a=0;a<n.length;a++){let i=n[a];"."!==i&&" "!==i&&A.rectfill(e+a,t+l,1,1,parseInt(i,36)||0)}}},paint(e,t,l,a={}){let n=a.canvas||new OffscreenCanvas(1,1),i=a.scale||1,o=m;return n.width=e*i,n.height=t*i,(m=n.getContext("2d")).scale(i,i),l(m),m=o,n.transferToImageBitmap()},ctx:e=>(e&&(m=e),m),push(){m.save()},pop(){m.restore()},translate(e,t){m.translate(~~e,~~t)},scale(e,t=e){m.scale(e,t)},rotate(e){m.rotate(e)},alpha(e){m.globalAlpha=A.clamp(e,0,1)},fill(e){m.fillStyle=N(e),m.fill()},stroke(e){m.strokeStyle=N(e),m.stroke()},clip(e){m.beginPath(),e(m),m.clip()},sfx:(e,t=0,l=1)=>!!a.zzfxV&&(!navigator.userActivation||!!navigator.userActivation.hasBeenActive)&&(e=e||L,(0!==t||1!==l)&&((e=e.slice())[0]=l*(e[0]||1),e[10]=~~e[10]+t),d.apply(0,e),e),volume(e){a.zzfxV=e},canvas:()=>u,use(e,t={}){var l=e,a=t;let n=l(A,a);for(let e in n)A.def(e,n[e])},listen:(e,t)=>{D[e=e.toLowerCase()]=D[e]||new Set,D[e].add(t)},unlisten:(e,t)=>{D[e=e.toLowerCase()]&&D[e].delete(t)},emit:(e,l,n,i,o)=>(c&&(M("before:"+(e=e.toLowerCase()),l,n,i,o),t.loop||"function"!=typeof a[e]||a[e](l,n,i,o),M(e,l,n,i,o),M("after:"+e,l,n,i,o)),l),pal(t,l=3){C=t||e,I=[],k=l},palc(e,t){null==e?I=[]:I[e]=t},def(e,l){A[e]=l,t.global&&(a[e]=l)},timescale(e){w=e},framerate(e){x=1e3/~~e},stat:e=>[t,c,x/1e3,h,D,C,L,w,a.zzfxV,z,P,E,I,T][e],pause(){p||(p=!0,cancelAnimationFrame(b),A.emit("paused"))},resume(){c&&p&&(p=!1,y=x,v=i.now(),b=r(S),A.emit("resumed"))},ispaused:()=>p,quit(){for(let e of(A.emit("shutdown"),A.pause(),c=!1,D={},s))e();if(t.global){for(let e in A)delete a[e];delete a.ENGINE}}};for(let e of"PI,sin,cos,atan2,hypot,tan,abs,ceil,floor,trunc,min,max,pow,sqrt,sign,exp".split(","))A[e]=n[e];function S(){b=r(S);let e=i.now(),t=0,l=e-v;for(v=e,y+=l<100?l:x;y>=x;){t++,y-=x;let e=x/1e3*w;A.emit("update",e,t),A.def("T",A.T+e)}t&&(A.emit("draw",m),t>1&&(y=0))}function H(){let e=t.width>0?t.width:innerWidth,l=t.width>0?t.height||t.width:innerHeight;if(A.def("W",e),A.def("H",l),u.width=e,u.height=l,t.autoscale){let a=+t.autoscale;u.style.display||(u.style.display="block",u.style.margin="auto"),h=n.min(innerWidth/e,innerHeight/l),h=a>1&&h>a?a:h,u.style.width=e*h+"px",u.style.height=l*h+"px"}m.imageSmoothingEnabled=!1,A.textalign("start","top"),A.emit("resized",h)}function M(e,t,l,a,n){if(D[e])for(let i of D[e])i(t,l,a,n)}function N(e){return C[~~(I[e]??e)%C.length]}if(t.global){if(a.ENGINE)throw Error("only one global litecanvas is allowed");Object.assign(a,A),a.ENGINE=A}if(m=(u=(u="string"==typeof t.canvas?document.querySelector(t.canvas):t.canvas)||document.createElement("canvas")).getContext("2d"),f(u,"click",()=>focus()),H(),u.parentNode||document.body.appendChild(u),u.style.imageRendering="pixelated",u.oncontextmenu=()=>!1,t.loop)for(let e in t.loop)t.loop[e]&&A.listen(e,t.loop[e]);return b=r(function(){if(t.autoscale&&f(a,"resize",H),t.tapEvents){let e=e=>[(e.pageX-u.offsetLeft)/h,(e.pageY-u.offsetTop)/h],t=new Map,l=(e,l,a)=>{let n={x:l,y:a,xi:l,yi:a,t:i.now()};return t.set(e,n),n},n=(e,a,n)=>{let i=t.get(e)||l(e);i.x=a,i.y=n},o=e=>e&&i.now()-e.t<=300,r=!1;f(u,"mousedown",t=>{if(0===t.button){t.preventDefault();let[a,n]=e(t);A.emit("tap",a,n,0),l(0,a,n),r=!0}}),f(u,"mouseup",l=>{if(0===l.button){l.preventDefault();let a=t.get(0),[n,i]=e(l);o(a)&&A.emit("tapped",a.xi,a.yi,0),A.emit("untap",n,i,0),t.delete(0),r=!1}}),f(a,"mousemove",t=>{t.preventDefault();let[l,a]=e(t);A.def("MX",l),A.def("MY",a),r&&(A.emit("tapping",l,a,0),n(0,l,a))}),f(u,"touchstart",t=>{for(let a of(t.preventDefault(),t.changedTouches)){let[t,n]=e(a);A.emit("tap",t,n,a.identifier+1),l(a.identifier+1,t,n)}}),f(u,"touchmove",t=>{for(let l of(t.preventDefault(),t.changedTouches)){let[t,a]=e(l);A.emit("tapping",t,a,l.identifier+1),n(l.identifier+1,t,a)}});let s=e=>{e.preventDefault();let l=[];if(e.targetTouches.length>0)for(let t of e.targetTouches)l.push(t.identifier+1);for(let[e,a]of t)l.includes(e)||(o(a)&&A.emit("tapped",a.xi,a.yi,e),A.emit("untap",a.x,a.y,e),t.delete(e))};f(u,"touchend",s),f(u,"touchcancel",s),f(a,"blur",()=>{for(let[e,l]of(r=!1,t))A.emit("untap",l.x,l.y,e),t.delete(e)})}if(t.keyboardEvents){let e=new Set,t=new Set,l=(e,t="")=>(t=t.toLowerCase())?e.has("space"===t?" ":t):e.size>0,n="";f(a,"keydown",l=>{let a=l.key.toLowerCase();e.has(a)||(e.add(a),t.add(a),n=" "===a?"space":a)}),f(a,"keyup",t=>{e.delete(t.key.toLowerCase())}),f(a,"blur",()=>e.clear()),A.listen("after:update",()=>t.clear()),A.def("iskeydown",t=>l(e,t)),A.def("iskeypressed",e=>l(t,e)),A.def("lastkey",()=>n)}c=!0,A.resume(),A.emit("init",A)}),A}})();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "litecanvas",
-    "version": "0.202.0",
+    "version": "0.204.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>",
@@ -32,16 +32,16 @@
         "creative coding"
     ],
     "devDependencies": {
-        "@happy-dom/global-registrator": "^20.8.4",
-        "@size-limit/preset-small-lib": "^12.0.1",
-        "@swc/core": "^1.15.18",
+        "@happy-dom/global-registrator": "^20.9.0",
+        "@size-limit/preset-small-lib": "^12.1.0",
+        "@swc/core": "^1.15.26",
         "ava": "^7.0.0",
-        "esbuild": "^0.27.4",
+        "esbuild": "^0.27.7",
         "genversion": "^3.2.0",
         "gzip-size": "^7.0.0",
-        "prettier": "^3.8.1",
-        "sinon": "^21.0.2",
-        "size-limit": "^12.0.1",
+        "prettier": "^3.8.3",
+        "sinon": "^21.1.2",
+        "size-limit": "^12.1.0",
         "tap-min": "^3.0.0"
     },
     "trustedDependencies": [

package/src/index.js

@@ -86,7 +86,7 @@ export default function litecanvas(settings = {}) {
         _colorPaletteState = [],
         /** @type {number[]} */
         _defaultSound = [0.5, 0, 1750, , , 0.3, 1, , , , 600, 0.1],
-        /** @type {string} list of functions copied from `Math` module*/
+        /** @type {string} list of functions copied from `Math` module */
         _mathFunctions =
             'PI,sin,cos,atan2,hypot,tan,abs,ceil,floor,trunc,min,max,pow,sqrt,sign,exp',
         /**
@@ -155,7 +155,7 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the value in radians
          */
         deg2rad: (degs) => {
-            DEV: assert(isNumber(degs), 'deg2rad: 1st param must be a number')
+            DEV: assert(isNumber(degs), 'deg2rad() 1st param must be a number')
 
             return (math.PI / 180) * degs
         },
@@ -167,7 +167,7 @@ export default function litecanvas(settings = {}) {
          * @returns {number} the value in degrees
          */
         rad2deg: (rads) => {
-            DEV: assert(isNumber(rads), 'rad2deg: 1st param must be a number')
+            DEV: assert(isNumber(rads), 'rad2deg() 1st param must be a number')
 
             return (180 / math.PI) * rads
         },
@@ -706,9 +706,10 @@ export default function litecanvas(settings = {}) {
          *
          * Default = `1.2`
          *
-         * @param value
+         * @param {number} value
          */
         textgap(value) {
+            DEV: assert(isNumber(value), loggerPrefix + 'textgap() 1st param must be a number')
             _fontLineHeight = value
         },
 
@@ -833,8 +834,9 @@ export default function litecanvas(settings = {}) {
                 loggerPrefix + 'paint() 3rd param must be a function'
             )
             DEV: assert(
-                (options && null == options.scale) || isNumber(options.scale),
-                loggerPrefix + 'paint() 4th param (options.scale) must be a number'
+                (options && null == options.scale) ||
+                    (isNumber(options.scale) && options.scale > 0),
+                loggerPrefix + 'paint() 4th param (options.scale) must be a positive number'
             )
             DEV: assert(
                 (options && null == options.canvas) || options.canvas instanceof OffscreenCanvas,
@@ -867,6 +869,13 @@ export default function litecanvas(settings = {}) {
          * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D
          */
         ctx(context) {
+            DEV: assert(
+                null == context ||
+                    context instanceof CanvasRenderingContext2D ||
+                    context instanceof OffscreenCanvasRenderingContext2D,
+                loggerPrefix + 'ctx() 1st param must be an [Offscreen]CanvasRenderingContext2D'
+            )
+
             if (context) {
                 _ctx = context
             }
@@ -910,14 +919,11 @@ export default function litecanvas(settings = {}) {
          * @param {number} x
          * @param {number} [y]
          */
-        scale(x, y) {
+        scale(x, y = x) {
             DEV: assert(isNumber(x), loggerPrefix + 'scale() 1st param must be a number')
-            DEV: assert(
-                null == y || isNumber(y),
-                loggerPrefix + 'scale() 2nd param must be a number'
-            )
+            DEV: assert(isNumber(y), loggerPrefix + 'scale() 2nd param must be a number')
 
-            _ctx.scale(x, y || x)
+            _ctx.scale(x, y)
         },
 
         /**
@@ -982,7 +988,7 @@ export default function litecanvas(settings = {}) {
         clip(callback) {
             DEV: assert(
                 'function' === typeof callback,
-                loggerPrefix + 'clip() 1st param must be a function'
+                loggerPrefix + 'clip() 1st param must be a function (ctx) => void'
             )
 
             beginPath(_ctx)
@@ -1055,14 +1061,15 @@ export default function litecanvas(settings = {}) {
         canvas: () => _canvas,
 
         /**
-         * Prepares a plugin to be loaded
+         * Loads a Litecanvas plugin
          *
          * @param {pluginCallback} callback
+         * @param {object} [config]
          */
         use(callback, config = {}) {
             DEV: assert(
                 'function' === typeof callback,
-                loggerPrefix + 'use() 1st param must be a function'
+                loggerPrefix + 'use() 1st param must be a function (instance, config) => any'
             )
             DEV: assert(
                 'object' === typeof config,
@@ -1129,6 +1136,7 @@ export default function litecanvas(settings = {}) {
          * @param {any} [arg2] any data to be passed over the listeners
          * @param {any} [arg3] any data to be passed over the listeners
          * @param {any} [arg4] any data to be passed over the listeners
+         * @returns {any} always returns the second argument
          */
         emit(eventName, arg1, arg2, arg3, arg4) {
             DEV: assert(
@@ -1148,6 +1156,8 @@ export default function litecanvas(settings = {}) {
 
                 triggerEvent('after:' + eventName, arg1, arg2, arg3, arg4)
             }
+
+            return arg1
         },
 
         /**
@@ -1202,7 +1212,7 @@ export default function litecanvas(settings = {}) {
          * Define or update a instance property.
          *
          * Note: when the `litecanvas()` option "global" is `true` (default),
-         * `def()` with set/update a global property.
+         * `def()` with set/update a window property.
          *
          * E.g: `def('ONE', 1)` do `window.ONE = 1`.
          *
@@ -1266,30 +1276,43 @@ export default function litecanvas(settings = {}) {
             const internals = [
                 // 0
                 settings,
+
                 // 1
                 _initialized,
+
                 // 2
                 _fpsInterval / 1000,
+
                 // 3
                 _canvasScale,
+
                 // 4
                 _eventListeners,
+
                 // 5
                 _colorPalette,
+
                 // 6
                 _defaultSound,
+
                 // 7
                 _timeScale,
+
                 // 8
                 root.zzfxV,
+
                 // 9
                 _rngSeed,
+
                 // 10
                 _fontSize,
+
                 // 11
                 _fontFamily,
+
                 // 12
                 _colorPaletteState,
+
                 // 13
                 _fontLineHeight,
             ]
@@ -1308,8 +1331,11 @@ export default function litecanvas(settings = {}) {
          * Pauses the engine loop (update & draw).
          */
         pause() {
-            _paused = true
-            cancelAnimationFrame(_rafid)
+            if (!_paused) {
+                _paused = true
+                cancelAnimationFrame(_rafid)
+                instance.emit('paused')
+            }
         },
 
         /**
@@ -1326,6 +1352,7 @@ export default function litecanvas(settings = {}) {
                 _accumulated = _fpsInterval
                 _lastFrameTime = perf.now()
                 _rafid = raf(drawFrame)
+                instance.emit('resumed')
             }
         },
 
@@ -1334,7 +1361,7 @@ export default function litecanvas(settings = {}) {
          *
          * @returns {boolean}
          */
-        paused() {
+        ispaused() {
             return _paused
         },
 
@@ -1342,8 +1369,8 @@ export default function litecanvas(settings = {}) {
          * Shutdown the litecanvas instance and remove all event listeners.
          */
         quit() {
-            // emit "quit" event to manual clean ups
-            instance.emit('quit')
+            // emit "shutdown" event to manual clean ups
+            instance.emit('shutdown')
 
             // stop the game loop (update & draw)
             instance.pause()
@@ -1826,11 +1853,7 @@ export default function litecanvas(settings = {}) {
     }
 
     // init the engine (async)
-    if ('loading' === document.readyState) {
-        on(root, 'DOMContentLoaded', () => raf(init))
-    } else {
-        _rafid = raf(init)
-    }
+    _rafid = raf(init)
 
     return instance
 }

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.202.0'
+export const version = '0.204.0'

package/types/global.d.ts

@@ -541,11 +541,12 @@ declare global {
      */
     function canvas(): HTMLCanvasElement
     /**
-     * Prepares a plugin to be loaded
+     * Loads a plugin
      *
      * @param callback
+     * @param config
      */
-    function use(callback: pluginCallback): void
+    function use(callback: pluginCallback, config: object): void
     /**
      * Add a game loop event listener.
      *
@@ -572,8 +573,9 @@ declare global {
      * @param [arg2] any data to be passed over the listeners
      * @param [arg3] any data to be passed over the listeners
      * @param [arg4] any data to be passed over the listeners
+     * @returns always returns the second argument
      */
-    function emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): void
+    function emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): any
     /**
      * Set new palette colors or restore the default palette.
      *
@@ -596,7 +598,7 @@ declare global {
      * Define or update a instance property.
      *
      * Note: when the `litecanvas()` option "global" is `true` (default),
-     * `def()` with set/update a global property.
+     * `def()` with set/update a window property.
      * E.g: `def('ONE', 1)` also do `window.ONE = 1`.
      *
      * @param key the property name
@@ -649,7 +651,7 @@ declare global {
     /**
      * Returns `true` if the engine loop is paused.
      */
-    function paused(): boolean
+    function ispaused(): boolean
     /**
      * Shutdown the litecanvas instance and remove all event listeners.
      */

package/types/types.d.ts

@@ -525,11 +525,12 @@ type LitecanvasInstance = {
      */
     canvas(): HTMLCanvasElement
     /**
-     * Prepares a plugin to be loaded
+     * Loads a plugin
      *
      * @param callback
+     * @param config
      */
-    use(callback: pluginCallback): void
+    use(callback: pluginCallback, config: object): void
     /**
      * Add a game loop event listener.
      *
@@ -556,13 +557,14 @@ type LitecanvasInstance = {
      * @param [arg2] any data to be passed over the listeners
      * @param [arg3] any data to be passed over the listeners
      * @param [arg4] any data to be passed over the listeners
+     * @returns always returns the second argument
      */
-    emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): void
+    emit(event: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any): any
     /**
      * Define or update a instance property.
      *
      * Note: when the `litecanvas()` option "global" is `true` (default),
-     * `def()` with set/update a global property.
+     * `def()` with set/update a window property.
      * E.g: `def('ONE', 1)` also do `window.ONE = 1`.
      *
      * @param key the property name
@@ -633,7 +635,7 @@ type LitecanvasInstance = {
     /**
      * Returns `true` if the engine loop is paused.
      */
-    paused(): boolean
+    ispaused(): boolean
     /**
      * Shutdown the litecanvas instance and remove all event listeners.
      */
@@ -703,7 +705,7 @@ type LitecanvasGameLoop = {
 
 type drawCallback = (context: OffscreenCanvasRenderingContext2D) => void
 
-type pluginCallback = (instance: LitecanvasInstance, config?: any) => any
+type pluginCallback = (instance: LitecanvasInstance, config?: object) => any
 
 type clipCallback = (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void