sprite-detector

Auto-detect sprites from spritesheets, edit frame-by-frame animations, and export to GIF, Aseprite, or LibreSprite format.

A browser SDK and web tool for game developers and pixel artists. Upload a sprite sheet, automatically detect sprite boundaries, create frame animations, and export to GIF or Aseprite-compatible formats for use in game engines like Unity, Godot, or GameMaker.

Live Demo: https://timely-haupia-b34a61.netlify.app/

Detect sprites on spritesheets automatically! Browser SDK with a clean web interface for sprite detection, animation editing, GIF export, and Aseprite-compatible export.

Create and edit frame-by-frame animations!

Features

Web Interface — Drag-drop a sprite sheet, watch it auto-detect sprites with bounding boxes, then edit frame animations in a timeline and export to GIF or Aseprite/LibreSprite format.

SDK — ES modules for sprite detection, animation generation, GIF encoding, and Aseprite-compatible export. Use in the browser or Node.js.

CLI — Coming soon.

See FEATURES.md for the complete feature breakdown.

SDK API Reference

SpriteDetector

Detects individual sprites within a spritesheet using boundary detection.

import { SpriteDetector } from 'sprite-detector';

const detector = new SpriteDetector();
const sprites = detector.detect(imageData);
// Returns: [{ x, y, width, height }, ...]

AnimationGenerator

Generates row-wise or column-wise animations from detected sprites.

import { AnimationGenerator } from 'sprite-detector';

const generator = new AnimationGenerator({
  centerlineTolerance: 20,  // Pixels of variance to group into same row/column
  frameDuration: 100,       // Default frame duration in ms
  loopMode: 'forward',      // 'forward' | 'ping-pong' | 'reverse'
  orientation: 'horizontal' // 'horizontal' (rows) | 'vertical' (columns)
});

const spriteSheet = generator.generate(sprites);
// Returns: { frames: [...], animations: [...] }

AsepriteExporter

Export sprite sheets in Aseprite-compatible JSON + PNG format.

import { generateAsepriteJSON } from 'sprite-detector/sdk/aseprite-exporter.js';

const asepriteData = generateAsepriteJSON(spriteSheet, sourceImage, {
  name: 'MySprite'
});
// Returns: { frames: [...], meta: { frameTags: [...], ... } }

Image Utilities

import { 
  loadImage, 
  getImageData, 
  detectBackgroundColor, 
  makeTransparent,
  imageDataToImage 
} from 'sprite-detector';

// Load an image file
const img = await loadImage(file);

// Get ImageData for processing
const imageData = getImageData(img);

// Auto-detect background color
const bgColor = detectBackgroundColor(imageData);

// Remove background with threshold
const transparentImageData = makeTransparent(imageData, bgColor, threshold);

// Convert back to image
const processedImg = await imageDataToImage(transparentImageData);

Browser Usage

The SDK is designed for zero-dependency browser use. No build step required:

<script type="module">
  import { SpriteDetector } from './node_modules/sprite-detector/src/sdk/index.js';
  
  const detector = new SpriteDetector();
  // ... use as above
</script>

File Structure

sprite-detector/
├── src/
│   ├── sdk/
│   │   ├── index.js              # Main SDK exports
│   │   ├── detector.js           # Sprite detection logic
│   │   ├── animation-generator.js # Animation generation
│   │   ├── aseprite-exporter.js  # Aseprite format export
│   │   └── image-utils.js        # Image processing utilities
│   ├── ui/
│   │   ├── animation-editor.js   # Animation Editor component
│   │   ├── drop-zone.js          # File upload component
│   │   ├── preview-canvas.js     # Sprite preview component
│   │   └── status.js             # Status messages
│   └── main.js                   # App entry point
├── index.html                    # Web interface
├── styles.css                    # App styles
└── tests/fixtures/               # Sample Aseprite JSON files

Development

# Clone the repository
git clone https://github.com/yourusername/sprite-detector.git
cd sprite-detector

# Start local dev server
npm start
# or
npx http-server .

Open http://localhost:8080 (or the URL shown) to use the web interface.

Supported Formats

• Input: PNG, JPG, WEBP, GIF (any browser-supported image format)
• Output:
  • PNG (original or background-removed spritesheet)
  • JSON (Aseprite/LibreSprite compatible with frames, frameTags, and metadata)

Browser Compatibility

Works in all modern browsers with ES module support:

• Chrome 61+
• Firefox 60+
• Safari 10.1+
• Edge 16+

License

ISC

Made with love for game developers and pixel artists