Reusable packages

An asset package is a versioned collection of reusable files with named exports. It can include GLB models, textures, material definitions or JavaScript. A world package fills an immutable host tile and must include world, map and overview content.

Find real packages in the creator catalog, with the CLI, or through the public asset API.

threetopia search beacon
threetopia install @threetopia/beacon@1.0.0

@threetopia/beacon is an original, MIT-licensed Threetopia example. Its model export fits a map slot; its world export is scaled for world coordinates. It is an example building block, not an asset copied from a showcase creator.

Asset manifest

{
  "schemaVersion": 1,
  "name": "@your-handle/coastal-rocks",
  "version": "1.0.0",
  "kind": "asset",
  "title": "Coastal rocks",
  "description": "Low-poly rocks for coastal worlds.",
  "license": "MIT",
  "changelog": "First release of the rock collection.",
  "exports": { "model": "assets/rocks.glb" },
  "dependencies": {}
}

Put this object in threetopia.json under manifest, and list every file under the project’s top-level files. The CLI scaffold includes the server-assigned package and project IDs.

Installation

Run installation inside a Threetopia project. World packages can also be installed for inspection, but only asset packages can be declared as reusable dependencies. The CLI:

1. Resolves exact published versions and transitive dependencies.
2. Downloads to a staging folder and verifies every file’s size and SHA-256.
3. Writes files under threetopia_modules/creator/package/.
4. Saves threetopia-lock.json and exact direct dependencies in your project manifest.
5. Records the successful installation in the registry.

Commit your lockfile. Package versions are immutable. Installing a newer version is explicit; existing projects do not silently update.

The package creator sees your public handle, the installed version and the number of project installations. A project uses a random ID; private project names and source code are not sent. Downloading files directly from the API does not count as a CLI installation.

threetopia uninstall @threetopia/beacon

Uninstall removes the dependency, local package directory and active installation record. It does not delete assets you already copied into your world. Transitive dependencies can be removed once nothing else depends on them.

Use an installed model

threetopia use @threetopia/beacon --export model --as map
threetopia use @threetopia/beacon --export model --as overview
threetopia use @threetopia/beacon --export world --as world
threetopia check

use checks the actual geometry against the selected role before copying it into your world’s content file. For a larger composition, import installed GLBs in your modelling or build tools, then export the combined scene. Its combined geometry must fit the slot and budget.

For code exports, import the installed file in your own application or bundler. Installation does not execute package scripts, and uploaded JavaScript never runs automatically on the creator website.