angry-pixel 2.2.2 → 2.3.1

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
@@ -904,8 +908,8 @@ declare class EntityManager {
904
908
  createEntity(): Entity;
905
909
  /**
906
910
  * Creates an Entity with the given components.\
907
- * Since the components are not cloned, the collection of components must not be reused.
908
- * @param components A collection of component instances and component classes
911
+ * Component instances are cloned, so the collection of components can be reused to create multiple entities.
912
+ * @param components A collection of component instances and/or component classes
909
913
  * @param parent The parent entity (optional)
910
914
  * @return The created Entity
911
915
  * @public
@@ -919,33 +923,45 @@ 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
+ * Component instances 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
+ private createEntityFromArray;
949
+ /**
950
+ * Creates an Entity from an Archetype.
951
+ * @param archetype
952
+ * @param parent
953
+ * @returns The created Entity
954
+ * @private
955
+ */
956
+ private createEntityFromArchetype;
942
957
  /**
943
- * Creates components from an archetype
958
+ * Creates components from a collection of component types and instances, and adds them to the entity.\
944
959
  * @param components The components to create
945
960
  * @param entity The entity to create the components for
961
+ * @param disabled If TRUE, each created component is disabled. Default is FALSE.
946
962
  * @private
947
963
  */
948
- private createComponentsFromArchetype;
964
+ private createComponentsForEntity;
949
965
  /**
950
966
  * Removes an Entity and all its Components
951
967
  * @param entity The entity to remove
@@ -1278,63 +1294,67 @@ declare class EntityManager {
1278
1294
  getComponentFromParent<T extends Component>(parent: Entity, componentType: ComponentType<T>): T | undefined;
1279
1295
  /**
1280
1296
  * 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.
1297
+ * 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.\
1298
+ * 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
1299
  * @param componentType The component class
1285
- * @param filter The filter function
1286
- * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
1300
+ * @param includeDisabled TRUE to include disabled entities and components. Default is FALSE.
1287
1301
  * @returns SearchResult
1288
1302
  * @public
1289
1303
  * @example
1290
1304
  * ```js
1291
- * const searchResult = entityManager.search(SpriteRenderer);
1292
- * searchResult.forEach(({component, entity}) => {
1305
+ * // recommended: pass a callback to iterate without allocations
1306
+ * entityManager.search(SpriteRenderer, (spriteRenderer, entity) => {
1293
1307
  * // do something with the component and entity
1294
- * })
1308
+ * });
1295
1309
  * ```
1296
1310
  * @example
1297
1311
  * ```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
- * })
1312
+ * // short-circuit inside the callback to filter
1313
+ * entityManager.search(Enemy, (enemy, entity) => {
1314
+ * if (enemy.status !== "alive") return;
1315
+ * // ...
1316
+ * });
1302
1317
  * ```
1303
1318
  * @example
1304
1319
  * ```js
1305
- * // include disabled entities and components
1306
- * const searchResult = entityManager.search(Enemy, (component) => component.status === "dead", true);
1320
+ * // alternative: array form, useful when you need to sort/slice/etc.
1321
+ * const searchResult = entityManager.search(SpriteRenderer);
1307
1322
  * searchResult.forEach(({component, entity}) => {
1308
1323
  * // do something with the component and entity
1309
- * })
1324
+ * });
1310
1325
  * ```
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
1326
  * @example
1322
1327
  * ```js
1323
- * const searchResult = entityManager.search(SpriteRenderer);
1324
- * searchResult.forEach(({component, entity}) => {
1325
- * // do something with the component and entity
1326
- * })
1328
+ * // filter the array form
1329
+ * const aliveEnemies = entityManager
1330
+ * .search(Enemy)
1331
+ * .filter(({component}) => component.status === "alive");
1327
1332
  * ```
1328
1333
  * @example
1329
1334
  * ```js
1330
1335
  * // include disabled entities and components
1331
1336
  * const searchResult = entityManager.search(Enemy, true);
1332
- * searchResult.forEach(({component, entity}) => {
1337
+ * ```
1338
+ */
1339
+ search<T extends Component>(componentType: ComponentType<T>): SearchResult<T>[];
1340
+ search<T extends Component>(componentType: ComponentType<T>, includeDisabled: boolean): SearchResult<T>[];
1341
+ /**
1342
+ * Performs a search for entities given a component type and invokes the callback for each match without allocating an intermediate array.\
1343
+ * Intended for hot per-frame loops in systems. The callback receives the component instance and the entity.\
1344
+ * Disabled entities and components are skipped unless `includeDisabled` is TRUE.\
1345
+ * Do NOT add or remove entities/components for the same component type from within the callback.
1346
+ * @param componentType The component class
1347
+ * @param callback Invoked once per matching entity
1348
+ * @param includeDisabled TRUE to include disabled entities and components. Default is FALSE.
1349
+ * @public
1350
+ * @example
1351
+ * ```js
1352
+ * entityManager.search(SpriteRenderer, (spriteRenderer, entity) => {
1333
1353
  * // do something with the component and entity
1334
- * })
1354
+ * });
1335
1355
  * ```
1336
1356
  */
1337
- search<T extends Component>(componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
1357
+ search<T extends Component>(componentType: ComponentType<T>, callback: (component: T, entity: Entity) => void, includeDisabled?: boolean): void;
1338
1358
  /**
1339
1359
  * Performs an entity search given a collection of component types.\
1340
1360
  * The entities found must have an instance of all the given component types.\
@@ -1373,6 +1393,11 @@ declare class EntityManager {
1373
1393
  * ```
1374
1394
  */
1375
1395
  searchInChildren<T extends Component>(parent: Entity, componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
1396
+ /**
1397
+ * Returns the id for the given component type.
1398
+ * @param component The component class
1399
+ * @returns The component type id
1400
+ */
1376
1401
  private getComponentTypeId;
1377
1402
  }
1378
1403
 
@@ -1472,19 +1497,6 @@ declare class SystemManager {
1472
1497
  update(group: SystemGroup): void;
1473
1498
  }
1474
1499
 
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
1500
  /**
1489
1501
  * Represents a collision between two entities in the game world. It contains information about the colliding entities,
1490
1502
  * their collider components, and resolution data for handling the collision response.
@@ -1601,7 +1613,7 @@ type CollisionMatrix = [string, string][];
1601
1613
  * containerNode: document.getElementById("app"),
1602
1614
  * width: 1920,
1603
1615
  * height: 1080,
1604
- * debugEnabled: false,
1616
+ * debug: { colliders: false, mousePosition: false, textRendererBoundingBoxes: false },
1605
1617
  * canvasColor: "#000000",
1606
1618
  * physicsFramerate: 180,
1607
1619
  * headless: false,
@@ -1612,7 +1624,7 @@ type CollisionMatrix = [string, string][];
1612
1624
  * ["layer1", "layer3"],
1613
1625
  * ],
1614
1626
  * collisionMethod: CollisionMethods.SAT,
1615
- * collisionBroadPhaseMethod: BroadPhaseMethods.SpartialGrid,
1627
+ * collisionBroadPhaseMethod: BroadPhaseMethods.SpatialGrid,
1616
1628
  * }
1617
1629
  * };
1618
1630
  * ```
@@ -1654,11 +1666,11 @@ interface GameConfig {
1654
1666
  dependencies?: [DependencyName, any][];
1655
1667
  /** Collision configuration options */
1656
1668
  collisions?: {
1657
- /** Collision detection method: CollisionMethods.SAT or CollisionMethods.ABB. Default value is CollisionMethods.SAT */
1669
+ /** Collision detection method: CollisionMethods.SAT or CollisionMethods.AABB. Default value is CollisionMethods.SAT */
1658
1670
  collisionMethod?: CollisionMethods;
1659
- /** Define a fixed rectangular area for collision detection */
1671
+ /** Pairs of collision layers that are allowed to collide with each other */
1660
1672
  collisionMatrix?: CollisionMatrix;
1661
- /** Collision broad phase method: BroadPhaseMethods.QuadTree or BroadPhaseMethods.SpartialGrid. Default values is BroadPhaseMethods.SpartialGrid */
1673
+ /** Collision broad phase method: BroadPhaseMethods.QuadTree or BroadPhaseMethods.SpatialGrid. Default values is BroadPhaseMethods.SpatialGrid */
1662
1674
  collisionBroadPhaseMethod?: BroadPhaseMethods;
1663
1675
  };
1664
1676
  }
@@ -1671,6 +1683,15 @@ declare class CreateSystemService {
1671
1683
  createSystemIfNotExists(systemType: SystemType): void;
1672
1684
  }
1673
1685
 
1686
+ /**
1687
+ * A loaded audio asset. Holds both a decoded `AudioBuffer` and an `HTMLAudioElement`.
1688
+ * @public
1689
+ * @category Assets
1690
+ */
1691
+ interface AudioSource {
1692
+ buffer?: AudioBuffer;
1693
+ element: HTMLAudioElement;
1694
+ }
1674
1695
  /**
1675
1696
  * Manages loading and retrieval of game assets including images, fonts, audio files, videos and JSON data.\
1676
1697
  * Provides methods to load assets asynchronously and check their loading status.\
@@ -1686,7 +1707,7 @@ declare class CreateSystemService {
1686
1707
  * this.assetManager.loadJson("data.json");
1687
1708
  *
1688
1709
  * const imageElement = this.assetManager.getImage("image.png");
1689
- * const audioElement = this.assetManager.getAudio("audio.ogg");
1710
+ * const audioSource = this.assetManager.getAudio("audio.ogg");
1690
1711
  * const videoElement = this.assetManager.getVideo("video.mp4");
1691
1712
  * const fontFace = this.assetManager.getFont("custom-font");
1692
1713
  * const jsonData = this.assetManager.getJson("data.json");
@@ -1697,7 +1718,9 @@ declare class CreateSystemService {
1697
1718
  * ```
1698
1719
  */
1699
1720
  declare class AssetManager {
1721
+ private readonly audioContext;
1700
1722
  private readonly assets;
1723
+ constructor(audioContext: AudioContext | null);
1701
1724
  /**
1702
1725
  * Returns TRUE if the assets are loaded
1703
1726
  * @returns TRUE or FALSE
@@ -1714,9 +1737,10 @@ declare class AssetManager {
1714
1737
  * Loads an audio asset
1715
1738
  * @param url The asset URL
1716
1739
  * @param name The asset name [optional]
1717
- * @returns The HTML Audio element created
1740
+ * @returns The {@link AudioSource} (with its `buffer` populated asynchronously), or `null` if no AudioContext is available.
1718
1741
  */
1719
- loadAudio(url: string, name?: string): HTMLAudioElement;
1742
+ loadAudio(url: string, name?: string): AudioSource | null;
1743
+ private decodeAudioBuffer;
1720
1744
  /**
1721
1745
  * Loads a font asset
1722
1746
  * @param family The font family name
@@ -1753,15 +1777,15 @@ declare class AssetManager {
1753
1777
  /**
1754
1778
  * Retrieves an audio asset
1755
1779
  * @param url The asset URL
1756
- * @returns The HTML Audio element
1780
+ * @returns The loaded {@link AudioSource}.
1757
1781
  */
1758
- getAudio(url: string): HTMLAudioElement;
1782
+ getAudio(url: string): AudioSource;
1759
1783
  /**
1760
1784
  * Retrieves an audio asset
1761
1785
  * @param name The asset name
1762
- * @returns The HTML Audio element
1786
+ * @returns The loaded {@link AudioSource}.
1763
1787
  */
1764
- getAudio(name: string): HTMLAudioElement;
1788
+ getAudio(name: string): AudioSource;
1765
1789
  /**
1766
1790
  * Retrieves a font asset
1767
1791
  * @param family The font family name
@@ -2137,7 +2161,7 @@ declare abstract class Scene {
2137
2161
  * containerNode: document.getElementById("app"),
2138
2162
  * width: 1920,
2139
2163
  * height: 1080,
2140
- * debugEnabled: false,
2164
+ * debug: { colliders: false, mousePosition: false, textRendererBoundingBoxes: false },
2141
2165
  * canvasColor: "#000000",
2142
2166
  * physicsFramerate: 180,
2143
2167
  * collisions: {
@@ -2146,7 +2170,7 @@ declare abstract class Scene {
2146
2170
  * ["layer1", "layer3"],
2147
2171
  * ],
2148
2172
  * collisionMethod: CollisionMethods.SAT,
2149
- * collisionBroadPhaseMethod: BroadPhaseMethods.SpartialGrid,
2173
+ * collisionBroadPhaseMethod: BroadPhaseMethods.SpatialGrid,
2150
2174
  * }
2151
2175
  * });
2152
2176
  * game.addScene(MainScene, "MainScene");
@@ -2290,6 +2314,12 @@ declare class Animator {
2290
2314
  /** @internal */
2291
2315
  static componentName: string;
2292
2316
  constructor(options?: Partial<AnimatorOptions>);
2317
+ /** Play the animation. If a new animation name is given, switches to it and resets. */
2318
+ play(animation?: string): void;
2319
+ /** Pause the animation, keeping the current frame. */
2320
+ pause(): void;
2321
+ /** Stop the animation and reset to the first frame. */
2322
+ stop(): void;
2293
2323
  }
2294
2324
  /**
2295
2325
  * Animation configuration
@@ -2403,9 +2433,9 @@ type AnimationSlice = {
2403
2433
  */
2404
2434
  interface AudioPlayerOptions {
2405
2435
  /** The action to perform with the audio source. */
2406
- action: AudioPlayerAction;
2407
- /** The audio source to play. */
2408
- audioSource: HTMLAudioElement | string;
2436
+ action: "stop" | "play" | "pause";
2437
+ /** The audio source to play. Either an `AudioSource` (from `AssetManager.getAudio`) or an asset URL/name string. */
2438
+ audioSource: AudioSource | string;
2409
2439
  /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
2410
2440
  stopOnSceneTransition: boolean;
2411
2441
  /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
@@ -2432,9 +2462,9 @@ interface AudioPlayerOptions {
2432
2462
  */
2433
2463
  declare class AudioPlayer {
2434
2464
  /** 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;
2465
+ action: "stop" | "play" | "pause";
2466
+ /** The audio source to play. Either an `AudioSource` (from `AssetManager.getAudio`) or an asset URL/name string. */
2467
+ audioSource: AudioSource | string;
2438
2468
  /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
2439
2469
  stopOnSceneTransition: boolean;
2440
2470
  /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
@@ -2442,7 +2472,7 @@ declare class AudioPlayer {
2442
2472
  /** TRUE If the audio source should loop. */
2443
2473
  loop: boolean;
2444
2474
  /** READONLY, The current state of the audio source. */
2445
- state: AudioPlayerState;
2475
+ state: "stopped" | "playing" | "paused";
2446
2476
  /** The volume of the audio source. */
2447
2477
  volume: number;
2448
2478
  /** READONLY, TRUE If the audio source is playing. */
@@ -2452,8 +2482,16 @@ declare class AudioPlayer {
2452
2482
  /** READONLY, TRUE If the audio source is stopped. */
2453
2483
  get stopped(): boolean;
2454
2484
  /** @internal */
2455
- _currentAudioSource: HTMLAudioElement;
2456
- _playPromisePendind: boolean;
2485
+ _currentAudioSource: AudioSource;
2486
+ /** @internal Active BufferSourceNode that's playing the current buffer (null when not playing) */
2487
+ _sourceNode: AudioBufferSourceNode;
2488
+ /** @internal GainNode wired between sourceNode and destination, used to set volume */
2489
+ _gainNode: GainNode;
2490
+ /** @internal AudioContext.currentTime when the current sourceNode started */
2491
+ _startedAt: number;
2492
+ /** @internal Offset (seconds) within the buffer at which the next play should resume from (used on pause) */
2493
+ _pauseOffset: number;
2494
+ /** @internal */
2457
2495
  _playAfterUserInput: boolean;
2458
2496
  /** @internal */
2459
2497
  static componentName: string;
@@ -2461,7 +2499,7 @@ declare class AudioPlayer {
2461
2499
  /**
2462
2500
  * Play the audio source.
2463
2501
  */
2464
- play(audioSource?: HTMLAudioElement): void;
2502
+ play(audioSource?: AudioSource | string): void;
2465
2503
  /**
2466
2504
  * Pause the audio source.
2467
2505
  */
@@ -2471,16 +2509,6 @@ declare class AudioPlayer {
2471
2509
  */
2472
2510
  stop(): void;
2473
2511
  }
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
2512
 
2485
2513
  /**
2486
2514
  * Button component configuration
@@ -5008,9 +5036,7 @@ declare function gamePreRenderSystem(): (target: SystemType) => void;
5008
5036
  declare function decorate(decorator: (...args: any[]) => any, target: any, propertyKey?: string | symbol | number): void;
5009
5037
 
5010
5038
  /**
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.
5039
+ * Configuration options for playing sound effects with {@link playSfx}.
5014
5040
  * @public
5015
5041
  * @category Audio
5016
5042
  * @example
@@ -5020,25 +5046,27 @@ declare function decorate(decorator: (...args: any[]) => any, target: any, prope
5020
5046
  * ```
5021
5047
  * @example
5022
5048
  * ```javascript
5023
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5024
5049
  * playSfx({ audioSource, volume: 0.5 });
5025
5050
  * ```
5026
5051
  * @example
5027
5052
  * ```javascript
5028
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5029
5053
  * playSfx({ audioSource, loop: true });
5030
5054
  * ```
5031
5055
  */
5032
5056
  interface PlaySfxOptions {
5033
- audioSource: HTMLAudioElement;
5057
+ /** The audio asset to play (typically obtained via `AssetManager.getAudio`). */
5058
+ audioSource: AudioSource;
5059
+ /** The volume of the audio source. */
5034
5060
  volume?: number;
5061
+ /** TRUE If the audio source should loop. */
5035
5062
  loop?: boolean;
5036
5063
  }
5037
5064
  /**
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.
5065
+ * Plays a sound effect from the beginning, even if it's currently playing. Ideal for one-shot sound effects like
5066
+ * explosions, impacts, or UI feedback.\
5067
+ * For background music or longer tracks with pause/resume semantics, prefer the `AudioPlayer` component
5068
+ * (which uses the Web Audio API and handles browser autoplay policies).
5069
+ * @param options Sound effect configuration.
5042
5070
  * @public
5043
5071
  * @category Audio
5044
5072
  * @example
@@ -5048,21 +5076,18 @@ interface PlaySfxOptions {
5048
5076
  * ```
5049
5077
  * @example
5050
5078
  * ```javascript
5051
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5052
5079
  * playSfx({ audioSource, volume: 0.5 });
5053
5080
  * ```
5054
5081
  * @example
5055
5082
  * ```javascript
5056
- * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
5057
5083
  * playSfx({ audioSource, loop: true });
5058
5084
  * ```
5059
5085
  */
5060
5086
  declare const playSfx: ({ audioSource, volume, loop }: PlaySfxOptions) => void;
5061
5087
  /**
5062
5088
  * 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.
5089
+ * Useful for immediately silencing sound effects or interrupting looped audio.
5090
+ * @param audioSource The audio asset to stop.
5066
5091
  * @public
5067
5092
  * @category Audio
5068
5093
  * @example
@@ -5071,7 +5096,7 @@ declare const playSfx: ({ audioSource, volume, loop }: PlaySfxOptions) => void;
5071
5096
  * stopSfx(audioSource);
5072
5097
  * ```
5073
5098
  */
5074
- declare const stopSfx: (audioSource: HTMLAudioElement) => void;
5099
+ declare const stopSfx: (audioSource: AudioSource) => void;
5075
5100
 
5076
5101
  /**
5077
5102
  * Symbols to be used as dependency identifiers
@@ -5090,4 +5115,4 @@ declare const SYMBOLS: {
5090
5115
  TimeManager: symbol;
5091
5116
  };
5092
5117
 
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 };
5118
+ 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 };