@drawcall/flipbook

Tiny Three.js flipbook billboards loaded from KTX2 files.

Install

pnpm add @drawcall/flipbook three

three is a peer dependency.

Usage

import { Flipbook } from "@drawcall/flipbook";
import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";

const ktx2Loader = new KTX2Loader()
  .setTranscoderPath("/basis/")
  .detectSupport(renderer);
Flipbook.setKtx2Loader(ktx2Loader);

const explosion = new Flipbook("/explosion.ktx2", {
  height: 1,
  origin: "bottom-center"
});

scene.add(explosion);
await explosion.ready;

function animate(delta: number) {
  explosion.update(delta);
}

KTX2 Metadata

The KTX2 file may be Basis-compressed KTX2, loaded through Three.js KTX2Loader, or uncompressed R8G8B8A8. It must contain these key/value pairs:

• flipbook.columns
• flipbook.rows

Optional keys:

• flipbook.aspectRatio, defaults to the per-frame texture aspect ratio
• flipbook.frames, defaults to columns * rows
• flipbook.duration, defaults to frames / 24
• flipbook.playbackRate, defaults to 1
• flipbook.billboard, supports spherical, cylindrical, and none

Runtime options can override asset metadata:

const flame = new Flipbook("/flame.ktx2", {
  billboard: "cylindrical",
  playbackRate: 0.8,
  opacity: 0.9,
  loop: true
});

Use cylindrical for Y-axis billboards that stay upright.