asset

Asset references, catalogs, and loading orchestration for browser and Node.js

💃 Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @jolly-pixel/asset
# or
$ yarn add @jolly-pixel/asset

💡 About

An asset keeps the same identity when its file, URL, or revision changes. Scenes and components store an AssetReference. An AssetCatalog resolves that reference to an AssetRecord, which describes the current source and revision.

Choose the path that matches your work:

• Game developers using @jolly-pixel/runtime should start with using assets in a game.
• Runtime, editor, and server maintainers should read runtime loading architecture and custom runtime integration.

The asset glossary defines the terms shared by these APIs.

👀 Usage example

Create a reference with one of the engine's shared asset types, then declare it as a scene dependency:

import { AssetReference } from "@jolly-pixel/asset";
import {
  AssetTypes,
  ModelRenderer,
  Systems
} from "@jolly-pixel/engine";

const heroModel = new AssetReference(
  "hero-model",
  AssetTypes.model
);

class GameScene extends Systems.Scene {
  constructor() {
    super("game", {
      assets: [heroModel]
    });
  }

  override awake(): void {
    this.world.createActor("hero")
      .addComponent(ModelRenderer, {
        asset: heroModel
      });
  }
}

The JollyPixel runtime loads scene.assets before activating the scene. The catalog supplies the source for "hero-model"; gameplay code keeps the stable reference. The game developer guide shows the matching catalog and runtime setup.

📚 API

Core model

Start here. These types define persistent asset identity and catalog lookup.

• AssetReference: the stable, typed value stored by scenes and components.
• AssetCatalog: the authoritative records for one project or session.

Supporting domain types

• AssetId: validated stable identity.
• AssetType: the shared token connecting a persistent kind to its loaded value type.
• AssetRecord: source and revision metadata held by a catalog.

Runtime orchestration

These APIs are primarily for runtime integrations, editor tools, and explicit dynamic loading.

• AssetCoordinator: resolves references and starts loads.
• AssetLoader and AssetLoaderRegistry: produce runtime values for registered asset types.
• AssetStore and AssetHandle: own and expose runtime state.
• AssetLoadBatch: tracks one fixed loading operation.

The reference also covers package errors and the room-name and URL helpers shared with server and collaboration packages.

✨ Contributors guide

If you are a developer looking to contribute to the project, you must first read the CONTRIBUTING guide.

Once you have finished your development, check that the tests (and linter) are still good by running the following script:

npm run test -w @jolly-pixel/asset
npm run lint

CAUTION

In case you introduce a new feature or fix a bug, make sure to include tests for it as well.

📃 License

MIT