bloody-engine 1.0.5 → 1.0.7

package/README.md

@@ -1,15 +1,16 @@
 # Bloody Engine
 
-A WebGL-based 2.5D graphics engine for isometric rendering, written in TypeScript. Designed for both browser and Node.js environments with full isomorphic support.
+A WebGL-based 2.5D graphics engine for isometric rendering on Node.js, written in TypeScript. Designed for server-side rendering and headless graphics processing.
 
 ## Features
 
 - **2.5D Rendering** - Optimized for isometric and dimetric projections
-- **Cross-Platform** - Works in browsers and Node.js (headless rendering)
+- **Server-Side Rendering** - Headless WebGL rendering on Node.js using `gl` and `@kmamal/sdl`
 - **Batch Rendering** - Efficient sprite batching with GPU-accelerated transformations
 - **Resource Management** - Unified asset loading pipeline for textures and resources
 - **TypeScript** - Fully typed for excellent developer experience
 - **Depth Sorting** - Proper 2.5D occlusion handling
+- **Window Management** - SDL-based window creation for interactive applications
 
 ## Installation
 
@@ -19,49 +20,59 @@ npm install bloody-engine
 
 ## Quick Start
 
-### Browser
-
 ```typescript
-import { BloodyEngine } from 'bloody-engine';
-
-// Initialize engine
-const engine = new BloodyEngine({
-  width: 800,
-  height: 600
-});
-
-// Start rendering loop
-engine.start();
-```
+import { GraphicsDevice, Shader, Texture } from 'bloody-engine';
+
+// Create a graphics device with SDL window
+const device = new GraphicsDevice(800, 600);
+
+// Get the WebGL context
+const gl = device.getGLContext();
+
+// Create a shader
+const shader = device.createShader(`
+  attribute vec3 aPosition;
+  uniform mat4 uMatrix;
+
+  void main() {
+    gl_Position = uMatrix * vec4(aPosition, 1.0);
+  }
+`, `
+  precision mediump float;
+  uniform vec3 uColor;
+
+  void main() {
+    gl_FragColor = vec4(uColor, 1.0);
+  }
+`);
+
+// Create a texture from PNG
+const { PNG } = require('pngjs');
+const fs = require('fs/promises');
+const pngData = await fs.readFile('texture.png');
+const png = PNG.sync.read(pngData);
+const texture = Texture.createFromPNG(gl, png);
 
-### Node.js
-
-```typescript
-import { BloodyEngine } from 'bloody-engine';
-
-// Initialize engine for headless rendering
-const engine = new BloodyEngine({
-  width: 800,
-  height: 600,
-  headless: true
-});
-
-// Render and capture output
-engine.renderFrame();
-const pixels = engine.getPixels();
+// Render
+device.clear({ r: 0.1, g: 0.1, b: 0.1, a: 1.0 });
+shader.use();
+// ... rendering code ...
+device.present();
+
+// For headless rendering, capture the output
+const context = device.getRenderingContext();
+const pixels = context.readPixels();
 ```
 
-## Documentation
-
-For detailed documentation and architecture, see [docs/README.MD](docs/README.MD).
-
 ## Examples
 
+### Sprite Batch Rendering
+
 ```typescript
-// Create a sprite batch renderer
-import { SpriteBatchRenderer, Texture } from 'bloody-engine';
+import { SpriteBatchRenderer, Camera, Texture } from 'bloody-engine';
 
-const batchRenderer = new SpriteBatchRenderer(gl, shader);
+const batchRenderer = new SpriteBatchRenderer(gl, shader, 1000);
+const camera = new Camera(0, 0, 1.0);
 
 // Add sprites
 batchRenderer.addQuad({
@@ -79,6 +90,43 @@ batchRenderer.addQuad({
 batchRenderer.render(camera);
 ```
 
+### Resource Loading
+
+```typescript
+import { NodeResourceLoader } from 'bloody-engine';
+
+const loader = new NodeResourceLoader('./assets');
+
+// Load a shader
+const vertexSource = await loader.load('shaders/basic.vert');
+const fragmentSource = await loader.load('shaders/basic.frag');
+
+// Batch load multiple resources
+const { succeeded, failed } = await loader.loadMultiple([
+  'textures/sprite1.png',
+  'textures/sprite2.png',
+  'shaders/shader.vert'
+]);
+```
+
+## Dependencies
+
+- **gl** - Headless WebGL for Node.js
+- **@kmamal/sdl** - SDL2 bindings for window and input management
+- **pngjs** - PNG image decoding
+
+## Documentation
+
+For detailed documentation and architecture, see [docs/README.MD](docs/README.MD).
+
+## Building
+
+```bash
+npm run build
+```
+
+This will generate the distribution files in `dist/node/`.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

package/dist/node/core/interpolation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Linear interpolation between two values
+ * @param a - Start value
+ * @param b - End value
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated value
+ */
+export declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Interpolate between two 2D vectors
+ * @param a - Start vector
+ * @param b - End vector
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated vector
+ */
+export declare function lerpVec2(a: {
+    x: number;
+    y: number;
+}, b: {
+    x: number;
+    y: number;
+}, t: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Interpolate between two 3D vectors
+ * @param a - Start vector
+ * @param b - End vector
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated vector
+ */
+export declare function lerpVec3(a: {
+    x: number;
+    y: number;
+    z: number;
+}, b: {
+    x: number;
+    y: number;
+    z: number;
+}, t: number): {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Interpolate rotation (handles angle wrapping)
+ * @param a - Start angle in radians
+ * @param b - End angle in radians
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated angle
+ */
+export declare function lerpAngle(a: number, b: number, t: number): number;
+/**
+ * State buffer for interpolation
+ * Stores previous and current states for smooth interpolation
+ */
+export declare class StateBuffer<T> {
+    private previous;
+    private current;
+    constructor(initialState: T);
+    /**
+     * Update to new state (shifts current to previous)
+     * @param newState - The new state to set as current
+     */
+    update(newState: T): void;
+    /**
+     * Get interpolated state
+     * @param alpha - Interpolation factor (0-1)
+     * @param lerpFn - Interpolation function for the state type
+     * @returns Interpolated state
+     */
+    interpolate(alpha: number, lerpFn: (a: T, b: T, t: number) => T): T;
+    /**
+     * Get current state without interpolation
+     * @returns Current state
+     */
+    getCurrent(): T;
+    /**
+     * Get previous state
+     * @returns Previous state
+     */
+    getPrevious(): T;
+}
+//# sourceMappingURL=interpolation.d.ts.map

package/dist/node/core/interpolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.d.ts","sourceRoot":"","sources":["../../../src/core/interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B,CAAC,EAAE,MAAM,GACR;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAK1B;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACtC,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACtC,CAAC,EAAE,MAAM,GACR;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAMrC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;GAGG;AACH,qBAAa,WAAW,CAAC,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,OAAO,CAAI;gBAEP,YAAY,EAAE,CAAC;IAK3B;;;OAGG;IACI,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI;IAKhC;;;;;OAKG;IACI,WAAW,CAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC,GACnC,CAAC;IAIJ;;;OAGG;IACI,UAAU,IAAI,CAAC;IAItB;;;OAGG;IACI,WAAW,IAAI,CAAC;CAGxB"}

package/dist/node/core/resource-loader-factory.d.ts

@@ -0,0 +1,58 @@
+import { IResourceLoader } from './resource-loader';
+/**
+ * Environment type enumeration
+ */
+export declare enum Environment {
+    /** Node.js environment (file system APIs available) */
+    NODE = "node"
+}
+/**
+ * Resource loader factory configuration
+ */
+export interface ResourceLoaderFactoryOptions {
+    /**
+     * Base directory for Node.js resource loader
+     */
+    baseDir?: string;
+}
+/**
+ * Factory class for creating resource loaders
+ * Creates Node.js resource loaders
+ */
+export declare class ResourceLoaderFactory {
+    /**
+     * Detect the current runtime environment
+     * @returns The detected environment type (always NODE)
+     */
+    static detectEnvironment(): Environment;
+    /**
+     * Check if the current environment is a browser
+     * @returns false (not browser)
+     */
+    static isBrowser(): boolean;
+    /**
+     * Check if the current environment is Node.js
+     * @returns true
+     */
+    static isNode(): boolean;
+    /**
+     * Create a Node.js resource loader
+     * @param options Optional factory configuration
+     * @returns A Node.js resource loader instance
+     */
+    static create(options?: ResourceLoaderFactoryOptions): Promise<IResourceLoader>;
+    /**
+     * Create a Node.js resource loader
+     * @param options Optional factory configuration
+     * @returns A Node.js resource loader instance
+     */
+    static createNodeLoader(options?: ResourceLoaderFactoryOptions): Promise<IResourceLoader>;
+}
+/**
+ * Convenience function to create a resource loader
+ * Shortcut for ResourceLoaderFactory.create()
+ * @param options Optional factory configuration
+ * @returns A resource loader instance
+ */
+export declare function createResourceLoader(options?: ResourceLoaderFactoryOptions): Promise<IResourceLoader>;
+//# sourceMappingURL=resource-loader-factory.d.ts.map

package/dist/node/core/resource-loader-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-loader-factory.d.ts","sourceRoot":"","sources":["../../../src/core/resource-loader-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD;;GAEG;AACH,oBAAY,WAAW;IACrB,uDAAuD;IACvD,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IAChC;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,WAAW;IAIvC;;;OAGG;IACH,MAAM,CAAC,SAAS,IAAI,OAAO;IAI3B;;;OAGG;IACH,MAAM,CAAC,MAAM,IAAI,OAAO;IAIxB;;;;OAIG;WACU,MAAM,CAAC,OAAO,CAAC,EAAE,4BAA4B,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrF;;;;OAIG;WACU,gBAAgB,CAC3B,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,eAAe,CAAC;CAG5B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/node/core/resource-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-pipeline.d.ts","sourceRoot":"","sources":["../../../src/core/resource-pipeline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA8CD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAMtE;;;;;OAKG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBxE;;;;;OAKG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,eAAe,CAAC;IA4B3B;;;;;;OAMG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,YAAY,CAAC;IASxB;;;;;OAKG;IACG,WAAW,CACf,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,EACF,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAkB/B;;;;;OAKG;IACG,gBAAgB,CACpB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,eAAe,CAAC;IAS3B;;;;;OAKG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI3C;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIzC;;;OAGG;IACH,SAAS,IAAI,eAAe;CAG7B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,CAAC,EAAE,uBAAuB,GAAG;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,gBAAgB,CAAC,CAS3B"}

package/dist/node/core/sprite-atlas.d.ts

@@ -0,0 +1,356 @@
+import { Texture } from './texture';
+/**
+ * UV rectangle defining a region in texture space (0-1 range)
+ */
+export interface UVRect {
+    /** Minimum U coordinate (left edge) */
+    uMin: number;
+    /** Minimum V coordinate (bottom edge) */
+    vMin: number;
+    /** Maximum U coordinate (right edge) */
+    uMax: number;
+    /** Maximum V coordinate (top edge) */
+    vMax: number;
+}
+/**
+ * Pixel rectangle defining a region in pixel coordinates
+ */
+export interface PixelRect {
+    /** Left edge in pixels */
+    x: number;
+    /** Bottom edge in pixels (Y-up coordinate system) */
+    y: number;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Sprite metadata stored in the atlas
+ */
+export interface SpriteInfo {
+    /** Unique identifier for this sprite */
+    name: string;
+    /** UV rectangle in texture space */
+    uvRect: UVRect;
+    /** Pixel rectangle in the source texture */
+    pixelRect: PixelRect;
+    /** Width of the sprite in pixels */
+    width: number;
+    /** Height of the sprite in pixels */
+    height: number;
+}
+/**
+ * Represents a single sprite within a texture atlas.
+ * Provides convenient access to UV coordinates and sprite dimensions.
+ */
+export declare class Sprite {
+    private readonly info;
+    /**
+     * Create a new sprite instance
+     * @param info Sprite information including UV coordinates and dimensions
+     */
+    constructor(info: SpriteInfo);
+    /**
+     * Get the sprite's unique name/identifier
+     */
+    getName(): string;
+    /**
+     * Get the UV rectangle for this sprite
+     * @returns UV coordinates in 0-1 range
+     */
+    getUVRect(): UVRect;
+    /**
+     * Get the pixel rectangle for this sprite
+     * @returns Pixel coordinates in the source texture
+     */
+    getPixelRect(): PixelRect;
+    /**
+     * Get the sprite width in pixels
+     */
+    getWidth(): number;
+    /**
+     * Get the sprite height in pixels
+     */
+    getHeight(): number;
+    /**
+     * Get the aspect ratio (width / height)
+     */
+    getAspectRatio(): number;
+    /**
+     * Create a UV rect object suitable for SpriteQuadInstance
+     * @returns UV rect as expected by batch renderer
+     */
+    toQuadUVRect(): {
+        uMin: number;
+        vMin: number;
+        uMax: number;
+        vMax: number;
+    };
+    /**
+     * Get a string representation of this sprite
+     */
+    toString(): string;
+}
+/**
+ * Options for creating a texture atlas
+ */
+export interface AtlasOptions {
+    /** Texture containing the atlas image */
+    texture: Texture;
+    /** Width of the texture in pixels (auto-detected from texture if not provided) */
+    textureWidth?: number;
+    /** Height of the texture in pixels (auto-detected from texture if not provided) */
+    textureHeight?: number;
+}
+/**
+ * Texture Atlas Manager
+ *
+ * Manages a collection of sprites within a single texture.
+ * Provides methods to define sprites by pixel or normalized coordinates,
+ * and retrieve sprite information by name.
+ *
+ * @example
+ * ```typescript
+ * // Create an atlas from a loaded texture
+ * const atlas = new TextureAtlas({ texture: myTexture });
+ *
+ * // Define sprites by pixel coordinates
+ * atlas.defineSprite("player_idle_1", { x: 0, y: 0, width: 32, height: 32 });
+ * atlas.defineSprite("player_idle_2", { x: 32, y: 0, width: 32, height: 32 });
+ *
+ * // Or define sprites by normalized UV coordinates
+ * atlas.defineSpriteUV("background", { uMin: 0, vMin: 0, uMax: 1, vMax: 1 }, 512, 512);
+ *
+ * // Get a sprite for rendering
+ * const sprite = atlas.getSprite("player_idle_1");
+ * renderer.addQuad({
+ *   x: 100, y: 100, z: 0,
+ *   width: sprite.getWidth(),
+ *   height: sprite.getHeight(),
+ *   rotation: 0,
+ *   uvRect: sprite.toQuadUVRect(),
+ *   texIndex: 0
+ * });
+ * ```
+ */
+export declare class TextureAtlas {
+    private readonly texture;
+    private readonly textureWidth;
+    private readonly textureHeight;
+    private readonly sprites;
+    /**
+     * Create a new texture atlas
+     * @param options Atlas configuration options
+     */
+    constructor(options: AtlasOptions);
+    /**
+     * Get the underlying texture
+     */
+    getTexture(): Texture;
+    /**
+     * Get the texture dimensions
+     */
+    getTextureDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Define a sprite by pixel coordinates.
+     * Pixels are in Y-up coordinate system (bottom-left origin).
+     *
+     * @param name Unique identifier for this sprite
+     * @param rect Pixel rectangle defining the sprite region
+     * @returns The created Sprite instance
+     *
+     * @example
+     * ```typescript
+     * // Define a 32x32 sprite at the bottom-left corner
+     * atlas.defineSprite("player", { x: 0, y: 0, width: 32, height: 32 });
+     *
+     * // Define a sprite starting at column 2, row 1 (assuming 32px tiles)
+     * atlas.defineSprite("enemy", { x: 64, y: 32, width: 32, height: 32 });
+     * ```
+     */
+    defineSprite(name: string, rect: PixelRect): Sprite;
+    /**
+     * Define a sprite grid (regular grid of same-sized sprites).
+     * Useful for sprite sheets and tilesets.
+     *
+     * @param prefix Name prefix for each sprite (e.g., "tile_")
+     * @param startX Starting X position in pixels
+     * @param startY Starting Y position in pixels
+     * @param spriteWidth Width of each sprite in pixels
+     * @param spriteHeight Height of each sprite in pixels
+     * @param columns Number of columns in the grid
+     * @param rows Number of rows in the grid
+     * @param columnSpacing Optional horizontal gap between sprites (default 0)
+     * @param rowSpacing Optional vertical gap between sprites (default 0)
+     * @returns Array of created sprite names
+     *
+     * @example
+     * ```typescript
+     * // Define a 4x4 grid of 32x32 tiles
+     * const tiles = atlas.defineGrid(
+     *   "tile_", 0, 0, 32, 32, 4, 4
+     * );
+     * // tiles = ["tile_0_0", "tile_1_0", ..., "tile_3_3"]
+     * ```
+     */
+    defineGrid(prefix: string, startX: number, startY: number, spriteWidth: number, spriteHeight: number, columns: number, rows: number, columnSpacing?: number, rowSpacing?: number): string[];
+    /**
+     * Define a sprite by normalized UV coordinates.
+     * Useful when you have pre-computed UV values.
+     *
+     * @param name Unique identifier for this sprite
+     * @param uvRect UV rectangle (0-1 range)
+     * @param pixelWidth Width in pixels (for reference, optional)
+     * @param pixelHeight Height in pixels (for reference, optional)
+     * @returns The created Sprite instance
+     *
+     * @example
+     * ```typescript
+     * // Define a sprite covering the entire texture
+     * atlas.defineSpriteUV("full", {
+     *   uMin: 0, vMin: 0, uMax: 1, vMax: 1
+     * }, 512, 512);
+     * ```
+     */
+    defineSpriteUV(name: string, uvRect: UVRect, pixelWidth?: number, pixelHeight?: number): Sprite;
+    /**
+     * Get a sprite by name
+     * @param name Sprite identifier
+     * @returns Sprite instance or undefined if not found
+     */
+    getSprite(name: string): Sprite | undefined;
+    /**
+     * Check if a sprite exists in the atlas
+     * @param name Sprite identifier
+     */
+    hasSprite(name: string): boolean;
+    /**
+     * Get all sprite names in the atlas
+     */
+    getSpriteNames(): string[];
+    /**
+     * Get the number of sprites defined in the atlas
+     */
+    getSpriteCount(): number;
+    /**
+     * Remove a sprite from the atlas
+     * @param name Sprite identifier
+     * @returns true if sprite was removed, false if it didn't exist
+     */
+    removeSprite(name: string): boolean;
+    /**
+     * Clear all sprites from the atlas
+     */
+    clear(): void;
+    /**
+     * Create a sprite definition JSON from all sprites in the atlas.
+     * Useful for serializing atlas data to disk.
+     *
+     * @returns JSON-serializable object containing all sprite data
+     */
+    toJSON(): object;
+    /**
+     * Load sprite definitions from a JSON object.
+     * Useful for loading atlas data from disk.
+     *
+     * @param data JSON object containing sprite definitions
+     * @example
+     * ```typescript
+     * // Load from a parsed JSON file
+     * const data = JSON.parse(fs.readFileSync("atlas.json", "utf8"));
+     * atlas.fromJSON(data);
+     * ```
+     */
+    fromJSON(data: {
+        textureWidth?: number;
+        textureHeight?: number;
+        sprites: Record<string, {
+            pixelRect: PixelRect;
+            width?: number;
+            height?: number;
+        }>;
+    }): void;
+    /**
+     * Bind the atlas texture to a texture unit
+     * @param unit Texture unit (0-7 typically, default 0)
+     */
+    bind(unit?: number): void;
+    /**
+     * Unbind the atlas texture
+     */
+    unbind(): void;
+    /**
+     * Get a string representation of the atlas
+     */
+    toString(): string;
+}
+/**
+ * Utility function to create a TextureAtlas from common sprite sheet formats.
+ */
+export declare class AtlasLoader {
+    /**
+     * Create an atlas from a regular grid sprite sheet.
+     * All sprites must have the same dimensions and be arranged in rows and columns.
+     *
+     * @param texture The texture containing the sprite sheet
+     * @param options Grid configuration options
+     * @returns A configured TextureAtlas with all sprites defined
+     *
+     * @example
+     * ```typescript
+     * const atlas = AtlasLoader.loadFromGrid(myTexture, {
+     *   spriteWidth: 32,
+     *   spriteHeight: 32,
+     *   columns: 4,
+     *   rows: 4,
+     *   prefix: "character_"
+     * });
+     * ```
+     */
+    static loadFromGrid(texture: Texture, options: {
+        spriteWidth: number;
+        spriteHeight: number;
+        columns: number;
+        rows: number;
+        prefix?: string;
+        columnSpacing?: number;
+        rowSpacing?: number;
+        startX?: number;
+        startY?: number;
+    }): TextureAtlas;
+    /**
+     * Create an atlas from a JSON definition file.
+     * The JSON should contain sprite names and their pixel rectangles.
+     *
+     * @param texture The texture containing the atlas
+     * @param jsonData Parsed JSON object with sprite definitions
+     * @returns A configured TextureAtlas
+     *
+     * @example
+     * ```typescript
+     * // JSON format:
+     * // {
+     * //   "textureWidth": 512,
+     * //   "textureHeight": 512,
+     * //   "sprites": {
+     * //     "player": { "pixelRect": { "x": 0, "y": 0, "width": 32, "height": 32 } },
+     * //     "enemy": { "pixelRect": { "x": 32, "y": 0, "width": 32, "height": 32 } }
+     * //   }
+     * // }
+     *
+     * const atlas = AtlasLoader.loadFromJSON(myTexture, jsonData);
+     * ```
+     */
+    static loadFromJSON(texture: Texture, jsonData: {
+        textureWidth?: number;
+        textureHeight?: number;
+        sprites: Record<string, {
+            pixelRect: PixelRect;
+        }>;
+    }): TextureAtlas;
+}
+//# sourceMappingURL=sprite-atlas.d.ts.map

package/dist/node/core/sprite-atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-atlas.d.ts","sourceRoot":"","sources":["../../../src/core/sprite-atlas.ts"],"names":[],"mappings":"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"}