SuperBillboardBacker

A sophisticated TypeScript library and interactive tool designed for game artists to "bake" 3D objects into high-quality 2D sprite frames. It features a configurable orbital camera system that captures models from multiple angles, perfect for creating assets for 2D isometric, top-down, or side-scrolling games.

Features

• Orbital Capture: Define distance, elevation, and number of frames.
• Three.js Integration: Seamlessly loads GLTF, GLB, and OBJ formats.
• High-Resolution Baking: Captures frames to a stitched sprite sheet.
• Interactive Preview: Real-time visualization of capture orbits and camera positions.
• Embeddable UI: A full-featured, framework-agnostic UI class ready to be dropped into any div.
• Developer Friendly: Written in modern TypeScript with full ESM support.

Demo

Check out the interactive tool: this is the demo

Quick Start

npm install @gnuton/super-billboard-backer

import { SpriteBaker } from '@gnuton/super-billboard-backer';

const baker = new SpriteBaker();
const result = await baker.bake({
  model: 'path/to/model.glb',
  frameCount: 16,
  isAutoDistance: true,
  elevation: 30, // Degrees
});

// Download or use the generated sprite sheet

Embedding in your App

The library provides a standalone, embeddable UI class called BillboardBackerUI. This allows you to integrate the full baking tool into your own web application with just a few lines of code.

Usage

import { BillboardBackerUI } from '@gnuton/super-billboard-backer';
import '@gnuton/super-billboard-backer/dist/ui/BillboardBackerUI.css';

const container = document.getElementById('my-container');
const ui = new BillboardBackerUI({
  container: container,
  theme: 'dark', // 'dark' | 'light' | customRecord
  onBakeComplete: (dataUrl) => {
    console.log('Bake finished!', dataUrl);
  }
});

// Programmatic control
ui.loadModel('url/to/model.glb');
ui.setParams({ frameCount: 32 });

Skinning & Theming

BillboardBackerUI is highly skinnable via CSS variables. You can override the default look by setting variables on your container or globally:

#my-container {
  --sbb-primary-color: #ff5722;
  --sbb-bg-color: #1a1a1a;
  --sbb-radius: 4px;
}

Available variables:

• --sbb-primary-color: Accent/Active color.
• --sbb-bg-color: Main background.
• --sbb-text-color: Main text color.
• --sbb-glass-bg: Panel backgrounds.
• --sbb-viewport-bg: 3D viewport background.
• --sbb-radius: Main border radius.

Development & Demo Setup

To test the library and the demo application locally:

1. Clone and Install:

   npm install

2. Build the Library: The demo relies on the core library logic.

   npm run build

3. Run the Demo: Navigate to the demo directory and start the dev server.

   cd demo
   npm install
   npm run dev

4. Testing the Tool:

   • Once the server is running (usually at http://localhost:3000), open your browser.
   • Upload a .glb or .gltf file.
   • Adjust the Frames, Distance, and Elevation sliders.
   • Observe the blue "Orbit Preview" ring in the 3D viewport.
   • Click BAKE SPRITES and verify the generated sprite sheet on the right panel.

Documentation

Detailed specifications can be found in the docs directory.

License

GPL-3.0