angry-pixel 2.0.21 → 2.1.0

package/lib/index.d.ts

@@ -352,7 +352,7 @@ declare class Rectangle {
      * @param rect The target rectangle
      * @returns TRUE or FALSE
      */
-    overlaps(rect: Rectangle): boolean;
+    intersects(rect: Rectangle): boolean;
     /**
      * Check if the target rectangle is contained
      *
@@ -367,6 +367,7 @@ declare class Rectangle {
      * @returns TRUE or FALSE
      */
     contains(vector: Vector2): boolean;
+    toString(): string;
 }
 
 /**
@@ -654,6 +655,81 @@ type SearchResult<T extends Component> = {
 type SearchCriteria = {
     [key: string]: any;
 };
+/**
+ * This type represents an Entity Archetype
+ * @public
+ * @category Entity-Component-System
+ */
+type Archetype = {
+    components: (ArchetypeComponent | Component)[];
+    children?: Archetype[];
+    enabled?: boolean;
+};
+/**
+ * This type represents an Entity Archetype Component
+ * @public
+ * @category Entity-Component-System
+ */
+type ArchetypeComponent<T extends Component = Component> = {
+    type: ComponentType<T>;
+    data?: Partial<T>;
+    enabled?: boolean;
+};
+/**
+ * This interface is used for the creation of system classes. You will have to inject the dependencies you need manully.
+ * @public
+ * @category Entity-Component-System
+ * @example
+ * ```typescript
+ * class PlayerSystem implements System {
+ *   @inject(Symbols.EntityManager) private readonly entityManager: EntityManager;
+ *
+ *   public onUpdate() {
+ *     this.entityManager.search(Player).forEach(({component, entity}) => {
+ *       // do somethng
+ *     });
+ *   }
+ * }
+ * ```
+ */
+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
+     */
+    onUpdate(): void;
+}
+/**
+ * This type represents a system class
+ * @public
+ * @category Entity-Component-System
+ */
+type SystemType<T extends System = System> = {
+    new (...args: any[]): T;
+};
+/** @internal */
+type SystemGroup = string | number | symbol;
+
 /**
  * The EntityManager manages the entities and components.\
  * It provides the necessary methods for reading and writing entities and components.
@@ -666,7 +742,10 @@ declare class EntityManager {
     private entities;
     private components;
     private disabledEntities;
+    private manuallyDisabledEntities;
     private disabledComponents;
+    private parentEntities;
+    private childEntities;
     /**
      * Creates an entity without component
      * @return The created Entity
@@ -677,6 +756,83 @@ declare class EntityManager {
      * ```
      */
     createEntity(): Entity;
+    /**
+     * Creates an Entity based on an Archetype
+     * @param archetype The Archetype to create the Entity
+     * @return The created Entity
+     * @public
+     * @example
+     * ```js
+     * // Using ArchetypeComponent to define components
+     * const entity = entityManager.createEntity({
+     *   components: [
+     *     {type: Transform, data: {position: new Vector2(100, 100)}},
+     *     {type: SpriteRenderer, data: {image: "images/player.png"}},
+     *     {type: Player},
+     *   ],
+     *   children: [
+     *     {
+     *       components: [
+     *         {type: Transform, data: {position: new Vector2(8, 0)}},
+     *         {type: SpriteRenderer, data: {image: "images/sword.png"}},
+     *         {type: Weapon, data: {damage: 10}},
+     *       ],
+     *     },
+     *     {
+     *       components: [
+     *         {type: Transform, data: {position: new Vector2(-8, 0)}},
+     *         {type: SpriteRenderer, data: {image: "images/shield.png"}},
+     *         {type: Shield, data: {defense: 5}, enabled: false},
+     *       ],
+     *     },
+     *     {
+     *       components: [
+     *         {type: Transform, data: {position: new Vector2(8, 0)}},
+     *         {type: SpriteRenderer, data: {image: "images/staf.png"}},
+     *         {type: Staff, data: {mana: 5}},
+     *       ],
+     *       enabled: false,
+     *     }
+     *   ]
+     * });
+     * ```
+     * @example
+     * ```js
+     * // Using Component instances as templates
+     * const entity = entityManager.createEntity({
+     *   components: [
+     *     new Transform({position: new Vector2(100, 100)}),
+     *     new SpriteRenderer({image: "images/player.png"}),
+     *     new Player(),
+     *   ],
+     *   children: [
+     *     {
+     *       components: [
+     *         new Transform({position: new Vector2(8, 0)}),
+     *         new SpriteRenderer({image: "images/sword.png"}),
+     *         new Weapon({damage: 10}),
+     *       ],
+     *     },
+     *     {
+     *       components: [
+     *         new Transform({position: new Vector2(-8, 0)}),
+     *         new SpriteRenderer({image: "images/shield.png"}),
+     *         new Shield({defense: 5}),
+     *       ],
+     *     },
+     *     {
+     *       components: [
+     *         new Transform({position: new Vector2(8, 0)}),
+     *         new SpriteRenderer({image: "images/staf.png"}),
+     *         new Staff({mana: 5}),
+     *       ],
+     *       enabled: false,
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    createEntity(archetype: Archetype): Entity;
     /**
      * Creates an Entity based on a collection of Component instances and ComponentTypes
      * @param components A collection of component instances and component classes
@@ -690,7 +846,9 @@ declare class EntityManager {
      * ]);
      * ```
      */
-    createEntity(components: Array<ComponentType | Component>): Entity;
+    createEntity(components: Array<ComponentType | Component>, parent?: Entity): Entity;
+    private createEntityFromComponents;
+    private createEntityFromArchetype;
     /**
      * Creates multiple entities based on an array of component collections
      * @param componentsList An array of collections of component instances and component classes
@@ -698,20 +856,22 @@ declare class EntityManager {
      * @public
      * @example
      * ```js
-     * const parent =  [
+     * const player =  [
      *   new Transform({position: new Vector2(100, 100)}),
-     *   SpriteRenderer
+     *   SpriteRenderer,
+     *   Player
      * ];
      *
-     * const child =  [
-     *   new Transform({parent: parent[0]}),
-     *   SpriteRenderer
+     * const enemy =  [
+     *   new Transform({position: new Vector2(-100, 100)}),
+     *   SpriteRenderer,
+     *   Enemy
      * ];
      *
-     * const entity = entityManager.createEntities([parent, child]);
+     * const entities = entityManager.createEntities([player, enemy]);
      * ```
      */
-    createEntities(componentsList: Component[][]): Entity[];
+    createEntities(componentsList: Array<ComponentType | Component>[]): Entity[];
     /**
      * Removes an Entity and all its Components
      * @param entity The entity to remove
@@ -753,7 +913,11 @@ declare class EntityManager {
      */
     isEntityEnabled(entity: Entity): boolean;
     /**
-     * Enables an Entity
+     * Enables an Entity.\
+     * The entity's components will be included in the `search` results\
+     * and therefore will be processed by their respective systems\
+     * (the engine built-in systems use the `search` method to retrieve the entities).
+     * If the entity has children, they will also be enabled, except for those that have been manually disabled.
      * @param entity The entity to be enabled
      * @public
      * @example
@@ -763,7 +927,11 @@ declare class EntityManager {
      */
     enableEntity(entity: Entity): void;
     /**
-     * Disables an Entity
+     * Disables an entity.\
+     * The entity's components will not be included in the `search` results\
+     * and therefore will not be processed by their respective systems\
+     * (the engine built-in systems use the `search` method to retrieve the entities).
+     * If the entity has children, they will also be disabled.
      * @param entity The entity to be disabled
      * @public
      * @example
@@ -792,6 +960,60 @@ declare class EntityManager {
      * ```
      */
     enableEntitiesByComponent(componentType: ComponentType): void;
+    /**
+     * Sets a parent-child relationship between two entities
+     * @param child The child entity
+     * @param parent The parent entity
+     * @public
+     * @example
+     * ```js
+     * entityManager.setParent(child, parent);
+     * ```
+     */
+    setParent(child: Entity, parent: Entity): void;
+    /**
+     * Returns the parent entity of the child entity
+     * @param child
+     * @returns The parent entity
+     * @public
+     * @example
+     * ```js
+     * const parent = entityManager.getParent(child);
+     * ```
+     */
+    getParent(child: Entity): Entity;
+    /**
+     * Returns all child entities of the parent entity
+     * @param parent
+     * @returns A collection of child entities
+     * @public
+     * @example
+     * ```js
+     * const children = entityManager.getChildren(parent);
+     * ```
+     */
+    getChildren(parent: Entity): Entity[];
+    /**
+     * Removes the parent-child relationship between two entities
+     * @param child The child entity
+     * @public
+     * @example
+     * ```js
+     * entityManager.removeParent(child);
+     * ```
+     */
+    removeParent(child: Entity): void;
+    /**
+     * Removes a child entity from the parent entity
+     * @param parent The parent entity
+     * @param child The child entity
+     * @public
+     * @example
+     * ```js
+     * entityManager.removeChild(parent, child);
+     * ```
+     */
+    removeChild(parent: Entity, child: Entity): void;
     /**
      * Adds a component to the entity
      * @param entity The Entity to which the component will be added
@@ -949,6 +1171,18 @@ declare class EntityManager {
      * ```
      */
     enableComponent<T extends Component>(entity: Entity, componentType: ComponentType<T>): void;
+    /**
+     * Returns the component of a parent entity, if it exists.
+     * @param parent The parent entity
+     * @param componentType The component class to search
+     * @returns  The instance of the component
+     * @public
+     * @example
+     * ```js
+     * const spriteRenderer = entityManager.getComponentFromParent(parent, SpriteRenderer);
+     * ```
+     */
+    getComponentFromParent<T extends Component>(parent: Entity, componentType: ComponentType<T>): T | undefined;
     /**
      * 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.\
@@ -973,8 +1207,39 @@ declare class EntityManager {
      *   // do something with the component and entity
      * })
      * ```
+     * @example
+     * ```js
+     * const searchResult = entityManager.search(Enemy, {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>[];
+    /**
+     * 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
+     * @returns SearchResult
+     * @public
+     * @example
+     * ```js
+     * const searchResult = entityManager.search(SpriteRenderer);
+     * searchResult.forEach(({component, entity}) => {
+     *   // do something with the component and entity
+     * })
+     * ```
+     * @example
+     * ```js
+     * const searchResult = entityManager.search(Enemy, true);
+     * searchResult.forEach(({component, entity}) => {
+     *   // do something with the component and entity
+     * })
+     * ```
+     */
+    search<T extends Component>(componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
     /**
      * Performs an entity search given a collection of component types.\
      * The entities found must have an instance of all the given component types.\
@@ -988,63 +1253,34 @@ declare class EntityManager {
      * ```
      */
     searchEntitiesByComponents(componentTypes: ComponentType[]): Entity[];
-    private getComponentTypeId;
-}
-
-/**
- * This interface is used for the creation of system classes. You will have to inject the dependencies you need manully.
- * @public
- * @category Entity-Component-System
- * @example
- * ```typescript
- * class PlayerSystem implements System {
- *   @inject(Symbols.EntityManager) private readonly entityManager: EntityManager;
- *
- *   public onUpdate() {
- *     this.entityManager.search(Player).forEach(({component, entity}) => {
- *       // do somethng
- *     });
- *   }
- * }
- * ```
- */
-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
+     * Performs a search for entities that have a component of the given type and are children of the parent entity.\
+     * This method returns a collection of objects of type SearchResult, which has the entity found, and the instance of the component.\
+     * 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
+     * @returns SearchResult
      * @public
+     * @example
+     * ```js
+     * const searchResult = entityManager.searchInChildren(parent, SpriteRenderer);
+     * searchResult.forEach(({component, entity}) => {
+     *  // do something with the component and entity
+     * })
+     * ```
+     * @example
+     * ```js
+     * const searchResult = entityManager.searchInChildren(parent, SpriteRenderer, true);
+     * searchResult.forEach(({component, entity}) => {
+     * // do something with the component and entity
+     * })
+     * ```
      */
-    onUpdate(): void;
+    searchInChildren<T extends Component>(parent: Entity, componentType: ComponentType<T>, includeDisabled?: boolean): SearchResult<T>[];
+    private getComponentTypeId;
 }
-/**
- * This type represents a system class
- * @public
- * @category Entity-Component-System
- */
-type SystemType<T extends System = System> = {
-    new (...args: any[]): T;
-};
-/** @internal */
-type SystemGroup = string | number | symbol;
+
 /**
  * The SystemManager manages the systems.\
  * It provides the necessary methods for reading and writing systems.
@@ -1842,22 +2078,6 @@ declare enum ButtonShape {
     Circumference = 1
 }
 
-/**
- * @public
- * @category Components
- */
-declare class Children {
-    entities: Entity[];
-}
-
-/**
- * @public
- * @category Components
- */
-declare class Parent {
-    entity: Entity;
-}
-
 /**
  * @public
  * @category Components
@@ -1986,10 +2206,6 @@ interface TransformOptions {
     position: Vector2;
     scale: Vector2;
     rotation: number;
-    parent: Transform;
-    localPosition: Vector2;
-    localScale: Vector2;
-    localRotation: number;
 }
 /**
  * @public
@@ -2009,14 +2225,9 @@ declare class Transform {
     /** The real rotation in the simulated world. It has the same value as `rotation` property if there is no parent */
     localRotation: number;
     /** @internal */
-    _parentEntity: Entity;
+    _awake: boolean;
     /** @internal */
-    _childEntities: Entity[];
-    private _parent;
-    /** The parent transform. The position property became relative to this transform */
-    get parent(): Transform;
-    /** The parent transform. The position property became relative to this transform */
-    set parent(parent: Transform);
+    _parent: Transform;
     constructor(options?: Partial<TransformOptions>);
 }
 
@@ -3767,4 +3978,4 @@ declare const Symbols: {
     TimeManager: symbol;
 };
 
-export { Animation, type AnimationSlice, Animator, type AnimatorOptions, AssetManager, AudioPlayer, type AudioPlayerAction, type AudioPlayerOptions, type AudioPlayerState, BallCollider, type BallColliderOptions, BoxCollider, type BoxColliderOptions, BroadPhaseMethods, Button, type ButtonOptions, ButtonShape, Camera, type CameraOptions, Children, type Chunk, Circumference, type Collider, type Collision, type CollisionMatrix, CollisionMethods, CollisionRepository, type CollisionResolution, type Component, type ComponentType, type DependencyName, type DependencyType, EdgeCollider, type EdgeColliderOptions, type Entity, EntityManager, Game, type GameConfig, GameSystem, GamepadController, InputManager, type IntervalOptions, Keyboard, LightRenderer, type LightRendererOptions, MaskRenderer, type MaskRendererOptions, MaskShape, Mouse, Parent, 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, Symbols, 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, fixedRound, gameLogicSystem, gamePhysicsSystem, gamePreRenderSystem, inject, injectable, playSfx, radiansToDegrees, randomFloat, randomInt, range, rgbToHex, stopSfx };
+export { Animation, type AnimationSlice, Animator, type AnimatorOptions, type Archetype, type ArchetypeComponent, 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, type DependencyName, type DependencyType, 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, Symbols, 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, fixedRound, gameLogicSystem, gamePhysicsSystem, gamePreRenderSystem, inject, injectable, playSfx, radiansToDegrees, randomFloat, randomInt, range, rgbToHex, stopSfx };