incanto 0.1.0

package/dist/register-BuUV1_KB.js

@@ -0,0 +1,561 @@
+import { f as Node } from "./loader-CGs_G-r0.js";
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { t as Rng } from "./rng-DP-SR7eg.js";
+import { l as registerNode } from "./registry-BVJ2HbCn.js";
+//#region src/core/audio/sfx-presets.ts
+/**
+* A tasteful, distinct set of common game sounds. Pick one via
+* `AudioPlayer.preset`. Tuned by ear for crisp arcade feel; `seed`/`pitch`
+* props add free variation so repeated sounds don't feel robotic.
+*/
+const SFX_PRESETS = {
+	coin: {
+		wave: "square",
+		baseFreq: 988,
+		freqRamp: 1800,
+		attack: 0,
+		sustain: .04,
+		decay: .18,
+		duty: .5,
+		volume: .4
+	},
+	pickup: {
+		wave: "sine",
+		baseFreq: 660,
+		freqRamp: 900,
+		attack: .005,
+		sustain: .05,
+		decay: .12,
+		volume: .45
+	},
+	jump: {
+		wave: "square",
+		baseFreq: 320,
+		freqRamp: 600,
+		attack: 0,
+		sustain: .03,
+		decay: .12,
+		duty: .35,
+		volume: .4
+	},
+	hurt: {
+		wave: "sawtooth",
+		baseFreq: 380,
+		freqRamp: -520,
+		attack: 0,
+		sustain: .05,
+		decay: .16,
+		volume: .5
+	},
+	hit: {
+		wave: "noise",
+		baseFreq: 600,
+		freqRamp: -400,
+		attack: 0,
+		sustain: .02,
+		decay: .1,
+		volume: .55
+	},
+	explosion: {
+		wave: "noise",
+		baseFreq: 420,
+		freqRamp: -360,
+		attack: 0,
+		sustain: .12,
+		decay: .5,
+		volume: .6
+	},
+	powerup: {
+		wave: "square",
+		baseFreq: 440,
+		freqRamp: 1200,
+		attack: .01,
+		sustain: .18,
+		decay: .22,
+		duty: .5,
+		vibratoDepth: .08,
+		vibratoRate: 18,
+		volume: .4
+	},
+	laser: {
+		wave: "sawtooth",
+		baseFreq: 1400,
+		freqRamp: -2600,
+		attack: 0,
+		sustain: .03,
+		decay: .14,
+		volume: .4
+	},
+	shoot: {
+		wave: "square",
+		baseFreq: 900,
+		freqRamp: -1400,
+		attack: 0,
+		sustain: .02,
+		decay: .1,
+		duty: .25,
+		volume: .45
+	},
+	blip: {
+		wave: "square",
+		baseFreq: 760,
+		freqRamp: 0,
+		attack: 0,
+		sustain: .015,
+		decay: .04,
+		duty: .5,
+		volume: .35
+	},
+	select: {
+		wave: "triangle",
+		baseFreq: 520,
+		freqRamp: 420,
+		attack: .002,
+		sustain: .04,
+		decay: .08,
+		volume: .4
+	},
+	step: {
+		wave: "noise",
+		baseFreq: 220,
+		freqRamp: -120,
+		attack: 0,
+		sustain: .01,
+		decay: .05,
+		volume: .3
+	},
+	win: {
+		wave: "square",
+		baseFreq: 523,
+		freqRamp: 900,
+		attack: .01,
+		sustain: .35,
+		decay: .3,
+		duty: .5,
+		vibratoDepth: .05,
+		vibratoRate: 10,
+		volume: .42
+	},
+	lose: {
+		wave: "sawtooth",
+		baseFreq: 392,
+		freqRamp: -300,
+		attack: .01,
+		sustain: .3,
+		decay: .4,
+		volume: .45
+	}
+};
+const SFX_PRESET_NAMES = Object.keys(SFX_PRESETS);
+const TWO_PI = Math.PI * 2;
+/**
+* Render a preset to mono PCM in [-1, 1]. PURE: identical inputs → identical
+* output (the only randomness is the seeded noise generator), so determinism is
+* unit-testable headlessly. Length = ceil((attack+sustain+decay) * sampleRate).
+*/
+function synthSfx(params, opts = {}) {
+	const sampleRate = opts.sampleRate ?? 44100;
+	const pitch = opts.pitch ?? 1;
+	const rng = new Rng((opts.seed ?? 0) ^ 42405);
+	const total = params.attack + params.sustain + params.decay;
+	const length = Math.max(1, Math.ceil(total * sampleRate));
+	const out = new Float32Array(length);
+	const duty = params.duty ?? .5;
+	const vibDepth = params.vibratoDepth ?? 0;
+	const vibRate = params.vibratoRate ?? 0;
+	let phase = 0;
+	let lastNoise = rng.range(-1, 1);
+	let noiseHold = 0;
+	for (let i = 0; i < length; i++) {
+		const t = i / sampleRate;
+		let env;
+		if (t < params.attack) env = params.attack > 0 ? t / params.attack : 1;
+		else if (t < params.attack + params.sustain) env = 1;
+		else {
+			const d = t - params.attack - params.sustain;
+			env = params.decay > 0 ? Math.max(0, 1 - d / params.decay) : 0;
+		}
+		let freq = (params.baseFreq + params.freqRamp * t) * pitch;
+		if (vibDepth > 0 && vibRate > 0) freq += freq * vibDepth * Math.sin(TWO_PI * vibRate * t);
+		freq = Math.max(0, freq);
+		phase += freq / sampleRate;
+		phase -= Math.floor(phase);
+		let sample;
+		switch (params.wave) {
+			case "square":
+				sample = phase < duty ? 1 : -1;
+				break;
+			case "sawtooth":
+				sample = 2 * phase - 1;
+				break;
+			case "triangle":
+				sample = 4 * Math.abs(phase - .5) - 1;
+				break;
+			case "sine":
+				sample = Math.sin(TWO_PI * phase);
+				break;
+			default:
+				noiseHold -= freq / sampleRate;
+				if (noiseHold <= 0) {
+					lastNoise = rng.range(-1, 1);
+					noiseHold += 1;
+				}
+				sample = lastNoise;
+				break;
+		}
+		out[i] = clamp$1(sample * env * params.volume);
+	}
+	return out;
+}
+function clamp$1(v) {
+	return v < -1 ? -1 : v > 1 ? 1 : v;
+}
+//#endregion
+//#region src/core/audio/spatial.ts
+const ROLLOFF_MODELS = [
+	"inverse",
+	"linear",
+	"exponential"
+];
+/**
+* Gain (0..1) for a source `distance` units from the listener, per the chosen
+* model. Identical to the WebAudio PannerNode formulas so the headless number
+* matches the browser panner:
+*
+* - inverse:     ref / (ref + factor·(clamp(d) − ref))
+* - linear:      1 − factor·(clamp(d) − ref) / (max − ref)
+* - exponential: (clamp(d) / ref)^(−factor)
+*
+* where `clamp(d)` is `d` clamped to `[ref, max]`. Always full inside
+* `refDistance`; monotonic non-increasing out to `maxDistance`. Non-finite or
+* degenerate inputs return a safe finite gain.
+*/
+function spatialGain(distance, params) {
+	const ref = Math.max(0, params.refDistance);
+	const max = Math.max(ref, params.maxDistance);
+	const factor = params.rolloffFactor ?? 1;
+	if (!Number.isFinite(distance)) return 1;
+	const d = clamp(distance, ref, max);
+	if (d <= ref) return 1;
+	let g;
+	switch (params.rolloff) {
+		case "linear": {
+			const span = max - ref;
+			g = span <= 0 ? 1 : 1 - factor * (d - ref) / span;
+			break;
+		}
+		case "exponential":
+			g = ref <= 0 ? 1 : (d / ref) ** -factor;
+			break;
+		default:
+			g = ref / (ref + factor * (d - ref));
+			break;
+	}
+	if (!Number.isFinite(g)) return 0;
+	return clamp01(g);
+}
+const scratchToSource = [
+	0,
+	0,
+	0
+];
+/**
+* Stereo pan (−1 left … 0 center … +1 right) for a source at `sourcePos`,
+* relative to the listener's orientation. Projects the listener→source vector
+* onto the listener's RIGHT axis (forward × up) and normalizes by its length —
+* sign tells left/right, magnitude tells how far off-axis. A source at the
+* listener position (or dead ahead) is centered. Result clamped to [−1, 1].
+*
+* This is the CPU twin of what HRTF/equalpower panning does to the azimuth; the
+* real PannerNode does the full spatialization, but exposing the sign here makes
+* the geometry unit-testable and lets the 2D fallback pan by the same rule.
+*/
+function spatialPan(sourcePos, listener) {
+	const dx = sourcePos[0] - listener.position[0];
+	const dy = sourcePos[1] - listener.position[1];
+	const dz = sourcePos[2] - listener.position[2];
+	const len = Math.hypot(dx, dy, dz);
+	if (len < 1e-6) return 0;
+	scratchToSource[0] = dx / len;
+	scratchToSource[1] = dy / len;
+	scratchToSource[2] = dz / len;
+	const [fx, fy, fz] = listener.forward;
+	const [ux, uy, uz] = listener.up;
+	const rx = fy * uz - fz * uy;
+	const ry = fz * ux - fx * uz;
+	const rz = fx * uy - fy * ux;
+	const rLen = Math.hypot(rx, ry, rz);
+	if (rLen < 1e-6) return 0;
+	return clamp((scratchToSource[0] * rx + scratchToSource[1] * ry + scratchToSource[2] * rz) / rLen, -1, 1);
+}
+function clamp(v, lo, hi) {
+	return v < lo ? lo : v > hi ? hi : v;
+}
+function clamp01(v) {
+	return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+function createElement() {
+	if (typeof Audio === "undefined") return null;
+	return new Audio();
+}
+/**
+* One sound. `play()` (or `autoplay: true`) starts it; `finished` fires when
+* it ends. Browsers block audio before the first user gesture — a blocked
+* play marks `pendingGesture`; `createGame` retries pending players on the
+* first pointer/key gesture automatically.
+*
+* Two playback modes:
+* - `preset: 'custom'` (default) → plays the audio file at `src` via an HTMLAudio
+*   element (good for music / long clips; supports `loop`).
+* - `preset: 'coin' | 'jump' | …` (a procedural SFX preset) → synthesizes a
+*   zero-asset sound through WebAudio: instant, deterministic, overlap-friendly
+*   for rapid-fire SFX. `pitch`/`seed` vary it. The art-free audio analog of the
+*   particle presets. See `incanto-audio.md` for the full preset list.
+*
+* Volume routes through the engine's buses: `engine.audio.master × bus(sfx|music)
+* × volume`. Set `engine.audio.master`/`sfx`/`music`/`muted` for global control.
+*/
+var AudioPlayer = class extends Node {
+	static typeName = "AudioPlayer";
+	static signals = ["finished"];
+	static props = {
+		src: { default: "" },
+		preset: {
+			default: "custom",
+			options: ["custom", ...SFX_PRESET_NAMES]
+		},
+		volume: { default: 1 },
+		pitch: { default: 1 },
+		seed: { default: 0 },
+		bus: {
+			default: "sfx",
+			options: ["sfx", "music"]
+		},
+		loop: { default: false },
+		autoplay: { default: false },
+		spatial: { default: false },
+		refDistance: { default: 1 },
+		maxDistance: { default: 50 },
+		rolloff: {
+			default: "inverse",
+			options: [...ROLLOFF_MODELS]
+		}
+	};
+	/** Audio file url (same resolution rules as scene asset urls). Used when
+	*  `preset === 'custom'`; ignored for procedural presets. */
+	src = "";
+	/** A procedural SFX preset name (zero-asset), or 'custom' to use `src`. */
+	preset = "custom";
+	volume = 1;
+	/** Pitch multiplier for procedural presets (1 = unchanged). */
+	pitch = 1;
+	/** Variation seed for noisy presets (e.g. explosion/hit/step). */
+	seed = 0;
+	/** Which volume bus this routes through. */
+	bus = "sfx";
+	loop = false;
+	/** Start on the first frame in the tree (subject to the gesture policy). */
+	autoplay = false;
+	/**
+	* 3D positional audio: in a 3D scene the sound pans + attenuates by the
+	* emitter's world position relative to the active Camera3D (the listener).
+	* Default false → identical non-spatial behavior (back-compat). In a 2D scene
+	* spatial is currently ignored (the adapter feeds no pose) — see incanto-audio.
+	*/
+	spatial = false;
+	/** Distance at which spatial gain is full; closer never gets louder. */
+	refDistance = 1;
+	/** Distance past which spatial gain stops falling. */
+	maxDistance = 50;
+	/** Spatial attenuation curve: 'inverse' | 'linear' | 'exponential'. */
+	rolloff = "inverse";
+	/** Loader hook: unknown presets / buses fail at LOAD (agents self-correct). */
+	static validateJson(node) {
+		const a = node;
+		if (a.preset !== "custom" && !SFX_PRESET_NAMES.includes(a.preset)) throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' preset must be 'custom' or one of [${SFX_PRESET_NAMES.join(", ")}], got '${a.preset}'.`, {
+			prop: "preset",
+			validOptions: SFX_PRESET_NAMES
+		});
+		if (a.bus !== "sfx" && a.bus !== "music") throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' bus must be 'sfx' or 'music', got '${a.bus}'.`, {
+			prop: "bus",
+			validOptions: ["sfx", "music"]
+		});
+		if (!ROLLOFF_MODELS.includes(a.rolloff)) throw new IncantoError("BAD_FORMAT", `AudioPlayer '${node.name}' rolloff must be one of [${ROLLOFF_MODELS.join(", ")}], got '${a.rolloff}'.`, {
+			prop: "rolloff",
+			validOptions: [...ROLLOFF_MODELS]
+		});
+	}
+	/** A play() was blocked by the browser's autoplay policy. */
+	pendingGesture = false;
+	element = null;
+	_playing = false;
+	autoplayed = false;
+	/** Last spatial pose pushed by the 3D adapter (null until/unless spatial). */
+	_spatialPose = null;
+	get playing() {
+		return this._playing;
+	}
+	/**
+	* @internal Per-frame spatial feed from the 3D adapter (detected structurally
+	* by syncTree). Stores the emitter world position + listener pose; ignored
+	* unless `spatial` is on. Headless / 2D scenes never call this.
+	*/
+	_setSpatialPose(pose) {
+		this._spatialPose = pose;
+	}
+	/** Final gain = engine buses × this volume (1 when not in a tree). */
+	gain() {
+		const buses = this.tree?.engine?.audio;
+		return buses ? buses.effectiveVolume(this.bus, this.volume) : this.volume;
+	}
+	/** Distance gain for the src/element path (1 when not spatial / no pose). */
+	spatialElementGain() {
+		if (!this.spatial || !this._spatialPose) return 1;
+		const { position, listener } = this._spatialPose;
+		const dx = position[0] - listener.position[0];
+		const dy = position[1] - listener.position[1];
+		const dz = position[2] - listener.position[2];
+		return spatialGain(Math.hypot(dx, dy, dz), {
+			refDistance: this.refDistance,
+			maxDistance: this.maxDistance,
+			rolloff: this.rolloff
+		});
+	}
+	/** The `spatial` option for the SFX path, or undefined when not spatial. */
+	spatialPlay() {
+		if (!this.spatial || !this._spatialPose) return void 0;
+		return {
+			position: this._spatialPose.position,
+			listener: this._spatialPose.listener,
+			refDistance: this.refDistance,
+			maxDistance: this.maxDistance,
+			rolloff: this.rolloff
+		};
+	}
+	play() {
+		if (this.preset !== "custom") {
+			this.playPreset();
+			return;
+		}
+		if (!this.src) return;
+		if (!this.element) {
+			this.element = createElement();
+			if (!this.element) return;
+			this.element.addEventListener("ended", () => {
+				if (this.loop) return;
+				this._playing = false;
+				this.emit("finished");
+			});
+		}
+		const el = this.element;
+		el.src = this.src;
+		el.volume = this.gain() * this.spatialElementGain();
+		el.loop = this.loop;
+		this._playing = true;
+		this.pendingGesture = false;
+		el.play().catch(() => {
+			this._playing = false;
+			this.pendingGesture = true;
+		});
+	}
+	/**
+	* Procedural-SFX path: synthesize the preset and fire it through WebAudio
+	* (low-latency, overlap-friendly). Fire-and-forget — no `finished`/`playing`
+	* tracking (these are short one-shots, not the element-driven `src` clip).
+	* Headless (no AudioContext) → silent no-op. WebAudio also needs a gesture;
+	* a suspended context is resumed by the same unlock listener as `src` players.
+	*/
+	playPreset() {
+		const params = SFX_PRESETS[this.preset];
+		if (!params) return;
+		const sfx = this.tree?.engine?.sfx;
+		if (!sfx) return;
+		sfx.play(params, this.gain(), {
+			pitch: this.pitch,
+			seed: this.seed,
+			spatial: this.spatialPlay()
+		});
+	}
+	stop() {
+		if (this.element) {
+			this.element.pause();
+			this.element.currentTime = 0;
+		}
+		this._playing = false;
+		this.pendingGesture = false;
+	}
+	/** Replay a gesture-blocked play (wired to the first user gesture). */
+	retryPending() {
+		if (this.pendingGesture) this.play();
+	}
+	update(_dt) {
+		if (this.autoplay && !this.autoplayed) {
+			this.autoplayed = true;
+			this.play();
+		}
+		if (this.element && this._playing) {
+			this.element.volume = this.gain() * this.spatialElementGain();
+			this.element.loop = this.loop;
+		}
+	}
+};
+//#endregion
+//#region src/core/nodes/timer.ts
+/**
+* The canonical serializable game clock — never `setTimeout` in game logic.
+* Emits `timeout` every `waitTime` seconds (once with `oneShot`).
+*/
+var Timer = class extends Node {
+	static typeName = "Timer";
+	static signals = ["timeout"];
+	static props = {
+		waitTime: { default: 1 },
+		oneShot: { default: false },
+		autostart: { default: false }
+	};
+	/** Seconds between timeouts. */
+	waitTime = 1;
+	oneShot = false;
+	autostart = false;
+	running = false;
+	remaining = 0;
+	start(time) {
+		if (time !== void 0) this.waitTime = time;
+		this.remaining = this.waitTime;
+		this.running = true;
+	}
+	stop() {
+		this.running = false;
+	}
+	onReady() {
+		if (this.autostart) this.start();
+	}
+	update(dt) {
+		if (!this.running) return;
+		if (this.waitTime <= 0) {
+			this.stop();
+			return;
+		}
+		this.remaining -= dt;
+		while (this.remaining <= 0 && this.running) {
+			this.emit("timeout");
+			if (this.oneShot) this.stop();
+			else if (this.waitTime <= 0) this.stop();
+			else this.remaining += this.waitTime;
+		}
+	}
+};
+//#endregion
+//#region src/core/register.ts
+/**
+* Register the core node types. Call once in your game entry before loading
+* scenes. Registration is explicit — never an import-time side effect — so
+* bundler tree-shaking can never silently drop node types.
+*/
+function registerCoreNodes() {
+	registerNode(Node);
+	registerNode(Timer);
+	registerNode(AudioPlayer);
+}
+//#endregion
+export { spatialGain as a, SFX_PRESET_NAMES as c, ROLLOFF_MODELS as i, synthSfx as l, Timer as n, spatialPan as o, AudioPlayer as r, SFX_PRESETS as s, registerCoreNodes as t };