angry-pixel 2.3.3 → 2.3.5

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 {
@@ -3490,7 +3638,6 @@ interface TilemapRenderData extends RenderData {
     tiles: number[];
     tilemap: Tilemap;
     tileset: Tileset$1;
-    tileAnimations?: Map<number, number>;
     smooth?: boolean;
     flipHorizontal?: boolean;
     flipVertical?: boolean;
@@ -3503,12 +3650,30 @@ interface TilemapRenderData extends RenderData {
 }
 type Tileset$1 = {
     image: HTMLImageElement;
-    width: number;
     tileWidth: number;
     tileHeight: number;
-    margin?: Vector2;
-    spacing?: Vector2;
-    correction?: Vector2;
+    /** Space in pixels between the tiles and the four edges of the image */
+    margin?: number;
+    /** Space in pixels between adjacent tiles */
+    spacing?: number;
+    /** Maps each animated tile id to the tile id currently displayed. @internal */
+    _animationState?: Map<number, number>;
+    /** Tileset values in texture coordinates. Computed once by the renderer. @internal */
+    _texData?: TilesetTexData;
+};
+/**
+ * Tileset values expressed in texture coordinates (0 to 1), plus the number of columns of the tileset.
+ * @internal
+ */
+type TilesetTexData = {
+    /** The width of the tileset (in tiles) */
+    columns: number;
+    /** The margin of the image */
+    margin: Vector2;
+    /** The distance between the origin of two adjacent tiles */
+    step: Vector2;
+    /** The size of a tile */
+    tileSize: Vector2;
 };
 type Tilemap = {
     width: number;
@@ -4111,7 +4276,7 @@ declare const defaultTextureAtlasOptions: {
  *     opacity: 0.5,
  *   },
  *   textureAtlas: {
- *     charRanges: [32, 126, 161, 255, 0x3040, 0x309f],
+ *     charRanges: [32, 132, 161, 255, 0x3040, 0x309f],
  *     fontSize: 64,
  *     spacing: 4,
  *   },
@@ -4166,9 +4331,15 @@ interface TextRendererOptions {
     text: string;
     /** The texture atlas configuration */
     textureAtlas: {
-        /** Range of characters covered by the component defined in number pairs.
-         * The default value is [32, 126, 161, 255], this means that the component
-         * will render characters from 32 to 126 and from 161 to 255. */
+        /** Ranges of characters covered by the component, defined as pairs of
+         * Unicode code points (each pair is an inclusive from–to range).
+         * The default value is [32, 132, 161, 255], which covers Basic Latin
+         * (letters, digits and punctuation) and the Latin-1 Supplement
+         * (accented letters and symbols used by Western European languages).
+         * Additional pairs can be appended to render other alphabets, e.g.
+         * [0x3040, 0x309F] for Japanese Hiragana or [0x0400, 0x04FF] for Cyrillic.
+         * See the official Unicode Character Code Charts to find the range of
+         * each alphabet: {@link https://www.unicode.org/charts/} */
         charRanges?: number[];
         /** The size of the font in pixels for bitmap fonts. */
         fontSize?: number;
@@ -4219,7 +4390,7 @@ interface TextRendererOptions {
  *     opacity: 0.5,
  *   },
  *   textureAtlas: {
- *     charRanges: [32, 126, 161, 255, 0x3040, 0x309f],
+ *     charRanges: [32, 132, 161, 255, 0x3040, 0x309f],
  *     fontSize: 64,
  *     spacing: 4,
  *   },
@@ -4276,9 +4447,15 @@ declare class TextRenderer {
     text: string;
     /** The texture atlas configuration */
     textureAtlas: {
-        /** Range of characters covered by the component defined in number pairs.
-         * The default value is [32, 126, 161, 255], this means that the component
-         * will render characters from 32 to 126 and from 161 to 255. */
+        /** Ranges of characters covered by the component, defined as pairs of
+         * Unicode code points (each pair is an inclusive from–to range).
+         * The default value is [32, 132, 161, 255], which covers Basic Latin
+         * (letters, digits and punctuation) and the Latin-1 Supplement
+         * (accented letters and symbols used by Western European languages).
+         * Additional pairs can be appended to render other alphabets, e.g.
+         * [0x3040, 0x309F] for Japanese Hiragana or [0x0400, 0x04FF] for Cyrillic.
+         * See the official Unicode Character Code Charts to find the range of
+         * each alphabet: {@link https://www.unicode.org/charts/} */
         charRanges?: number[];
         /** The size of the font in pixels for bitmap fonts. */
         fontSize?: number;
@@ -4304,11 +4481,10 @@ declare class TextRenderer {
  *   layer: "Default",
  *   tileset: {
  *     image: this.assetManager.getImage("tileset.png"),
- *     width: 10,
  *     tileWidth: 32,
  *     tileHeight: 32,
- *     margin: new Vector2(0, 0),
- *     spacing: new Vector2(0, 0)
+ *     margin: 0,
+ *     spacing: 0
  *   },
  *   data: [1, 2, 3, 4],
  *   chunks: [],
@@ -4338,7 +4514,7 @@ interface TilemapRendererOptions {
     maskColorMix: number;
     opacity: number;
     smooth: boolean;
-    animations: Map<number, TileAnimation>;
+    offset: Vector2;
 }
 /**
  * The TilemapRenderer component renders 2D tile-based maps to the screen.\
@@ -4354,11 +4530,10 @@ interface TilemapRendererOptions {
  *   layer: "Default",
  *   tileset: {
  *     image: this.assetManager.getImage("tileset.png"),
- *     width: 10,
  *     tileWidth: 32,
  *     tileHeight: 32,
- *     margin: new Vector2(0, 0),
- *     spacing: new Vector2(0, 0)
+ *     margin: 0,
+ *     spacing: 0
  *   },
  *   data: [1, 2, 3, 4],
  *   chunks: [],
@@ -4401,17 +4576,23 @@ declare class TilemapRenderer {
     maskColorMix: number;
     /** TRUE for smooth pixels (not recommended for pixel art) */
     smooth: boolean;
-    /** Animated tiles, keyed by the tile id to animate. */
-    animations: Map<number, TileAnimation>;
+    /** X-Y axis offset */
+    offset: Vector2;
     /** @internal */
     _processed: boolean;
     /** @internal */
+    _dataFromChunks: boolean;
+    /** @internal */
     _renderData: TilemapRenderData[];
-    /** Maps each animated tile id to the tile id currently displayed. @internal */
-    _tileAnimationState: Map<number, number>;
     /** @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
@@ -4431,18 +4612,23 @@ interface TileAnimationOptions {
 }
 /**
  * TileAnimation cycles a tile through a sequence of tile ids from the tileset.\
- * It is assigned to a {@link TilemapRenderer} keyed by the tile id that should animate.
+ * It is assigned to a {@link Tileset} keyed by the tile id that should animate,\
+ * so every tilemap using that tileset plays the animation in sync.
  * @public
  * @category Components Configuration
  * @example
  * ```js
  * const tilemapRenderer = new TilemapRenderer({
- *   tileset: { image: "tileset.png", width: 10, tileWidth: 32, tileHeight: 32 },
+ *   tileset: {
+ *     image: "tileset.png",
+ *     tileWidth: 32,
+ *     tileHeight: 32,
+ *     animations: new Map([
+ *       [3, new TileAnimation({ tiles: [3, 4, 5], fps: 6 })]
+ *     ])
+ *   },
  *   data: [1, 2, 3, 4],
- *   width: 2,
- *   animations: new Map([
- *     [3, new TileAnimation({ tiles: [3, 4, 5], fps: 6 })]
- *   ])
+ *   width: 2
  * });
  * ```
  */
@@ -4459,22 +4645,36 @@ declare class TileAnimation {
 }
 /**
  * The Tileset configuration defines the properties of a tileset used by the TilemapRenderer.\
- * It specifies the source image containing the tiles, the dimensions of the tileset and individual tiles,\
- * and optional margin and spacing between tiles. This configuration is essential for properly\
- * slicing and rendering tiles from the tileset image.
+ * It specifies the source image containing the tiles, the size of the individual tiles,\
+ * and the optional margin and spacing of the image. The number of columns of the tileset\
+ * is obtained from the image. The tileset cannot be updated at runtime.
  * @public
  * @category Components Configuration
+ * @example
+ * ```js
+ * // a tileset of 16x16 tiles extruded by 1 pixel
+ * const tileset = {
+ *   image: this.assetManager.getImage("tileset.png"),
+ *   tileWidth: 16,
+ *   tileHeight: 16,
+ *   margin: 1,
+ *   spacing: 2
+ * };
+ * ```
  */
 type Tileset = {
     /** The tileset image element */
     image: HTMLImageElement | string;
-    width: number;
     tileWidth: number;
     tileHeight: number;
-    /** Margin of the tile in pixels (space in the top and the left) */
-    margin?: Vector2;
-    /** Spacing of the tile in pixels (space in the bottom and the right) */
-    spacing?: Vector2;
+    /** Space in pixels between the tiles and the four edges of the image */
+    margin?: number;
+    /** Space in pixels between adjacent tiles */
+    spacing?: number;
+    /** Animated tiles, keyed by the tile id to animate */
+    animations?: Map<number, TileAnimation>;
+    /** Maps each animated tile id to the tile id currently displayed. @internal */
+    _animationState?: Map<number, number>;
 };
 /**
  * Chunk of tile data
@@ -5195,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 };