アセット

素材ファイルは assets/ に置きます。CLI がそこからマニフェストを組み立てます。dev で配信され、ビルドに含まれるのはマニフェストが参照しているファイルだけで、元のファイルが書き換えられることはありません。

ファイル	アセット ID	グループ
assets/logo.png	logo	default
assets/level1/map.json	level1/map	level1
assets/hero@16x24.png	hero（16×24 のスプライトグリッド）	default

フォルダは プリロードグループ になるので、レベルのアセットを必要になったタイミングで読み込めます。

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 }) => bar(loaded / total));

const hero = new Sprite({ frames: assets.frames("hero"), animations: { run: { frames: [0, 1, 2, 3], fps: 12 } } });
draw.sprite(assets.frame("coin"), x, y); // どこにある画像でも OK

アトラスは自動で

ビルド時（と dev 中）に、各プリロードグループの PNG が 1 枚のテクスチャアトラスにまとめられます。プレイヤーは何十ものファイルではなく 1 ファイルをダウンロードするだけで済み、レンダラーがバインドするテクスチャも減ります。パッキングはロスレスで、端のにじみを防ぐパディングも入ります。frame() / frames() はどちらの場合も同じように動きます。アトラスサイズの半分を超える画像（背景など）は単体のまま残ります。調整や無効化は debuff.config.ts で行います。

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

npx debuff assets は、すべてのアセットと、それを生成したインポーター、サイズ、使われていなさそうなものを一覧にします。

新しいフォーマット

アセットインポーターはプラグインで、どんな言語でも書けます。プラグインを見てください。