Asset Packs

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.

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

Every push to the main branch will be deployed to the development environment.

Every release will be deployed to the production environment.

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 8000 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. Run npm link to allow other projects to symlink to this one.
5. Copy the path to the bin/index.js in this repo (something like /Users/my-user/path/to/asset-packs/bin/index.js).

Go the js-sdk-toolchain repo in your machine and do this:

1. Run cd packages/@dcl/inspector.
2. Run npm link @dcl/asset-packs to symlink to your local repository
3. Run npm start to start a local dev server. It should start by default on port 8000 but since we are already using it for the SDK7 dev server, it will start on port 8001.

Go to the creator-hub repo in your machine and do this:

1. Set the VITE_INSPECTOR_PORT env var in .env to be 8001 (this is the @dcl/inspector dev server we started in the previous section).
2. Set the VITE_ASSET_PACKS_JS_PORT to the port where the SDK7 started running in the first section (by defualt 8000).
3. 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.
4. Set the VITE_ASSET_PACKS_CONTENT_URL variable in src/config/env/[dev|stg|prod].json to be http://localhost:9000/asset-packs (this is the content server we started in the first section).
5. 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.

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.