angry-pixel 2.3.4 → 2.3.6

package/lib/index.d.ts

@@ -945,6 +945,20 @@ declare class EntityManager {
      * ```
      */
     createEntity(archetype: Archetype, parent?: Entity): Entity;
+    /**
+     * Adds the components of an Archetype to an existing Entity.\
+     * Component instances are cloned, so the archetype can be reused.\
+     * Child archetypes are created as new entities parented to the given one.
+     * @param entity The entity to add the archetype to
+     * @param archetype The archetype to add
+     * @public
+     * @example
+     * ```js
+     * const entity = entityManager.createEntity();
+     * entityManager.addArchetype(entity, archetype);
+     * ```
+     */
+    addArchetype(entity: Entity, { components, disabledComponents, children, enabled }: Archetype): void;
     private createEntityFromArray;
     /**
      * Creates an Entity from an Archetype.
@@ -1644,8 +1658,12 @@ interface GameConfig {
         mousePosition: boolean;
         /** Show text renderer bounding boxes */
         textRendererBoundingBoxes: boolean;
+        /** Show button shapes */
+        buttons?: boolean;
         /** Color of the colliders, default "#00FF00" (green) */
         collidersColor?: string;
+        /** Color of the button shapes, default "#FF00FF" (magenta) */
+        buttonColor?: string;
         /** Color of the text box, default "#0000FF" (blue) */
         textBoxColor?: string;
         /** Color of the text, default "#00FF00" (green) */
@@ -2619,17 +2637,25 @@ declare enum ButtonShape {
  *
  * const tiledWrapper = new TiledWrapper({
  *   tilemap: assetManager.getJson("tilemap.json"),
- *   layerToRender: "Ground"
+ *   layerToRender: "Ground",
+ *   objects: new Map([
+ *     ["Player", playerArchetype],
+ *     ["Coin", [new Transform(), new SpriteRenderer({ image: "coin.png" })]],
+ *     ["Door", (properties) => doorArchetype(properties.get("locked"))]
+ *   ])
  * });
  * ```
  */
 interface TiledWrapperOptions {
     tilemap: TiledTilemap | string;
     layerToRender: string;
+    objects: Map<string, TiledObjectBlueprint>;
 }
 /**
  * The TiledWrapper component wraps a Tiled map editor tilemap and handles rendering a specific layer.\
- * It provides an interface between Tiled's map format and the engine's tilemap rendering system.
+ * It provides an interface between Tiled's map format and the engine's tilemap rendering system.\
+ * The tiles animated in Tiled are mapped to the animations of the TilemapRenderer tileset.\
+ * It can also create entities from the objects of the tilemap, matching them by class with the `objects` map.
  * @public
  * @category Components
  * @example
@@ -2654,10 +2680,62 @@ declare class TiledWrapper {
     tilemap: TiledTilemap | string;
     /** The layer to render. */
     layerToRender: string;
+    /**
+     * Entities to create from the objects found in the tilemap, keyed by the object class.\
+     * Objects are matched by class in every visible object layer of the tilemap.
+     */
+    objects: Map<string, TiledObjectBlueprint>;
+    /** @internal */
+    _processed: boolean;
+    /** @internal */
+    _objectsCreated: boolean;
+    /** @internal */
+    _animationsMapped: boolean;
+    /** The coordinates (in tiles) of the top-left corner of the rendered layer. @internal */
+    _origin: Vector2;
     /** @internal */
     static componentName: string;
     constructor(options?: Partial<TiledWrapperOptions>);
+    /**
+     * Reads the tilemap again, to apply the changes made to it at runtime, such as rendering another layer.\
+     * The entities created from the objects of the tilemap are not created again.\
+     * The TilemapRenderer and the TilemapCollider of the entity need to be refreshed too.\
+     * This operation is expensive, avoid calling it on every frame.
+     */
+    refresh(): void;
 }
+/**
+ * The properties of a Tiled object, keyed by property name.\
+ * `int` and `float` properties are given as `number`, `bool` as `boolean`, `string`, `color` and `file` as `string`,\
+ * and `class` as a nested set of values.\
+ * Properties of type `object` are given as the {@link Entity} created for the referenced Tiled object,\
+ * or `undefined` if no entity was created for it.
+ * @public
+ * @category Components Configuration
+ */
+type TiledObjectProperties = Map<string, number | boolean | string | Entity | Record<string, unknown>>;
+/**
+ * Creates the entity for a Tiled object, based on its properties.
+ * @param properties The properties of the Tiled object
+ * @param object The Tiled object itself
+ * @returns An archetype or a collection of components
+ * @public
+ * @category Components Configuration
+ * @example
+ * ```js
+ * const doorFactory = (properties, object) => ({
+ *   components: [new Door({ locked: properties.get("locked"), lever: properties.get("lever") })]
+ * });
+ * ```
+ */
+type TiledObjectFactory = (properties: TiledObjectProperties, object: TiledObject) => Archetype | Component[];
+/**
+ * Defines the entity to create for a Tiled object class. It can be an archetype, a collection of components,\
+ * or a {@link TiledObjectFactory} function that builds either of them from the object's properties.
+ * @public
+ * @category Components Configuration
+ */
+type TiledObjectBlueprint = Archetype | Component[] | TiledObjectFactory;
 /**
  * @public
  * @category Components Configuration
@@ -2666,15 +2744,55 @@ interface TiledTilemap {
     width: number;
     height: number;
     infinite: boolean;
-    layers: (TiledLayer | TiledObjectLayer)[];
+    layers: (TiledLayer | TiledObjectLayer | TiledGroupLayer)[];
     renderorder: string;
-    tilesets: {
-        firstgid: number;
-    }[];
+    tilesets: TiledTileset[];
     tilewidth: number;
     tileheight: number;
     properties?: TiledProperty[];
 }
+/**
+ * @public
+ * @category Components Configuration
+ */
+interface TiledTileset {
+    /** The id of the first tile of the tileset. The id of a tile is this value plus the id it has within the tileset */
+    firstgid: number;
+    /** Only present in external tilesets, which are not read by the engine */
+    source?: string;
+    name?: string;
+    image?: string;
+    columns?: number;
+    tilecount?: number;
+    tilewidth?: number;
+    tileheight?: number;
+    margin?: number;
+    spacing?: number;
+    /** Only the tiles with data of their own, such as animations or properties */
+    tiles?: TiledTilesetTile[];
+}
+/**
+ * @public
+ * @category Components Configuration
+ */
+interface TiledTilesetTile {
+    /** The id of the tile within the tileset */
+    id: number;
+    animation?: TiledTileAnimationFrame[];
+    objectgroup?: TiledObjectLayer;
+    properties?: TiledProperty[];
+    type?: string;
+}
+/**
+ * @public
+ * @category Components Configuration
+ */
+interface TiledTileAnimationFrame {
+    /** The duration of the frame in milliseconds */
+    duration: number;
+    /** The id of the tile to render, within the tileset */
+    tileid: number;
+}
 /**
  * @public
  * @category Components Configuration
@@ -2721,9 +2839,29 @@ interface TiledObjectLayer {
     objects: TiledObject[];
     opacity: number;
     type: "objectgroup";
-    visible: true;
+    visible: boolean;
+    x: number;
+    y: number;
+    offsetx?: number;
+    offsety?: number;
+    properties?: TiledProperty[];
+}
+/**
+ * A layer that groups other layers. Its offset and its visibility are applied to all of them.
+ * @public
+ * @category Components Configuration
+ */
+interface TiledGroupLayer {
+    id: number;
+    name: string;
+    type: "group";
+    layers: (TiledLayer | TiledObjectLayer | TiledGroupLayer)[];
+    opacity: number;
+    visible: boolean;
     x: number;
     y: number;
+    offsetx?: number;
+    offsety?: number;
     properties?: TiledProperty[];
 }
 /**
@@ -2731,13 +2869,17 @@ interface TiledObjectLayer {
  * @category Components Configuration
  */
 interface TiledObject {
-    gid: number;
+    /** Only present in tile objects. Their origin is the bottom-left corner, instead of the top-left corner */
+    gid?: number;
     height: number;
     id: number;
     name: string;
     rotation: number;
-    type: string;
-    visible: true;
+    /** The class of the object. Tiled 1.9 exports it as `class`, the other versions as `type` */
+    type?: string;
+    /** The class of the object, as exported by Tiled 1.9 */
+    class?: string;
+    visible: boolean;
     width: number;
     x: number;
     y: number;
@@ -2757,8 +2899,9 @@ interface TiledObject {
  */
 interface TiledProperty {
     name: string;
-    type: "int" | "bool" | "float" | "color" | "string";
-    value: number | string | boolean;
+    type: "int" | "bool" | "float" | "color" | "string" | "file" | "object" | "class";
+    /** Properties of type `object` hold the id of another Tiled object, and `class` properties hold a nested set of values */
+    value: number | string | boolean | Record<string, unknown>;
 }
 
 /**
@@ -3317,6 +3460,11 @@ declare class TilemapCollider implements Collider {
     /** @internal */
     static componentName: string;
     constructor(options?: Partial<TilemapColliderOptions>);
+    /**
+     * Generates the collider shapes again, to apply the changes made to the tilemap at runtime.\
+     * This operation is expensive, avoid calling it on every frame.
+     */
+    refresh(): void;
 }
 
 declare enum RenderDataType {
@@ -4366,6 +4514,7 @@ interface TilemapRendererOptions {
     maskColorMix: number;
     opacity: number;
     smooth: boolean;
+    offset: Vector2;
 }
 /**
  * The TilemapRenderer component renders 2D tile-based maps to the screen.\
@@ -4427,13 +4576,23 @@ declare class TilemapRenderer {
     maskColorMix: number;
     /** TRUE for smooth pixels (not recommended for pixel art) */
     smooth: boolean;
+    /** X-Y axis offset */
+    offset: Vector2;
     /** @internal */
     _processed: boolean;
     /** @internal */
+    _dataFromChunks: boolean;
+    /** @internal */
     _renderData: TilemapRenderData[];
     /** @internal */
     static componentName: string;
     constructor(options?: Partial<TilemapRendererOptions>);
+    /**
+     * Processes the tilemap data again, to apply the changes made to it at runtime.\
+     * The array that was generated from the other one is emptied, so it is generated again.\
+     * This operation is expensive, avoid calling it on every frame.
+     */
+    refresh(): void;
 }
 /**
  * TileAnimation configuration
@@ -5236,4 +5395,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 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 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 };