angry-pixel 2.1.3 → 2.1.5

package/lib/index.d.ts

@@ -720,14 +720,6 @@ type SearchResult<T extends Component> = {
     entity: Entity;
     component: T;
 };
-/**
- * This type represents a search criteria object used to filter components when searching for entities.\
- * It defines a set of key-value pairs where the keys correspond to component properties\
- * and the values are the criteria to match against those properties.
- * @public
- * @category Entity-Component-System
- */
-type SearchCriteria = Record<string, any>;
 /**
  * This type represents an Entity Archetype, which defines a template for creating entities with a specific set of components.\
  * It specifies which components should be attached to the entity, whether the entity should be enabled/disabled,\
@@ -860,8 +852,8 @@ type SystemGroup = string | number | symbol;
  * const entityWithSprite = entityManager.getEntityForComponent(spriteRenderer);
  *
  * // Update component data
- * entityManager.updateComponentData(entity, Transform, {
- *   position: new Vector2(200, 200)
+ * entityManager.updateComponentData(entity, Transform, (component) => {
+ *   component.position = new Vector2(200, 200);
  * });
  *
  * // Create parent-child relationship
@@ -883,7 +875,7 @@ type SystemGroup = string | number | symbol;
  *   // do something with the component and entity
  * })
  *
- * const searchResult = entityManager.search(Enemy, {status: "alive"});
+ * const searchResult = entityManager.search(Enemy, (component) => component.status === "alive");
  * searchResult.forEach(({component, entity}) => {
  *   // do something with the component and entity
  * })
@@ -965,13 +957,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
@@ -1159,14 +1156,16 @@ declare class EntityManager {
      * Updates the data of a component instance
      * @param entity The entity
      * @param componentType The component type
-     * @param data The data to update
+     * @param updateCallback The callback to update the component
      * @public
      * @example
      * ```js
-     * entityManager.updateComponentData(entity, Transform, { position: new Vector2(100, 100) });
+     * entityManager.updateComponentData(entity, Transform, (component) => {
+     *   component.position = new Vector2(100, 100);
+     * });
      * ```
      */
-    updateComponentData<T extends Component = Component>(entity: Entity, componentType: ComponentType<T>, data: Partial<T>): void;
+    updateComponentData<T extends Component = Component>(entity: Entity, componentType: ComponentType<T>, updateCallback: (component: T) => void): void;
     /**
      * Searches for and returns an entity for the component instance
      * @param component The component instance
@@ -1279,11 +1278,11 @@ declare class EntityManager {
     /**
      * Performs a search for entities given a component type.\
      * This method returns a collection of objects of type SearchResult, which has the entity found, and the instance of the component.\
-     * This search can be filtered by passing as a second argument an instance of SearchCriteria, which performs a match between the attributes of the component and the given value.\
+     * This search can be filtered by passing as a second argument a filter function.\
      * 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 criteria The search criteria
-     * @param includeDisabled TRUE to incluide disabled entities and components, FALSE otherwise
+     * @param filter The filter function
+     * @param includeDisabled TRUE to incluide disabled entities and components. Default is FALSE.
      * @returns SearchResult
      * @public
      * @example
@@ -1295,26 +1294,27 @@ declare class EntityManager {
      * ```
      * @example
      * ```js
-     * const searchResult = entityManager.search(Enemy, {status: "alive"});
+     * const searchResult = entityManager.search(Enemy, (component) => component.status === "alive");
      * searchResult.forEach(({component, entity}) => {
      *   // do something with the component and entity
      * })
      * ```
      * @example
      * ```js
-     * const searchResult = entityManager.search(Enemy, {status: "dead"}, true);
+     * // include disabled entities and components
+     * const searchResult = entityManager.search(Enemy, (component) => component.status === "dead", true);
      * searchResult.forEach(({component, entity}) => {
      *   // do something with the component and entity
      * })
      * ```
      */
-    search<T extends Component>(componentType: ComponentType<T>, criteria?: SearchCriteria, includeDisabled?: boolean): SearchResult<T>[];
+    search<T extends Component>(componentType: ComponentType<T>, filter?: (component: T, entity?: Entity) => boolean, includeDisabled?: boolean): SearchResult<T>[];
     /**
      * Performs a search for entities given a component type.\
      * 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
@@ -1326,6 +1326,7 @@ declare class EntityManager {
      * ```
      * @example
      * ```js
+     * // include disabled entities and components
      * const searchResult = entityManager.search(Enemy, true);
      * searchResult.forEach(({component, entity}) => {
      *   // do something with the component and entity
@@ -1352,7 +1353,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
@@ -1946,6 +1947,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
@@ -1969,14 +2030,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
@@ -1990,43 +2051,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;
 }
 
 /**
@@ -2120,6 +2171,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
  * });
@@ -2127,6 +2179,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
  * });
@@ -2158,6 +2211,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
  * });
@@ -2165,6 +2219,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
  * });
@@ -2203,6 +2258,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
  * });
@@ -2210,6 +2266,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
  * });
@@ -2246,6 +2303,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
  * });
@@ -2253,6 +2311,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
  * });
@@ -2305,6 +2364,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. */
@@ -2332,6 +2393,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. */
@@ -3135,7 +3198,7 @@ declare enum RenderDataType {
     Mask = 3,
     Geometric = 4,
     Video = 5,
-    Shadow = 6
+    Darkness = 6
 }
 interface CameraData {
     depth: number;
@@ -3170,7 +3233,7 @@ interface MaskRenderData extends RenderData {
     opacity: number;
 }
 
-interface ShadowRenderData extends RenderData {
+interface DarknessRenderData extends RenderData {
     color: string;
     height: number;
     opacity: number;
@@ -3409,8 +3472,8 @@ interface LightRendererOptions {
  * The LightRenderer component is used to render a light effect on the screen.\
  * It supports a circular light source with a specified radius and intensity.\
  * The light can be optionally smoothed for a softer edge effect.\
- * This component requires a ShadowRenderer component to be present in the scene to function properly,
- * as it works by illuminating areas within the shadow map.\
+ * This component requires a DarknessRenderer component to be present in the scene to function properly,
+ * as it works by illuminating areas within the darkness mask.\
  * @public
  * @category Components
  * @example
@@ -3428,7 +3491,7 @@ declare class LightRenderer {
     radius: number;
     /** Smooth */
     smooth: boolean;
-    /** Shadow render layer */
+    /** Darkness render layer */
     layer: string;
     /** Light intensitry between 0 and 1 */
     intensity: number;
@@ -3559,12 +3622,12 @@ declare class MaskRenderer {
 }
 
 /**
- * ShadowRenderer component configuration
+ * DarknessRenderer component configuration
  * @public
  * @category Components Configuration
  * @example
  * ```js
- * const shadowRenderer = new ShadowRenderer({
+ * const darknessRenderer = new DarknessRenderer({
  *   width: 100,
  *   height: 50,
  *   color: "#000000",
@@ -3573,7 +3636,7 @@ declare class MaskRenderer {
  * });
  * ```
  */
-interface ShadowRendererOptions {
+interface DarknessRendererOptions {
     width: number;
     height: number;
     color: string;
@@ -3581,15 +3644,15 @@ interface ShadowRendererOptions {
     layer: string;
 }
 /**
- * The ShadowRenderer component is used to render a shadow effect on the screen.\
- * It supports a rectangular shadow with configurable width, height, color, opacity, and render layer.\
- * This component works in conjunction with LightRenderer components in the scene - the shadow will
- * block and be affected by any lights that intersect with it.\
+ * The DarknessRenderer component is used to render a darkness effect on the screen.\
+ * It supports a rectangular darkness mask with configurable width, height, color, opacity, and render layer.\
+ * This component works in conjunction with LightRenderer components in the scene - the darkness will
+ * block and be affected by any lights that intersect with it.
  * @public
  * @category Components
  * @example
  * ```js
- * const shadowRenderer = new ShadowRenderer({
+ * const darknessRenderer = new DarknessRenderer({
  *   width: 100,
  *   height: 50,
  *   color: "#000000",
@@ -3598,22 +3661,22 @@ interface ShadowRendererOptions {
  * });
  * ```
  */
-declare class ShadowRenderer {
-    /** Shadow width */
+declare class DarknessRenderer {
+    /** Darkness rectangle width */
     width: number;
-    /** Shadow height */
+    /** Darkness height */
     height: number;
-    /** Shadow color */
+    /** Darkness color */
     color: string;
-    /** Shadow opacity between 0 and 1 */
+    /** Darkness opacity between 0 and 1 */
     opacity: number;
     /** The render layer */
     layer: string;
     /** @internal */
     _boundingBox: Rectangle;
     /** @internal */
-    _renderData: ShadowRenderData;
-    constructor(options?: Partial<ShadowRendererOptions>);
+    _renderData: DarknessRenderData;
+    constructor(options?: Partial<DarknessRendererOptions>);
 }
 
 /**
@@ -4788,4 +4851,4 @@ declare const BuiltInDependencyIdentifiers: {
     TimeManager: symbol;
 };
 
-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, BuiltInDependencyIdentifiers, Button, type ButtonOptions, ButtonShape, Camera, type CameraOptions, type Chunk, Circumference, type Collider, type Collision, type CollisionMatrix, CollisionMethods, CollisionRepository, type CollisionResolution, type Component, type ComponentType, type DependencyName, type DependencyType, type DisabledComponent, EdgeCollider, type EdgeColliderOptions, type Entity, EntityManager, Game, type GameConfig, GameSystem, GamepadController, 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, Scene, SceneManager, type SceneType, type SearchCriteria, type SearchResult, ShadowRenderer, type ShadowRendererOptions, type Shape, type Slice, SpriteRenderer, type SpriteRendererOptions, type System, type SystemGroup, SystemManager, type SystemType, TextOrientation, 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 };
+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, BuiltInDependencyIdentifiers, 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, 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, Scene, SceneManager, type SceneType, type SearchResult, type Shape, type Slice, SpriteRenderer, type SpriteRendererOptions, type System, type SystemGroup, SystemManager, type SystemType, TextOrientation, 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 };