rapid-render 1.0.13 → 1.0.16

package/README.md

@@ -3,11 +3,18 @@
 </p>
 
 <p align="center">
-  A stateless, high-performance WebGL 2D renderer for browser games.
+  <a href="https://www.npmjs.com/package/rapid-render"><img src="https://img.shields.io/npm/v/rapid-render?logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/rapid-render"><img src="https://img.shields.io/badge/gzipped-~20.8%20kB-5C7CFA" alt="gzipped size"></a>
+  <a href="https://github.com/Nightre/Rapid.js/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/rapid-render" alt="license"></a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript strict">
 </p>
 
 <p align="center">
-  <a href="https://nightre.github.io/Rapid.js/">Website</a>
+  An immediate-mode, high-performance WebGL 2D renderer for browser games.
+</p>
+
+<p align="center">
+  <a href="https://nightre.github.io/Rapid.js/">Website & Examples</a>
   |
   <a href="https://nightre.github.io/Rapid.js/docs.html">Docs</a>
   |
@@ -20,21 +27,19 @@
 
 ## What is Rapid?
 
-Rapid is a focused WebGL 2D rendering engine for games and visual tools. lightweight at just **67 kB** (**~20 kB gzipped**) It handles the rendering layer while leaving your game architecture, update loop, and state management fully in your hands.
+Rapid is a focused WebGL 2D rendering engine for games and visual tools. lightweight just **69 kB** (**~20 kB gzipped**) and handles only the rendering layer, leaving your game architecture entirely in your hands.
 
-## Highlights
+If you don't want your renderer to dictate how your game is organized, Rapid.js is for you!
 
-- **Rendering speed**  
-  An efficient batching system significantly reduces draw calls, allowing Rapid.js to maintain smooth, stable performance even when rendering large numbers of sprites at once.
+## Architecture Recipes
 
-- **Powerful custom shaders**  
-  Add sprite and geometry effects through shader hooks while still using Rapid's normal renderer, transforms, textures, and draw APIs.
+Rapid.js is frame-stateless, making it easy to build games with different architectures. Below are minimal, working implementations of several popular architectures built on Rapid.js, each in **around 100 lines** of JavaScript.
 
-- **Flexible transforms**  
-  Fast, flexible, matrix-powered transforms for motion and hierarchies. Retain the matrix tree after traversal; local changes update only affected subtrees. No rebuild required.
+- **Architecture recipes**  
+  [Game Object](recipes/game-object.js) · [Component](recipes/component.js) · [Display List](recipes/display-list.js) · [ECS Integration](recipes/ecs-integration.js) · [Immediate Mode](recipes/immediate-mode.js)
 
-- **A complete 2D toolkit**  
-  Draw sprites, lines, masks, particles, render textures, text, and custom geometry from one compact WebGL renderer.
+- **Game-engine-style recipes**  
+[Kaplay-like](recipes/game-engine/kaplay-like.js) · [Pixi-like](recipes/game-engine/pixi-like.js) · [Phaser-like](recipes/game-engine/phaser-like.js) · [Excalibur-like](recipes/game-engine/excalibur-like.js) · [LittleJS-like](recipes/game-engine/littlejs-like.js) · [p5-like](recipes/game-engine/p5-like.js)
 
 ## Install
 
@@ -42,6 +47,12 @@ Rapid is a focused WebGL 2D rendering engine for games and visual tools. lightwe
 npm install rapid-render
 ```
 
+Or via the unpkg CDN
+
+```html
+<script src="https://unpkg.com/rapid-render/dist/rapid-render.umd.cjs"></script>
+```
+
 ## Quick Start
 
 ```ts
@@ -49,19 +60,93 @@ import { Rapid, Color } from "rapid-render";
 
 const canvas = document.querySelector("canvas")!;
 const rapid = new Rapid({canvas});
+const texture = await rapid.texture.load("./image/sprite.png")
 
 rapid.clear();
-rapid.drawRect({
-   x: 40,
-   y: 40,
-   width: 160,
-   height: 96,
-   color: new Color(84, 184, 234),
+rapid.drawSprite({
+    texture: texture,
+    x: 40,
+    y: 40,
 });
 rapid.flush();
 ```
 
-Next step: <a href="https://nightre.github.io/Rapid.js/docs.html">Docs</a>
+## Render a scene
+
+`rapid.matrixStack` brings the familiar, intuitive `save()` and `restore()` flow from Canvas 2D into high-performance WebGL, letting you compose parent-child relationships with zero object allocation.
+
+```ts
+// root
+// ├── world
+// │   ├── player
+// │   └── enemies
+// │       ├── enemy #0
+// │       ├── enemy #1
+// │       └── ...
+// └── ui
+
+const stack = rapid.matrixStack;
+// 1.root
+stack.save();
+    stack.translate(0, 0);
+    // 2.world
+    stack.save();
+        rapid.drawSprite(player); // player
+        // 3.enemies
+        stack.save();
+            for (let i = 0; i < 2; i++) {
+                stack.translate(x, y);
+                rapid.drawSprite(enemies[i]); // enemy
+            }
+        stack.restore(); // 3.enemies
+    stack.restore(); // 2.world
+stack.restore(); // 1.root
+// ui
+rapid.drawSprite(ui);
+```
+
+## Reuse and Update Matrix Subtrees
+
+Use `customMatrix` to render with any matrix in the hierarchy(even after its stack scope has been popped)
+
+When you modify a node's local matrix, call `updateMatrixSubtree()` to automatically recalculate that node and all affected descendant world matrices, without rebuilding the entire matrix hierarchy.
+
+```ts
+rapid.clear();
+
+const stack = rapid.matrixStack;
+const matrix = rapid.matrix;
+
+// Build a transform hierarchy.
+const world = stack.save();
+stack.translate(200, 200);
+
+const enemyNode = stack.save();
+stack.translate(80, 0);
+
+stack.restore(); // enemyNode
+stack.restore(); // world
+
+// Both nodes have been popped, but their matrices remain available.
+// Move the world node later in the same frame.
+matrix.identity(world.local);
+matrix.translate(world.local, 100, 100);
+
+// Recalculate only `world` and its descendants.
+stack.updateMatrixSubtree(world);
+
+// Render using the stored matrix of the popped child node.
+rapid.drawSprite({
+  texture: enemy,
+  customMatrix: enemyNode.world,
+});
+
+rapid.flush();
+```
+
+With this flexible matrix stack, you can build your own architecture with minimal friction. It doesn't care how you organize your game logic. you can use ECS, scene graphs, components, or any hybrid approach you prefer.
+
+For more information about matrix transformations, see the [Transformations](https://nightre.github.io/Rapid.js/docs.html#transformations).
 
 ## Benchmark
 

package/dist/buffer.d.ts

@@ -104,11 +104,6 @@ export declare class DynamicArrayBuffer {
      * The number of elements currently stored in the buffer.
      */
     get length(): number;
-    /**
-     * Resets the buffer's used element count, effectively emptying it.
-     * Same behavior as `clear`.
-     */
-    reset(): void;
 }
 /**
  * A specialized dynamic buffer intended for WebGL operations.

package/dist/color.d.ts

@@ -66,7 +66,6 @@ export declare class Color {
      */
     setRGBA(r: number, g: number, b: number, a: number): void;
     setHSL(h: number, s: number, l: number): Color;
-    toHex(): string;
     /**
      * Copies the RGBA values from another color.
      * @param color - The color to copy from.
@@ -88,7 +87,6 @@ export declare class Color {
      * @param color - The color to compare with.
      * @returns True if the colors are equal, otherwise false.
      */
-    equal(color: Color): boolean;
     equals(color: Color): boolean;
     /**
      * Creates a Color instance from normalized float components (0–1 range).
@@ -104,7 +102,6 @@ export declare class Color {
     static FromHSL(h: number, s: number, l: number): Color;
     static FromRGB(r: number, g: number, b: number): Color;
     static fromNorm(r: number, g: number, b: number, a?: number): Color;
-    static clampColorByte(value: number): number;
     static packColor(r: number, g: number, b: number, a: number, premultipliedAlpha: boolean): number;
     /**
      * Creates a Color instance from a hexadecimal color string.
@@ -142,5 +139,4 @@ export declare class Color {
     static White: Color;
     static Black: Color;
     static Transparent: Color;
-    static TRANSPARENT: Color;
 }

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './texture';
 export * from './webgl/glshader';
 export * from './region/region';
 export * from './region/spriteRegion';
+export * from './region/particleRegion';
 export * from './region/graphicRegion';
 export * from './math';
 export * from './particle';

package/dist/math.d.ts

@@ -11,16 +11,13 @@ export declare class Vec2 {
     set(x: number, y?: number): Vec2;
     add(v: Vec2): Vec2;
     subtract(v: Vec2): Vec2;
-    sub(v: Vec2): Vec2;
     multiply(f: number | Vec2): Vec2;
-    mul(f: number | Vec2): Vec2;
     divide(f: number | Vec2): Vec2;
     dot(v: Vec2): number;
     cross(v: Vec2): number;
     distanceTo(v: Vec2): number;
     clone(): Vec2;
     to(vec: Vec2): void;
-    copy(): Vec2;
     equals(vec: Vec2): boolean;
     perpendicular(): this;
     invert(): this;

package/dist/matrix-engine.d.ts

@@ -204,6 +204,11 @@ export declare class MatrixStore {
     multiplyAffineInPlace(index: number, a: number, b: number, c: number, dValue: number, tx: number, ty: number): void;
     multiplyAffine(indexIn: number, indexOut: number, a: number, b: number, c: number, dValue: number, tx: number, ty: number): void;
 }
+export interface MatrixSaveState {
+    world: number;
+    local: number;
+    step: number;
+}
 /**
  * A highly performant MatrixStack useful for hierarchal scene graphs.
  * Handles both local and world transformations automatically.
@@ -221,8 +226,8 @@ export declare class MatrixStack {
     stepAction: DynamicArrayBuffer;
     /** Records the parent world matrix for each step (used by updateMatrixSubtree). */
     stepParentM: DynamicArrayBuffer;
-    /** Buffer used during hierarchy traversal updates. */
-    parentStack: DynamicArrayBuffer;
+    stepClose: DynamicArrayBuffer;
+    stepStack: DynamicArrayBuffer;
     /** The index of the current local matrix in the matrix store. */
     curLocalM: number;
     /** The index of the current world matrix in the matrix store. */
@@ -237,20 +242,21 @@ export declare class MatrixStack {
      * Equivalent to context.save().
      * @returns The current step counter before saving.
      */
-    save(): {
-        world: number;
-        local: number;
-        step: number;
-    };
+    save(): MatrixSaveState;
     /**
      * Restores the matrix state from the top of the stack.
      * Equivalent to context.restore().
      */
     restore(): void;
-    /**
-     * Evaluates and updates matrices from the given step. Used primarily for deferred transformation.
-     * @param step - The initial step to update matrices from.
-     */
+    restoreAll(): void;
+    private getStep;
+    private walkSubtree;
+    getParent(step: number | {
+        step: number;
+    }): number;
+    getChildren(step: number | {
+        step: number;
+    }): number[];
     updateMatrixSubtree(step: number | {
         step: number;
     }): void;

package/dist/particle.d.ts

@@ -121,6 +121,7 @@ export declare class ParticleEmitter {
     scaleY: DynamicArrayBuffer;
     rotation: DynamicArrayBuffer;
     color: DynamicArrayBuffer;
+    private remainingLife;
     animations: {
         speed: ParticleAttributeStore;
         rotation: ParticleAttributeStore;