angry-pixel 2.1.4 → 2.1.6

package/lib/index.d.ts

@@ -708,6 +708,7 @@ type Component = Record<string, any>;
  */
 type ComponentType<T extends Component = Component> = {
     new (...args: any[]): T;
+    componentName?: string;
 };
 /**
  * This type represents a search result object containing an entity and its matching component.\
@@ -957,13 +958,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
      * @public
      * @example
      * ```js
+     * // Remove all entities
      * entityManager.removeAllEntities();
+     *
+     * // Remove all entities except those that have a SpriteRenderer component
+     * entityManager.removeAllEntities(SpriteRenderer);
      * ```
      */
-    removeAllEntities(): void;
+    removeAllEntities(preserveComponentType?: ComponentType): void;
     /**
      * If the Entity exists, returns TRUE, otherwise it returns FALSE
      * @param entity
@@ -1277,7 +1283,7 @@ declare class EntityManager {
      * The third argument determines if disabled entities or components are included in the search result,\its default value is FALSE.
      * @param componentType The component class
      * @param filter The filter function
-     * @param includeDisabled TRUE to incluide disabled entities and components, FALSE otherwise
+     * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
      * @returns SearchResult
      * @public
      * @example
@@ -1309,7 +1315,7 @@ declare class EntityManager {
      * This method returns a collection of objects of type SearchResult, which has the entity found, and the instance of the component.\
      * The second argument determines if disabled entities or components are included in the search result,\its default value is FALSE.
      * @param componentType The component class
-     * @param includeDisabled TRUE to incluide disabled entities and components, FALSE otherwise
+     * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
      * @returns SearchResult
      * @public
      * @example
@@ -1348,7 +1354,7 @@ declare class EntityManager {
      * The third argument determines if disabled entities or components are included in the search result,\its default value is FALSE.
      * @param parent The parent entity
      * @param componentType The component class
-     * @param includeDisabled TRUE to incluide disabled entities and components, FALSE otherwise
+     * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
      * @returns SearchResult
      * @public
      * @example
@@ -1812,6 +1818,12 @@ type IntervalOptions = {
     times?: number;
     /** Whether to execute the callback immediately before starting the interval timer */
     executeImmediately?: boolean;
+    /** Entity reference to cancel the interval when the entity is disabled or destroyed */
+    entityRef?: Entity;
+    /** Component reference to cancel the interval when the component is disabled or destroyed */
+    componentRef?: Component;
+    /** Whether to use the time scale for the interval, default is TRUE */
+    useTimeScale?: boolean;
 };
 /**
  * Manages the properties associated with time.\
@@ -1851,11 +1863,26 @@ type IntervalOptions = {
  *     executeImmediately: true,
  * });
  *
+ * // set an interval that will be cleared when the entity is destroyed
+ * const intervalId = timeManager.setInterval({
+ *     callback: () => console.log("Will be called indefinitely!"),
+ *     delay: 1000,
+ *     entityRef: entity,
+ * });
+ *
+ * // set an interval that will be cleared when the component is destroyed
+ * const intervalId = timeManager.setInterval({
+ *     callback: () => console.log("Will be called indefinitely!"),
+ *     delay: 1000,
+ *     componentRef: component,
+ * });
+ *
  * // clear the interval with the given id
  * this.timeManager.clearInterval(intervalId);
  * ```
  */
 declare class TimeManager {
+    private readonly entityManager;
     /** @internal */
     readonly fixedGameFramerate: number;
     /** @internal */
@@ -1889,7 +1916,7 @@ declare class TimeManager {
     get physicsDeltaTime(): number;
     /** The browser delta time affected by time scale. */
     get renderDeltaTime(): number;
-    constructor({ physicsFramerate }: GameConfig);
+    constructor({ physicsFramerate }: GameConfig, entityManager: EntityManager);
     /** @internal */
     updateForRender(time: number): void;
     /** @internal */
@@ -1898,11 +1925,13 @@ declare class TimeManager {
     updateForPhysics(time: number): void;
     /** @internal */
     updateIntervals(): void;
+    private intervalHealthCheck;
     /**
      * Sets a timer which executes a function repeatedly at a fixed time interval.\
      * If `times` is provided, the interval will be cleared after the function has been called that many times.\
      * But if `times` is not provided, the interval will continue until it is cleared.\
      * If `executeImmediately` is set to true, the function will be called immediately after the interval is set.\
+     * If `useTimeScale` is set to false, the interval will use the unscaled delta time.\
      * Intervals are cleared when loading a new scene.
      * @param intervalOptions
      * @returns intervalId
@@ -1930,7 +1959,7 @@ declare class TimeManager {
      * });
      * ```
      */
-    setInterval({ callback, delay, times, executeImmediately }: IntervalOptions): number;
+    setInterval({ callback, delay, times, executeImmediately, entityRef, componentRef, useTimeScale, }: IntervalOptions): number;
     /**
      * Clears the interval with the given id.
      * @param intervalId
@@ -1942,6 +1971,66 @@ declare class TimeManager {
     clearAllIntervals(): void;
 }
 
+/**
+ * Manages scene loading, transitions and lifecycle.\
+ * Provides methods to register scenes, load scenes by name, and handles the opening scene.\
+ * Ensures proper cleanup between scene transitions and maintains scene state.
+ * @public
+ * @category Managers
+ * @example
+ * ```js
+ * this.sceneManager.loadScene("MainScene");
+ * ```
+ */
+declare class SceneManager {
+    private readonly systemManager;
+    private readonly systemFactory;
+    private readonly entityManager;
+    private readonly assetManager;
+    private readonly timeManager;
+    private readonly scenes;
+    private openingSceneName;
+    private currentSceneName;
+    private sceneNameToBeLoaded;
+    private _loadingScene;
+    private _sceneLoadedThisFrame;
+    private preserveEntitiesWithComponent;
+    /** @internal */
+    constructor(systemManager: SystemManager, systemFactory: CreateSystemService, entityManager: EntityManager, assetManager: AssetManager, timeManager: TimeManager);
+    /**
+     * Adds a scene to the SceneManager
+     * @param sceneType The scene class
+     * @param name The name of the scene
+     * @param openingScene Whether the scene is the opening scene
+     * @public
+     */
+    addScene(sceneType: SceneType, name: string, openingScene?: boolean): void;
+    /**
+     * Loads a scene
+     * @param name The name of the scene
+     * @param preserveEntitiesWithComponent Optional component type to preserve entities that have this component
+     * @public
+     */
+    loadScene(name: string, preserveEntitiesWithComponent?: ComponentType): void;
+    /**
+     * Loads the opening scene
+     * @public
+     */
+    loadOpeningScene(): void;
+    /**
+     * Returns true if the scene is loading
+     * @public
+     */
+    get loadingScene(): boolean;
+    /**
+     * Returns true if the scene was loaded this frame
+     * @public
+     */
+    get sceneLoadedThisFrame(): boolean;
+    /** @internal */
+    update(): void;
+    private destroyCurrentScene;
+}
 /**
  * This type represents a scene class
  * @public
@@ -1965,14 +2054,14 @@ type SceneType<T extends Scene = Scene> = {
  *      this.assetManager.loadImage("image.png");
  *   }
  *
- *   loadSystems() {
+ *   registerSystems() {
  *     this.systems.push(
  *         SomeSystem,
  *         AnotherSystem
  *     );
  *   }
  *
- *   setup() {
+ *   createEntities() {
  *     this.entityManager.createEntity([
  *       SomeComponent,
  *       AnotherComponent
@@ -1986,43 +2075,33 @@ declare abstract class Scene {
     protected readonly assetManager: AssetManager;
     systems: SystemType[];
     constructor(entityManager: EntityManager, assetManager: AssetManager);
-    loadSystems(): void;
+    /**
+     * 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;
-    setup(): void;
-}
-/**
- * Manages scene loading, transitions and lifecycle.\
- * Provides methods to register scenes, load scenes by name, and handles the opening scene.\
- * Ensures proper cleanup between scene transitions and maintains scene state.
- * @public
- * @category Managers
- * @example
- * ```js
- * this.sceneManager.loadScene("MainScene");
- * ```
- */
-declare class SceneManager {
-    private readonly systemManager;
-    private readonly systemFactory;
-    private readonly entityManager;
-    private readonly assetManager;
-    private readonly timeManager;
-    private readonly scenes;
-    private openingSceneName;
-    private currentSceneName;
-    private sceneNameToBeLoaded;
-    private _loadingScene;
-    private _sceneLoadedThisFrame;
-    /** @internal */
-    constructor(systemManager: SystemManager, systemFactory: CreateSystemService, entityManager: EntityManager, assetManager: AssetManager, timeManager: TimeManager);
-    addScene(sceneType: SceneType, name: string, openingScene?: boolean): void;
-    loadScene(name: string): void;
-    loadOpeningScene(): void;
-    get loadingScene(): boolean;
-    get sceneLoadedThisFrame(): boolean;
-    /** @internal */
-    update(): void;
-    private destroyCurrentScene;
+    /**
+     * 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
+     * @public
+     */
+    protected addSystem(system: SystemType): void;
+    /**
+     * Adds multiple systems to the scene
+     * @param systems The systems to add
+     * @public
+     */
+    protected addSystems(systems: SystemType[]): void;
 }
 
 /**
@@ -2116,6 +2195,7 @@ declare class Game {
  * const walkAnimation = new Animation({
  *   image: "walk.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [0, 1, 2, 3, 4, 5],
  *   fps: 12,
  *   loop: true
  * });
@@ -2123,6 +2203,7 @@ declare class Game {
  * const idleAnimation = new Animation({
  *   image: "idle.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [6, 7, 8, 9]
  *   fps: 8,
  *   loop: true
  * });
@@ -2154,6 +2235,7 @@ interface AnimatorOptions {
  * const walkAnimation = new Animation({
  *   image: "walk.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [0, 1, 2, 3, 4, 5],
  *   fps: 12,
  *   loop: true
  * });
@@ -2161,6 +2243,7 @@ interface AnimatorOptions {
  * const idleAnimation = new Animation({
  *   image: "idle.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [6, 7, 8, 9],
  *   fps: 8,
  *   loop: true
  * });
@@ -2177,17 +2260,26 @@ interface AnimatorOptions {
  * ```
  */
 declare class Animator {
+    /** The animations to play. */
     animations: Map<string, Animation>;
+    /** The animation to play. */
     animation: string;
+    /** The speed of the animation. */
     speed: number;
+    /** TRUE If the animation should reset to the first frame when the animation is stopped, FALSE otherwise. */
     reset: boolean;
+    /** TRUE If the animation is playing, FALSE otherwise. */
     playing: boolean;
+    /** The current frame of the animation. */
     currentFrame: number;
+    /** The current time of the animation. */
     currentTime: number;
     /**  @internal */
     _currentAnimation: string;
     /**  @internal */
     _assetsReady: boolean;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<AnimatorOptions>);
 }
 /**
@@ -2199,6 +2291,7 @@ declare class Animator {
  * const walkAnimation = new Animation({
  *   image: "walk.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [0, 1, 2, 3, 4, 5],
  *   fps: 12,
  *   loop: true
  * });
@@ -2206,6 +2299,7 @@ declare class Animator {
  * const idleAnimation = new Animation({
  *   image: "idle.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [6, 7, 8, 9],
  *   fps: 8,
  *   loop: true
  * });
@@ -2242,6 +2336,7 @@ interface AnimationOptions {
  * const walkAnimation = new Animation({
  *   image: "walk.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [0, 1, 2, 3, 4, 5],
  *   fps: 12,
  *   loop: true
  * });
@@ -2249,6 +2344,7 @@ interface AnimationOptions {
  * const idleAnimation = new Animation({
  *   image: "idle.png",
  *   slice: { size: new Vector2(32, 32) },
+ *   frames: [6, 7, 8, 9],
  *   fps: 8,
  *   loop: true
  * });
@@ -2301,6 +2397,8 @@ interface AudioPlayerOptions {
     action: AudioPlayerAction;
     /** The audio source to play. */
     audioSource: HTMLAudioElement | string;
+    /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
+    stopOnSceneTransition: boolean;
     /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
     fixedToTimeScale: boolean;
     /** TRUE If the audio source should loop. */
@@ -2328,6 +2426,8 @@ declare class AudioPlayer {
     action: AudioPlayerAction;
     /** The audio source to play. */
     audioSource: HTMLAudioElement | string;
+    /** TRUE If the audio source should stop on scene transition, FALSE otherwise. Default is TRUE. */
+    stopOnSceneTransition: boolean;
     /** TRUE If the playback rate is fixed to the TimeManager time scale, default FALSE */
     fixedToTimeScale: boolean;
     /** TRUE If the audio source should loop. */
@@ -2346,6 +2446,8 @@ declare class AudioPlayer {
     _currentAudioSource: HTMLAudioElement;
     _playPromisePendind: boolean;
     _playAfterUserInput: boolean;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<AudioPlayerOptions>);
     /**
      * Play the audio source.
@@ -2438,6 +2540,8 @@ declare class Button {
     onClick: () => void;
     /** Function executed when the button is pressed */
     onPressed: () => void;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<ButtonOptions>);
 }
 /**
@@ -2493,8 +2597,12 @@ interface TiledWrapperOptions {
  * ```
  */
 declare class TiledWrapper {
+    /** The tilemap to render. */
     tilemap: TiledTilemap | string;
+    /** The layer to render. */
     layerToRender: string;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<TiledWrapperOptions>);
 }
 /**
@@ -2657,6 +2765,8 @@ declare class Transform {
     _awake: boolean;
     /** @internal */
     _parent: Transform;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<TransformOptions>);
 }
 
@@ -2718,6 +2828,8 @@ declare class BallCollider implements Collider {
     ignoreCollisionsWithLayers: string[];
     /** @internal */
     shapes: Shape[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<BallColliderOptions>);
 }
 
@@ -2791,6 +2903,8 @@ declare class BoxCollider implements Collider {
     ignoreCollisionsWithLayers: string[];
     /** @internal */
     shapes: Shape[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<BoxColliderOptions>);
 }
 
@@ -2857,6 +2971,8 @@ declare class EdgeCollider implements Collider {
     ignoreCollisionsWithLayers: string[];
     /** @internal */
     shapes: Shape[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<EdgeColliderOptions>);
 }
 
@@ -2925,6 +3041,8 @@ declare class PolygonCollider implements Collider {
     ignoreCollisionsWithLayers: string[];
     /** @internal */
     shapes: Shape[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<PolygonColliderOptions>);
 }
 
@@ -3058,6 +3176,8 @@ declare class RigidBody {
      * @public
      */
     acceleration: Vector2;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<RigidBodyOptions>);
 }
 
@@ -3121,6 +3241,8 @@ declare class TilemapCollider implements Collider {
     physics: boolean;
     /** @internal */
     shapes: Shape[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<TilemapColliderOptions>);
 }
 
@@ -3378,6 +3500,8 @@ declare class Camera {
     debug: boolean;
     /** @internal */
     _renderData: CameraData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<CameraOptions>);
 }
 
@@ -3430,6 +3554,8 @@ declare class LightRenderer {
     intensity: number;
     /** @internal */
     _boundingBox: Rectangle;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<LightRendererOptions>);
 }
 
@@ -3551,6 +3677,8 @@ declare class MaskRenderer {
     layer: string;
     /** @internal */
     _renderData: MaskRenderData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<MaskRendererOptions>);
 }
 
@@ -3609,6 +3737,8 @@ declare class DarknessRenderer {
     _boundingBox: Rectangle;
     /** @internal */
     _renderData: DarknessRenderData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<DarknessRendererOptions>);
 }
 
@@ -3720,6 +3850,8 @@ declare class SpriteRenderer {
     tiled: Vector2;
     /** @internal */
     _renderData: SpriteRenderData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<SpriteRendererOptions>);
 }
 
@@ -3930,6 +4062,8 @@ declare class TextRenderer {
     width: number;
     /** @internal */
     _renderData: TextRenderData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<TextRendererOptions>);
 }
 
@@ -4043,6 +4177,8 @@ declare class TilemapRenderer {
     _processed: boolean;
     /** @internal */
     _renderData: TilemapRenderData[];
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<TilemapRendererOptions>);
 }
 /**
@@ -4197,6 +4333,8 @@ declare class VideoRenderer {
     _playPromisePendind: boolean;
     /** @internal */
     _renderData: VideoRenderData;
+    /** @internal */
+    static componentName: string;
     constructor(options?: Partial<VideoRendererOptions>);
     /**
      * Play the video source.