@web-engine-dev/sprites

2D sprite and spritesheet rendering with animation, atlas packing, and batching.

Features

• Sprite Rendering: Textured quads with transforms
• Spritesheets: Animation from texture atlases
• Atlas Packing: Runtime atlas generation
• Nine-Slice: Scalable UI sprites
• Batching: Efficient draw call batching
• Sorting: Layer and depth sorting

Installation

npm install @web-engine-dev/sprites
# or
pnpm add @web-engine-dev/sprites

Quick Start

import { SpriteRenderer, Sprite, SpriteSheet, SpriteAnimation } from '@web-engine-dev/sprites';

// Create renderer
const sprites = new SpriteRenderer(device);

// Load spritesheet
const sheet = await SpriteSheet.load('characters.json');

// Create sprite
const player = new Sprite({
  texture: sheet.getFrame('player_idle_0'),
  position: { x: 100, y: 100 },
  anchor: { x: 0.5, y: 0.5 },
});

// Create animation
const walkAnim = new SpriteAnimation({
  frames: sheet.getFrames('player_walk'),
  frameRate: 12,
  loop: true,
});

// Render frame
sprites.begin();
sprites.draw(player);
sprites.end();

API Overview

Sprite

const sprite = new Sprite({
  texture: texture,
  position: { x: 0, y: 0 },
  rotation: 0, // Radians
  scale: { x: 1, y: 1 },
  anchor: { x: 0.5, y: 0.5 },
  tint: '#ffffff',
  alpha: 1.0,
  layer: 0,
});

SpriteSheet

// Load from JSON (TexturePacker format)
const sheet = await SpriteSheet.load('sprites.json');

// Get single frame
const frame = sheet.getFrame('hero_idle_0');

// Get animation frames
const frames = sheet.getFrames('hero_walk'); // Matches prefix

Animation

const anim = new SpriteAnimation({
  frames: frames,
  frameRate: 10,
  loop: true,
});

// Update
anim.update(deltaTime);

// Get current frame
sprite.texture = anim.currentFrame;

// Control
anim.play();
anim.pause();
anim.stop();
anim.setFrame(3);

Nine-Slice

const panel = new NineSlice({
  texture: panelTexture,
  borders: { left: 10, right: 10, top: 10, bottom: 10 },
  width: 200,
  height: 100,
});

Batching

const batch = new SpriteBatch({ maxSprites: 10000 });

batch.begin();
for (const sprite of sprites) {
  batch.draw(sprite);
}
batch.end(); // Single draw call