rapid-render 0.1.0 → 0.1.2-1.1

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 capable of rendering 10k sprites at 60fps.
+# 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.
 
-[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,92 @@
+import { AudioPlayer } from "./audio";
+import { Game } from "./game";
+import { IAsset as IAsset, IAssets } from "./interface";
+import 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.
+     * @param name - The unique identifier for the audio asset.
+     * @param url - The URL of the audio file.
+     */
+    loadAudio(name: string, url: string): void;
+    /**
+     * Loads an image file asynchronously.
+     * @param name - The unique identifier for the image asset.
+     * @param url - The URL of the image file.
+     */
+    loadImage(name: string, url: string): 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,59 @@
+import EventEmitter from "eventemitter3";
+/**
+ * Events emitted by AudioPlayer.
+ */
+interface AudioPlayerEvents {
+    ended: () => void;
+}
+/**
+ * Audio class for managing individual audio elements.
+ * Encapsulates an HTMLAudioElement and its Web Audio API nodes.
+ */
+export declare class AudioPlayer extends EventEmitter<AudioPlayerEvents> {
+    element: HTMLAudioElement;
+    source: AudioNode | null;
+    gainNode: GainNode;
+    private audioContext;
+    /**
+     * Creates an instance of Audio.
+     * @param audioElement - The HTMLAudioElement to manage.
+     * @param audioContext - The Web Audio API context.
+     */
+    constructor(audioElement: HTMLAudioElement, audioContext: AudioContext);
+    /**
+     * Handles the 'ended' event when audio playback completes.
+     */
+    private handleEnded;
+    /**
+     * Plays the audio with optional looping.
+     * @param loop - Whether the audio should loop (default: false).
+     */
+    play(loop?: boolean): Promise<void>;
+    /**
+     * Pauses the audio.
+     */
+    pause(): void;
+    /**
+     * Stops the audio and resets playback position.
+     */
+    stop(): void;
+    /**
+     * Sets the volume for the audio.
+     * @param volume - Volume level (0.0 to 1.0).
+     */
+    setVolume(volume: number): void;
+    /**
+     * Cleans up resources associated with the audio.
+     */
+    destroy(): void;
+}
+/**
+ * AudioManager class for managing game audio, including background music (BGM) and sound effects (SFX).
+ * Delegates audio-specific responsibilities to AudioPlayer instances.
+ */
+declare class AudioManager {
+    audioContext: AudioContext;
+    constructor();
+    destroy(): void;
+}
+export default AudioManager;

package/dist/depth.d.ts

@@ -0,0 +1,8 @@
+declare class DepthScaler {
+    private max;
+    private min;
+    constructor();
+    getDepth(depth?: number): number | undefined;
+}
+declare const _default: DepthScaler;
+export default _default;

package/dist/game.d.ts

@@ -0,0 +1,292 @@
+import AssetsLoader from "./assets";
+import AudioManager from "./audio";
+import { InputManager } from "./input";
+import { IEntityTilemapLayerOptions, IEntityTransformOptions, IGameOptions, IMathObject, ISpriteRenderOptions, TilemapShape, YSortCallback } from "./interface";
+import { MatrixStack, Vec2 } from "./math";
+import Rapid from "./render";
+import { TextureCache } from "./texture";
+import { TileSet } from "./tilemap";
+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);
+    /**
+     * 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
+     */
+    beforOnRender(): 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;
+}
+/**
+ * Camera entity for managing the view transform in the game.
+ */
+export declare class Camera extends Entity {
+    /**
+     * Updates the camera's transform to center the view and apply transformations.
+     */
+    updateTransform(): void;
+}
+/**
+ * Tilemap entity for rendering tiled maps.
+ */
+export declare class Tilemap extends Entity {
+    static readonly DEFAULT_ERROR = 0;
+    static readonly EMPTY_TILE = -1;
+    error: Vec2;
+    shape: TilemapShape;
+    tileSet: TileSet;
+    data: (number | string)[][];
+    eachTile?: (tileId: string | number, mapX: number, mapY: number) => ISpriteRenderOptions | undefined | void;
+    ySortCallback: YSortCallback[];
+    /**
+     * Creates a tilemap entity.
+     * @param game - The game instance this tilemap belongs to.
+     * @param options - Configuration options for the tilemap.
+     */
+    constructor(game: Game, options: IEntityTilemapLayerOptions);
+    /**
+     * Collects renderable entities, excluding children unless they override onRender.
+     * @param queue - The array to collect renderable entities.
+     */
+    collectRenderables(queue: Entity[]): void;
+    /**
+     * Sets a tile at the specified map coordinates.
+     * @param x - The X coordinate (column) on the map.
+     * @param y - The Y coordinate (row) on the map.
+     * @param tileId - The tile ID to set (number or string).
+     * @returns True if the tile was set successfully, false if coordinates are out of bounds.
+     */
+    setTile(x: number, y: number, tileId: number | string): boolean;
+    /**
+     * Gets the tile ID at the specified map coordinates.
+     * @param x - The X coordinate (column) on the map.
+     * @param y - The Y coordinate (row) on the map.
+     * @returns The tile ID (number or string) or undefined if coordinates are out of bounds.
+     */
+    getTile(x: number, y: number): number | string | undefined;
+    /**
+     * Removes a tile at the specified map coordinates (sets it to EMPTY_TILE).
+     * @param x - The X coordinate (column) on the map.
+     * @param y - The Y coordinate (row) on the map.
+     * @returns True if the tile was removed successfully, false if coordinates are out of bounds.
+     */
+    removeTile(x: number, y: number): boolean;
+    /**
+     * Fills a rectangular area with a specified tile ID.
+     * @param tileId - The tile ID to use for filling.
+     * @param startX - The starting X coordinate.
+     * @param startY - The starting Y coordinate.
+     * @param width - The width of the fill area.
+     * @param height - The height of the fill area.
+     */
+    fill(tileId: number | string, startX: number, startY: number, width: number, height: number): void;
+    /**
+     * Replaces the entire tilemap data and updates dimensions.
+     * @param newData - The new 2D array of tile data.
+     */
+    setData(newData: (number | string)[][]): void;
+    /**
+     * Converts local coordinates to map coordinates.
+     * @param local - The local coordinates to convert.
+     */
+    localToMap(local: Vec2): void;
+    /**
+     * Converts map coordinates to local coordinates.
+     * @param local - The map coordinates to convert.
+     */
+    mapToLocal(local: Vec2): void;
+    /**
+     * Renders the tilemap layer.
+     * @param render - The rendering engine instance.
+     */
+    onRender(render: Rapid): 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;
+    renderQueue: Entity[];
+    /**
+     * Creates a new game instance.
+     * @param options - Configuration options for the game.
+     */
+    constructor(options: IGameOptions);
+    /**
+     * 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;
+}

package/dist/index.d.ts

@@ -1,10 +1,16 @@
-import { graphicAttributes } from "./regions/graphic_region";
-import { spriteAttributes } from "./regions/sprite_region";
 import Rapid from "./render";
 import GLShader from "./webgl/glshader";
 import { Text } from "./texture";
-export { Text, Rapid, GLShader, spriteAttributes, graphicAttributes, };
+import { TileMapRender, TileSet } from "./tilemap";
+import { Uniform } from "./webgl/uniform";
+import { spriteAttributes, graphicAttributes } from "./regions/attributes";
+import { ParticleEmitter } from "./particle";
+export { Text, Rapid, GLShader, TileMapRender, TileSet, Uniform, ParticleEmitter, graphicAttributes, spriteAttributes, };
 export * from "./math";
 export * from "./interface";
 export * from "./texture";
 export * from "./render";
+export * from "./particle";
+export * from "./game";
+export * from "./input";
+export * from "./assets";