melonjs 20.1.1 → 20.3.0

package/README.md

@@ -5,19 +5,18 @@ melonJS 2
 [![Build Status](https://github.com/melonjs/melonJS/actions/workflows/main.yml/badge.svg)](https://github.com/melonjs/melonJS/actions/workflows/main.yml)
 [![NPM Package](https://img.shields.io/npm/v/melonjs)](https://www.npmjs.com/package/melonjs)
 [![NPM Downloads](https://img.shields.io/npm/dm/melonjs)](https://www.npmjs.com/package/melonjs)
-[![Build Size](https://badgen.net/bundlephobia/minzip/melonjs)](https://bundlephobia.com/result?p=melonjs)
-[![Tree-shaking](https://badgen.net/bundlephobia/tree-shaking/melonjs)](https://bundlephobia.com/result?p=melonjs)
+[![Build Size](https://img.shields.io/bundlejs/size/melonjs?label=minzip)](https://bundlejs.com/?q=melonjs)
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/melonjs/badge?style=rounded)](https://www.jsdelivr.com/package/npm/melonjs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
 [![Discord](https://img.shields.io/discord/608636676461428758?color=7289da&label=discord)](https://discord.gg/aur7JMk)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
 
-A modern & lightweight HTML5 game engine
+A modern & fully featured HTML5 game engine
 -------------------------------------------------------------------------------
 ![melonJS](https://melonjs.org/img/alex4-github.png)
 
-[melonJS](https://melonjs.org/) is an open-source 2.5D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGPU, WebGL 2 or Canvas2D with automatic fallback, tree-shakeable so you only pay for what you use, and the entire engine fits in ~150 KB minzipped of vanilla JS/TS with no toolchain lock-in. Built with ES6 classes and bundled with [esbuild](https://esbuild.github.io).
+[melonJS](https://melonjs.org/) is an open-source 2.5D game engine designed for indie developers — perspective and orthogonal cameras, GPU-accelerated tilemap rendering, post-processing effects, custom shaders, 3D mesh support, polygon-accurate physics, modern Tiled workflows, and high performance. Runs on WebGPU, WebGL 2 or Canvas2D with automatic fallback. The whole engine is ~250 KB minzipped of vanilla JS/TS, with no dependencies and no toolchain lock-in. Built with modern class syntax and bundled with [esbuild](https://esbuild.github.io).
 
 [melonJS](https://melonjs.org/) is licensed under the [MIT License](LICENSE.md) and actively maintained by the team at AltByte in Singapore.
 
@@ -34,7 +33,7 @@ melonJS is designed so you can **focus on making games, not on graphics plumbing
 
 - **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering on the GPU backends — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.
 
-- **Batteries included, hackable by design** — Get started in minutes with minimal setup. When you need to go deeper: ES6 classes throughout, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.
+- **Batteries included, hackable by design** — Get started in minutes with minimal setup. When you need to go deeper: modern class-based architecture, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.
 
 About melonJS
 -------------------------------------------------------------------------------
@@ -51,7 +50,7 @@ Graphics
 - Extensible batcher system for custom rendering pipelines, with backend-neutral vertex formats and draw topologies (declare a layout once, describe it to either GPU backend)
 - High DPI resolution & Canvas advanced auto scaling
 - Sprite with 9-slice scaling option and frame animation
-- Built-in effects such as tinting, masking, and CSS-style blend modes (normal, none, additive, multiply, screen, darken, lighten)
+- Built-in effects such as tinting, masking, and the full set of CSS-style blend modes (normal, none, additive, multiply, screen, exclusion, darken, lighten, overlay, hard-light, color-dodge, color-burn, soft-light, difference) — all of them supported identically on WebGPU, WebGL 2 and Canvas since 20.2
 - Standard spritesheet, single and multiple Packed Textures support
 - Compressed texture support (DDS, KTX, KTX2, PVR, PKM) with automatic format detection and fallback
 - Hardware antialiasing (`antiAlias: true`) on both GPU backends — and it survives post-processing, since the offscreen targets a post-effect chain renders into are multisampled to match
@@ -138,7 +137,7 @@ Core
 - Tween effects with multiple easing functions (Quadratic, Cubic, Elastic, Bounce, etc.) and Bezier/Catmull-Rom interpolation
 - Transition effects
 - Pooling support for object recycling
-- Particle system with `ParticleEmitter` (emission rate, lifetime, velocity, gravity, blend modes)
+- Particle system with `ParticleEmitter` (emission rate, lifetime, velocity, gravity, blend modes), and a reference space so particles can be measured from the emitter, from the world, or from any container — a moving emitter leaves a trail instead of dragging its cloud along
 - EventEmitter based event system
 - Persistent data storage (save/load via localStorage)
 - Plugin system for extending engine capabilities
@@ -263,7 +262,8 @@ See the [Migrating to the Physics Adapter API](https://github.com/melonjs/melonJ
 Installation
 -------------------------------------------------------------------------------
 
-melonJS is distributed as a tree-shakeable ES6 module with TypeScript declarations included.
+melonJS is distributed as a tree-shakeable ES module with TypeScript declarations included.
+The published bundle targets **ES2022** — transpile it if you need to support older browsers.
 
 Install via [npm](https://www.npmjs.com/package/melonjs) :
 
@@ -278,14 +278,92 @@ import { Application, Sprite, loader } from 'melonjs';
 Or use it directly via [jsDelivr](https://www.jsdelivr.com/package/npm/melonjs) CDN :
 
 ```html
-<!-- load the ES6 module bundle of melonJS v19.x -->
-<script type="module" src="https://cdn.jsdelivr.net/npm/melonjs@19/+esm"></script>
+<!-- load the ES module bundle of melonJS v20.x -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/melonjs@20/+esm"></script>
 <!-- omit the version completely to get the latest one -->
 <!-- you should NOT use this in production -->
 <script type="module" src="https://cdn.jsdelivr.net/npm/melonjs/+esm"></script>
 ```
 > Note: the debug plugin is available separately as [`@melonjs/debug-plugin`](https://www.npmjs.com/package/@melonjs/debug-plugin)
 
+### Supporting older browsers
+
+The published bundle targets ES2022, so it uses private class members and other
+modern syntax. A browser that predates those cannot parse the file at all — this
+fails at load, not at the point a feature is used.
+
+To support older browsers, transpile melonJS **together with your own code**.
+The usual trap is that build setups skip `node_modules` by default, which leaves
+melonJS untouched no matter how low you set your target.
+
+With [Vite](https://vite.dev) :
+
+```javascript
+// vite.config.js
+export default {
+    build: {
+        // esbuild downlevels dependencies too, melonjs included
+        target: "es2020",
+    },
+};
+```
+
+With Babel, make sure melonJS is not excluded :
+
+```javascript
+// webpack.config.js
+{
+    test: /\.js$/,
+    // the default `exclude: /node_modules/` would skip melonjs
+    exclude: /node_modules\/(?!melonjs)/,
+    use: "babel-loader",
+}
+```
+
+Transpiling costs some size and speed: private class members become `WeakMap`
+lookups, which are on hot paths in the renderer. Only reach for it if you have
+users on browsers that need it.
+
+Building with AI agents
+-------------------------------------------------------------------------------
+
+melonJS ships **skills** — guidance files that teach AI coding assistants the
+engine's conventions and, more usefully, the mistakes that fail silently rather
+than raising an error.
+
+They are installed with the package, at `node_modules/melonjs/skills/`, and are
+versioned with the engine — so the guidance always matches the release you have.
+
+**Claude Code** — install as a plugin :
+
+```
+/plugin marketplace add melonjs/melonJS
+```
+
+or copy the skills into a project :
+
+```bash
+mkdir -p .claude/skills && cp -r node_modules/melonjs/skills/melonjs* .claude/skills/
+```
+
+**Other agents** (Codex, Cursor, Gemini CLI, …) read an `AGENTS.md` from your own
+project root. One ships ready to use — copy it across :
+
+```bash
+cp node_modules/melonjs/skills/AGENTS.md ./AGENTS.md
+```
+
+It points at the shipped skills, names the three rules that produce code which
+runs and is wrong, and links the API index below. If you already have an
+`AGENTS.md`, paste its sections into yours.
+
+The skills are plain markdown and can be read by any agent, or by a human.
+
+For anything the skills do not cover, the complete API is indexed for agents at
+[llms.txt](https://melonjs.github.io/melonJS/llms.txt) — every exported class,
+function and type with a one-line summary and a link to its reference page,
+regenerated on every docs build.
+
 Community
 -------------------------------------------------------------------------------
 Join us and get help or share your projects :

package/build/application/settings.d.ts

@@ -8,7 +8,7 @@ import { PhysicsAdapter } from "../physics/adapter";
 import Renderer from "../video/renderer";
 import { WebGLBatcher } from "../video/webgl/batchers/batcher.js";
 import { ScaleMethod } from "./scaleMethods";
-type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen" | "darken" | "lighten" | "exclusion" | "none";
+type BlendMode = "normal" | "multiply" | "lighter" | "additive" | "screen" | "darken" | "lighten" | "exclusion" | "none" | "overlay" | "hard-light" | "color-dodge" | "color-burn" | "soft-light" | "difference";
 /**
  * How the application's physics is configured.
  *
@@ -207,7 +207,9 @@ export type ApplicationSettings = {
      */
     consoleHeader: boolean;
     /**
-     * the default blend mode to use ("normal", "multiply", "lighter", "additive", "screen")
+     * the default blend mode to use. Both GPU renderers support the full set;
+     * the Canvas fallback supports every mode except `"none"` — see
+     * {@link CanvasRenderer#setBlendMode} for the list.
      * @default "normal"
      */
     blendMode: BlendMode;

package/build/application/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/application/settings.ts"],"names":[],"mappings":"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"}

package/build/audio/audio.d.ts

@@ -14,9 +14,9 @@
  * This file owns the remaining lifecycle / track / mix / unload
  * helpers, plus the barrel re-exports that compose the namespace.
  */
-export { getAudioContext, getMasterGain, setStopOnAudioError, stopOnAudioError, } from "./backend.ts";
-export { fade, load, orientation, panner, pause, play, position, rate, resume, seek, stereo, stop, } from "./playback.ts";
+export { duration, fade, load, orientation, panner, pause, play, playing, position, rate, resume, seek, state, stereo, stop, } from "./playback.ts";
 export { noise, tone } from "./procedural.ts";
+export { getAudioContext, getMasterGain, setStopOnAudioError, stopOnAudioError, } from "./state.ts";
 export type { LoadSettings, NoiseFilter, NoiseOptions, PannerAttributes, SoundAsset, ToneOptions, } from "./types.ts";
 /**
  * Initialize and configure the audio module.

package/build/audio/audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/audio/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH,OAAO,EACN,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,gBAAgB,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,MAAM,EACN,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,MAAM,EACN,IAAI,GACJ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE9C,YAAY,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,GACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,MAAc,GAAG,OAAO,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,IAAI,CAE7B;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAE9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAKhC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAIlC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CACnB,UAAU,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,MAAM,EACX,UAAU,GAAE,OAAc,GACxB,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAE9B;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAgBlD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAMhC"}
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/audio/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,OAAO,EACN,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,MAAM,EACN,KAAK,EACL,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,MAAM,EACN,IAAI,GACJ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EACN,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,GACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,MAAc,GAAG,OAAO,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,IAAI,CAE7B;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAE9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAKhC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAIlC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CACnB,UAAU,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,MAAM,EACX,UAAU,GAAE,OAAc,GACxB,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAE9B;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAgBlD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAMhC"}

package/build/audio/backend/buffer.d.ts

@@ -0,0 +1,26 @@
+import type { Sound } from "./core.ts";
+/**
+ * Fetches the bytes for an audio URL.
+ *
+ * Defaults to the engine's shared transport, which falls back to XHR for `file:`
+ * URLs — `fetch()` cannot read that scheme in a Cordova or Capacitor WebView.
+ * {@link setAudioFetcher} overrides it, for a custom transport or a test.
+ *
+ * The default is a working implementation rather than a stub that must be
+ * installed, because a rejection here is not reported as an error: it tells the
+ * backend to abandon Web Audio for that clip and fall back to a streaming HTML5
+ * element. An un-installed stub would therefore degrade every network clip
+ * silently instead of failing loudly.
+ */
+export type AudioFetcher = (url: string, options: {
+    withCredentials?: boolean | undefined;
+}) => Promise<ArrayBuffer>;
+/**
+ * Install the function the backend uses to fetch audio bytes.
+ * @param fetcher - obtains the bytes for a URL, rejecting on failure
+ */
+export declare const setAudioFetcher: (fetcher: AudioFetcher) => void;
+export declare const loadBuffer: (self: Sound) => void;
+export declare const decodeAudioData: (arraybuffer: ArrayBuffer, self: Sound) => void;
+export declare const loadSound: (self: Sound, buffer?: AudioBuffer) => void;
+//# sourceMappingURL=buffer.d.ts.map

package/build/audio/backend/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/buffer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAIvC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,KAC9C,OAAO,CAAC,WAAW,CAAC,CAAC;AAO1B;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,YAAY,SAEpD,CAAC;AAuBF,eAAO,MAAM,UAAU,GAAI,MAAM,KAAK,SAgCrC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,aAAa,WAAW,EAAE,MAAM,KAAK,SAsBpE,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,MAAM,KAAK,EAAE,SAAS,WAAW,SAiB1D,CAAC"}

package/build/audio/backend/cache.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/build/audio/backend/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/cache.ts"],"names":[],"mappings":""}

package/build/audio/backend/core.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Constructs the singleton engine instance and re-exports the core types.
+ *
+ * Split from `index.ts` so `voice.ts` and `sound.ts` can reach the singleton
+ * without importing the public barrel, which would be a cycle.
+ */
+import { AudioEngine } from "./engine.ts";
+import { Sound } from "./sound.ts";
+import type { SpatialAudioEngine } from "./spatial.ts";
+import { Voice } from "./voice.ts";
+/**
+ * The global audio controller singleton.
+ *
+ * Upstream shipped spatial audio as an opt-in plugin behind a registry. There
+ * was only ever one plugin, so the registry was pure indirection: spatial is
+ * installed directly by the engine constructor and the singleton is typed
+ * `SpatialAudioEngine`.
+ */
+declare const audioEngine: SpatialAudioEngine;
+export { cache } from "./cache.ts";
+export type { AudioBufferSourceNodeWithLegacy, EventListener, GainNodeWithBufferSource, HTMLAudioElementWithUnlocked, QueueItem, SoundOptions, WindowWithAudio, } from "./types.ts";
+export { isGainNode, isHTMLAudioElement } from "./types.ts";
+export { AudioEngine, audioEngine, Sound, Voice };
+//# sourceMappingURL=core.d.ts.map

package/build/audio/backend/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;GAOG;AACH,QAAA,MAAM,WAAW,EAAwB,kBAAkB,CAAC;AAE5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EACX,+BAA+B,EAC/B,aAAa,EACb,wBAAwB,EACxB,4BAA4B,EAC5B,SAAS,EACT,YAAY,EACZ,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC"}

package/build/audio/backend/engine.d.ts

@@ -0,0 +1,54 @@
+import type { Sound } from "./sound.ts";
+import { type HTMLAudioElementWithUnlocked } from "./types.ts";
+export declare class AudioEngine {
+    _counter: number;
+    _html5AudioPool: HTMLAudioElement[];
+    html5PoolSize: number;
+    _codecs: Record<string, boolean>;
+    sounds: Sound[];
+    _muted: boolean;
+    _volume: number;
+    _canPlayEvent: string;
+    _navigator: Navigator | null;
+    masterGain: GainNode | null;
+    noAudio: boolean;
+    usingWebAudio: boolean;
+    autoSuspend: boolean;
+    ctx: AudioContext | null;
+    autoUnlock: boolean;
+    state: string;
+    _audioUnlocked: boolean;
+    _scratchBuffer: AudioBuffer | null;
+    _suspendTimer: ReturnType<typeof setTimeout> | null;
+    _resumeAfterSuspend?: boolean;
+    _mobileUnloaded?: boolean;
+    constructor();
+    volume(vol?: number): number | this;
+    mute(muted: boolean): this;
+    stop(): this;
+    unload(): this;
+    codecs(ext: string): boolean;
+    /**
+     * Create the shared `AudioContext` and master gain node if they do not exist
+     * yet, and return the context.
+     *
+     * Idempotent: with a context already live this returns it untouched. It used
+     * to be a free function in `helpers/` that reached back into the singleton,
+     * with no internal guard — so six call sites each carried their own
+     * `if (!ctx)` check to stop a second context being built and the first
+     * leaked.
+     *
+     * Browsers create a context in the `suspended` state until a user gesture
+     * resumes it, so building one early costs nothing and plays nothing.
+     * @returns the shared context, or `null` when Web Audio is unavailable
+     */
+    ensureContext(): AudioContext | null;
+    _setup(): this;
+    _setupCodecs(): this;
+    _unlockAudio(): void;
+    _obtainHtml5Audio(): HTMLAudioElementWithUnlocked;
+    _releaseHtml5Audio(audio: HTMLAudioElementWithUnlocked): this;
+    _autoSuspend(): void;
+    _autoResume(): void;
+}
+//# sourceMappingURL=engine.d.ts.map

package/build/audio/backend/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EACN,KAAK,4BAA4B,EAGjC,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACvB,QAAQ,EAAE,MAAM,CAAQ;IACxB,eAAe,EAAE,gBAAgB,EAAE,CAAM;IACzC,aAAa,EAAE,MAAM,CAAM;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IACtC,MAAM,EAAE,KAAK,EAAE,CAAM;IACrB,MAAM,EAAE,OAAO,CAAS;IACxB,OAAO,EAAE,MAAM,CAAK;IACpB,aAAa,EAAE,MAAM,CAAoB;IACzC,UAAU,EAAE,SAAS,GAAG,IAAI,CAAQ;IACpC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAQ;IACnC,OAAO,EAAE,OAAO,CAAS;IACzB,aAAa,EAAE,OAAO,CAAQ;IAC9B,WAAW,EAAE,OAAO,CAAQ;IAC5B,GAAG,EAAE,YAAY,GAAG,IAAI,CAAQ;IAChC,UAAU,EAAE,OAAO,CAAQ;IAC3B,KAAK,EAAE,MAAM,CAAe;IAC5B,cAAc,EAAE,OAAO,CAAS;IAChC,cAAc,EAAE,WAAW,GAAG,IAAI,CAAQ;IAC1C,aAAa,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAQ;IAC3D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,EAAE,OAAO,CAAC;;IA4B1B,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoCnC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IA2B1B,IAAI,IAAI,IAAI;IAQZ,MAAM,IAAI,IAAI;IAkBd,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,YAAY,GAAG,IAAI;IAmCpC,MAAM,IAAI,IAAI;IAmCd,YAAY,IAAI,IAAI;IAqEpB,YAAY,IAAI,IAAI;IAiGpB,iBAAiB,IAAI,4BAA4B;IAoCjD,kBAAkB,CAAC,KAAK,EAAE,4BAA4B,GAAG,IAAI;IAQ7D,YAAY,IAAI,IAAI;IA6CpB,WAAW,IAAI,IAAI;CAsDnB"}

package/build/audio/backend/sound.d.ts

@@ -0,0 +1,79 @@
+import { type EventListener, type HTMLAudioElementWithUnlocked, type QueueItem, type SoundOptions } from "./types.ts";
+import { Voice } from "./voice.ts";
+declare class Sound {
+    _autoplay: boolean;
+    _format: string[];
+    _html5: boolean;
+    _muted: boolean;
+    _loop: boolean;
+    _pool: number;
+    _preload: boolean | "metadata";
+    _rate: number;
+    _sprite: Record<string, [number, number, boolean?]>;
+    _src: string | string[];
+    _volume: number;
+    _xhr: {
+        method: string;
+        headers?: HeadersInit | undefined;
+        withCredentials: boolean;
+    };
+    _duration: number;
+    _state: string;
+    _sounds: Voice[];
+    _endTimers: Record<number, ReturnType<typeof setTimeout>>;
+    _queue: QueueItem[];
+    _playLock: boolean;
+    _webAudio: boolean;
+    _onend: EventListener[];
+    _onfade: EventListener[];
+    _onload: EventListener[];
+    _onloaderror: EventListener[];
+    _onplayerror: EventListener[];
+    _onpause: EventListener[];
+    _onplay: EventListener[];
+    _onstop: EventListener[];
+    _onmute: EventListener[];
+    _onvolume: EventListener[];
+    _onrate: EventListener[];
+    _onseek: EventListener[];
+    _onunlock: EventListener[];
+    _onresume: EventListener[];
+    constructor(o: SoundOptions);
+    init(o: SoundOptions): this;
+    load(): this;
+    play(sprite?: string | number, internal?: boolean): number | null;
+    pause(id?: number, internal?: boolean): this;
+    stop(id?: number, internal?: boolean): this;
+    mute(muted: boolean, id?: number): boolean | this;
+    volume(): number;
+    volume(vol: number, id?: number, internal?: boolean): this;
+    fade(from: number, to: number, len: number, id?: number): this;
+    _startFadeInterval(sound: Voice, from: number, to: number, len: number, _id: number, isGroup: boolean): void;
+    _stopFade(id: number): this;
+    loop(): boolean;
+    loop(loop: boolean, id?: number): this;
+    rate(): number;
+    rate(rate: number, id?: number): this;
+    seek(): number;
+    seek(seek: number, id?: number): this;
+    playing(id?: number): boolean;
+    duration(id?: number): number;
+    state(): string;
+    unload(): null;
+    on(event: string, fn: (...args: unknown[]) => void, id?: number, once?: boolean): this;
+    off(event: string, fn?: (...args: unknown[]) => void, id?: number): this;
+    once(event: string, fn: (...args: unknown[]) => void, id?: number): this;
+    _emit(event: string, id?: number | null, msg?: string): this;
+    _loadQueue(event?: string): this;
+    _ended(sound: Voice): this;
+    _clearTimer(id: number): this;
+    _soundById(id: number): Voice | null;
+    _inactiveSound(): Voice;
+    _drain(): void;
+    _getSoundIds(id?: number): number[];
+    _refreshBuffer(sound: Voice): this;
+    _cleanBuffer(node: any): this;
+    _clearSound(node: HTMLAudioElementWithUnlocked): void;
+}
+export { Sound };
+//# sourceMappingURL=sound.d.ts.map

package/build/audio/backend/sound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/sound.ts"],"names":[],"mappings":"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"}

package/build/audio/backend/spatial.d.ts

@@ -0,0 +1,191 @@
+import type { SoundOptions } from "./core.ts";
+import { type AudioEngine, type Sound, type Voice } from "./core.ts";
+/**
+ * Extended SoundOptions with spatial audio properties.
+ * Use this interface when creating a Sound instance with spatial audio capabilities.
+ * @example
+ * ```typescript
+ * const sound = new Sound({
+ *   src: ['sound.mp3'],
+ *   pos: [10, 20, 30],
+ *   stereo: 0.5,
+ *   distanceModel: 'inverse'
+ * } as SpatialSoundOptions);
+ * ```
+ */
+/** Panner attributes a spatial sound can be configured with. */
+export interface PannerAttrOptions {
+    /** Inner angle of the sound cone in degrees. */
+    coneInnerAngle: number;
+    /** Outer angle of the sound cone in degrees. */
+    coneOuterAngle: number;
+    /** Gain value outside the outer cone (0.0 to 1.0). */
+    coneOuterGain: number;
+    /** Distance model algorithm. */
+    distanceModel: "linear" | "inverse" | "exponential";
+    /** Maximum distance for the distance model. */
+    maxDistance: number;
+    /** Panning model algorithm. */
+    panningModel: "equalpower" | "HRTF";
+    /** Reference distance for the distance model. */
+    refDistance: number;
+    /** Rolloff factor for the distance model. */
+    rolloffFactor: number;
+}
+export interface SpatialSoundOptions extends SoundOptions {
+    /** 3D position of the sound source [x, y, z]. */
+    pos?: [number, number, number];
+    /** Orientation vector of the sound source [x, y, z]. */
+    orientation?: [number, number, number];
+    /** Stereo panning value from -1.0 (left) to 1.0 (right). */
+    stereo?: number;
+    /** Inner angle of the sound cone in degrees. Default: `360` */
+    coneInnerAngle?: number;
+    /** Outer angle of the sound cone in degrees. Default: `360` */
+    coneOuterAngle?: number;
+    /** Gain value outside the outer cone. Range: 0.0 to 1.0. Default: `0` */
+    coneOuterGain?: number;
+    /** Distance model algorithm: 'linear', 'inverse', or 'exponential'. Default: `'inverse'` */
+    distanceModel?: "linear" | "inverse" | "exponential";
+    /** Maximum distance for the distance model. Default: `10000` */
+    maxDistance?: number;
+    /** Panning model: 'equalpower' or 'HRTF'. Default: `'HRTF'` */
+    panningModel?: "equalpower" | "HRTF";
+    /** Reference distance for the distance model. Default: `1` */
+    refDistance?: number;
+    /** Rolloff factor for the distance model. Default: `1` */
+    rolloffFactor?: number;
+    /** Fires when the stereo panning changes. */
+    onstereo?: () => void;
+    /** Fires when the 3D position changes. */
+    onpos?: () => void;
+    /** Fires when the orientation changes. */
+    onorientation?: () => void;
+}
+/**
+ * audioEngine instance with spatial audio capabilities.
+ * Use this type when the spatial plugin is registered to get full type safety for spatial audio methods.
+ * @example
+ * ```typescript
+ * import { audioEngine } from 'engine';
+ * import { SpatialAudioPlugin, type SpatialAudioEngine } from 'engine/plugins/spatial';
+ *
+ * audioEngine.addPlugin(new SpatialAudioPlugin());
+ *
+ * const engine: SpatialAudioEngine = audioEngine as SpatialAudioEngine;
+ * engine.pos(10, 20, 30); // Set listener position
+ * engine.orientation(0, 0, -1, 0, 1, 0); // Set listener orientation
+ * engine.stereo(0.5); // Set stereo panning
+ * ```
+ */
+export type SpatialAudioEngine = AudioEngine & SpatialAudioState & {
+    /**
+     * Set or get the listener's 3D position.
+     * @param x - X coordinate (optional)
+     * @param y - Y coordinate (optional)
+     * @param z - Z coordinate (optional)
+     * @returns If called with no arguments, returns the current position [x, y, z]. Otherwise, returns the audioEngine instance for chaining.
+     */
+    pos(x?: number, y?: number, z?: number): SpatialAudioEngine | [number, number, number];
+    /**
+     * Set or get the listener's orientation.
+     * @param x - Forward X component (optional)
+     * @param y - Forward Y component (optional)
+     * @param z - Forward Z component (optional)
+     * @param xUp - Up X component (optional)
+     * @param yUp - Up Y component (optional)
+     * @param zUp - Up Z component (optional)
+     * @returns If called with no arguments, returns the current orientation [forwardX, forwardY, forwardZ, upX, upY, upZ]. Otherwise, returns the audioEngine instance for chaining.
+     */
+    orientation(x?: number, y?: number, z?: number, xUp?: number, yUp?: number, zUp?: number): SpatialAudioEngine | [number, number, number, number, number, number];
+    /**
+     * Set or get the stereo panning value.
+     * @param pan - Panning value from -1.0 (left) to 1.0 (right) (optional)
+     * @returns If called with no arguments, returns the current panning value. Otherwise, returns the audioEngine instance for chaining.
+     */
+    stereo(pan?: number): SpatialAudioEngine;
+};
+/**
+ * Sound instance with spatial audio capabilities.
+ * Use this type when the spatial plugin is registered to get full type safety for spatial audio methods.
+ * @example
+ * ```typescript
+ * import { Sound } from 'engine';
+ * import { SpatialAudioPlugin, type SpatialSound, type SpatialSoundOptions } from 'engine/plugins/spatial';
+ *
+ * audioEngine.addPlugin(new SpatialAudioPlugin());
+ *
+ * const sound: SpatialSound = new Sound({
+ *   src: ['sound.mp3'],
+ *   pos: [10, 20, 30]
+ * } as SpatialSoundOptions) as SpatialSound;
+ *
+ * sound.pos(5, 10, 15); // Set sound position
+ * sound.stereo(0.5); // Set stereo panning
+ * sound.orientation(0, 1, 0); // Set sound orientation
+ * ```
+ */
+export type SpatialSound = Sound & SpatialSoundState & {
+    /**
+     * Set or get the sound's 3D position.
+     * @param x - X coordinate (optional)
+     * @param y - Y coordinate (optional)
+     * @param z - Z coordinate (optional)
+     * @param id - Voice ID to target a specific sound instance (optional)
+     * @returns If called with no arguments, returns the current position [x, y, z]. Otherwise, returns the Sound instance for chaining.
+     */
+    pos(x?: number, y?: number, z?: number, id?: number): SpatialSound | [number, number, number] | null;
+    /**
+     * Set or get the sound's orientation vector.
+     * @param x - X component (optional)
+     * @param y - Y component (optional)
+     * @param z - Z component (optional)
+     * @param id - Voice ID to target a specific sound instance (optional)
+     * @returns If called with no arguments, returns the current orientation [x, y, z]. Otherwise, returns the Sound instance for chaining.
+     */
+    orientation(x?: number, y?: number, z?: number, id?: number): SpatialSound | [number, number, number] | null;
+    /**
+     * Set or get the stereo panning value.
+     * @param pan - Panning value from -1.0 (left) to 1.0 (right) (optional)
+     * @param id - Voice ID to target a specific sound instance (optional)
+     * @returns If called with no arguments, returns the current panning value. Otherwise, returns the Sound instance for chaining.
+     */
+    stereo(pan?: number, id?: number): SpatialSound | number | null;
+    /**
+     * Set or get panner node attributes.
+     * @param o - Panner attributes object (optional)
+     * @param id - Voice ID to target a specific sound instance (optional)
+     * @returns If called with no arguments, returns the current panner attributes. Otherwise, returns the Sound instance for chaining.
+     */
+    pannerAttr(o?: PannerAttrOptions | number, id?: number): SpatialSound | PannerAttrOptions;
+};
+/**
+ * Spatial Audio Plugin
+ * Adds 3D spatial audio and stereo panning capabilities to audioEngine and Sound instances
+ */
+/**
+ * Initialize spatial audio when audioEngine is initialized
+ * This is called either:
+ * - When audioEngine initializes (if plugin was registered before)
+ * - Immediately during registration (if audioEngine is already initialized)
+ * @param engine - the audio engine singleton
+ */
+export declare function installSpatialOnEngine(engine: AudioEngine): void;
+/**
+ * Extend Sound instances with spatial audio methods
+ * @param sound - the sound the hook fires for
+ * @param options - the options the sound was constructed with
+ */
+export declare function installSpatialOnSound(sound: Sound, options: SoundOptions): void;
+/**
+ * Extend Voice instances with spatial audio properties
+ * @param voice - the individual playing instance
+ * @param parent - the sound the voice belongs to
+ */
+export declare function installSpatialOnVoice(voice: Voice, parent: Sound): void;
+/**
+ * Handle load queue for spatial audio
+ * @param sound - the sound the hook fires for
+ */
+export declare function applySpatialAfterLoad(sound: Sound): void;
+//# sourceMappingURL=spatial.d.ts.map

package/build/audio/backend/spatial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial.d.ts","sourceRoot":"","sources":["../../../src/audio/backend/spatial.ts"],"names":[],"mappings":"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"}