excalibur 0.33.0-alpha.99 → 1.1.0-alpha.310

package/build/esm/src/engine/resources/sound/sound-track.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Context handed to an {@apilink AudioGraphBuilder} each time a {@apilink SoundTrack} starts or resumes
+ * The builder is responsible for connecting `source` to `destination` through any Web Audio nodes it likes
+ * (panners, filters, convolvers, analysers...).
+ */
+export interface AudioGraphContext {
+    /**
+     * The shared {@apilink AudioContext} for this engine, use it to create effect nodes.
+     */
+    readonly audioContext: AudioContext;
+    /**
+     * The track's audio: the buffer source already routed through the track's own volume gain.
+     * Connect this (not `bufferSource`) to `destination`, or the per-play volume is bypassed.
+     * Excalibur disconnects it each time the track restarts or stops.
+     */
+    readonly source: AudioNode;
+    /**
+     * The single-use {@apilink AudioBufferSourceNode} feeding `source`. It is fully configured
+     * (buffer, loop, playbackRate, detune) but not yet started, so you may schedule automation on
+     * its params. It is already connected to `source`; do not connect it anywhere else.
+     */
+    readonly bufferSource: AudioBufferSourceNode;
+    /**
+     * The {@apilink Sound}'s output node (a {@apilink GainNode} that carries {@apilink Sound.volume}
+     * and is connected onwards to the speakers or a {@apilink SoundManager}). Anything you wire must
+     * eventually reach this node or the track will be silent.
+     */
+    readonly destination: AudioNode;
+    /**
+     * The {@apilink SoundTrack} being (re)started, useful for correlation (e.g. as a `WeakMap` key
+     * for per-track effect state) and runtime reads.
+     */
+    readonly track: SoundTrack;
+}
+/**
+ * Hook that wires the Web Audio graph for one playback of a {@apilink Sound}.
+ *
+ * It runs every time a track (re)starts a buffer source: on a fresh `play()`, and again when a
+ * paused or seeked track resumes, because Web Audio buffer sources are single use. Nodes you
+ * create outside the hook can be reused freely (connecting the same two nodes twice is a no-op in
+ * Web Audio), and Excalibur never disconnects nodes it did not create.
+ *
+ * If no hook is provided Excalibur wires `source → destination` directly.
+ *
+ * ```typescript
+ * // A low-pass filter shared by every playback of this sound
+ * const muffle = ex.AudioContextFactory.create().createBiquadFilter();
+ * muffle.type = 'lowpass';
+ * muffle.frequency.value = 400;
+ *
+ * const sound = new ex.Sound({
+ *   paths: ['/sfx/explosion.ogg'],
+ *   onPlay: ({ source, destination }) => {
+ *     source.connect(muffle).connect(destination);
+ *   }
+ * });
+ *
+ * // Spatial audio positioned per play
+ * sound.play({
+ *   onPlay: ({ audioContext, source, destination }) => {
+ *     const panner = audioContext.createPanner();
+ *     panner.positionX.value = enemy.pos.x;
+ *     source.connect(panner).connect(destination);
+ *   }
+ * });
+ * ```
+ */
+export type AudioGraphBuilder = (ctx: AudioGraphContext) => void;
+/**
+ * A single playback of a {@apilink Sound}. Produced by `Sound.play()`, `Sound.start()` and
+ * `Sound.seek()`, see {@apilink Sound.instances}.
+ *
+ * Wraps a single-use Web Audio `AudioBufferSourceNode` routed through a per-track volume gain;
+ * a fresh buffer source is allocated each time the track (re)starts.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API
+ */
+export declare class SoundTrack {
+    private _buffer;
+    private _destination;
+    private _onPlay?;
+    private static _NEXT_ID;
+    /**
+     * Monotonically increasing id, older tracks have lower ids
+     */
+    readonly id: number;
+    private _audioContext;
+    private _gain;
+    private _source;
+    private _playingFuture;
+    private _playStarted;
+    /**
+     * Buffer offset in seconds to start from on the next (re)start
+     */
+    private _offset;
+    /**
+     * Audio context time and buffer offset at which the current source started
+     */
+    private _startedAt;
+    private _startOffset;
+    private _stateMachine;
+    /**
+     * @param _buffer       The decoded audio to play
+     * @param _destination  The node this track is wired into (the owning Sound's output)
+     * @param _onPlay       Optional hook that wires `source → destination`, see {@apilink AudioGraphBuilder}
+     */
+    constructor(_buffer: AudioBuffer, _destination: AudioNode, _onPlay?: AudioGraphBuilder | undefined);
+    /**
+     * Allocate and configure a fresh single-use buffer source and (re)wire the track into the graph
+     */
+    private _createSource;
+    /**
+     * Stop and disconnect the current single-use source, if any
+     */
+    private _disconnectSource;
+    private _volume;
+    /**
+     * Volume [0-1] of this track only, multiplied with {@apilink Sound.volume}. Default 1.
+     */
+    get volume(): number;
+    set volume(value: number);
+    private _loop;
+    /**
+     * Loop infinitely, when changed the live source is updated
+     */
+    get loop(): boolean;
+    set loop(value: boolean);
+    private _playbackRate;
+    /**
+     * Playback speed multiplier, default 1
+     */
+    get playbackRate(): number;
+    set playbackRate(playbackRate: number);
+    private _pitch;
+    /**
+     * Pitch shift in cents (a semitone is 100 cents), default 0. Backed by
+     * {@apilink AudioBufferSourceNode.detune} and composes with {@apilink SoundTrack.playbackRate}.
+     * Note: detune also changes playback speed, this is a Web Audio limitation.
+     */
+    get pitch(): number;
+    set pitch(pitch: number);
+    private _duration;
+    /**
+     * The duration in seconds this track plays for, or the buffer's total duration when unset.
+     *
+     * Note: the duration starts from the seeked position, seeking a 10 second clip to 5 seconds and
+     * setting a duration of 2 plays seconds 5-7.
+     */
+    get duration(): number;
+    set duration(duration: number | undefined);
+    /**
+     * Audio context time in seconds at which the next (re)start is scheduled, 0 means immediately
+     */
+    scheduledStartTime: number;
+    /**
+     * Resolves when the track completes or is stopped
+     */
+    get done(): Promise<boolean>;
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    isStopped(): boolean;
+    /**
+     * Start or resume playback, resolves when the track stops or completes
+     */
+    play(playStarted?: () => any): Promise<boolean>;
+    pause(): void;
+    stop(): void;
+    /**
+     * Move to a position in seconds, the track is paused until the next play()
+     */
+    seek(position: number): void;
+    getTotalPlaybackDuration(): number;
+    /**
+     * Current position in the buffer in seconds
+     */
+    getPlaybackPosition(): number;
+}

package/build/esm/src/engine/resources/sound/sound.d.ts

@@ -0,0 +1,351 @@
+import { SoundTrack, type AudioGraphBuilder } from './sound-track';
+import { NativeSoundEvent, NativeSoundProcessedEvent } from '../../events/media-events';
+import type { Loadable } from '../../interfaces/index';
+import type { Engine } from '../../engine';
+import { Logger } from '../../util/log';
+import type { EventKey, Handler, Subscription } from '../../event-emitter';
+import { EventEmitter } from '../../event-emitter';
+export interface SoundEvents {
+    volumechange: NativeSoundEvent;
+    processed: NativeSoundProcessedEvent;
+    pause: NativeSoundEvent;
+    stop: NativeSoundEvent;
+    playbackend: NativeSoundEvent;
+    resume: NativeSoundEvent;
+    playbackstart: NativeSoundEvent;
+}
+export declare const SoundEvents: {
+    VolumeChange: string;
+    Processed: string;
+    Pause: string;
+    Stop: string;
+    PlaybackEnd: string;
+    Resume: string;
+    PlaybackStart: string;
+};
+export interface SoundOptions<TName extends string = string> {
+    /**
+     * Optional explicit name for this sound. Used as the default key when this
+     * Sound is registered with a {@apilink SoundManager} (otherwise the basename
+     * without extension of the selected path is used, e.g. `/sfx/coin.mp3` → `coin`).
+     *
+     * If passed as a string literal, it is inferred as the {@apilink Sound}'s
+     * name type parameter for strong typing.
+     */
+    name?: TName;
+    /**
+     * @param paths A list of audio sources (clip.wav, clip.mp3, clip.ogg) for this audio clip. This is done for browser compatibility.
+     */
+    paths: string[];
+    /**
+     * Optionally bust the cache on load
+     *
+     * Default is false
+     */
+    bustCache?: boolean;
+    /**
+     * [0-1] 0% to 100%
+     *
+     * By default 1 (100%)
+     */
+    volume?: number;
+    /**
+     * Loop infinitely
+     */
+    loop?: boolean;
+    /**
+     * Multiplyer
+     *
+     * By default 1
+     */
+    playbackRate?: number;
+    /**
+     * Pitch shift in cents (semitones are 100 cents). Default 0 (no change).
+     * Backed by {@apilink AudioBufferSourceNode.detune}; composes with
+     * {@apilink Sound.playbackRate}. Note: changing pitch also affects playback
+     * speed (this is a Web Audio limitation).
+     */
+    pitch?: number;
+    /**
+     * Seconds?
+     *
+     * By default unset, will play the natural length of the clip
+     */
+    duration?: number;
+    /**
+     * Advance to a position in the audio clip
+     */
+    position?: number;
+    /**
+     * Maximum number of simultaneously playing tracks allowed for this single
+     * Sound. When the cap is reached, new `play()` calls are dropped and resolve
+     * to `false`. Default unset (unbounded).
+     */
+    maxConcurrentTracks?: number;
+    /**
+     * What happens when a `maxConcurrentTracks` cap
+     * *`false` (default) drops the new play
+     * *`true` stops the oldest playing track in that scope to make room for it.
+     */
+    voiceStealing?: boolean;
+    /**
+     * Optional hook to wire custom Web Audio nodes (spatial panners, filters,
+     * reverb, analysers...) between this sound's source and its output. Runs each
+     * time a track (re)starts. See {@apilink AudioGraphBuilder}.
+     */
+    onPlay?: AudioGraphBuilder;
+}
+/**
+ * One-off overrides for a single playback, see {@apilink Sound.play}. Unset options fall back to the
+ * {@apilink Sound}'s configuration; nothing here changes the Sound itself.
+ */
+export interface PlayOptions {
+    /**
+     * Volume [0-1] of this track, multiplied with {@apilink Sound.volume}. Default 1.
+     */
+    volume?: number;
+    /**
+     * Pitch shift in cents for this track, overrides {@apilink Sound.pitch}
+     */
+    pitch?: number;
+    /**
+     * Playback speed multiplier for this track, overrides {@apilink Sound.playbackRate}
+     */
+    playbackRate?: number;
+    /**
+     * Loop this track, overrides {@apilink Sound.loop}
+     */
+    loop?: boolean;
+    /**
+     * Position in seconds to start this track from, overrides {@apilink Sound.position}
+     */
+    position?: number;
+    /**
+     * Duration in seconds to play this track for, overrides {@apilink Sound.duration}
+     */
+    duration?: number;
+    /**
+     * Schedule time to play in milliseconds from the audio context origin
+     *
+     * Compute using the audio context
+     *
+     * ```typescript
+     * const sound: Sound = ...;
+     * const oneThousandMillisecondsFromNow = AudioContextFactory.currentTime() + 1000;
+     *
+     * sound.play({ scheduledStartTime: oneThousandMillisecondsFromNow });
+     * ```
+     */
+    scheduledStartTime?: number;
+    /**
+     * Audio graph hook for this track (and its later resumes), overrides {@apilink Sound.onPlay}.
+     * See {@apilink AudioGraphBuilder}.
+     */
+    onPlay?: AudioGraphBuilder;
+}
+/**
+ * The {@apilink Sound} object allows games built in Excalibur to load audio
+ * components, from soundtracks to sound effects. {@apilink Sound} is an {@apilink Loadable}
+ * which means it can be passed to a {@apilink Loader} to pre-load before a game or level.
+ *
+ */
+export declare class Sound<const TName extends string = string> implements Loadable<AudioBuffer> {
+    events: EventEmitter<SoundEvents>;
+    logger: Logger;
+    data: AudioBuffer;
+    private _resource;
+    /**
+     * The registered name of this Sound. Either the explicit `name` option or
+     * the basename-without-extension of the selected path. Used as the default
+     * key when registered with a {@apilink SoundManager}.
+     */
+    readonly name: TName;
+    /**
+     * Position in seconds new tracks start from, see {@apilink PlayOptions.position} for a one-off
+     */
+    position: number | undefined;
+    /**
+     * Indicates whether the clip should loop when complete
+     * @param value  Set the looping flag
+     */
+    set loop(value: boolean);
+    get loop(): boolean;
+    /**
+     * Volume [0-1] applied to every track of this sound, ramped smoothly while playing
+     */
+    set volume(value: number);
+    get volume(): number;
+    private _duration;
+    /**
+     * Get the duration that this audio should play. If unset the total natural playback duration will be used.
+     */
+    get duration(): number | undefined;
+    /**
+     * Set the duration that this audio should play. If unset the total natural playback duration will be used.
+     *
+     * Note: if you seek to a specific point the duration will start from that point, for example
+     *
+     * If you have a 10 second clip, seek to 5 seconds, then set the duration to 2, it will play the clip from 5-7 seconds.
+     */
+    set duration(duration: number | undefined);
+    /**
+     * Return array of Current {@apilink SoundTrack} instances playing or being paused
+     */
+    get instances(): SoundTrack[];
+    get path(): string;
+    set path(val: string);
+    /**
+     * Should excalibur add a cache busting querystring? By default false.
+     * Must be set before loading
+     */
+    get bustCache(): boolean;
+    set bustCache(val: boolean);
+    private _loop;
+    private _volume;
+    private _isStopped;
+    private _tracks;
+    private _engine?;
+    private _wasPlayingOnHidden;
+    private _playbackRate;
+    private _pitch;
+    maxConcurrentTracks: number;
+    voiceStealing: boolean;
+    private _audioContext;
+    /**
+     * Output gain shared by every track of this sound, created on first use
+     */
+    private _output?;
+    /**
+     * Construct a Sound from an options object with an explicit `name`. The class
+     * generic `TName` is inferred from the `name` literal when one is provided.
+     */
+    constructor(options: SoundOptions<TName>);
+    /**
+     * Construct a Sound from a variadic list of audio source paths. `TName` defaults to `string`
+     */
+    constructor(...paths: string[]);
+    /**
+     * Whether or not the browser can play this file as HTML5 Audio
+     */
+    static canPlayFile(file: string): boolean;
+    static canPlayMime(mime: string): boolean;
+    /**
+     * Optional hook to wire custom Web Audio nodes between this sound's source
+     * and its output, runs each time a track (re)starts. See {@apilink AudioGraphBuilder}.
+     */
+    onPlay?: AudioGraphBuilder;
+    /**
+     * Pitch shift in cents (semitones are 100 cents). Default 0 (no change).
+     * Backed by {@apilink AudioBufferSourceNode.detune}; composes with
+     * {@apilink Sound.playbackRate}. Note: changing pitch also affects playback
+     * speed (this is a Web Audio limitation).
+     */
+    get pitch(): number;
+    set pitch(pitch: number);
+    isLoaded(): boolean;
+    load(): Promise<AudioBuffer>;
+    decodeAudio(data: ArrayBuffer): Promise<AudioBuffer>;
+    wireEngine(engine: Engine): void;
+    /**
+     * Returns how many tracks of the sound currently exist (playing or paused)
+     */
+    instanceCount(): number;
+    /**
+     * Returns how many tracks of the sound are currently playing
+     */
+    playingCount(): number;
+    /**
+     * Whether or not the sound is playing right now
+     */
+    isPlaying(): boolean;
+    isPaused(): boolean;
+    isStopped(): boolean;
+    /**
+     * Play a new track of this sound, returns a promise that resolves when that track is done
+     * playing (false if the play was dropped, e.g. by {@apilink Sound.maxConcurrentTracks}).
+     *
+     * Options apply to this track only and never change the Sound's own configuration:
+     *
+     * ```typescript
+     * sound.play();                                   // the sound as configured
+     * sound.play({ volume: 0.3, pitch: -200 });       // quieter and lower, this time only
+     * sound.play({ position: 2, duration: 1 });       // one second starting two seconds in
+     * ```
+     *
+     * To continue paused tracks use {@apilink Sound.resume}, to get a handle on the track
+     * use {@apilink Sound.start}.
+     */
+    play(options?: PlayOptions): Promise<boolean>;
+    /**
+     * Play a new track at a volume [0-1] (multiplied with {@apilink Sound.volume}) for this track only
+     * @deprecated Use `play({ volume })` instead. Will be removed in v1.x
+     */
+    play(volume: number): Promise<boolean>;
+    private _makeRoom;
+    /**
+     * Like {@apilink Sound.play} but returns the {@apilink SoundTrack} synchronously so it can be
+     * stopped, seeked or adjusted while it plays. Returns `null` if the play was dropped.
+     *
+     * ```typescript
+     * const footstep = sound.start({ volume: 0.5 });
+     * footstep?.stop();
+     * await footstep?.done;
+     * ```
+     */
+    start(options?: PlayOptions): SoundTrack | null;
+    /**
+     * Resume every paused (or seeked) track, resolves when they are done playing.
+     * Resolves `false` immediately if nothing was paused.
+     */
+    resume(): Promise<boolean>;
+    /**
+     * Stop the sound, and do not rewind
+     */
+    pause(): void;
+    /**
+     * Stop the sound if it is currently playing and rewind the track. If the sound is not playing, rewinds the track.
+     */
+    stop(): void;
+    get playbackRate(): number;
+    set playbackRate(playbackRate: number);
+    /**
+     * Seek a track to a position in seconds, the track is paused until the next {@apilink Sound.resume}.
+     *
+     * If no track exists one is created so that `seek(); resume()` starts from the position.
+     */
+    seek(position: number, trackId?: number): void;
+    getTotalPlaybackDuration(): number;
+    /**
+     * Return the current playback time of the playing track in seconds from the start.
+     *
+     * Optionally specify the track to query if multiple are playing at once.
+     * @param trackId
+     */
+    getPlaybackPosition(trackId?: number): number;
+    /**
+     * Get Id of provided {@apilink SoundTrack} in current trackList
+     * @param track {@apilink SoundTrack} which Id is to be given
+     */
+    getTrackId(track: SoundTrack): number;
+    private _removeTrack;
+    /**
+     * The {@apilink GainNode} every track of this sound is mixed into, carrying {@apilink Sound.volume}.
+     * Connected straight to the audio context destination until a {@apilink SoundManager} re-routes it
+     * through its mixer graph.
+     */
+    get output(): GainNode;
+    /**
+     * Snapshot the sound's configuration, overlaid with per-play overrides, into a new track
+     */
+    private _createTrack;
+    emit<TEventName extends EventKey<SoundEvents>>(eventName: TEventName, event: SoundEvents[TEventName]): void;
+    emit(eventName: string, event?: any): void;
+    on<TEventName extends EventKey<SoundEvents>>(eventName: TEventName, handler: Handler<SoundEvents[TEventName]>): Subscription;
+    on(eventName: string, handler: Handler<unknown>): Subscription;
+    once<TEventName extends EventKey<SoundEvents>>(eventName: TEventName, handler: Handler<SoundEvents[TEventName]>): Subscription;
+    once(eventName: string, handler: Handler<unknown>): Subscription;
+    off<TEventName extends EventKey<SoundEvents>>(eventName: TEventName, handler: Handler<SoundEvents[TEventName]>): void;
+    off(eventName: string, handler: Handler<unknown>): void;
+    off(eventName: string): void;
+    static fromBlob(blob: Blob): Promise<Sound<string>>;
+}

package/build/{dist → esm/src/engine}/scene.d.ts

@@ -73,8 +73,12 @@ export declare function isSceneConstructor(x: any): x is SceneConstructor;
  * 5. onPostUpdate - called every update
  * 6. onPreDraw - called every draw
  * 7. onPostDraw - called every draw
- * 8. onDeactivate - called teh first frame thescene is no longer current
+ * 8. onDeactivate - called the first frame the scene is no longer current
  *
+ * Each lifecycle stage also fires corresponding {@apilink Plugin} hooks:
+ * `onScenePreInitialize`/`onScenePostInitialize`,
+ * `onScenePreActivate`/`onScenePostActivate`,
+ * `onScenePreDeactivate`/`onScenePostDeactivate`.
  */
 export declare class Scene<TActivationData = unknown> implements CanInitialize, CanActivate<TActivationData>, CanDeactivate, CanUpdate, CanDraw {
     private _logger;
@@ -123,6 +127,7 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
      */
     input: InputHost;
     private _isInitialized;
+    private _lastLightingEnabled;
     private _timers;
     get timers(): readonly Timer[];
     private _cancelQueue;
@@ -155,7 +160,7 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
      *
      * This can be used to configure custom transitions for a scene dynamically
      */
-    onTransition(direction: 'in' | 'out'): Transition | undefined;
+    onTransition(direction: 'in' | 'out'): Transition | null;
     /**
      * This is called before the first update of the {@apilink Scene}. Initializes scene members like the camera. This method is meant to be
      * overridden. This is where initialization of child actors should take place.
@@ -181,7 +186,7 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
      */
     onPreUpdate(engine: Engine, elapsed: number): void;
     /**
-     * Safe to override onPostUpdate lifecycle event handler. Synonymous with `.on('preupdate', (evt) =>{...})`
+     * Safe to override onPostUpdate lifecycle event handler. Synonymous with `.on('postupdate', (evt) =>{...})`
      *
      * `onPostUpdate` is called directly after a scene is updated.
      * @param engine reference to the engine
@@ -189,14 +194,14 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
      */
     onPostUpdate(engine: Engine, elapsed: number): void;
     /**
-     * Safe to override onPreDraw lifecycle event handler. Synonymous with `.on('preupdate', (evt) =>{...})`
+     * Safe to override onPreDraw lifecycle event handler. Synonymous with `.on('predraw', (evt) =>{...})`
      *
      * `onPreDraw` is called directly before a scene is drawn.
      *
      */
     onPreDraw(ctx: ExcaliburGraphicsContext, elapsed: number): void;
     /**
-     * Safe to override onPostDraw lifecycle event handler. Synonymous with `.on('preupdate', (evt) =>{...})`
+     * Safe to override onPostDraw lifecycle event handler. Synonymous with `.on('postdraw', (evt) =>{...})`
      *
      * `onPostDraw` is called directly after a scene is drawn.
      *
@@ -260,6 +265,7 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
      * @internal
      */
     _postdraw(ctx: ExcaliburGraphicsContext, elapsed: number): void;
+    private _checkEnableDisableSystems;
     /**
      * Updates all the actors and timers in the scene. Called by the {@apilink Engine}.
      * @param engine  Reference to the current Engine
@@ -408,6 +414,6 @@ export declare class Scene<TActivationData = unknown> implements CanInitialize,
     isTimerActive(timer: Timer): boolean;
     isCurrentScene(): boolean;
     private _collectActorStats;
-    pauseScene(): void;
-    resumeScene(): void;
+    pause(): void;
+    resume(): void;
 }

package/build/{dist → esm/src/engine}/screen-element.d.ts

@@ -1,5 +1,5 @@
 import type { Engine } from './engine';
-import type { ActorArgs } from './actor';
+import type { ActorOptions } from './actor';
 import { Actor } from './actor';
 /**
  * Type guard to detect a screen element
@@ -12,7 +12,7 @@ export declare function isScreenElement(actor: Actor): actor is ScreenElement;
 export declare class ScreenElement extends Actor {
     protected _engine: Engine;
     constructor();
-    constructor(config?: ActorArgs);
+    constructor(config?: ActorOptions);
     _initialize(engine: Engine): void;
     contains(x: number, y: number, useWorld?: boolean): boolean;
 }