angry-pixel 2.3.7 → 2.4.0

package/lib/index.d.ts

@@ -771,11 +771,24 @@ type Archetype = {
     /** Whether the entity starts enabled. Defaults to `true`. Set to `false` to disable the entity on creation. */
     enabled?: boolean;
 };
+/**
+ * Options for the `removeAllEntities` method of the EntityManager
+ * @public
+ * @category Entity-Component-System
+ * @example
+ * ```js
+ * entityManager.removeAllEntities({ preserveEntitiesWithComponent: DontDestroy });
+ * ```
+ */
+type RemoveAllEntitiesOptions = {
+    /** The entities that have a component of this type are preserved instead of being removed */
+    preserveEntitiesWithComponent: ComponentType;
+};
 /**
  * This interface defines the core structure for system classes in the ECS architecture.\
  * Systems contain the game logic that operates on entities and their components.\
  * Dependencies like EntityManager can be injected using dependency injection decorators.\
- * Systems must implement onUpdate() and can optionally implement lifecycle hooks like onCreate(), onDestroy(), onEnabled() and onDisabled().
+ * Systems must implement onUpdate().
  * @public
  * @category Entity-Component-System
  * @example
@@ -792,26 +805,6 @@ type Archetype = {
  * ```
  */
 interface System {
-    /**
-     * This method is called the first time the system is enabled
-     * @public
-     */
-    onCreate?(): void;
-    /**
-     * This method is called when the system is destroyed
-     * @public
-     */
-    onDestroy?(): void;
-    /**
-     * This method is called when the system is disabled
-     * @public
-     */
-    onDisabled?(): void;
-    /**
-     * This method is called when the system is enabled
-     * @public
-     */
-    onEnabled?(): void;
     /**
      * This method is called once every frame
      * @public
@@ -988,18 +981,18 @@ declare class EntityManager {
     removeEntity(entity: Entity): void;
     /**
      * Removes all Entities and all their Components
-     * @param preserveComponentType Optional component type to preserve entities that have this component
+     * @param options Optional options object. See {@link RemoveAllEntitiesOptions}
      * @public
      * @example
      * ```js
      * // Remove all entities
      * entityManager.removeAllEntities();
      *
-     * // Remove all entities except those that have a SpriteRenderer component
-     * entityManager.removeAllEntities(SpriteRenderer);
+     * // Remove all entities except those that have a component of type DontDestroy
+     * entityManager.removeAllEntities({ preserveEntitiesWithComponent: DontDestroy });
      * ```
      */
-    removeAllEntities(preserveComponentType?: ComponentType): void;
+    removeAllEntities(options?: RemoveAllEntitiesOptions): void;
     /**
      * If the Entity exists, returns TRUE, otherwise it returns FALSE
      * @param entity
@@ -1463,8 +1456,7 @@ declare class SystemManager {
      */
     groupHasSystems(group: SystemGroup): boolean;
     /**
-     * Enables a system by its type.\
-     * The method `onEnabled` of the system will be called. If the system is enabled for the first time, the method `onCreate` will also be called.
+     * Enables a system by its type.
      * @param systemType The system class
      * @public
      * @example
@@ -1474,8 +1466,7 @@ declare class SystemManager {
      */
     enableSystem(systemType: SystemType): void;
     /**
-     * Disables a system by its type.\
-     * The method `onDisabled` of the system will be called.
+     * Disables a system by its type.
      * @param systemType The system class
      * @public
      * @example
@@ -1493,7 +1484,6 @@ declare class SystemManager {
     setExecutionOrder(systemType: SystemType, position: number): void;
     /**
      * Removes a system by its type.
-     * The method `onDestroy` of the system will be called.
      * @param systemType The system class
      * @internal
      */
@@ -1575,13 +1565,16 @@ interface Collision {
  *   playerCollider,
  *   "enemy"
  * );
- *
- * // Get all current collisions
- * const allCollisions = collisionRepository.findAll();
  * ```
  */
 declare class CollisionRepository {
+    private collisionPool;
+    private collisionPoolIndex;
     private collisions;
+    private step;
+    private findCache;
+    /** @internal */
+    private updateCache;
     /**
      * Searches for and returns a collection of collisions for the given collider
      * @param collider The local collider
@@ -1596,15 +1589,22 @@ declare class CollisionRepository {
      */
     findCollisionsForColliderAndLayer(collider: Collider, layer: string): Collision[];
     /**
-     * Returns all the collisions
-     * @public
-     * @returns A collection of collisions
+     * Returns the raw collisions of the current physics step, for engine systems that need every collision at once.
+     * - Each pair of colliding shapes is stored once, not once per side: the shape that detected the collision is
+     *   the local one. Check both `localEntity` and `remoteEntity` (and negate `resolution.direction` for the
+     *   remote side) to find every collision of an entity.
+     * - The collisions are pooled: the objects and the array are reused on the next physics step. Read them
+     *   synchronously and do not keep references to them.
+     *
+     * Use `findCollisionsForCollider` or `findCollisionsForColliderAndLayer` instead when querying the collisions of
+     * a single collider: they return copies, already oriented with that collider as the local one.
+     * @internal
      */
-    findAll(): Collision[];
+    getCollisions(): Collision[];
     /** @internal */
-    persist(collision: Collision): void;
+    persist(localEntity: Entity, localCollider: Collider, remoteEntity: Entity, remoteCollider: Collider, { direction, penetration }: CollisionResolution): void;
     /** @internal */
-    removeAll(): void;
+    clear(): void;
 }
 
 /**
@@ -1738,7 +1738,7 @@ interface AudioSource {
 declare class AssetManager {
     private readonly audioContext;
     private readonly assets;
-    constructor(audioContext: AudioContext | null);
+    constructor(audioContext: AudioContext | undefined);
     /**
      * Returns TRUE if the assets are loaded
      * @returns TRUE or FALSE
@@ -1755,9 +1755,9 @@ declare class AssetManager {
      * Loads an audio asset
      * @param url The asset URL
      * @param name The asset name [optional]
-     * @returns The {@link AudioSource} (with its `buffer` populated asynchronously), or `null` if no AudioContext is available.
+     * @returns The {@link AudioSource} (with its `buffer` populated asynchronously), or `undefined` if no AudioContext is available.
      */
-    loadAudio(url: string, name?: string): AudioSource | null;
+    loadAudio(url: string, name?: string): AudioSource | undefined;
     private decodeAudioBuffer;
     /**
      * Loads a font asset
@@ -2056,15 +2056,16 @@ declare class SceneManager {
     /**
      * Loads a scene
      * @param name The name of the scene
-     * @param preserveEntitiesWithComponent Optional component type to preserve entities that have this component
+     * @param options Optional options object. See {@link LoadSceneOptions}
      * @public
      */
-    loadScene(name: string, preserveEntitiesWithComponent?: ComponentType): void;
+    loadScene(name: string, options?: LoadSceneOptions): void;
     /**
      * Loads the opening scene
+     * @param options Optional options object. See {@link LoadSceneOptions}
      * @public
      */
-    loadOpeningScene(): void;
+    loadOpeningScene(options?: LoadSceneOptions): void;
     /**
      * Returns true if the scene is loading
      * @public
@@ -2077,8 +2078,22 @@ declare class SceneManager {
     get sceneLoadedThisFrame(): boolean;
     /** @internal */
     update(): void;
-    private destroyCurrentScene;
+    /** @internal */
+    destroyCurrentScene(): void;
 }
+/**
+ * Options for the `loadScene` and `loadOpeningScene` methods of the SceneManager
+ * @public
+ * @category Managers
+ * @example
+ * ```js
+ * this.sceneManager.loadScene("Level2", { preserveEntitiesWithComponent: DontDestroy });
+ * ```
+ */
+type LoadSceneOptions = {
+    /** The entities that have a component of this type are preserved across the scene transition */
+    preserveEntitiesWithComponent: ComponentType;
+};
 /**
  * This type represents a scene class
  * @public
@@ -2102,14 +2117,12 @@ type SceneType<T extends Scene = Scene> = {
  *      this.assetManager.loadImage("image.png");
  *   }
  *
- *   registerSystems() {
- *     this.systems.push(
+ *   setup() {
+ *     this.systems = [
  *         SomeSystem,
  *         AnotherSystem
- *     );
- *   }
+ *     ];
  *
- *   createEntities() {
  *     this.entityManager.createEntity([
  *       SomeComponent,
  *       AnotherComponent
@@ -2123,33 +2136,16 @@ declare abstract class Scene {
     protected readonly assetManager: AssetManager;
     systems: SystemType[];
     constructor(entityManager: EntityManager, assetManager: AssetManager);
-    /**
-     * Override this method to register the systems that will be executed in the scene
-     * @public
-     */
-    registerSystems(): void;
     /**
      * Override this method to load the assets needed for the scene
      * @public
      */
     loadAssets(): void;
     /**
-     * Override this method to create the entities needed for the scene
-     * @public
-     */
-    createEntities(): void;
-    /**
-     * Adds a system to the scene
-     * @param system The system to add
+     * Override this method to create the entities and register the systems that will be executed in the scene
      * @public
      */
-    protected addSystem(system: SystemType): void;
-    /**
-     * Adds multiple systems to the scene
-     * @param systems The systems to add
-     * @public
-     */
-    protected addSystems(systems: SystemType[]): void;
+    setup(): void;
 }
 
 /**
@@ -5229,13 +5225,14 @@ declare class InputManager {
 
 /**
  * Abstract base class for creating game systems with commonly needed dependencies injected.\
- * Provides access to the following core managers and services:\
- * - EntityManager: For managing game entities and components\
- * - AssetManager: For loading and managing game resources\
- * - SceneManager: For controlling scene transitions and state\
- * - TimeManager: For handling game timing and delta time\
- * - InputManager: For processing keyboard, mouse and touch input\
- * - CollisionRepository: For physics and collision detection\
+ * Provides access to the following core managers and services:
+ * - EntityManager: For managing game entities and components
+ * - SystemManager: For managing game systems
+ * - AssetManager: For loading and managing game resources
+ * - SceneManager: For controlling scene transitions and state
+ * - TimeManager: For handling game timing and delta time
+ * - InputManager: For processing keyboard, mouse and touch input
+ * - CollisionRepository: For physics and collision detection
  * - GameConfig: For accessing game configuration settings
  * @public
  * @category Core
@@ -5250,17 +5247,28 @@ declare class InputManager {
  */
 declare abstract class GameSystem implements System {
     protected readonly entityManager: EntityManager;
+    protected readonly systemManager: SystemManager;
     protected readonly assetManager: AssetManager;
     protected readonly sceneManager: SceneManager;
     protected readonly timeManager: TimeManager;
     protected readonly inputManager: InputManager;
     protected readonly collisionRepository: CollisionRepository;
     protected readonly gameConfig: GameConfig;
+    /**
+     * This method is called once every frame
+     * @public
+     */
     onUpdate(): void;
-    onCreate(): void;
-    onEnabled(): void;
-    onDisabled(): void;
-    onDestroy(): void;
+    /**
+     * This method is called when the scene finishes loading, after its entities have been created
+     * @public
+     */
+    onSceneLoaded(): void;
+    /**
+     * This method is called when the scene is destroyed, before its entities are removed
+     * @public
+     */
+    onSceneDestroyed(): void;
 }
 
 /**
@@ -5419,4 +5427,4 @@ declare const SYMBOLS: {
     TimeManager: symbol;
 };
 
-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, TileAnimation, type TileAnimationOptions, type TiledChunk, type TiledGroupLayer, type TiledLayer, type TiledObject, type TiledObjectBlueprint, type TiledObjectFactory, type TiledObjectLayer, type TiledObjectProperties, type TiledProperty, type TiledTileAnimationFrame, type TiledTilemap, type TiledTileset, type TiledTilesetTile, 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 };
+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, type LoadSceneOptions, MaskRenderer, type MaskRendererOptions, MaskShape, Mouse, type PlaySfxOptions, Polygon, PolygonCollider, type PolygonColliderOptions, type PropertyKey, Rectangle, type RemoveAllEntitiesOptions, 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, TileAnimation, type TileAnimationOptions, type TiledChunk, type TiledGroupLayer, type TiledLayer, type TiledObject, type TiledObjectBlueprint, type TiledObjectFactory, type TiledObjectLayer, type TiledObjectProperties, type TiledProperty, type TiledTileAnimationFrame, type TiledTilemap, type TiledTileset, type TiledTilesetTile, 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 };