angry-pixel 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.ts CHANGED
@@ -603,13 +603,13 @@ declare class Circumference implements Shape {
603
603
  /**
604
604
  * Broad phase collision methods
605
605
  * - QuadTree: Stores the shapes in an incremental quad tree.
606
- * - SpartialGrid: Stores the shapes in an incremental spartial grid.
606
+ * - SpatialGrid: Stores the shapes in an incremental spatial grid.
607
607
  * @category Config
608
608
  * @public
609
609
  */
610
610
  declare enum BroadPhaseMethods {
611
611
  QuadTree = 0,
612
- SpartialGrid = 1
612
+ SpatialGrid = 1
613
613
  }
614
614
 
615
615
  /**
@@ -718,12 +718,12 @@ type ComponentType<T extends Component = Component> = {
718
718
  * @category Entity-Component-System
719
719
  */
720
720
  type SearchResult<T extends Component> = {
721
- entity: Entity;
722
721
  component: T;
722
+ entity: Entity;
723
723
  };
724
724
  /**
725
725
  * This type represents an Entity Archetype, which defines a template for creating entities with a specific set of components.\
726
- * It specifies which components should be attached to the entity, whether the entity should be enabled/disabled,\
726
+ * It specifies which components should be attached to the entity, which of them should start disabled, whether the entity should be enabled/disabled,\
727
727
  * and can include child archetypes to create hierarchical entity structures.
728
728
  * @public
729
729
  * @category Entity-Component-System
@@ -742,9 +742,9 @@ type SearchResult<T extends Component> = {
742
742
  * const enemyArchetype: Archetype = {
743
743
  * components: [
744
744
  * new Transform(),
745
- * new Enemy(),
746
- * disableComponent(new BoxCollider()) // This component starts disabled
745
+ * new Enemy()
747
746
  * ],
747
+ * disabledComponents: [new BoxCollider()], // The BoxCollider is attached but starts disabled
748
748
  * children: [
749
749
  * {
750
750
  * components: [new WeaponMount()],
@@ -755,19 +755,22 @@ type SearchResult<T extends Component> = {
755
755
  * ```
756
756
  */
757
757
  type Archetype = {
758
- components: (Component | ComponentType | DisabledComponent)[];
758
+ /**
759
+ * Components to attach to the entity. Each entry can be a component instance (cloned on creation, so the archetype can be reused)
760
+ * or a component class (instantiated with no arguments).
761
+ */
762
+ components: (Component | ComponentType)[];
763
+ /**
764
+ * Components to attach to the entity that should start disabled. Same shape as `components`:
765
+ * entries can be component instances (cloned on creation) or component classes (instantiated with no arguments).
766
+ * Do not list the same component type in both arrays.
767
+ */
768
+ disabledComponents?: (Component | ComponentType)[];
769
+ /** Child archetypes. Each one is created as a separate entity parented to this archetype's entity. */
759
770
  children?: Archetype[];
771
+ /** Whether the entity starts enabled. Defaults to `true`. Set to `false` to disable the entity on creation. */
760
772
  enabled?: boolean;
761
773
  };
762
- /**
763
- * This type represents a disabled component
764
- * @public
765
- * @category Entity-Component-System
766
- */
767
- type DisabledComponent = {
768
- enabled: false;
769
- component: Component | ComponentType;
770
- };
771
774
  /**
772
775
  * This interface defines the core structure for system classes in the ECS architecture.\
773
776
  * Systems contain the game logic that operates on entities and their components.\
@@ -871,29 +874,30 @@ type SystemGroup = string | number | symbol;
871
874
  * entityManager.removeComponent(spriteRenderer);
872
875
  *
873
876
  * // Search for entities with specific components
874
- * const searchResult = entityManager.search(SpriteRenderer);
875
- * searchResult.forEach(({component, entity}) => {
876
- * // do something with the component and entity
877
- * })
877
+ * entityManager.search(Enemy, (enemy, entity) => {
878
+ * if (enemy.status !== "alive") return;
879
+ * // do something
880
+ * });
878
881
  *
879
- * const searchResult = entityManager.search(Enemy, (component) => component.status === "alive");
882
+ * const searchResult = entityManager.search(SpriteRenderer);
880
883
  * searchResult.forEach(({component, entity}) => {
881
- * // do something with the component and entity
882
- * })
884
+ * // do something
885
+ * });
883
886
  * ```
884
887
  */
885
888
  declare class EntityManager {
886
889
  private lastEntityId;
887
- private lastComponentTypeId;
888
890
  private entities;
889
891
  private components;
892
+ private entityComponents;
893
+ private componentToEntity;
890
894
  private disabledEntities;
891
895
  private manuallyDisabledEntities;
892
896
  private disabledComponents;
893
897
  private parentEntities;
894
898
  private childEntities;
895
899
  /**
896
- * Creates an entity without component
900
+ * Creates an entity without components.
897
901
  * @return The created Entity
898
902
  * @public
899
903
  * @example
@@ -919,30 +923,41 @@ declare class EntityManager {
919
923
  */
920
924
  createEntity(components: (ComponentType | Component)[], parent?: Entity): Entity;
921
925
  /**
922
- * Creates an Entity based on an Archetype.\
923
- * Since the components are cloned, the archetype can be reused to create multiple entities.
926
+ * Creates an Entity from an Archetype template.\
927
+ * Components are cloned, so the archetype can be reused to create multiple entities.
924
928
  * @param archetype The archetype to create the entity from
925
929
  * @param parent The parent entity (optional)
926
- * @returns The created Entity
930
+ * @return The created Entity
927
931
  * @public
928
932
  * @example
929
933
  * ```js
930
934
  * const archetype = {
931
935
  * components: [
932
936
  * new Transform({position: new Vector2(100, 100)}),
933
- * SpriteRenderer
937
+ * SpriteRenderer,
938
+ * new BoxCollider(),
934
939
  * ],
940
+ * disabledComponents: [BoxCollider],
935
941
  * children: [childArchetype],
936
- * enabled: true
937
- * }
938
- * const entity = entityManager.createEntityFromArchetype(archetype);
942
+ * enabled: true,
943
+ * };
944
+ * const entity = entityManager.createEntity(archetype);
939
945
  * ```
940
946
  */
941
- createEntityFromArchetype({ components, children, enabled }: Archetype, parent?: Entity): Entity;
947
+ createEntity(archetype: Archetype, parent?: Entity): Entity;
948
+ /**
949
+ * Creates an Entity from an Archetype.
950
+ * @param archetype
951
+ * @param parent
952
+ * @returns The created Entity
953
+ * @private
954
+ */
955
+ private createEntityFromArchetype;
942
956
  /**
943
957
  * Creates components from an archetype
944
958
  * @param components The components to create
945
959
  * @param entity The entity to create the components for
960
+ * @param disabled If TRUE, each created component is disabled. Default is FALSE.
946
961
  * @private
947
962
  */
948
963
  private createComponentsFromArchetype;
@@ -1278,63 +1293,67 @@ declare class EntityManager {
1278
1293
  getComponentFromParent<T extends Component>(parent: Entity, componentType: ComponentType<T>): T | undefined;
1279
1294
  /**
1280
1295
  * Performs a search for entities given a component type.\
1281
- * This method returns a collection of objects of type SearchResult, which has the entity found, and the instance of the component.\
1282
- * This search can be filtered by passing as a second argument a filter function.\
1283
- * The third argument determines if disabled entities or components are included in the search result,\its default value is FALSE.
1296
+ * The recommended form passes a callback as the second argument it iterates directly over the underlying store without allocating an intermediate array, which is the right choice for system `onUpdate` and any per-frame loop.\
1297
+ * Without a callback, returns a collection of `SearchResult` objects (each containing the entity and the component instance) that you can sort, slice, or treat as a collection.
1284
1298
  * @param componentType The component class
1285
- * @param filter The filter function
1286
- * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
1299
+ * @param includeDisabled TRUE to include disabled entities and components. Default is FALSE.
1287
1300
  * @returns SearchResult
1288
1301
  * @public
1289
1302
  * @example
1290
1303
  * ```js
1291
- * const searchResult = entityManager.search(SpriteRenderer);
1292
- * searchResult.forEach(({component, entity}) => {
1304
+ * // recommended: pass a callback to iterate without allocations
1305
+ * entityManager.search(SpriteRenderer, (spriteRenderer, entity) => {
1293
1306
  * // do something with the component and entity
1294
- * })
1307
+ * });
1295
1308
  * ```
1296
1309
  * @example
1297
1310
  * ```js
1298
- * const searchResult = entityManager.search(Enemy, (component) => component.status === "alive");
1299
- * searchResult.forEach(({component, entity}) => {
1300
- * // do something with the component and entity
1301
- * })
1311
+ * // short-circuit inside the callback to filter
1312
+ * entityManager.search(Enemy, (enemy, entity) => {
1313
+ * if (enemy.status !== "alive") return;
1314
+ * // ...
1315
+ * });
1302
1316
  * ```
1303
1317
  * @example
1304
1318
  * ```js
1305
- * // include disabled entities and components
1306
- * const searchResult = entityManager.search(Enemy, (component) => component.status === "dead", true);
1319
+ * // alternative: array form, useful when you need to sort/slice/etc.
1320
+ * const searchResult = entityManager.search(SpriteRenderer);
1307
1321
  * searchResult.forEach(({component, entity}) => {
1308
1322
  * // do something with the component and entity
1309
- * })
1323
+ * });
1310
1324
  * ```
1311
- */
1312
- search<T extends Component>(componentType: ComponentType<T>, filter?: (component: T, entity?: Entity) => boolean, includeDisabled?: boolean): SearchResult<T>[];
1313
- /**
1314
- * Performs a search for entities given a component type.\
1315
- * This method returns a collection of objects of type SearchResult, which has the entity found, and the instance of the component.\
1316
- * The second argument determines if disabled entities or components are included in the search result,\its default value is FALSE.
1317
- * @param componentType The component class
1318
- * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
1319
- * @returns SearchResult
1320
- * @public
1321
1325
  * @example
1322
1326
  * ```js
1323
- * const searchResult = entityManager.search(SpriteRenderer);
1324
- * searchResult.forEach(({component, entity}) => {
1325
- * // do something with the component and entity
1326
- * })
1327
+ * // filter the array form
1328
+ * const aliveEnemies = entityManager
1329
+ * .search(Enemy)
1330
+ * .filter(({component}) => component.status === "alive");
1327
1331
  * ```
1328
1332
  * @example
1329
1333
  * ```js
1330
1334
  * // include disabled entities and components
1331
1335
  * const searchResult = entityManager.search(Enemy, true);
1332
- * searchResult.forEach(({component, entity}) => {
1336
+ * ```
1337
+ */
1338
+ search<T extends Component>(componentType: ComponentType<T>): SearchResult<T>[];
1339
+ search<T extends Component>(componentType: ComponentType<T>, includeDisabled: boolean): SearchResult<T>[];
1340
+ /**
1341
+ * Performs a search for entities given a component type and invokes the callback for each match without allocating an intermediate array.\
1342
+ * Intended for hot per-frame loops in systems. The callback receives the component instance and the entity.\
1343
+ * Disabled entities and components are skipped unless `includeDisabled` is TRUE.\
1344
+ * Do NOT add or remove entities/components for the same component type from within the callback.
1345
+ * @param componentType The component class
1346
+ * @param callback Invoked once per matching entity
1347
+ * @param includeDisabled TRUE to include disabled entities and components. Default is FALSE.
1348
+ * @public
1349
+ * @example
1350
+ * ```js
1351
+ * entityManager.search(SpriteRenderer, (spriteRenderer, entity) => {
1333
1352
  * // do something with the component and entity
1334
- * })
1353
+ * });
1335
1354
  * ```
1336
1355
  */
1337
- search<T extends Component>(componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
1356
+ search<T extends Component>(componentType: ComponentType<T>, callback: (component: T, entity: Entity) => void, includeDisabled?: boolean): void;
1338
1357
  /**
1339
1358
  * Performs an entity search given a collection of component types.\
1340
1359
  * The entities found must have an instance of all the given component types.\
@@ -1373,6 +1392,11 @@ declare class EntityManager {
1373
1392
  * ```
1374
1393
  */
1375
1394
  searchInChildren<T extends Component>(parent: Entity, componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
1395
+ /**
1396
+ * Returns the id for the given component type.
1397
+ * @param component The component class
1398
+ * @returns The component type id
1399
+ */
1376
1400
  private getComponentTypeId;
1377
1401
  }
1378
1402
 
@@ -1472,19 +1496,6 @@ declare class SystemManager {
1472
1496
  update(group: SystemGroup): void;
1473
1497
  }
1474
1498
 
1475
- /**
1476
- * Creates a disabled component
1477
- * @param component The component to disable
1478
- * @returns The disabled component
1479
- * @category Entity-Component-System
1480
- * @public
1481
- * @example
1482
- * ```js
1483
- * const disabledTransform = disableComponent(Transform);
1484
- * ```
1485
- */
1486
- declare const disableComponent: (component: Component | ComponentType) => DisabledComponent;
1487
-
1488
1499
  /**
1489
1500
  * Represents a collision between two entities in the game world. It contains information about the colliding entities,
1490
1501
  * their collider components, and resolution data for handling the collision response.
@@ -1601,7 +1612,7 @@ type CollisionMatrix = [string, string][];
1601
1612
  * containerNode: document.getElementById("app"),
1602
1613
  * width: 1920,
1603
1614
  * height: 1080,
1604
- * debugEnabled: false,
1615
+ * debug: { colliders: false, mousePosition: false, textRendererBoundingBoxes: false },
1605
1616
  * canvasColor: "#000000",
1606
1617
  * physicsFramerate: 180,
1607
1618
  * headless: false,
@@ -1612,7 +1623,7 @@ type CollisionMatrix = [string, string][];
1612
1623
  * ["layer1", "layer3"],
1613
1624
  * ],
1614
1625
  * collisionMethod: CollisionMethods.SAT,
1615
- * collisionBroadPhaseMethod: BroadPhaseMethods.SpartialGrid,
1626
+ * collisionBroadPhaseMethod: BroadPhaseMethods.SpatialGrid,
1616
1627
  * }
1617
1628
  * };
1618
1629
  * ```
@@ -1654,11 +1665,11 @@ interface GameConfig {
1654
1665
  dependencies?: [DependencyName, any][];
1655
1666
  /** Collision configuration options */
1656
1667
  collisions?: {
1657
- /** Collision detection method: CollisionMethods.SAT or CollisionMethods.ABB. Default value is CollisionMethods.SAT */
1668
+ /** Collision detection method: CollisionMethods.SAT or CollisionMethods.AABB. Default value is CollisionMethods.SAT */
1658
1669
  collisionMethod?: CollisionMethods;
1659
- /** Define a fixed rectangular area for collision detection */
1670
+ /** Pairs of collision layers that are allowed to collide with each other */
1660
1671
  collisionMatrix?: CollisionMatrix;
1661
- /** Collision broad phase method: BroadPhaseMethods.QuadTree or BroadPhaseMethods.SpartialGrid. Default values is BroadPhaseMethods.SpartialGrid */
1672
+ /** Collision broad phase method: BroadPhaseMethods.QuadTree or BroadPhaseMethods.SpatialGrid. Default values is BroadPhaseMethods.SpatialGrid */
1662
1673
  collisionBroadPhaseMethod?: BroadPhaseMethods;
1663
1674
  };
1664
1675
  }
@@ -1671,6 +1682,15 @@ declare class CreateSystemService {
1671
1682
  createSystemIfNotExists(systemType: SystemType): void;
1672
1683
  }
1673
1684
 
1685
+ /**
1686
+ * A loaded audio asset. Holds both a decoded `AudioBuffer` and an `HTMLAudioElement`.
1687
+ * @public
1688
+ * @category Assets
1689
+ */
1690
+ interface AudioSource {
1691
+ buffer?: AudioBuffer;
1692
+ element: HTMLAudioElement;
1693
+ }
1674
1694
  /**
1675
1695
  * Manages loading and retrieval of game assets including images, fonts, audio files, videos and JSON data.\
1676
1696
  * Provides methods to load assets asynchronously and check their loading status.\
@@ -1686,7 +1706,7 @@ declare class CreateSystemService {
1686
1706
  * this.assetManager.loadJson("data.json");
1687
1707
  *
1688
1708
  * const imageElement = this.assetManager.getImage("image.png");
1689
- * const audioElement = this.assetManager.getAudio("audio.ogg");
1709
+ * const audioSource = this.assetManager.getAudio("audio.ogg");
1690
1710
  * const videoElement = this.assetManager.getVideo("video.mp4");
1691
1711
  * const fontFace = this.assetManager.getFont("custom-font");
1692
1712
  * const jsonData = this.assetManager.getJson("data.json");
@@ -1697,7 +1717,9 @@ declare class CreateSystemService {
1697
1717
  * ```
1698
1718
  */
1699
1719
  declare class AssetManager {
1720
+ private readonly audioContext;
1700
1721
  private readonly assets;
1722
+ constructor(audioContext: AudioContext | null);
1701
1723
  /**
1702
1724
  * Returns TRUE if the assets are loaded
1703
1725
  * @returns TRUE or FALSE
@@ -1714,9 +1736,10 @@ declare class AssetManager {
1714
1736
  * Loads an audio asset
1715
1737
  * @param url The asset URL
1716
1738
  * @param name The asset name [optional]
1717
- * @returns The HTML Audio element created
1739
+ * @returns The {@link AudioSource} (with its `buffer` populated asynchronously), or `null` if no AudioContext is available.
1718
1740
  */
1719
- loadAudio(url: string, name?: string): HTMLAudioElement;
1741
+ loadAudio(url: string, name?: string): AudioSource | null;
1742
+ private decodeAudioBuffer;
1720
1743
  /**
1721
1744
  * Loads a font asset
1722
1745
  * @param family The font family name
@@ -1753,15 +1776,15 @@ declare class AssetManager {
1753
1776
  /**
1754
1777
  * Retrieves an audio asset
1755
1778
  * @param url The asset URL
1756
- * @returns The HTML Audio element
1779
+ * @returns The loaded {@link AudioSource}.
1757
1780
  */
1758
- getAudio(url: string): HTMLAudioElement;
1781
+ getAudio(url: string): AudioSource;
1759
1782
  /**
1760
1783
  * Retrieves an audio asset
1761
1784
  * @param name The asset name
1762
- * @returns The HTML Audio element
1785
+ * @returns The loaded {@link AudioSource}.
1763
1786
  */
1764
- getAudio(name: string): HTMLAudioElement;
1787
+ getAudio(name: string): AudioSource;
1765
1788
  /**
1766
1789
  * Retrieves a font asset
1767
1790
  * @param family The font family name
@@ -2137,7 +2160,7 @@ declare abstract class Scene {
2137
2160
  * containerNode: document.getElementById("app"),
2138
2161
  * width: 1920,
2139
2162
  * height: 1080,
2140
- * debugEnabled: false,
2163
+ * debug: { colliders: false, mousePosition: false, textRendererBoundingBoxes: false },
2141
2164
  * canvasColor: "#000000",
2142
2165
  * physicsFramerate: 180,
2143
2166
  * collisions: {
@@ -2146,7 +2169,7 @@ declare abstract class Scene {
2146
2169
  * ["layer1", "layer3"],
2147
2170
  * ],
2148
2171
  * collisionMethod: CollisionMethods.SAT,
2149
- * collisionBroadPhaseMethod: BroadPhaseMethods.SpartialGrid,
2172
+ * collisionBroadPhaseMethod: BroadPhaseMethods.SpatialGrid,
2150
2173
  * }
2151
2174
  * });
2152
2175
  * game.addScene(MainScene, "MainScene");
@@ -2290,6 +2313,12 @@ declare class Animator {
2290
2313
  /** @internal */
2291
2314
  static componentName: string;
2292
2315
  constructor(options?: Partial<AnimatorOptions>);
2316
+ /** Play the animation. If a new animation name is given, switches to it and resets. */
2317
+ play(animation?: string): void;
2318
+ /** Pause the animation, keeping the current frame. */
2319
+ pause(): void;
2320
+ /** Stop the animation and reset to the first frame. */
2321
+ stop(): void;
2293
2322
  }
2294
2323
  /**
2295
2324
  * Animation configuration
@@ -2403,9 +2432,9 @@ type AnimationSlice = {
2403
2432
  */
2404
2433
  interface AudioPlayerOptions {
2405
2434
  /** The action to perform with the audio source. */
2406
- action: AudioPlayerAction;
2407
- /** The audio source to play. */
2408
- audioSource: HTMLAudioElement | string;
2435
+ action: "stop" | "play" | "pause";
2436
+ /** The audio source to play. Either an `AudioSource` (from `AssetManager.getAudio`) or an asset URL/name string. */
2437
+ audioSource: AudioSource | string;
2409
2438
  /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
2410
2439
  stopOnSceneTransition: boolean;
2411
2440
  /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
@@ -2432,9 +2461,9 @@ interface AudioPlayerOptions {
2432
2461
  */
2433
2462
  declare class AudioPlayer {
2434
2463
  /** The action to perform with the audio source. This action will be erased at the end of the frame */
2435
- action: AudioPlayerAction;
2436
- /** The audio source to play. */
2437
- audioSource: HTMLAudioElement | string;
2464
+ action: "stop" | "play" | "pause";
2465
+ /** The audio source to play. Either an `AudioSource` (from `AssetManager.getAudio`) or an asset URL/name string. */
2466
+ audioSource: AudioSource | string;
2438
2467
  /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
2439
2468
  stopOnSceneTransition: boolean;
2440
2469
  /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
@@ -2442,7 +2471,7 @@ declare class AudioPlayer {
2442
2471
  /** TRUE If the audio source should loop. */
2443
2472
  loop: boolean;
2444
2473
  /** READONLY, The current state of the audio source. */
2445
- state: AudioPlayerState;
2474
+ state: "stopped" | "playing" | "paused";
2446
2475
  /** The volume of the audio source. */
2447
2476
  volume: number;
2448
2477
  /** READONLY, TRUE If the audio source is playing. */
@@ -2452,8 +2481,16 @@ declare class AudioPlayer {
2452
2481
  /** READONLY, TRUE If the audio source is stopped. */
2453
2482
  get stopped(): boolean;
2454
2483
  /** @internal */
2455
- _currentAudioSource: HTMLAudioElement;
2456
- _playPromisePendind: boolean;
2484
+ _currentAudioSource: AudioSource;
2485
+ /** @internal Active BufferSourceNode that's playing the current buffer (null when not playing) */
2486
+ _sourceNode: AudioBufferSourceNode;
2487
+ /** @internal GainNode wired between sourceNode and destination, used to set volume */
2488
+ _gainNode: GainNode;
2489
+ /** @internal AudioContext.currentTime when the current sourceNode started */
2490
+ _startedAt: number;
2491
+ /** @internal Offset (seconds) within the buffer at which the next play should resume from (used on pause) */
2492
+ _pauseOffset: number;
2493
+ /** @internal */
2457
2494
  _playAfterUserInput: boolean;
2458
2495
  /** @internal */
2459
2496
  static componentName: string;
@@ -2461,7 +2498,7 @@ declare class AudioPlayer {
2461
2498
  /**
2462
2499
  * Play the audio source.
2463
2500
  */
2464
- play(audioSource?: HTMLAudioElement): void;
2501
+ play(audioSource?: AudioSource | string): void;
2465
2502
  /**
2466
2503
  * Pause the audio source.
2467
2504
  */
@@ -2471,16 +2508,6 @@ declare class AudioPlayer {
2471
2508
  */
2472
2509
  stop(): void;
2473
2510
  }
2474
- /**
2475
- * @public
2476
- * @category Components Configuration
2477
- */
2478
- type AudioPlayerAction = "stop" | "play" | "pause";
2479
- /**
2480
- * @public
2481
- * @category Components Configuration
2482
- */
2483
- type AudioPlayerState = "stopped" | "playing" | "paused";
2484
2511
 
2485
2512
  /**
2486
2513
  * Button component configuration
@@ -5008,9 +5035,7 @@ declare function gamePreRenderSystem(): (target: SystemType) => void;
5008
5035
  declare function decorate(decorator: (...args: any[]) => any, target: any, propertyKey?: string | symbol | number): void;
5009
5036
 
5010
5037
  /**
5011
- * Configuration options for playing sound effects with the playSfx function.
5012
- * Allows specifying the audio source to play, optional volume level (0-1),
5013
- * and whether the sound should loop continuously.
5038
+ * Configuration options for playing sound effects with {@link playSfx}.
5014
5039
  * @public
5015
5040
  * @category Audio
5016
5041
  * @example
@@ -5020,25 +5045,27 @@ declare function decorate(decorator: (...args: any[]) => any, target: any, prope
5020
5045
  * ```
5021
5046
  * @example
5022
5047
  * ```javascript
5023
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5024
5048
  * playSfx({ audioSource, volume: 0.5 });
5025
5049
  * ```
5026
5050
  * @example
5027
5051
  * ```javascript
5028
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5029
5052
  * playSfx({ audioSource, loop: true });
5030
5053
  * ```
5031
5054
  */
5032
5055
  interface PlaySfxOptions {
5033
- audioSource: HTMLAudioElement;
5056
+ /** The audio asset to play (typically obtained via `AssetManager.getAudio`). */
5057
+ audioSource: AudioSource;
5058
+ /** The volume of the audio source. */
5034
5059
  volume?: number;
5060
+ /** TRUE If the audio source should loop. */
5035
5061
  loop?: boolean;
5036
5062
  }
5037
5063
  /**
5038
- * Plays a sound effect from the beginning, even if it's currently playing. Ideal for one-shot sound effects like explosions, impacts, or UI feedback.\
5039
- * While this function can play any audio, it's recommended to use the AudioPlayer component for background music or longer tracks.\
5040
- * The AudioPlayer component provides additional features like handling browser autoplay policies, fading, and advanced playback control.
5041
- * @param playSfxOptions - The options for playing the sound effect.
5064
+ * Plays a sound effect from the beginning, even if it's currently playing. Ideal for one-shot sound effects like
5065
+ * explosions, impacts, or UI feedback.\
5066
+ * For background music or longer tracks with pause/resume semantics, prefer the `AudioPlayer` component
5067
+ * (which uses the Web Audio API and handles browser autoplay policies).
5068
+ * @param options Sound effect configuration.
5042
5069
  * @public
5043
5070
  * @category Audio
5044
5071
  * @example
@@ -5048,21 +5075,18 @@ interface PlaySfxOptions {
5048
5075
  * ```
5049
5076
  * @example
5050
5077
  * ```javascript
5051
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5052
5078
  * playSfx({ audioSource, volume: 0.5 });
5053
5079
  * ```
5054
5080
  * @example
5055
5081
  * ```javascript
5056
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5057
5082
  * playSfx({ audioSource, loop: true });
5058
5083
  * ```
5059
5084
  */
5060
5085
  declare const playSfx: ({ audioSource, volume, loop }: PlaySfxOptions) => void;
5061
5086
  /**
5062
5087
  * Stops a sound effect by pausing playback and resetting its position to the beginning.\
5063
- * Useful for immediately silencing sound effects or interrupting looped audio.\
5064
- * Note that this completely stops the audio - to temporarily pause, use audioSource.pause() directly.
5065
- * @param audioSource - The audio source to stop.
5088
+ * Useful for immediately silencing sound effects or interrupting looped audio.
5089
+ * @param audioSource The audio asset to stop.
5066
5090
  * @public
5067
5091
  * @category Audio
5068
5092
  * @example
@@ -5071,7 +5095,7 @@ declare const playSfx: ({ audioSource, volume, loop }: PlaySfxOptions) => void;
5071
5095
  * stopSfx(audioSource);
5072
5096
  * ```
5073
5097
  */
5074
- declare const stopSfx: (audioSource: HTMLAudioElement) => void;
5098
+ declare const stopSfx: (audioSource: AudioSource) => void;
5075
5099
 
5076
5100
  /**
5077
5101
  * Symbols to be used as dependency identifiers
@@ -5090,4 +5114,4 @@ declare const SYMBOLS: {
5090
5114
  TimeManager: symbol;
5091
5115
  };
5092
5116
 
5093
- export { Animation, type AnimationOptions, type AnimationSlice, Animator, type AnimatorOptions, type Archetype, AssetManager, AudioPlayer, type AudioPlayerAction, type AudioPlayerOptions, type AudioPlayerState, BallCollider, type BallColliderOptions, BoxCollider, type BoxColliderOptions, BroadPhaseMethods, Button, type ButtonOptions, ButtonShape, Camera, type CameraOptions, type Chunk, Circumference, type Collider, type Collision, type CollisionMatrix, CollisionMethods, CollisionRepository, type CollisionResolution, type Component, type ComponentType, DarknessRenderer, type DarknessRendererOptions, type DependencyName, type DependencyType, type DisabledComponent, EdgeCollider, type EdgeColliderOptions, type Entity, EntityManager, Game, type GameConfig, GameSystem, GamepadController, GeometricRenderer, type GeometricRendererOptions, GeometricShape, InputManager, type IntervalOptions, Keyboard, LightRenderer, type LightRendererOptions, MaskRenderer, type MaskRendererOptions, MaskShape, Mouse, type PlaySfxOptions, Polygon, PolygonCollider, type PolygonColliderOptions, type PropertyKey, Rectangle, RigidBody, type RigidBodyOptions, RigidBodyType, SYMBOLS, Scene, SceneManager, type SceneType, type SearchResult, type Shape, type Slice, SpriteRenderer, type SpriteRendererOptions, type System, type SystemGroup, SystemManager, type SystemType, TextAlignment, TextRenderer, type TextRendererOptions, type TiledChunk, type TiledLayer, type TiledObject, type TiledObjectLayer, type TiledProperty, type TiledTilemap, TiledWrapper, type TiledWrapperOptions, TilemapCollider, type TilemapColliderOptions, TilemapOrientation, TilemapRenderer, type TilemapRendererOptions, type Tileset, TimeManager, type TouchInteraction, TouchScreen, Transform, type TransformOptions, Vector2, type VibrationInput, VideoRenderer, type VideoRendererOptions, between, clamp, debugRenderLayer, decorate, defaultRenderLayer, defaultTextureAtlasOptions, degreesToRadians, disableComponent, fixedRound, gameLogicSystem, gamePhysicsSystem, gamePreRenderSystem, inject, injectable, playSfx, radiansToDegrees, randomFloat, randomInt, range, rgbToHex, stopSfx };
5117
+ export { Animation, type AnimationOptions, type AnimationSlice, Animator, type AnimatorOptions, type Archetype, AssetManager, AudioPlayer, type AudioPlayerOptions, type AudioSource, BallCollider, type BallColliderOptions, BoxCollider, type BoxColliderOptions, BroadPhaseMethods, Button, type ButtonOptions, ButtonShape, Camera, type CameraOptions, type Chunk, Circumference, type Collider, type Collision, type CollisionMatrix, CollisionMethods, CollisionRepository, type CollisionResolution, type Component, type ComponentType, DarknessRenderer, type DarknessRendererOptions, type DependencyName, type DependencyType, EdgeCollider, type EdgeColliderOptions, type Entity, EntityManager, Game, type GameConfig, GameSystem, GamepadController, GeometricRenderer, type GeometricRendererOptions, GeometricShape, InputManager, type IntervalOptions, Keyboard, LightRenderer, type LightRendererOptions, MaskRenderer, type MaskRendererOptions, MaskShape, Mouse, type PlaySfxOptions, Polygon, PolygonCollider, type PolygonColliderOptions, type PropertyKey, Rectangle, RigidBody, type RigidBodyOptions, RigidBodyType, SYMBOLS, Scene, SceneManager, type SceneType, type SearchResult, type Shape, type Slice, SpriteRenderer, type SpriteRendererOptions, type System, type SystemGroup, SystemManager, type SystemType, TextAlignment, TextRenderer, type TextRendererOptions, type TiledChunk, type TiledLayer, type TiledObject, type TiledObjectLayer, type TiledProperty, type TiledTilemap, TiledWrapper, type TiledWrapperOptions, TilemapCollider, type TilemapColliderOptions, TilemapOrientation, TilemapRenderer, type TilemapRendererOptions, type Tileset, TimeManager, type TouchInteraction, TouchScreen, Transform, type TransformOptions, Vector2, type VibrationInput, VideoRenderer, type VideoRendererOptions, between, clamp, debugRenderLayer, decorate, defaultRenderLayer, defaultTextureAtlasOptions, degreesToRadians, fixedRound, gameLogicSystem, gamePhysicsSystem, gamePreRenderSystem, inject, injectable, playSfx, radiansToDegrees, randomFloat, randomInt, range, rgbToHex, stopSfx };