Asset Packs

Table of Contents

• Overview
• Quick Start
  • Using Asset Packs in Your Scene
  • Prerequisites for Development
• Distribution
  • Production
  • Development
  • Deployment
  • Local Development
  • Troubleshooting
• Related Architecture Decisions

Overview

The asset-packs repository is a fundamental component of the Decentraland ecosystem that serves as the central storage and distribution system for default items and assets. It manages and distributes:

• Asset Packs: Curated collections of 3D assets organized by themes (cyberpunk, steampunk, genesis city)
• Static Items: Basic 3D models with textures and materials
• Smart Items: Interactive items with programmable behaviors and configurations

When deployed, all assets are hashed and uploaded to an S3 bucket under contents/:hash. An npm package @dcl/asset-packs is published containing:

• A catalog.json with all asset packs data and content hashes
• A bin/index.js runtime required for Smart Items functionality

The assets are accessible through builder-items.decentraland.* via Cloudflare.

Quick Start

Using Asset Packs in Your Scene

Install the package in your Decentraland SDK7 scene:

npm install @dcl/asset-packs

Import and use asset packs in your scene:

import { readGltfLocator } from '@dcl/asset-packs'

// Use an asset from the catalog
const assetId = 'some-asset-id'
const gltfSrc = readGltfLocator(assetId)

// Use in your scene
engine.addEntity({
  transform: Transform.create(),
  gltfContainer: GltfContainer.create({ src: gltfSrc })
})

Prerequisites for Development

• Node.js 22.x or higher
• npm (comes with Node.js)
• Docker (for running local content server)
• @dcl/sdk-commands installed globally or locally

Distribution

Production

• npm: @dcl/asset-packs@latest
• cdn: https://builder-items.decentraland.org/contents/:hash

Development

• npm: @dcl/asset-packs@next
• cdn: https://builder-items.decentraland.zone/contents/:hash

Deployment

Production Deployment:

• Triggered by: Every merge to the main branch
• npm: Publishes @dcl/asset-packs@latest
• CDN: Uploads assets to https://builder-items.decentraland.org

Development Deployment:

• Triggered by: Manual comment /upload-assets on pull requests (org members only)
• npm: Test packages available via S3 for PR testing
• CDN: Uploads assets to https://builder-items.decentraland.zone

Note: All assets are content-addressed (hashed), ensuring immutability and correct caching.

Local Development

You can develop this repo locally and test it within the Web Editor by doing the following:

Go to this repo in your machine and do this:

1. Run npm run start to watch for changes and start the SDK7 dev server (on port 8001 by default).
2. On a new terminal, run docker-compose up to start the local content server on http://localhost:9000/asset-packs
3. On a new terminal, run npm run upload to upload all assets to your local content server (copy the .env.example into .env if you haven't done that before).
4. Copy the path to the bin/index.js in this repo (something like /Users/my-user/path/to/creators-hub/packages/asset-packs/bin/index.js).

Go to the packages/inspector in this monorepo and do this:

1. Run npm start to start a local dev server. It should start by default on port 8000.

Go to the packages/creator-hub in this monorepo and do this:

1. Copy the .env.example to .env if you haven't done that before.
2. Set the VITE_INSPECTOR_PORT env var in .env to be 8000 (this is the @dcl/inspector dev server we started in the previous section).
3. Set the VITE_ASSET_PACKS_JS_PORT to the port where the SDK7 started running in the first section (8001).
4. Set the VITE_ASSET_PACKS_JS_PATH env var in .env to the path to the bin/index.js that you copied in the first section.
5. Set the VITE_ASSET_PACKS_CONTENT_URL env var in .env to be http://localhost:9000/asset-packs (this is the content server we started in the first section).
6. Run npm start to start the builder local server which should start on port 3000

Now you are all set, you can start developing the SDK7 scene in this repo, use it from the local Builder and test it by previewing the scene, which should use your local Builder Server serving the development javascript files.

Testing New Assets in the Inspector

The inspector fetches the asset catalog at runtime from S3. If latest/catalog.json is unreachable (e.g. on a pre-merge PR branch, in CI, or offline), it automatically falls back to the catalog.json bundled in the @dcl/asset-packs npm package — so the inspector always loads.

When you add a new asset locally it won't appear in the Asset Packs tab automatically because neither the CDN nor the bundled catalog knows about it yet. There are two options:

Option 1 — Docker (full local stack, recommended)

The existing docker-compose setup handles everything. npm run upload now also uploads catalog.json as asset-packs/latest/catalog.json to MinIO, mirroring what CI does on S3.

Follow the steps in Local Development above, then open the inspector with:

http://localhost:8000/?contentUrl=http://localhost:9000/asset-packs

Both the catalog listing and all asset files are served locally — full end-to-end testing with no remote CDN needed.

Option 2 — Upload to dev CDN via PR

Push your branch and comment /upload-assets on the pull request (org members only). The CI will upload all asset files from your branch to the development CDN (https://builder-items.decentraland.zone) and post a comment confirming the upload.

Then configure the inspector to use the dev CDN:

VITE_ASSET_PACKS_CONTENT_URL=https://builder-items.decentraland.zone

Or when opening the inspector directly:

http://localhost:8000/?contentUrl=https://builder-items.decentraland.zone

The catalog pointer (latest/catalog.json) is only updated on merge to main, so the Asset Packs tab will still show the currently published catalog — but the asset files themselves will be available for loading.

Troubleshooting

Missing @dcl/ecs dependency

This package has a dependency on @dcl/ecs for several types. This is package is not added as a dependency even though it should be, because this causes an issue when installing @dcl/sdk@next on a scene. The problem is the following dependency chains:

1. @dcl/sdk -> @dcl/ecs
2. @dcl/sdk -> @dcl/sdk-commands -> @dcl/inspector -> @dcl/asset-packs -> @dcl/ecs

When a user installs @dcl/sdk@next on as scene, that updates @dcl/ecs from 1) but not the one from 2) and due to the clash npm stores the @latest version on the top level of node_modules and the @next version only whithin the @dcl/sdk/node_modules. This can cause runtime issues.

So we decisded to remove the explicit dependency of @dcl/ecs from the @dcl/asset-packs package, and that allows users to install @dcl/sdk@next or upgrade versions without problems. The downside is that if this package is used in some project where @dcl/ecs is not available, it's going to break. This package is not meant to be used outside of a Decentraland scene anyway so that shouldn't be a problem.

Related Architecture Decisions

For a deeper understanding of the architecture and design decisions:

• ADR-281: Items in Decentraland tooling - Describes the Items abstraction, types of items (Static, Smart, Custom), and technical implementation details.