@web-engine-dev/assets

Async asset loading with handles, caching, and hot-reload support.

Features

• Async Loading: Promise-based asset loading
• Asset Handles: Reference counting and lifecycle
• Caching: Automatic cache with configurable TTL
• Hot Reload: Development-time asset reloading
• Load Groups: Batch loading with progress
• Type Safety: Generic typed asset handles

Installation

npm install @web-engine-dev/assets
# or
pnpm add @web-engine-dev/assets

Quick Start

import { AssetManager, AssetHandle } from '@web-engine-dev/assets';

// Create asset manager
const assets = new AssetManager();

// Register loaders
assets.registerLoader('texture', textureLoader);
assets.registerLoader('audio', audioLoader);

// Load assets
const texture = await assets.load<Texture>('textures/player.png');

// Use handle
const sprite = new Sprite(texture.get());

// Release when done
texture.release();

API Overview

Asset Manager

Method	Description
registerLoader()	Add asset type loader
load<T>(path)	Load asset, returns handle
loadAll(paths)	Load multiple assets
get<T>(path)	Get cached asset
unload(path)	Force unload asset
preload(paths)	Preload assets in background

Asset Handle

const handle = await assets.load<Texture>('player.png');

// Check state
handle.isLoaded;
handle.isLoading;
handle.error;

// Get value
const texture = handle.get();

// Reference counting
handle.retain();
handle.release();

// Listen for reload
handle.onReload(() => {
  // Handle reloaded asset
});

Load Groups

const group = assets.createGroup(['textures/player.png', 'textures/enemy.png', 'audio/music.mp3']);

group.onProgress((loaded, total) => {
  console.log(`${loaded}/${total}`);
});

await group.load();

Hot Reload

const assets = new AssetManager({
  hotReload: true,
  watchPaths: ['./assets'],
});

// Assets automatically reload on file change
const handle = await assets.load('player.png');
handle.onReload((newAsset) => {
  updateSprite(newAsset);
});

Custom Loader

assets.registerLoader('json', {
  async load(path: string): Promise<unknown> {
    const response = await fetch(path);
    return response.json();
  },

  extensions: ['.json'],
});