audio

Author: Nightre

dist/assets.d.ts

@@ -1,6 +1,6 @@
 import { AudioPlayer } from './audio';
 import { Game } from './game';
-import { IAsset as IAsset, IAssets } from './interface';
+import { IAsset, IAssets } from './interface';
 import { default as EventEmitter } from 'eventemitter3';
 /**
  * Events emitted by AssetsLoader.
@@ -35,17 +35,18 @@ declare class AssetsLoader extends EventEmitter<AssetsLoaderEvents> {
      */
     loadJson(name: string, url: string): void;
     /**
-     * Loads an audio file asynchronously.
+     * Loads an audio file asynchronously using the AudioManager.
+     * The AudioManager will handle fetching and caching.
      * @param name - The unique identifier for the audio asset.
      * @param url - The URL of the audio file.
      */
-    loadAudio(name: string, url: string): void;
+    loadAudio(name: string, url: string): Promise<void>;
     /**
-     * Loads an image file asynchronously.
+     * Loads an image file asynchronously using the TextureManager.
      * @param name - The unique identifier for the image asset.
      * @param url - The URL of the image file.
      */
-    loadImage(name: string, url: string): void;
+    loadImage(name: string, url: string): Promise<void>;
     /**
      * Loads multiple assets from a list.
      * @param assetList - Array of assets to load.

dist/audio.d.ts

@@ -6,54 +6,76 @@ interface AudioPlayerEvents {
     ended: () => void;
 }
 /**
- * Audio class for managing individual audio elements.
- * Encapsulates an HTMLAudioElement and its Web Audio API nodes.
+ * Represents a single, playable audio instance.
+ * Created by the AudioManager.
  */
 export declare class AudioPlayer extends EventEmitter<AudioPlayerEvents> {
-    element: HTMLAudioElement;
-    source: AudioNode | null;
-    gainNode: GainNode;
     private audioContext;
+    private audioBuffer;
+    private sourceNode;
+    private gainNode;
+    private _volume;
+    private _loop;
+    private _isPlaying;
+    constructor(audioContext: AudioContext, audioBuffer: AudioBuffer);
     /**
-     * Creates an instance of Audio.
-     * @param audioElement - The HTMLAudioElement to manage.
-     * @param audioContext - The Web Audio API context.
+     * Plays the audio. If already playing, it will stop the current playback and start over.
      */
-    constructor(audioElement: HTMLAudioElement, audioContext: AudioContext);
+    play(): void;
     /**
-     * Handles the 'ended' event when audio playback completes.
+     * Stops the audio playback immediately.
      */
-    private handleEnded;
+    stop(): void;
     /**
-     * Plays the audio with optional looping.
-     * @param loop - Whether the audio should loop (default: false).
+     * Gets the volume of the audio, from 0.0 to 1.0.
      */
-    play(loop?: boolean): Promise<void>;
+    get volume(): number;
     /**
-     * Pauses the audio.
+     * Sets the volume of the audio.
+     * @param value - The volume, from 0.0 (silent) to 1.0 (full).
      */
-    pause(): void;
+    set volume(value: number);
     /**
-     * Stops the audio and resets playback position.
+     * Gets whether the audio will loop.
      */
-    stop(): void;
+    get loop(): boolean;
     /**
-     * Sets the volume for the audio.
-     * @param volume - Volume level (0.0 to 1.0).
+     * Sets whether the audio should loop.
+     * Can be changed while the audio is playing.
      */
-    setVolume(volume: number): void;
+    set loop(value: boolean);
     /**
-     * Cleans up resources associated with the audio.
+     * Gets whether the audio is currently playing.
+     */
+    get isPlaying(): boolean;
+    /**
+     * Stops playback, disconnects audio nodes, and removes all event listeners.
+     * This makes the AudioPlayer instance unusable.
      */
     destroy(): void;
 }
 /**
- * AudioManager class for managing game audio, including background music (BGM) and sound effects (SFX).
- * Delegates audio-specific responsibilities to AudioPlayer instances.
+ * Manages loading, decoding, and caching of audio assets.
+ * This is analogous to your TextureCache.
  */
-declare class AudioManager {
-    audioContext: AudioContext;
+export declare class AudioManager {
+    private audioContext;
+    private cache;
     constructor();
+    /**
+     * Creates an AudioPlayer from a URL.
+     * It fetches, decodes, and caches the audio data. If the URL is already cached,
+     * it skips the network request and uses the cached data.
+     *
+     * @param url - The URL of the audio file.
+     * @returns A Promise that resolves to a new AudioPlayer instance.
+     */
+    audioFromUrl(url: string): Promise<AudioPlayer>;
+    /**
+     * Destroys the AudioManager, clears the audio cache, and closes the AudioContext.
+     * This releases all associated audio resources. After calling this, the AudioManager
+     * and any AudioPlayers created by it will be unusable.
+     */
     destroy(): void;
 }
 export default AudioManager;

dist/game.d.ts

@@ -1,10 +1,10 @@
 import { default as AssetsLoader } from './assets';
 import { default as AudioManager } from './audio';
 import { InputManager } from './input';
-import { ICameraOptions, IEntityTransformOptions, IGameOptions, IMathObject } from './interface';
-import { MatrixStack, Vec2 } from './math';
+import { IAnimation, ICameraOptions, IEntityTransformOptions, IGameOptions, ILabelEntityOptions, IMathObject, ISpriteOptions } from './interface';
+import { Color, MatrixStack, Vec2 } from './math';
 import { default as Rapid } from './render';
-import { TextureCache } from './texture';
+import { Text, Texture, TextureCache } from './texture';
 import { EasingFunction, Timer, Tween } from './utils';
 /**
  * Base class for game entities with transform and rendering capabilities.
@@ -31,7 +31,7 @@ export declare class Entity {
      * @param options - Configuration options for position, scale, rotation, and tags.
      */
     constructor(game: Game, options?: IEntityTransformOptions);
-    getRoot(): Scene | null;
+    getScene(): Scene | null;
     /**
      * Gets the parent transform or the renderer's matrix stack if no parent exists.
      * @returns The transform matrix stack.
@@ -100,6 +100,8 @@ export declare class Entity {
      * Hook for custom cleanup logic before disposal.
      */
     protected postDispose(): void;
+    getMouseLocalPosition(): Vec2;
+    getMouseGlobalPosition(): Vec2;
 }
 /**
  * A layer that renders its children directly to the screen, ignoring any camera transforms.
@@ -109,7 +111,7 @@ export declare class Entity {
  * 非常适合用于UI元素，如HUD（状态栏）、菜单和分数显示。
  */
 export declare class CanvasLayer extends Entity {
-    constructor(game: Game);
+    constructor(game: Game, options: IEntityTransformOptions);
     updateTransform(): void;
 }
 /**
@@ -164,6 +166,7 @@ export declare class Game {
     private timers;
     mainCamera: Camera | null;
     renderQueue: Entity[];
+    worldTransform: MatrixStack;
     /**
      * Creates a new game instance.
      * @param options - Configuration options for the game.
@@ -247,3 +250,75 @@ export declare class Game {
      */
     private updateTweens;
 }
+/**
+ * An entity that displays a texture (a "sprite") and can play animations.
+ * Animations are defined as a sequence of textures.
+ */
+export declare class Sprite extends Entity {
+    /** The current texture being displayed. This can be a static texture or a frame from an animation. */
+    texture: Texture | null;
+    /** Whether the sprite is flipped horizontally. */
+    flipX: boolean;
+    /** Whether the sprite is flipped vertically. */
+    flipY: boolean;
+    color: Color;
+    offset: Vec2;
+    private animations;
+    private currentAnimation;
+    private currentFrame;
+    private frameTimer;
+    private isPlaying;
+    /**
+     * Creates a new Sprite entity.
+     * @param game - The game instance.
+     * @param options - Configuration for the sprite's transform and initial texture.
+     */
+    constructor(game: Game, options?: ISpriteOptions);
+    setAnimations(animations: IAnimation): void;
+    /**
+     * Defines a new animation sequence.
+     * @param name - A unique name for the animation (e.g., "walk", "jump").
+     * @param frames - An array of Textures to use as frames.
+     * @param fps - The playback speed in frames per second.
+     * @param loop - Whether the animation should repeat.
+     */
+    addAnimation(name: string, frames: Texture[], fps?: number, loop?: boolean): void;
+    /**
+     * Plays an animation that has been previously defined with `addAnimation`.
+     * @param name - The name of the animation to play.
+     * @param forceRestart - If true, the animation will restart from the first frame even if it's already playing.
+     */
+    play(name: string, forceRestart?: boolean): void;
+    /**
+     * Stops the currently playing animation.
+     * The sprite will remain on the current frame.
+     */
+    stop(): void;
+    /**
+     * Updates the animation frame based on the elapsed time.
+     * @param deltaTime - Time in seconds since the last frame.
+     * @override
+     */
+    onUpdate(deltaTime: number): void;
+    /**
+     * Renders the sprite's current texture to the screen.
+     * @param render - The Rapid rendering instance.
+     * @override
+     */
+    onRender(render: Rapid): void;
+}
+/**
+ * An entity designed specifically to display text on the screen.
+ * It encapsulates a `Text` texture, giving it position, scale, rotation,
+ * and other entity-based properties.
+ */
+export declare class Label extends Entity {
+    text: Text;
+    constructor(game: Game, options: ILabelEntityOptions);
+    onRender(render: Rapid): void;
+    /**
+     * Updates the displayed text. Re-renders the texture if the text has changed.
+     * @param text - The new text to display.
+     */
+    setText(text: string): void;
+}

dist/input.d.ts

@@ -8,7 +8,7 @@ import { Entity } from './game';
 export declare class InputManager {
     private rapid;
     private canvas;
-    private mousePosition;
+    mousePosition: Vec2;
     private keysDown;
     private keysDownLastFrame;
     private buttonsDown;
@@ -81,6 +81,8 @@ export declare class InputManager {
      * @returns The mouse position in the entity's local coordinate system.
      */
     getMouseLocal(entity: Entity): Vec2;
+    getAxis(negativeAction: string, positiveAction: string): number;
+    getVector(negativeX: string, positiveX: string, negativeY: string, positiveY: string): Vec2;
     /**
      * Removes all event listeners and cleans up resources.
      */

dist/interface.d.ts

@@ -114,7 +114,7 @@ export interface ITextTextureOptions {
      * The color of the text.
      * Default is '#000000' (black).
      */
-    color?: string;
+    color?: Color;
     /**
      * The alignment of the text.
      * Possible values: 'left', 'right', 'center', 'start', 'end'.
@@ -370,11 +370,6 @@ export interface IParticleEmitterOptions extends IParticleOptions, IEntityTransf
 }
 export interface IGameOptions extends IRapidOptions {
 }
-export interface ISound {
-    element: HTMLAudioElement;
-    source: MediaElementAudioSourceNode | null;
-    gainNode: GainNode;
-}
 /**
  * Interface for an asset to be loaded.
  */
@@ -397,3 +392,18 @@ export interface IAssets {
         [key: string]: Texture;
     };
 }
+export interface IAnimation {
+    /** The name of the animation, used to play it. */
+    name: string;
+    /** An array of Textures that make up the frames of the animation. */
+    frames: Texture[];
+    /** The speed of the animation in frames per second (FPS). */
+    fps: number;
+    /** Whether the animation should loop back to the first frame when it ends. */
+    loop: boolean;
+}
+export interface ISpriteOptions extends IEntityTransformOptions, ISpriteRenderOptions {
+    animations?: IAnimation;
+}
+export interface ILabelEntityOptions extends ITextTextureOptions, IEntityTransformOptions {
+}

dist/math.d.ts

@@ -265,6 +265,12 @@ export declare class Color implements IMathObject<Color> {
      * @returns A new `Color` instance with the same RGBA values.
      */
     clone(): Color;
+    /**
+     * Converts the color to a hexadecimal string representation (e.g., '#RRGGBBAA').
+     * @param includeAlpha - Whether to include the alpha channel in the hex string.
+     * @returns The hexadecimal string representation of the color.
+     */
+    toHexString(includeAlpha?: boolean): string;
     /**
      * Checks if the current color is equal to another color.
      * @param color - The color to compare with.