rapid-render 1.0.15 → 1.0.17

package/README.md

@@ -3,11 +3,18 @@
 </p>
 
 <p align="center">
-  A Immediate-mode, 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-22.5%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,23 +27,25 @@
 
 ## What is Rapid?
 
-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.
+Rapid is a focused WebGL 2D rendering engine for games and visual tools.
+
+If you want Pixi-level rendering without letting your renderer dictate how your game is organized, Rapid.js is for you!
+
+## Full 2D Toolkit
 
-If you don't want your renderer to dictate how your game is organized, Rapid.js is for you!
+Particles, Light & Shadow, Custom Shaders, Lines, Masks, Render textures, Sprites, Custom Geometry, Filters and more. all from one focused WebGL renderer. Yet it is only **22.5 kB gzipped**.
 
-## Highlights
+## Architecture Recipes
 
-- **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.
+Rapid.js handles only the rendering layer, leaving your game architecture entirely in your hands.
 
-- **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
 
@@ -44,10 +53,16 @@ If you don't want your renderer to dictate how your game is organized, Rapid.js
 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
-import { Rapid, Color } from "rapid-render";
+import { Rapid } from "rapid-render";
 
 const canvas = document.querySelector("canvas")!;
 const rapid = new Rapid({canvas});
@@ -64,7 +79,7 @@ rapid.flush();
 
 ## Render a scene
 
-Expressing complex game hierarchies doesn't require `DisplayObject` trees. `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.
+`rapid.matrixStack` brings the familiar, intuitive `save()` and `restore()` flow from Canvas 2D into high-performance WebGL. It reuses typed-array-backed matrix storage and avoids per-transform matrix allocation.
 
 ```ts
 // root
@@ -86,8 +101,10 @@ stack.save();
         // 3.enemies
         stack.save();
             for (let i = 0; i < 2; i++) {
-                stack.translate(x, y);
-                rapid.drawSprite(enemies[i]); // enemy
+                stack.save();
+                    stack.translate(enemyX[i], enemyY[i]);
+                    rapid.drawSprite(enemies[i]); // enemy
+                stack.restore();
             }
         stack.restore(); // 3.enemies
     stack.restore(); // 2.world
@@ -98,7 +115,7 @@ rapid.drawSprite(ui);
 
 ## Reuse and Update Matrix Subtrees
 
-`rapid.matrixStack` does not sacrifice the flexibility of a retained scene graph. Use `customMatrix` to render with any matrix in the hierarchy(even after its stack scope has been popped)
+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.
 
@@ -135,6 +152,8 @@ rapid.drawSprite({
 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/extensions/light.d.ts

@@ -0,0 +1,29 @@
+import { Rapid } from '../render';
+import { CustomGlShader, UniformValue } from '../webgl/glshader';
+import { Vec2 } from '../math';
+import { RenderTexture, Texture } from '../texture';
+import { Color } from '../color';
+import { MatrixSaveState } from '../matrix-engine';
+export declare const MAX_LIGHTS = 8;
+export declare class LightShader extends CustomGlShader {
+    constructor(rapid: Rapid, vs?: string, fs?: string, usedTextureUnitNum?: number, uniforms?: Record<string, UniformValue>);
+}
+export type LightMatrix = number | MatrixSaveState;
+export interface ILight {
+    lightMatrix: LightMatrix | LightMatrix[];
+    normalMap: Texture;
+    lightTexture: Texture[] | Texture;
+    metallic?: number;
+    roughness?: number;
+    color?: Color | Color[];
+    lightHeight?: number | number[];
+    customShader?: LightShader;
+}
+export declare class Light {
+    shader: CustomGlShader;
+    rapid: Rapid;
+    rt: RenderTexture;
+    constructor(rapid: Rapid);
+    lightShadow(texture: Texture, lightMatrix: LightMatrix, points: Array<Vec2>): RenderTexture | undefined;
+    setupLight(option: ILight): CustomGlShader;
+}

package/dist/{particle.d.ts → extensions/particle.d.ts}

@@ -1,9 +1,9 @@
-import { Color } from './color';
-import { Vec2 } from './math';
-import { Rapid } from './render';
-import { Texture } from './texture';
-import { DynamicArrayBuffer } from './buffer';
-import { CustomGlShader } from './webgl/glshader';
+import { Color } from '../color';
+import { Vec2 } from '../math';
+import { Rapid } from '../render';
+import { Texture } from '../texture';
+import { DynamicArrayBuffer } from '../buffer';
+import { CustomGlShader } from '../webgl/glshader';
 /**
  * Describes an animated attribute: it transitions from `start` to `end`
  * over the particle's lifetime, optionally with a per-second damping factor.

package/dist/index.d.ts

@@ -1,13 +1,8 @@
-export * from './buffer';
 export * from './color';
-export * from './matrix-engine';
 export * from './render';
-export * from './draw';
 export * from './texture';
 export * from './webgl/glshader';
-export * from './region/region';
-export * from './region/spriteRegion';
-export * from './region/graphicRegion';
 export * from './math';
-export * from './particle';
-export { LineTextureMode, type ILineRenderOptions } from './line';
+export * from './extensions/particle';
+export * from './extensions/light';
+export * from './line';

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,23 @@ 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;
+    getStep(step: number | {
+        step: number;
+    }): number;
+    private walkSubtree;
+    getParent(step: number | {
+        step: number;
+    }): number;
+    getChildren(step: number | {
+        step: number;
+    }): number[];
     updateMatrixSubtree(step: number | {
         step: number;
     }): void;