like2d 2.8.0 → 2.9.0

package/README.md

@@ -1,6 +1,6 @@
 # LÏKE2D
 
-<svg width="300mm" height="105mm" version="1.1" viewBox="0 0 300 105" xmlns="http://www.w3.org/2000/svg">
+<svg version="1.1" viewBox="0 0 300 105" xmlns="http://www.w3.org/2000/svg">
  <rect x="10" y="11.23" width="280" height="83.544" fill="#e48080" stroke="#000" stroke-linejoin="round" stroke-width="2"/>
  <g fill="none" stroke="#000" stroke-linejoin="round">
   <rect x="97.484" y="11.23" width="52.516" height="46.237"/>
@@ -31,37 +31,44 @@
  </g>
 </svg>
 
-A web-native 2D game framework inspired by [LÖVE](https://love2d.org/), built for simplicity and the modern web.
+Lightweight Web framework inspired by [LÖVE](https://love2d.org/).
 
+## <div style="color:red">During v2.x.x, LIKE's API will change.</div>
 ## What it is
 
-LIKE is a **curated toolkit** around browser APIs.
+LIKE is a cozy way to make 2d games for browser.
 
-It does less, because it **does the right thing**. And when that's not the right thing for you, we hand you the wrench.
+## What LIKE does
 
-- **Stateless Graphics:** Forget to reset native Canvas state (like LineCap) between calls and things break mysteriously. We make drawing explicit: what you see is what you set.
-
-- **Fire-and-forget Assets:** Async asset loading directly on realtime web games is annoying. We let you pretend it's instant and synchronous.
-
-- **Physical Joypad:** Our gamepad module auto-maps to physical buttons like "bottom" and "top". Because A isn't always in the same spot.
-
-- **Actions System:** Of course you can use device input callbacks just like love2d -- but you can also map inputs to actions and get callbacks on that.
-
-- **Scaling Modes:** Pixel art games need pixel-perfect scaling. So we do that: integer nearest -> linear. Or not; turn off pixelart mode to have a canvas that stays at native resolution.
-
-- **Sane Architecture:** Everything is built around a centralized event handler for browser-native events. We won't reinvent the wheel.
+- **🔥 Fire-and-forget Assets:** Graphics and audio that pretend to be synchronous.
+- **🎯 DWIM graphics:** Turns repetitive draw calls into one while removing state bleed for properties like `lineCap`.
+- **↔️ Two Canvas Modes:**
+   - 🖊️ Audio-resize the canvas; sharp at any resolution.
+   - 👾 For retro-style developers, pixels stay crisp but smooth via prescaling.
+- **⭕ Easier Geometry:** `Vector2` and `Rect` are just number tuples (arrays), but a pure-functional library makes them easy to work with and plays nice with `map` and `reduce`. 
+- **🚲 Easy Input:** Keyboard, Mouse, and Gamepad all are given both event-based and tracking-based options. Choose what fits your architecture.
+- **👟 Consistent APIs:** Colors 0-1, not 0-255. Seconds, not milliseconds.
+- **👉 Actions System:** An input layer maps inputs to actions, which fire usable events.
+- **🌎 Global control:** Choose how to handle LIKE events, and manage resources with centralized trackers. LIKE is a great foundation for your own engine.
+- **🐦 Light and Elegant:** Zero dependencies and less than 5000 lines of code -- focused entirely on what matters.
 
 ## Installation
 
+Most package managers will work.
 ```bash
 npm install like2d
-# or
-pnpm add like2d
+# or ...
+deno add jsr:@like2d/like
+# or...
 ```
 
 ## Quick Start
 
-[Like2D Starter Template](https://github.com/44100hertz/Like2D-starter)
+To try Like2D quickly, use this starter with
+hot reloading and a basic webpage.
+```bash
+npx degit 44100hertz/Like2D/examples/starter my-game
+```
 
 ## Usage Example
 
@@ -71,8 +78,8 @@ import { createLike } from 'like2d';
 const like = createLike(document.body);
 
 like.load = () => {
-  like.setMode({ pixelResolution: [800, 600] });
-  like.input.map('jump', ['Space', 'ButtonBottom']);
+  like.setMode([800, 600]);
+  like.input.setAction('jump', ['Space', 'ButtonBottom']);
 };
 
 like.update = (dt) => {
@@ -93,27 +100,19 @@ await like.start();
 ## For Love2D Developers
 
 LIKE's API is not the same as LOVE, but similar in spirit. Notable differences:
- - Graphics have less state, there is no setColor getColor etc.
- - Our APIs are, in general, a bit different. You'll have to learn some.
- - You manage your own state; like is not global, but you can share it around for similar results. This allows multiple LIKE instances per webpage.
- - We use Vector2 and Rect tuples (as in `[number, number]`) instead of loose coordinates.
- - Theres an actions system -- `input.map` / `actionpressed` and `actionreleased` callbacks.
+ - Draw your graphics in one call, that's all. No setup or state bleed.
+ - You manage your own instance of like in a big friendly object. This allows us to have multiple games on one page.
+ - We use Vector2 and Rect tuples (like `[x, y]`) instead of loose coordinates.
+ - Theres an actions system -- `input.setAction` / `actionpressed` and `actionreleased` callbacks.
  - Some things are missing either due to browser limitations or smaller scope.
 
 ## Feedback welcome
 
-Before you report a bug:
- 1. Make sure you're on the latest release.
- 2. If the issue exists already, just comment on that one.
- 3. See if it happens in other web browsers.
+[LIKE is on GitHub.](https://github.com/44100hertz/Like2D)
 
-Before you request a feature:
- 1. ask: Would it make sense as a core feature, or should it be an external library?
- 2. See if the feature exists already.
- 3. Think about the demand for it overall. Make your case why game developers want it.
- 4. Consider just making a PR yourself, or sending a prompt/spec that an AI can hack on.
+[Check out the docs for our long-term vision.](https://github.com/44100hertz/Like2D/tree/master/docs)
 
-[Then, put your feedback on GitHub.](https://github.com/44100hertz/Like2D/issues)
+[Feature requests welcome. PRs discouraged for now.](https://github.com/44100hertz/Like2D/issues/)
 
 ## License
 

package/dist/core/audio.d.ts

@@ -7,26 +7,26 @@
  * Start, stop, or set global volume for every currently playing sound.
  *
  */
-export type SourceOptions = {
+export type AudioSourceOptions = {
     volume?: number;
 };
 /**
- * Handle to a loaded audio resource.
+ * Handle to a loaded audio resource, which pretends to be synchronous.
  * Use `play()`, `stop()`, `pause()`, `resume()` for playback control.
  * Access the underlying HTMLAudioElement via `source.audio` for looping,
  * pitch, etc. Note: Use `source.setVolume()` instead of setting
  * `source.audio.volume` directly to ensure global volume scaling works correctly.
  */
-export declare class Source {
+export declare class AudioSource {
     readonly path: string;
     /** Underlying HTMLAudioElement. Modify directly for looping, pitch, etc. Use methods for playback control. Avoid setting volume directly. */
     readonly audio: HTMLAudioElement;
-    readonly options: Required<SourceOptions>;
+    readonly options: Required<AudioSourceOptions>;
     /** Resolves when the audio is loaded and ready to play. */
     readonly ready: Promise<void>;
     private loadState;
     private audioRef;
-    constructor(path: string, audioRef: Audio, options?: SourceOptions);
+    constructor(path: string, audioRef: AudioInternal, options?: AudioSourceOptions);
     isReady(): boolean;
     play(): void;
     stop(): void;
@@ -42,20 +42,23 @@ export declare class Source {
     getVolume(): number;
     getDuration(): number;
 }
-export declare class Audio {
+export declare class AudioInternal {
     private sources;
     private globalVolume;
-    newSource(path: string, options?: SourceOptions): Source;
+    /**
+     * Get a {@link AudioSource}
+     */
+    newSource(path: string, options?: AudioSourceOptions): AudioSource;
     /** Get all audio sources -- note that sources are tracked
       * using weak references, and storing this list can cause
       * a memory leak.
       */
-    private getAllSources;
+    getAllSources(): AudioSource[];
     stopAll(): void;
     pauseAll(): void;
     resumeAll(): void;
     setVolume(volume: number): void;
     getVolume(): number;
-    clone(source: Source): Source;
+    clone(source: AudioSource): AudioSource;
 }
 //# sourceMappingURL=audio.d.ts.map

package/dist/core/audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/core/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAA;AAMD;;;;;;GAMG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6IAA6I;IAC7I,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,SAAS,CAAoE;IACrF,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAE,aAAkB;IAmCtE,OAAO,IAAI,OAAO;IAIlB,IAAI,IAAI,IAAI;IAUZ,IAAI,IAAI,IAAI;IAUZ,KAAK,IAAI,IAAI;IAQb,MAAM,IAAI,IAAI;IAYd,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ5B,IAAI,IAAI,MAAM;IAKd,SAAS,IAAI,OAAO;IAKpB,QAAQ,IAAI,OAAO;IAKnB,SAAS,IAAI,OAAO;IAKpB,+FAA+F;IAC/F,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/B,SAAS,IAAI,MAAM;IAInB,WAAW,IAAI,MAAM;CAItB;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,YAAY,CAAK;IAEzB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAMxD;;;QAGI;IACJ,OAAO,CAAC,aAAa;IASrB,OAAO,IAAI,IAAI;IAIf,QAAQ,IAAI,IAAI;IAIhB,SAAS,IAAI,IAAI;IAIjB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO/B,SAAS,IAAI,MAAM;IAInB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAG9B"}
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/core/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAA;AAMD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6IAA6I;IAC7I,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAC/C,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,SAAS,CAAoE;IACrF,OAAO,CAAC,QAAQ,CAAgB;gBAEpB,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB;IAmCnF,OAAO,IAAI,OAAO;IAIlB,IAAI,IAAI,IAAI;IAUZ,IAAI,IAAI,IAAI;IAUZ,KAAK,IAAI,IAAI;IAQb,MAAM,IAAI,IAAI;IAYd,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ5B,IAAI,IAAI,MAAM;IAKd,SAAS,IAAI,OAAO;IAKpB,QAAQ,IAAI,OAAO;IAKnB,SAAS,IAAI,OAAO;IAKpB,+FAA+F;IAC/F,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/B,SAAS,IAAI,MAAM;IAInB,WAAW,IAAI,MAAM;CAItB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,YAAY,CAAK;IAEzB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAMlE;;;QAGI;IACJ,aAAa,IAAI,WAAW,EAAE;IAS9B,OAAO,IAAI,IAAI;IAIf,QAAQ,IAAI,IAAI;IAIhB,SAAS,IAAI,IAAI;IAIjB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO/B,SAAS,IAAI,MAAM;IAInB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW;CAGxC"}

package/dist/core/audio.js

@@ -8,13 +8,13 @@
  *
  */
 /**
- * Handle to a loaded audio resource.
+ * Handle to a loaded audio resource, which pretends to be synchronous.
  * Use `play()`, `stop()`, `pause()`, `resume()` for playback control.
  * Access the underlying HTMLAudioElement via `source.audio` for looping,
  * pitch, etc. Note: Use `source.setVolume()` instead of setting
  * `source.audio.volume` directly to ensure global volume scaling works correctly.
  */
-export class Source {
+export class AudioSource {
     constructor(path, audioRef, options = {}) {
         Object.defineProperty(this, "path", {
             enumerable: true,
@@ -169,7 +169,7 @@ export class Source {
         return 0;
     }
 }
-export class Audio {
+export class AudioInternal {
     constructor() {
         Object.defineProperty(this, "sources", {
             enumerable: true,
@@ -184,8 +184,11 @@ export class Audio {
             value: 1
         });
     }
+    /**
+     * Get a {@link AudioSource}
+     */
     newSource(path, options) {
-        const source = new Source(path, this, options);
+        const source = new AudioSource(path, this, options);
         this.sources.push(new WeakRef(source));
         return source;
     }

package/dist/core/canvas.d.ts

@@ -0,0 +1,58 @@
+import { EngineDispatch } from "../engine";
+import { Rectangle } from "../math/rect";
+import { type Vector2 } from "../math/vector2";
+export type CanvasModeOptions = {
+    fullscreen: boolean;
+};
+export type CanvasSize = Vector2 | 'native';
+export declare class CanvasInternal {
+    dispatch: EngineDispatch;
+    /** The ultimately visible canvas in the browser */
+    _displayCanvas: HTMLCanvasElement;
+    /** The canvas that we're drawing to with `like.gfx` functions.
+     * If it's the same as _displayCanvas, we're in native mode.
+     * Otherwise, we're in pixelart mode, consisting of nearest -> linear scaling.
+    */
+    _renderCanvas: HTMLCanvasElement;
+    private resizeTimeoutId;
+    private abort;
+    constructor(dispatch: EngineDispatch);
+    /** Get a unified canvas info object. */
+    getMode(): {
+        size: Vector2;
+        flags: CanvasModeOptions;
+    };
+    /** Set the game's apparent resolution, fullscreen, etc.
+     *
+     * ### `'native'` mode
+     * Keeps the canvas pixel resolution
+     * the same as the physical pixel resolution of the
+     * device.
+     *
+     * ### Pixel art mode `[width, height]`
+     * The canvas will use prescaling to keep your pixel
+     * games looking sharp, but without the uneven pixels
+     * caused by the naive approach.
+     *
+     * @param size 'native' for native mode, otherwise [width, height]
+     * @param flags optional options.
+     */
+    setMode(size: CanvasSize, flags?: Partial<CanvasModeOptions>): void;
+    /** Get the apparent (in-game) canvas size. */
+    getSize(): Vector2;
+    /** Sometimes you want a screen rect! */
+    getRect(): Rectangle;
+    /** Get the actual (physical) canvas size on screen. */
+    _getDisplayPixelSize(): Vector2;
+    /** Are we fullscreen? */
+    getFullscreen(): boolean;
+    /** Set fullscreen. */
+    setFullscreen(fullscreen: boolean): void;
+    /** Called every frame by the engine after drawing */
+    _present(): void;
+    /** @returns if size was changed.  */
+    static setCanvasElemSize(canvas: HTMLCanvasElement, newSize: Vector2): boolean;
+    static getCanvasElemSize(canvas: HTMLCanvasElement): Vector2;
+    _dispose(): void;
+}
+//# sourceMappingURL=canvas.d.ts.map

package/dist/core/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/core/canvas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAQ,SAAS,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE5C,qBAAa,cAAc;IAYJ,QAAQ,EAAE,cAAc;IAX3C,mDAAmD;IAC5C,cAAc,EAAE,iBAAiB,CAAC;IACzC;;;MAGE;IACK,aAAa,EAAE,iBAAiB,CAAC;IAExC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,KAAK,CAAyB;gBAEnB,QAAQ,EAAE,cAAc;IA0D3C,wCAAwC;IACxC,OAAO,IAAI;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,iBAAiB,CAAA;KAAE;IAStD;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,GAAE,OAAO,CAAC,iBAAiB,CAAM;IA2BhE,8CAA8C;IAC9C,OAAO,IAAI,OAAO;IAIlB,wCAAwC;IACxC,OAAO,IAAI,SAAS;IAIpB,uDAAuD;IACvD,oBAAoB,IAAI,OAAO;IAO/B,yBAAyB;IACzB,aAAa,IAAI,OAAO;IAIxB,sBAAsB;IACtB,aAAa,CAAC,UAAU,EAAE,OAAO;IASjC,qDAAqD;IACrD,QAAQ;IAyCR,qCAAqC;IACrC,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAO9E,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO;IAI5D,QAAQ,IAAI,IAAI;CAGnB"}

package/dist/core/canvas.js

@@ -0,0 +1,209 @@
+import { Rect } from "../math/rect";
+import { Vec2 } from "../math/vector2";
+export class CanvasInternal {
+    constructor(dispatch) {
+        Object.defineProperty(this, "dispatch", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: dispatch
+        });
+        /** The ultimately visible canvas in the browser */
+        Object.defineProperty(this, "_displayCanvas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The canvas that we're drawing to with `like.gfx` functions.
+         * If it's the same as _displayCanvas, we're in native mode.
+         * Otherwise, we're in pixelart mode, consisting of nearest -> linear scaling.
+        */
+        Object.defineProperty(this, "_renderCanvas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "resizeTimeoutId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "abort", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new AbortController()
+        });
+        this._displayCanvas = document.createElement('canvas');
+        this._displayCanvas.tabIndex = 0;
+        this._displayCanvas.style.width = '100%';
+        this._displayCanvas.style.height = '100%';
+        this._renderCanvas = this._displayCanvas;
+        this.setMode('native');
+        /** Only the canvas can really transform the mouse to the game size.
+         * This hack sends an event for the mouse module to listen to.
+         */
+        this._displayCanvas.addEventListener('mousemove', (ev) => {
+            let pos;
+            let delta;
+            const rawPos = [ev.offsetX, ev.offsetY];
+            const rawDelta = [ev.movementX, ev.movementY];
+            if (this._renderCanvas == this._displayCanvas) {
+                /* Native mode. */
+                pos = Vec2.mul(rawPos, window.devicePixelRatio ?? 1);
+                delta = Vec2.mul(rawDelta, window.devicePixelRatio ?? 1);
+            }
+            else {
+                /* Pixelart mode. This math simulates object-fit: contain,
+                * which preserves aspect ratio.
+                */
+                const csize = [
+                    this._displayCanvas.clientWidth,
+                    this._displayCanvas.clientHeight
+                ];
+                /* Scale of both dimensions */
+                const scale = calcAspectFriendlyScale(this.getSize(), csize);
+                /* Upper-left corner */
+                const offset = Vec2.div(Vec2.sub(csize, Vec2.mul(this.getSize(), scale)), 2);
+                pos = Vec2.div(Vec2.sub(rawPos, offset), scale);
+                delta = Vec2.div(rawDelta, scale);
+                /* Only handle mousemove events that are in bounds. */
+                if (!Rect.containsPoint(this.getRect(), pos)) {
+                    return;
+                }
+            }
+            this._displayCanvas.dispatchEvent(new CustomEvent('like:mousemoved', {
+                detail: {
+                    pos,
+                    delta,
+                    renderSize: this.getSize(),
+                }
+            }));
+        }, { signal: this.abort.signal });
+    }
+    /** Get a unified canvas info object. */
+    getMode() {
+        return {
+            size: this.getSize(),
+            flags: {
+                fullscreen: this.getFullscreen(),
+            }
+        };
+    }
+    /** Set the game's apparent resolution, fullscreen, etc.
+     *
+     * ### `'native'` mode
+     * Keeps the canvas pixel resolution
+     * the same as the physical pixel resolution of the
+     * device.
+     *
+     * ### Pixel art mode `[width, height]`
+     * The canvas will use prescaling to keep your pixel
+     * games looking sharp, but without the uneven pixels
+     * caused by the naive approach.
+     *
+     * @param size 'native' for native mode, otherwise [width, height]
+     * @param flags optional options.
+     */
+    setMode(size, flags = {}) {
+        // set up sizing / render target
+        const prevRenderCanvas = this._renderCanvas;
+        if (size == 'native') {
+            this._displayCanvas.style.objectFit = 'fill';
+            this._renderCanvas = this._displayCanvas;
+        }
+        else {
+            this._displayCanvas.style.objectFit = 'contain';
+            this._renderCanvas = document.createElement('canvas');
+            const changed = CanvasInternal.setCanvasElemSize(this._renderCanvas, size);
+            if (changed) {
+                this.dispatch('resize', [size]);
+            }
+        }
+        if (prevRenderCanvas != this._renderCanvas) {
+            this._displayCanvas.dispatchEvent(new CustomEvent('like:updateRenderTarget', {
+                detail: {
+                    target: this._renderCanvas,
+                }
+            }));
+        }
+        if ('fullscreen' in flags) {
+            this.setFullscreen(flags.fullscreen);
+        }
+    }
+    /** Get the apparent (in-game) canvas size. */
+    getSize() {
+        return [this._renderCanvas.width, this._renderCanvas.height];
+    }
+    /** Sometimes you want a screen rect! */
+    getRect() {
+        return [0, 0, ...this.getSize()];
+    }
+    /** Get the actual (physical) canvas size on screen. */
+    _getDisplayPixelSize() {
+        return Vec2.round(Vec2.mul([this._displayCanvas.clientWidth, this._displayCanvas.clientHeight], window.devicePixelRatio ?? 1));
+    }
+    /** Are we fullscreen? */
+    getFullscreen() {
+        return this._displayCanvas === document.fullscreenElement;
+    }
+    /** Set fullscreen. */
+    setFullscreen(fullscreen) {
+        if (fullscreen) {
+            this._displayCanvas.requestFullscreen();
+            this._displayCanvas.focus();
+        }
+        else {
+            document.exitFullscreen();
+        }
+    }
+    /** Called every frame by the engine after drawing */
+    _present() {
+        if (this._renderCanvas == this._displayCanvas) {
+            const realSize = this._getDisplayPixelSize();
+            if ((realSize[0] != this._displayCanvas.width ||
+                realSize[1] != this._displayCanvas.height) &&
+                !this.resizeTimeoutId) {
+                /** In native scaling mode, zooming and resizing the window cause us
+                 * to set canvas width and height every frame, which could cause
+                 * tons of canvas bitmap reallocations. So wait 1/4 second..
+                 */
+                CanvasInternal.setCanvasElemSize(this._displayCanvas, realSize);
+                this.dispatch('resize', [realSize]);
+                this.resizeTimeoutId = setTimeout(() => { this.resizeTimeoutId = 0; }, 250);
+            }
+        }
+        else if (this._renderCanvas != this._displayCanvas) {
+            /* We're in pixelart mode,
+             * so set output canvas size to an ideal integer scale.
+             * No debounce: changes to integer ratio are infrequent.
+             */
+            CanvasInternal.setCanvasElemSize(this._displayCanvas, Vec2.mul(this.getSize(), Math.round(calcAspectFriendlyScale(this.getSize(), this._getDisplayPixelSize()))));
+            // Copy the internal canvas to the visible one.
+            const ctx = this._displayCanvas.getContext('2d');
+            ctx.imageSmoothingEnabled = false;
+            ctx.drawImage(this._renderCanvas, 0, 0, this._renderCanvas.width, this._renderCanvas.height, 0, 0, this._displayCanvas.width, this._displayCanvas.height);
+        }
+    }
+    /** @returns if size was changed.  */
+    static setCanvasElemSize(canvas, newSize) {
+        if (canvas.width != newSize[0] || canvas.height != newSize[1]) {
+            [canvas.width, canvas.height] = newSize;
+            return true;
+        }
+        return false;
+    }
+    static getCanvasElemSize(canvas) {
+        return [canvas.width, canvas.height];
+    }
+    _dispose() {
+        this.abort.abort();
+    }
+}
+/** How much could this image be scaled, preserving aspect? */
+function calcAspectFriendlyScale(imageSize, containerSize) {
+    return Math.min(...Vec2.div(containerSize, imageSize));
+}

package/dist/core/events.d.ts

@@ -1,27 +1,105 @@
-import type { Vector2 } from './vector2';
-/** Game events. All events flow through handleEvent; these are also available as individual callbacks. */
+/**
+ * @module events
+ * @description All events that flow through the engine.
+ *
+ * ## Overview
+ *
+ * LIKE uses events at its core.
+ * These pass through the engine and down to your
+ * callbacks or scene.
+ *
+ * This module is the single source of truth for what
+ * events are possible.
+ *
+ * Use it as a reference.
+ *
+ * @see {@link EventMap} lists every event.
+ * @see {@link Scene} for implementing callbacks in a class
+ * @see {@link Like} for global callback assignment
+ * @see {@link Input} for action mapping
+ */
+import type { Vector2 } from '../math/vector2';
+import { LikeButton } from './gamepad-mapping';
+export type MouseButton = 'left' | 'middle' | 'right';
+declare global {
+    interface HTMLElementEventMap {
+        ['like:mousemoved']: CustomEvent<{
+            pos: Vector2;
+            delta: Vector2;
+            renderSize: Vector2;
+        }>;
+        ['like:updateRenderTarget']: CustomEvent<{
+            target: HTMLCanvasElement;
+        }>;
+    }
+}
+/**
+ * The master type will all events on it.
+ *
+ * Each frame:
+ * 1. `update(dt)` - Game logic with delta time in seconds
+ * 2. `draw` - Render the frame
+ *
+ * Input events fire immediately when they occur:
+ * - `keypressed`/`keyreleased` - Keyboard input
+ * - `mousemoved`/`mousepressed`/`mousereleased` - Mouse input
+ * - `gamepadpressed`/`gamepadreleased` - Controller input
+ * - `actionpressed`/`actionreleased` - Mapped actions (see {@link Input})
+ *
+ * Window events:
+ * - `focus`/`blur` - Tab/window focus changes
+ * - `resize` - Canvas size changes
+ *
+ * Lifecycle:
+ * - `load` - Called once when the game starts
+ */
 export type EventMap = {
+    /** Game initialization. Called once before the first frame. */
     load: [];
+    /** Frame update. dt is delta time in seconds (time since last frame). */
     update: [dt: number];
+    /** Render frame. Clear the screen and draw your game here. */
     draw: [];
-    resize: [size: Vector2, pixelSize: Vector2, fullscreen: boolean];
+    /** Canvas was resized. Used mostly in native mode, though setMode may send it too. */
+    resize: [size: Vector2];
+    /** Physical key pressed. scancode is the physical key, keycode is the character. */
     keypressed: [scancode: string, keycode: string];
+    /** Physical key released. */
     keyreleased: [scancode: string, keycode: string];
-    focus: [];
-    blur: [];
-    /** Mouse moved. relative=true means pos is delta [dx, dy] (pointer lock). */
-    mousemoved: [pos: Vector2, relative: boolean];
-    /** Mouse button pressed. pos in canvas pixels. Button 1 = left, 2 = middle, 3 = right. */
-    mousepressed: [pos: Vector2, button: number];
+    /** Canvas or tab gained focus. Game may resume audio/updates. */
+    focus: [source: 'canvas' | 'tab'];
+    /** Canvas or tab lost focus. Game may pause audio/updates. */
+    blur: [source: 'canvas' | 'tab'];
+    /** Mouse moved event. `pos` is absolute, `delta` is relative. */
+    mousemoved: [pos: Vector2, delta: Vector2];
+    /** Mouse button pressed. pos in canvas pixels. Button: 1=left, 2=middle, 3=right. */
+    mousepressed: [pos: Vector2, button: MouseButton];
     /** Mouse button released. */
-    mousereleased: [pos: Vector2, button: number];
-    gamepadpressed: [gamepadIndex: number, buttonIndex: number, buttonName: string];
-    gamepadreleased: [gamepadIndex: number, buttonIndex: number, buttonName: string];
+    mousereleased: [pos: Vector2, button: MouseButton];
+    /** Gamepad button pressed. index is controller number (0-3). */
+    gamepadpressed: [source: number, num: number, name: LikeButton];
+    /** Gamepad button released. */
+    gamepadreleased: [source: number, num: number, name: LikeButton];
+    /** Mapped action triggered. See {@link Input} for action mapping. */
     actionpressed: [action: string];
+    /** Mapped action released. */
     actionreleased: [action: string];
 };
 export type EventType = keyof EventMap;
-export type Like2DEvent = {
+/**
+ * Discriminated union of all event objects.
+ * Use this with `handleEvent` to receive all events generically.
+ *
+ * @example
+ * ```typescript
+ * handleEvent(like: Like, event: Like2DEvent) {
+ *   if (event.type === 'update') {
+ *     const dt = event.args[0];
+ *   }
+ * }
+ * ```
+ */
+export type LikeEvent = {
     [K in EventType]: {
         type: K;
         args: EventMap[K];

package/dist/core/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,0GAA0G;AAC1G,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,EAAE,CAAC;IACT,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACrB,IAAI,EAAE,EAAE,CAAC;IACT,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACjE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjD,KAAK,EAAE,EAAE,CAAC;IACV,IAAI,EAAE,EAAE,CAAC;IACT,6EAA6E;IAC7E,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,0FAA0F;IAC1F,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,6BAA6B;IAC7B,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAChF,eAAe,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACjF,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC;AAGvC,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,SAAS,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CACpE,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,mBAAmB;QAC3B,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC;YAAC,GAAG,EAAE,OAAO,CAAC;YAAC,KAAK,EAAE,OAAO,CAAC;YAAC,UAAU,EAAE,OAAO,CAAA;SAAC,CAAC,CAAC;QACtF,CAAC,yBAAyB,CAAC,EAAE,WAAW,CAAC;YAAC,MAAM,EAAE,iBAAiB,CAAA;SAAC,CAAC,CAAC;KACvE;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,+DAA+D;IAC/D,IAAI,EAAE,EAAE,CAAC;IAET,yEAAyE;IACzE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAErB,8DAA8D;IAC9D,IAAI,EAAE,EAAE,CAAC;IAET,sFAAsF;IACtF,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAExB,oFAAoF;IACpF,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAEhD,6BAA6B;IAC7B,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAEjD,iEAAiE;IACjE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;IAElC,8DAA8D;IAC9D,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;IAEjC,iEAAiE;IACjE,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAE3C,qFAAqF;IACrF,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAElD,6BAA6B;IAC7B,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAEnD,gEAAgE;IAChE,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAEhE,+BAA+B;IAC/B,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAEjE,qEAAqE;IACrE,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,8BAA8B;IAC9B,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG;KACrB,CAAC,IAAI,SAAS,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CACpE,CAAC,SAAS,CAAC,CAAC"}

package/dist/core/events.js

@@ -1 +1,21 @@
+/**
+ * @module events
+ * @description All events that flow through the engine.
+ *
+ * ## Overview
+ *
+ * LIKE uses events at its core.
+ * These pass through the engine and down to your
+ * callbacks or scene.
+ *
+ * This module is the single source of truth for what
+ * events are possible.
+ *
+ * Use it as a reference.
+ *
+ * @see {@link EventMap} lists every event.
+ * @see {@link Scene} for implementing callbacks in a class
+ * @see {@link Like} for global callback assignment
+ * @see {@link Input} for action mapping
+ */
 export {};