angry-pixel 2.0.19 → 2.0.21

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * This type represents a dependency class
  * @public
- * @category Core
+ * @category Dependency Injection
  */
 type DependencyType = {
     new (...args: any[]): any;
@@ -9,9 +9,14 @@ type DependencyType = {
 /**
  * This type represents a dependency name
  * @public
- * @category Core
+ * @category Dependency Injection
  */
 type DependencyName = string | symbol;
+/**
+ * This type represents a property key of a decorator target
+ * @public
+ * @category Dependency Injection
+ */
 type PropertyKey = string | symbol;
 declare class Container {
     private instances;
@@ -372,6 +377,11 @@ declare class Rectangle {
  * @param min min value
  * @param max max value
  * @returns clamped value
+ * @example
+ * ```js
+ * clamp(10, 0, 5); // 5
+ * clamp(10, 0, 15); // 10
+ * ```
  */
 declare const clamp: (value: number, min: number, max: number) => number;
 /**
@@ -381,6 +391,10 @@ declare const clamp: (value: number, min: number, max: number) => number;
  * @param min min value
  * @param max max value
  * @returns the random int value
+ * @example
+ * ```js
+ * randomInt(0, 10); // 5
+ * ```
  */
 declare const randomInt: (min: number, max: number) => number;
 /**
@@ -390,6 +404,11 @@ declare const randomInt: (min: number, max: number) => number;
  * @param min min value
  * @param max max value
  * @returns the random float value
+ * @example
+ * ```js
+ * randomFloat(0, 10); // 5.23
+ * randomFloat(0, 10, 4); // 5.2345
+ * ```
  */
 declare const randomFloat: (min: number, max: number, decimals?: number) => number;
 /**
@@ -399,6 +418,10 @@ declare const randomFloat: (min: number, max: number, decimals?: number) => numb
  * @param value the value to round
  * @param decimals the number of decimals
  * @returns the rounded value
+ * @example
+ * ```js
+ * fixedRound(5.2345, 2); // 5.23
+ * ```
  */
 declare const fixedRound: (value: number, decimals: number) => number;
 /**
@@ -409,6 +432,11 @@ declare const fixedRound: (value: number, decimals: number) => number;
  * @param end the end value
  * @param steps the steps to move
  * @returns number range
+ * @example
+ * ```js
+ * range(0, 5); // [0, 1, 2, 3, 4, 5]
+ * range(0, 10, 2); // [0, 2, 4, 6, 8, 10]
+ * ```
  */
 declare const range: (start: number, end: number, steps?: number) => number[];
 /**
@@ -419,12 +447,23 @@ declare const range: (start: number, end: number, steps?: number) => number[];
  * @param min min value
  * @param max max value
  * @returns true if the number is between the min and the max, false instead
+ * @example
+ * ```js
+ * between(5, 0, 10); // true
+ * between(5, 0, 4); // false
+ * ```
  */
 declare const between: (value: number, min: number, max: number) => boolean;
 /**
  * Converts the given radians to degrees.
  * @param radians
  * @returns degrees
+ * @category Math
+ * @public
+ * @example
+ * ```js
+ * radiansToDegrees(Math.PI); // 180
+ * ```
  */
 declare const radiansToDegrees: (radians: number) => number;
 /**
@@ -433,8 +472,35 @@ declare const radiansToDegrees: (radians: number) => number;
  * @returns radians
  * @category Math
  * @public
+ * @example
+ * ```js
+ * degreesToRadians(180); // 3.141592653589793
+ * ```
  */
 declare const degreesToRadians: (degrees: number) => number;
+/**
+ * Convert RGB to HEX as string
+ * @param rgb
+ * @param prefix default is "#"
+ * @returns string
+ * @public
+ * @category Math
+ * @example
+ * ```js
+ * // default prefix "#"
+ * rgbToHex({ r: 255, g: 255, b: 255 }); // #ffffff
+ * ```
+ * @example
+ * ```js
+ * // no prefix
+ * rgbToHex({ r: 0, g: 255, b: 0 }, ""); // 00ff00
+ * ```
+ */
+declare const rgbToHex: ({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}, prefix?: string) => string;
 
 /** @internal */
 interface Shape {
@@ -552,13 +618,13 @@ interface Collider {
 /**
  * This type an unique identifier of an Entity
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type Entity = number;
 /**
  * This type represents an instance of a component
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type Component = {
     [key: string]: any;
@@ -566,7 +632,7 @@ type Component = {
 /**
  * This type represents a component class
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type ComponentType<T extends Component = Component> = {
     new (...args: any[]): T;
@@ -574,7 +640,7 @@ type ComponentType<T extends Component = Component> = {
 /**
  * This type represents a search result object
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type SearchResult<T extends Component> = {
     entity: Entity;
@@ -583,7 +649,7 @@ type SearchResult<T extends Component> = {
 /**
  * This type represents a search criteria object
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type SearchCriteria = {
     [key: string]: any;
@@ -592,7 +658,7 @@ type SearchCriteria = {
  * The EntityManager manages the entities and components.\
  * It provides the necessary methods for reading and writing entities and components.
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 declare class EntityManager {
     private lastEntityId;
@@ -928,7 +994,7 @@ declare class EntityManager {
 /**
  * This interface is used for the creation of system classes. You will have to inject the dependencies you need manully.
  * @public
- * @category Core
+ * @category Entity-Component-System
  * @example
  * ```typescript
  * class PlayerSystem implements System {
@@ -972,7 +1038,7 @@ interface System {
 /**
  * This type represents a system class
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 type SystemType<T extends System = System> = {
     new (...args: any[]): T;
@@ -983,7 +1049,7 @@ type SystemGroup = string | number | symbol;
  * The SystemManager manages the systems.\
  * It provides the necessary methods for reading and writing systems.
  * @public
- * @category Core
+ * @category Entity-Component-System
  */
 declare class SystemManager {
     private systems;
@@ -1178,12 +1244,19 @@ interface GameConfig {
     width: number;
     /** Game height */
     height: number;
-    /** Enables the debug mode */
-    debugEnabled?: boolean;
-    /** Color of debug elements, default "#00FF00" (green) */
-    debugColor?: string;
-    /** Position of debug text, default "bottom-left" */
-    debugTextPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Debug options */
+    debug?: {
+        /** Show colliders */
+        colliders: boolean;
+        /** Show mouse position */
+        mousePosition: boolean;
+        /** Color of the colliders, default "#00FF00" (green) */
+        collidersColor?: string;
+        /** Color of the text, default "#00FF00" (green) */
+        textColor?: string;
+        /** Position of debug text, default "bottom-left" */
+        textPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    };
     /** Background color of canvas, default "#000000" (black) */
     canvasColor?: string;
     /** Framerate for physics execution. The allowed values are 60, 120, 180, 240.
@@ -1315,6 +1388,11 @@ declare class AssetManager {
     private createAsset;
 }
 
+/**
+ * Options for setting an interval.
+ * @public
+ * @category Managers
+ */
 type IntervalOptions = {
     callback: () => void;
     delay: number;
@@ -1668,7 +1746,7 @@ interface AudioPlayerOptions {
  * @category Components
  */
 declare class AudioPlayer {
-    /** The action to perform with the audio source. */
+    /** The action to perform with the audio source. This action will be erased at the end of the frame */
     action: AudioPlayerAction;
     /** The audio source to play. */
     audioSource: HTMLAudioElement;
@@ -1676,12 +1754,18 @@ declare class AudioPlayer {
     fixedToTimeScale: boolean;
     /** TRUE If the audio source should loop. */
     loop: boolean;
-    /** READONLY, TRUE If the audio source is playing. */
-    playing: boolean;
+    /** READONLY, The current state of the audio source. */
+    state: AudioPlayerState;
     /** The volume of the audio source. */
     volume: number;
+    /** READONLY, TRUE If the audio source is playing. */
+    get playing(): boolean;
+    /** READONLY, TRUE If the audio source is paused. */
+    get paused(): boolean;
+    /** READONLY, TRUE If the audio source is stopped. */
+    get stopped(): boolean;
     /** @internal */
-    _currentAudioSrc: string;
+    _currentAudioSource: HTMLAudioElement;
     _playPromisePendind: boolean;
     constructor(options?: Partial<AudioPlayerOptions>);
     /**
@@ -1702,6 +1786,11 @@ declare class AudioPlayer {
  * @category Components
  */
 type AudioPlayerAction = "stop" | "play" | "pause";
+/**
+ * @public
+ * @category Components
+ */
+type AudioPlayerState = "stopped" | "playing" | "paused";
 
 /**
  * @public
@@ -3615,6 +3704,52 @@ declare function gamePreRenderSystem(): (target: SystemType) => void;
  */
 declare function decorate(decorator: (...args: any[]) => any, target: any, propertyKey?: string | symbol | number): void;
 
+/**
+ * Options for playSfx function.
+ * @public
+ * @category Audio
+ */
+interface PlaySfxOptions {
+    audioSource: HTMLAudioElement;
+    volume?: number;
+    loop?: boolean;
+}
+/**
+ * This funciton is ideal to play one-shot sound effects. It will play the sound effect from the beginning, even if it's already playing.\
+ * You can also use this function to play audio tracks, but it is recommended to use the AudioPlayer component for this. The AudioPlayer component can handle the browser's autoplay policy and other audio-related functions.
+ * @param playSfxOptions - The options for playing the sound effect.
+ * @public
+ * @category Audio
+ * @example
+ * ```javascript
+ * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
+ * playSfx({ audioSource });
+ * ```
+ * @example
+ * ```javascript
+ * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
+ * playSfx({ audioSource, volume: 0.5 });
+ * ```
+ * @example
+ * ```javascript
+ * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
+ * playSfx({ audioSource, loop: true });
+ * ```
+ */
+declare const playSfx: ({ audioSource, volume, loop }: PlaySfxOptions) => void;
+/**
+ * Stop a sound effect.
+ * @param audioSource - The audio source to stop.
+ * @public
+ * @category Audio
+ * @example
+ * ```javascript
+ * const audioSource = this.assetManager.getAudio("audio/sfx/coin.ogg");
+ * stopSfx(audioSource);
+ * ```
+ */
+declare const stopSfx: (audioSource: HTMLAudioElement) => void;
+
 /**
  * Symbols to be used as dependency identifiers
  * @public
@@ -3632,4 +3767,4 @@ declare const Symbols: {
     TimeManager: symbol;
 };
 
-export { Animation, type AnimationSlice, Animator, type AnimatorOptions, AssetManager, AudioPlayer, type AudioPlayerAction, type AudioPlayerOptions, 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, Polygon, PolygonCollider, type PolygonColliderOptions, 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, radiansToDegrees, randomFloat, randomInt, range };
+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 };