rapid-render 0.1.1 → 0.1.2-1.3

package/README.md

@@ -1,126 +1,88 @@
-# 🚀 Rapid.js
+> [!WARNING]
+> **🚧 Major Refactoring in Progress 🚧**
+>
+> This project is currently undergoing a significant rewrite to improve its core architecture and introduce new features. As a result, the **current documentation and examples are outdated** and may not work with the `main` branch.
+>
+> We are working hard to update the documentation soon. Thank you for your patience!
 
-A highly efficient and lightweight WebGL renderer
+# Rapid.js
 
-## [API Docs](https://nightre.github.io/Rapid.js/docs/)
+A highly efficient ([stress-test](https://nightre.github.io/Rapid.js/docs/examples.html)) and lightweight WebGL-based 2D rendering engine focused on rendering capabilities.
 
-[stress test demo](https://nightre.github.io/Rapid.js/demo/) ( [source code](./demo/index.js) )
+### [Website](https://nightre.github.io/Rapid.js/docs/index.html)
 
-[render demo](https://nightre.github.io/Rapid.js/demo/matrix_stack.html) ( [source code](./demo/matrix_stack.js) )
+#### [Document](https://nightre.github.io/Rapid.js/docs/docs.html) | [API Docs](https://nightre.github.io/Rapid.js/docs/api/index.html) | [Examples](https://nightre.github.io/Rapid.js/docs/examples.html)
 
-[custom shader demo](https://nightre.github.io/Rapid.js/demo/custom-shader.html) ( [source code](./demo/custom-shader.js) )
+## Features
 
+* **Fast Rendering** ⚡
+* **TileMap** - YSort, isometric 🗺️
+* **Light Shadow** 💡
+* **Particle** 🎆
+* **Camera** 🎥
+* **Graphics Drawing** ✏️
+* **Text Rendering** 📝
+* **Line Drawing** - line texture 〰️
+* **Custom Shaders** 🎨
+* **Mask** 🎭
+* **Frame Buffer Object** 🖼️
 
+## Performance Testing
 
-# Features
-* **Fast Rendering**: Render 10,000 sprites at 60fps
-* **Multi-Texture Support**: Batch rendering using GPU's maximum texture units
-* **Graphics Drawing**
-* **Matrix Stack**
-* **Text Rendering**
-* **Line Drawing**
-* **Custom Shaders**
-* **Texture Clipping**
+32x32 Texture Sprites 60FPS
 
-# Install
+* `Intel® Iris® Xe Graphics` : 42K sprites
 
-```
+## Install
+
+```bash
 npm i rapid-render
 ```
 
-Or use unpkg
+Or via CDN:
 
 ```html
 <script src="https://unpkg.com/rapid-render/dist/rapid.umd.cjs"></script>
 ```
 
-# Import
+## Quick Start
 
 ```js
-import { Rapid } from "rapid-render"
-```
-
-# Useage
-
-```js
-let rapid = new Rapid({
-    canvas: document.getElementById("game"),
-    backgroundColor: Color.fromHex("FFFFFF")
-});
-
-// Create texture
-const cat = await rapid.textures.textureFromUrl("./cat.png");
-//                      R   G   B   A
-const color = new Color(255, 255, 255, 255); // Or use Color.fromHex
-
-// Call before rendering
-rapid.startRender();
-
-// Render here...
-
-// Call after rendering
-rapid.endRender();
-
-// Set canvas size
-rapid.resize(100, 100);
+import { Rapid, Color, Vec2 } from "rapid-render"
+
+// Initialize
+const rapid = new Rapid({
+    canvas: document.getElementById("gameCanvas"),
+    backgroundColor: Color.fromHex("E6F0FF")
+})
+
+// Render example
+rapid.render(() => {
+    rapid.renderRect({ 
+        offset: new Vec2(100, 100), 
+        width: 50, 
+        height: 50, 
+        color: Color.Red 
+    })
+})
 ```
 
-# Render
+For more examples and detailed documentation, visit our [website](https://nightre.github.io/Rapid.js/docs/index.html).
 
-```js
-const text = rapid.textures.createText({ text: "Hello!", fontSize: 30 })
+## Roadmap
 
-rapid.save() // Save state
-rapid.matrixStack.translate(0,0)
-rapid.matrixStack.scale(1)
-rapid.matrixStack.rotate(0)
+* 9-slice 🚧 (In Progress)
+* Nodejs Support
 
-// Render Sprit
-rapid.renderSprite(cat, 0, 0, color) // or rapid.renderSprite(cat, 0, 0, { color })
+## Contributing
 
-// Rendr Graphic
-const path = Vec2.FormArray([[0, 0], [100, 0], [100, 100]])
-rapid.renderGraphic(0,0,{points:path, color:green})
-// or
-// rapid.startGraphicDraw()
-// rapid.addGraphicVertex(0, 0, color)
-// rapid.endGraphicDraw()
+Issues and PRs are welcome!
 
-// Render Text
-rapid.renderSprite(text, 200, 0)
-text.setText("time:" + Math.round(time))
-
-rapid.restore() // back to the previous saved state
-```
+## Screen shot
 
-# Custom Shader
-
-View demo and watch detailed shader code [custom shader demo](https://nightre.github.io/Rapid.js/demo/custom-shader.html) ( [source code](./demo/custom-shader.js) )
-
-```js
-const vertexShaderSource = `...`
-const fragmentShaderSource = `...`
-
-const customShader = new GLShader(rapid, vertexShaderSource, fragmentShaderSource)
-rapid.startRender()
-
-rapid.renderSprite(plane, 100, 100, {
-    shader: customShader, // shader
-    uniforms: {
-        // Set custom uniform (You can set mat3, vec2, and so on here)
-        uCustomUniform: Number(costumUniformValue)
-        //  uVec2Uniform: [0,2] // recognized as vec2
-        //  uMat3Uniform: [
-        //     [0,0,0],
-        //     [0,0,0],
-        //     [0,0,0],
-        //  ]
-        // recognized as mat3
-    }
-});
-
-rapid.endRender()
-```
-# Screen Shot
+![1](./screenshot/1.gif)
+![2](./screenshot/2.gif)
+![3](./screenshot/3.png)
+![4](./screenshot/4.png)
+![4](./screenshot/5.png)
 
-![screen](./screenshot/screen.png)

package/dist/assets.d.ts

@@ -0,0 +1,93 @@
+import { AudioPlayer } from './audio';
+import { Game } from './game';
+import { IAsset, IAssets } from './interface';
+import { default as EventEmitter } from 'eventemitter3';
+/**
+ * Events emitted by AssetsLoader.
+ */
+interface AssetsLoaderEvents {
+    progress: (progress: number, loaded: number, total: number) => void;
+    complete: (assets: IAssets) => void;
+    error: (error: {
+        name: string;
+        url: string;
+        error: any;
+    }) => void;
+}
+/**
+ * AssetsLoader class for loading game assets (JSON, audio, images).
+ * Supports asynchronous loading with progress tracking and error handling.
+ */
+declare class AssetsLoader extends EventEmitter<AssetsLoaderEvents> {
+    private assets;
+    private totalAsset;
+    private loadedAssets;
+    private game;
+    /**
+     * Creates an instance of AssetsLoader.
+     * Initializes the asset storage and counters.
+     */
+    constructor(game: Game);
+    /**
+     * Loads a JSON file asynchronously.
+     * @param name - The unique identifier for the JSON asset.
+     * @param url - The URL of the JSON file.
+     */
+    loadJson(name: string, url: string): void;
+    /**
+     * 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): Promise<void>;
+    /**
+     * 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): Promise<void>;
+    /**
+     * Loads multiple assets from a list.
+     * @param assetList - Array of assets to load.
+     */
+    loadAssets(assetList: IAsset[]): void;
+    /**
+     * Handles the completion of an asset load.
+     * Updates progress and triggers completion event if all assets are loaded.
+     */
+    private assetLoaded;
+    /**
+     * Handles errors during asset loading.
+     * @param name - The name of the asset.
+     * @param url - The URL of the asset.
+     * @param error - The error object or message.
+     */
+    private handleError;
+    /**
+     * Retrieves a loaded asset by type and name.
+     * @param type - The type of asset ('json', 'audio', or 'images').
+     * @param name - The name of the asset.
+     * @returns The loaded asset or undefined if not found.
+     */
+    get<T extends keyof IAssets>(type: T, name: string): IAssets[T][string] | undefined;
+    /**
+     * Retrieves a loaded JSON asset by name.
+     * @param name - The name of the JSON asset.
+     * @returns The loaded JSON data or undefined if not found.
+     */
+    getJSON(name: string): any | undefined;
+    /**
+     * Retrieves a loaded audio asset by name.
+     * @param name - The name of the audio asset.
+     * @returns The loaded AudioPlayer instance or undefined if not found.
+     */
+    getAudio(name: string): AudioPlayer | undefined;
+    /**
+     * Retrieves a loaded texture (image) asset by name.
+     * @param name - The name of the texture asset.
+     * @returns The loaded texture or undefined if not found.
+     */
+    getTexture(name: string): any | undefined;
+}
+export default AssetsLoader;

package/dist/audio.d.ts

@@ -0,0 +1,81 @@
+import { default as EventEmitter } from 'eventemitter3';
+/**
+ * Events emitted by AudioPlayer.
+ */
+interface AudioPlayerEvents {
+    ended: () => void;
+}
+/**
+ * Represents a single, playable audio instance.
+ * Created by the AudioManager.
+ */
+export declare class AudioPlayer extends EventEmitter<AudioPlayerEvents> {
+    private audioContext;
+    private audioBuffer;
+    private sourceNode;
+    private gainNode;
+    private _volume;
+    private _loop;
+    private _isPlaying;
+    constructor(audioContext: AudioContext, audioBuffer: AudioBuffer);
+    /**
+     * Plays the audio. If already playing, it will stop the current playback and start over.
+     */
+    play(): void;
+    /**
+     * Stops the audio playback immediately.
+     */
+    stop(): void;
+    /**
+     * Gets the volume of the audio, from 0.0 to 1.0.
+     */
+    get volume(): number;
+    /**
+     * Sets the volume of the audio.
+     * @param value - The volume, from 0.0 (silent) to 1.0 (full).
+     */
+    set volume(value: number);
+    /**
+     * Gets whether the audio will loop.
+     */
+    get loop(): boolean;
+    /**
+     * Sets whether the audio should loop.
+     * Can be changed while the audio is playing.
+     */
+    set loop(value: boolean);
+    /**
+     * 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;
+}
+/**
+ * Manages loading, decoding, and caching of audio assets.
+ * This is analogous to your TextureCache.
+ */
+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;

package/dist/game.d.ts

@@ -0,0 +1,324 @@
+import { default as AssetsLoader } from './assets';
+import { default as AudioManager } from './audio';
+import { InputManager } from './input';
+import { IAnimation, ICameraOptions, IEntityTransformOptions, IGameOptions, ILabelEntityOptions, IMathObject, ISpriteOptions } from './interface';
+import { Color, MatrixStack, Vec2 } from './math';
+import { default as Rapid } from './render';
+import { Text, Texture, TextureCache } from './texture';
+import { EasingFunction, Timer, Tween } from './utils';
+/**
+ * Base class for game entities with transform and rendering capabilities.
+ */
+export declare class Entity {
+    position: Vec2;
+    scale: Vec2;
+    rotation: number;
+    parent: Entity | null;
+    globalZindex: number;
+    localZindex: number;
+    tags: string[];
+    transform: MatrixStack;
+    readonly children: Entity[];
+    protected rapid: Rapid;
+    protected game: Game;
+    get x(): number;
+    get y(): number;
+    set x(nx: number);
+    set y(ny: number);
+    /**
+     * Creates an entity with optional transform properties.
+     * @param game - The game instance this entity belongs to.
+     * @param options - Configuration options for position, scale, rotation, and tags.
+     */
+    constructor(game: Game, options?: IEntityTransformOptions);
+    getScene(): Scene | null;
+    /**
+     * Gets the parent transform or the renderer's matrix stack if no parent exists.
+     * @returns The transform matrix stack.
+     */
+    getParentTransform(): MatrixStack;
+    /**
+     * Updates the entity and its children.
+     * @param deltaTime - Time elapsed since the last update in seconds.
+     */
+    update(deltaTime: number): void;
+    /**
+     * Hook for custom update logic.
+     * @param deltaTime - Time elapsed since the last update in seconds.
+     */
+    protected onUpdate(deltaTime: number): void;
+    /**
+     * Collects entities that need rendering.
+     * @param queue - The array to collect renderable entities.
+     * @ignore
+     */
+    collectRenderables(queue: Entity[]): void;
+    /**
+     * Prepares the entity's transform before rendering.
+     * @ignore
+     */
+    beforeOnRender(): void;
+    /**
+     * Hook for custom rendering logic.
+     * @param render - The rendering engine instance.
+     */
+    onRender(render: Rapid): void;
+    /**
+     * Updates the entity's transform, optionally updating parent transforms.
+     * @param deep - If true, recursively updates parent transforms.
+     */
+    updateTransform(deep?: boolean): void;
+    /**
+     * Adds a child entity to this entity.
+     * @param child - The entity to add as a child.
+     */
+    addChild(child: Entity): void;
+    /**
+     * Removes a child entity from this entity.
+     * @param child - The entity to remove.
+     */
+    removeChild(child: Entity): void;
+    /**
+     * Finds descendant entities matching a predicate.
+     * @param predicate - Function to test each entity.
+     * @param onlyFirst - If true, returns only the first match; otherwise, returns all matches.
+     * @returns A single entity, an array of entities, or null if no matches are found.
+     */
+    findDescendant(predicate: (entity: Entity) => boolean, onlyFirst?: boolean): Entity[] | Entity | null;
+    /**
+     * Finds descendant entities with all specified tags.
+     * @param tags - Array of tags to match.
+     * @param onlyFirst - If true, returns only the first match; otherwise, returns all matches.
+     * @returns A single entity, an array of entities, or null if no matches are found.
+     */
+    findDescendantByTag(tags: string[], onlyFirst?: boolean): Entity[] | Entity | null;
+    /**
+     * Disposes of the entity and its children.
+     */
+    dispose(): void;
+    /**
+     * 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.
+ * Ideal for UI elements like HUDs, menus, and scores.
+ *
+ * CanvasLayer 是一个特殊的层，它会直接将其子节点渲染到屏幕上，忽略任何摄像机的变换。
+ * 非常适合用于UI元素，如HUD（状态栏）、菜单和分数显示。
+ */
+export declare class CanvasLayer extends Entity {
+    constructor(game: Game, options: IEntityTransformOptions);
+    updateTransform(): void;
+}
+/**
+ * Camera entity for managing the view transform in the game.
+ */
+export declare class Camera extends Entity {
+    enable: boolean;
+    center: boolean;
+    positionSmoothingSpeed: number;
+    rotationSmoothingSpeed: number;
+    private _currentRenderPosition;
+    private _currentRenderRotation;
+    /**
+     * 设置此摄像机是否为当前场景的主摄像机。
+     * @param isEnable
+     */
+    setEnable(isEnable: boolean): void;
+    constructor(game: Game, options?: ICameraOptions);
+    /**
+     * 每帧更新，用于平滑摄像机的【局部】变换属性。
+     * @param deltaTime
+     */
+    onUpdate(deltaTime: number): void;
+    /**
+     * 根据摄像机的【全局】变换计算最终的视图矩阵。
+     * 这个方法现在正确地处理了父子关系。
+     */
+    updateTransform(): void;
+}
+/**
+ * Scene class representing a game scene with entities.
+ */
+export declare class Scene extends Entity {
+    /**
+     * Initializes the scene.
+     */
+    create(): void;
+}
+/**
+ * Main game class managing the game loop, rendering, and input.
+ */
+export declare class Game {
+    render: Rapid;
+    mainScene: Scene | null;
+    input: InputManager;
+    asset: AssetsLoader;
+    audio: AudioManager;
+    texture: TextureCache;
+    private isRunning;
+    private lastTime;
+    private tweens;
+    private timers;
+    mainCamera: Camera | null;
+    renderQueue: Entity[];
+    worldTransform: MatrixStack;
+    /**
+     * Creates a new game instance.
+     * @param options - Configuration options for the game.
+     */
+    constructor(options: IGameOptions);
+    getMainScene(): Scene | null;
+    setMainCamera(camera: Camera | null): void;
+    /**
+     * Switches to a new scene, disposing of the current one.
+     * @param newScene - The new scene to switch to.
+     */
+    switchScene(newScene: Scene): void;
+    /**
+     * Starts the game loop.
+     */
+    start(): void;
+    /**
+     * Stops the game loop.
+     */
+    stop(): void;
+    /**
+     * Adds an entity to the render queue.
+     * @param entity - The entity to add.
+     */
+    addEntityRenderQueue(entity: Entity): void;
+    /**
+     * Runs the game loop, updating and rendering the scene.
+     * @private
+     */
+    private gameLoop;
+    destroy(): void;
+    /**
+     * Creates and starts a new timer that will be automatically updated by the game loop.
+     * @param duration - The duration in seconds before the timer triggers.
+     * @param onComplete - The function to call when the timer finishes.
+     * @param repeat - If true, the timer will restart after completing. Defaults to false.
+     * @returns The created Timer instance, allowing you to `stop()` it manually if needed.
+     * @example
+     * // Log a message after 2.5 seconds
+     * game.createTimer(2.5, () => {
+     *     console.log('Timer finished!');
+     * });
+     *
+     * // Spawn an enemy every 5 seconds
+     * const enemySpawner = game.createTimer(5, () => {
+     *     scene.spawnEnemy();
+     * }, true);
+     */
+    createTimer(duration: number, repeat?: boolean): Timer;
+    /**
+     * Updates all active timers and removes completed ones.
+     * @param deltaTime - The time elapsed since the last frame.
+     * @private
+     */
+    private updateTimers;
+    /**
+     * Creates and starts a new tween animation.
+     * The tween will be automatically updated by the game loop.
+     * @template T - The type of the value being animated (e.g., Vec2, Color, number).
+     * @param target - The object to animate.
+     * @param property - The name of the property on the target to animate.
+     * @param to - The final value of the property.
+     * @param duration - The duration of the animation in seconds.
+     * @param easing - The easing function to use. Defaults to Linear.
+     * @returns The created Tween instance, allowing you to chain calls like .onComplete().
+     * @example
+     * // Tween a sprite's position over 2 seconds
+     * game.createTween(mySprite, 'position', new Vec2(500, 300), 2, Easing.EaseOutQuad);
+     *
+     * // Tween a shape's color to red and do something on completion
+     * game.createTween(myShape, 'color', Color.Red, 1.5)
+     *     .onComplete(() => {
+     *         console.log('Color tween finished!');
+     *     });
+     */
+    createTween<T extends IMathObject<T> | number>(target: any, property: string, to: T, duration: number, easing?: EasingFunction): Tween<T>;
+    /**
+     * Updates all active tweens and removes completed ones.
+     * @param deltaTime - The time elapsed since the last frame.
+     * @private
+     */
+    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;
+}