@debuffjp/assets

Runtime loader for the manifest that debuff generates from your project's assets/ folder. No dependencies.

import { Assets } from "@debuffjp/assets";
import { Sprite } from "@debuffjp/core";

const assets = new Assets(await (await fetch("assets/manifest.json")).json());
await assets.load("default", ({ loaded, total }) => showProgress(loaded / total));

const hero = new Sprite({ frames: assets.frames("hero") }); // [email protected], sliced on its grid
draw.sprite(assets.frame("coin"), x, y); // any image, atlased or not

Conventions (from the asset compiler)

Keep each image within 4096 pixels on a side: a GPU with a smaller texture limit draws a bigger one black, and the CLI warns about it. Spread a long run of frames over several sheets. Before 0.29.3, the CLI didn't warn.

API

• load(groups?, onProgress?): preload one or more groups
• fetch(id): lazy-load a single asset; concurrent calls share one request
• frame(id): { image, x, y, w, h } for draw.sprite; works for atlased and standalone images
• frames(id): sprite-sheet frames from the name@WxH grid
• image(id) (standalone images only), json(id), audio(id), text(id), entry(id), has(id)

Typed asset ids

debuff dev, debuff build and npx debuff assets write .debuff/assets.d.ts, which fills the AssetRegistry interface with every asset id, its type and its group. Include that file in tsconfig.json and a misspelt id, an id of the wrong type or an unknown group is a compile error. Without it, ids are plain strings (as before 0.22). AssetId<"image"> and AssetGroup are exported for your own signatures.

Atlases

The CLI packs PNGs into atlases per preload group, in dev and in builds, so a level loads one texture instead of dozens. It's lossless, with padding that prevents edge bleeding. Images over half the atlas size stay standalone. Configure or disable it in debuff.config.ts:

export default defineConfig({ assets: { atlas: { maxSize: 2048, padding: 2, exclude: ["ui/"] } } }); // or atlas: false

• Errors are AssetError with the asset id and a suggested fix