Skip to content
Jami3D
Developer docs menu

Game packages: reference and troubleshooting

Sizes and limits, error codes, what degraded means, versions and the compatibility promise, licences, bundlers, exporting a package, and what to do when a package does not play.

Tiers, sizes and limits

Each model is written at three levels of detail (or a plant's own levels): the high tier loads them all and draws the one its distance from your camera calls for, medium the two lightest, low the lightest. An instance set draws at most 4,096 of its instances on high and medium, and 1,024 on low.

The runtime's size, gzipped, with three.js left out (it is yours): its core at most 45 KB. What a world needs only when it holds it loads on demand: living bodies and the navmesh (at most 70 KB more), and the sky, fog, water, wind, terrain and effects. The format reader alone, @jami3d/three/format, is at most 12 KB.

A package past one of these limits is refused limit_exceeded:

ItemLimit
The file1 GiB
Files in it100,000
A world or prefab file32 MiB
Entities in a world16,384
Instances in a package / a set / a 32 m cell4,194,304 / 1,048,576 / 65,536
Clips of a character256
A navmesh64 MiB
A terrain's heights4,096 × 4,096
A mesh collider65,536 triangles

Errors

Loading and building throw a PackageError: isPackageError(error) tells one, across copies of the runtime; error.code says why, and error.path names the package's file when the fault is in one. Calls a game makes while playing answer {ok: false, reason} with the same codes. A few play-time calls throw for an argument they cannot take or a disposed world (disposed): update (a dt that is NaN or infinite), setTime (a time below 0), spawn (not_found), setQuality (unsupported), setAudio and restore (invalid_input). Branch on the code: messages are for people and may change, codes are never renamed or removed. A wrong address is not always fetch_failed: a server that answers an unknown path with your page (Vite's does, with 200) hands the runtime a page, read as package_unreadable.

TypeScript
import { isPackageError, loadPackage } from "@jami3d/three";

try {
  const pkg = await loadPackage("/scene.jpkg", { renderer });
  const world = await pkg.createWorld();
  // What a world draws or runs with less than it holds: once each, at the first update.
  world.on("degraded", ({ reason, detail, entity }) => console.warn(reason, detail, entity));
  world.on("deprecation", ({ id, detail }) => console.info(id, detail));
} catch (error) {
  if (!isPackageError(error)) throw error;
  switch (error.code) {
    case "runtime_outdated":
      console.error("This package needs a newer @jami3d/three.");
      break;
    case "fetch_failed":
      console.error("The package could not be fetched:", error.message);
      break;
    default:
      console.error(error.code, error.path ?? ""); // branch on the code; the message may change
  }
}
CodeMeaning
fetch_failedThe package's bytes could not be fetched (network, HTTP status, CORS).
package_unreadableNot a package this runtime opens (not a stored zip, no manifest first, another format).
package_corruptParts of the package contradict each other: sizes, hashes, a missing or malformed file.
package_too_newA format major version this runtime does not know.
runtime_outdatedThe package needs a newer runtime level (its runtimeMin).
three_unsupportedYour three.js is older than r180 or newer than r186.
ktx2_unconfiguredA package with KTX2 pictures, and neither ktx2.transcoderPath with a renderer nor a ktx2.loader whose detectSupport was called.
not_foundNo such world, prefab, entity, clip, param or action.
invalid_inputA call's argument is not one it takes.
not_allowedA param a host may not write, an action a host may not call, an entity the package placed (not spawned).
unsupportedSomething this world cannot do: a tier the package does not carry, no fetch.
abortedYour signal stopped the load.
disposedThe world or the package was disposed.
limit_exceededPast one of the limits.

What “degraded” means

A world that draws or runs less than its package holds goes on playing, and says why in a degraded event, once for each thing: it is a report, not a failure. A newer package on an older runtime, a second copy of three.js and a WebGPURenderer are each told this way, and world.stats().degraded counts the reports so far.

ReasonWhat
three_duplicateYour objects come from another copy of three.js than the runtime's: bundle one copy.
content_unknownAn entity of a kind this runtime does not know stands empty (a newer package's).
definition_unknownA definition of a kind or version this runtime does not draw.
definition_invalidA definition this runtime refused to build.
bone_missingA held prop whose bone its character lacks hangs from the character.
clip_missingA clip a character lists is not in its model.
static_materialOn WebGPURenderer: the sky, fog, water, terrain, effects and vegetation sway are left out or stand still. Models, instances, characters and lights draw.
life_unmappedA behaviour, target or region that could not be mapped is left out.
feature_unknownThe package names features this runtime does not know; it reads on.
audio_unplayableAn ambience loop your audio context does not decode stays silent.
motion_invalidAn entity's own clip or generators this runtime could not read: it stands where it rests.

Versions and the compatibility promise

.jpkg packages and @jami3d/three never break. A runtime reads every format version ever written; JAMI's exporter can target every runtime level released in the last 24 months; features, fields, event names, reasons and error codes are only ever added.

The runtime's version. @jami3d/three has versions of its own, apart from jami3d (the embed SDK) and from JAMI's releases. RUNTIME_VERSION says which runtime your game bundles, and THREE_REVISION_MIN and THREE_REVISION_MAX the oldest and the newest three.js it runs on.

TypeScript
import { RUNTIME_VERSION, THREE_REVISION_MAX, THREE_REVISION_MIN } from "@jami3d/three";
import { REVISION } from "three";

const range = `r${THREE_REVISION_MIN} to r${THREE_REVISION_MAX}`;
console.log(`@jami3d/three ${RUNTIME_VERSION} on three.js r${REVISION} (it runs on ${range})`);
console.log(pkg.version, pkg.features, pkg.unknownFeatures); // words this runtime does not know

Runtime levels. A package names the runtime level it needs (runtimeMin, shown when it is exported). A runtime refuses a package that needs a later level (runtime_outdated) and a format major it does not know (package_too_new); within its major it reads newer packages, ignoring fields it does not know and reporting what it does not draw (degraded). pkg.unknownFeatures lists the feature words your runtime does not know.

LevelFirst runtimeWhat it adds
11.0.0Worlds, models, instances, characters and their gaits, colliders, the ground and the navmesh, living bodies, controls, prefabs, sky, fog, wind, water, terrain, effects, KTX2 pictures and ambient sound.
21.1.0Effects and water drawn in a style (effect_styles, water_styles); living bodies that keep out of water (life_water).
31.2.0Props, lights, groups, anchors and cameras that move by themselves (entity_clips, generators); a character's performance that plays by itself (character_autoplay); spot lights' beams (light_beams); people who use places (life_visits); behaviours that apply only sometimes (life_spells); the navmesh's links (nav_links); feet planted on the ground (humanoid_footing).

When a package needs a newer runtime than your game ships, update the runtime, or ask for the package exported for yours: the export option compat: {runtime: <level>} brings each newer feature down to what that level reads, or leaves it out, and the export's report says which (feature_downleveled, feature_dropped).

The package's version. A package's version follows its interface: its worlds and prefabs, its entities by key, their tags and controls (params, actions, events), its instance sets, and the host targets its behaviours name. Each export compares the interface with the last version of the same package: a member removed or changed is a major version (a game that used it must change), a member added a minor one, anything else a patch. A game built on 2.x keeps working with every 2.y.

Licences and credits

A package carries its maker's own content, and files whose licence lets them be shared (CC0, CC BY and the open-source licences), each with its credit. Its terms and holder are in its LICENSE.txt and in pkg.licence: an SPDX id such as CC-BY-4.0, or a LicenseRef-… (LicenseRef-All-Rights-Reserved when its maker chose none). Its credits are in its credits.json, which pkg.credits() reads: show them where your game shows its credits. The runtime itself is MIT; its LICENSE lists the third-party code it bundles.

Bundlers

Parts loaded on demand. The runtime loads some of its parts by dynamic import, only when a world holds them: living bodies and the navmesh, the scenery (sky, fog, water, wind, terrain, effects), a spot light's beam and the ground's decoder — life.js, scenery.js, beams.js and ground-chunk.js beside index.js in its dist/. Vite, webpack and Next.js emit them as chunks of your build with no setting; serve them where your bundler puts them.

One three.js. The runtime imports your three and its addons (three/addons/…). Two copies on a page — a linked package, a second version — are reported as three_duplicate; make your bundler resolve one. With Vite:

vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  resolve: { dedupe: ["three"] }, // one copy of three.js for your game and the runtime
});

Next.js. Use the runtime in a client component, and call it only in effects (the quickstart).

WebGPU. On WebGPURenderer, standard content (models, instances, characters, lights) draws; JAMI's own materials (sky, fog, water, terrain, effects, vegetation sway) are left out or stand still, reported static_material.

KTX2 pictures

A package exported with KTX2 pictures (textures: "ktx2") needs your three.js's Basis transcoder, basis_transcoder.js and basis_transcoder.wasm, served by your site. Copy them from three with one command, run in your project's folder on Windows, macOS or Linux alike:

Terminal
node -e "require('fs').cpSync('node_modules/three/examples/jsm/libs/basis', 'public/basis', { recursive: true })"

They land in public/basis/, which Vite and Next.js both serve at /basis/, in development and in a build: that is the transcoderPath. They go with three's version, so run the command again after each update of three, or make it your project's postinstall script, which npm runs after every install:

package.json
{
  "scripts": {
    "postinstall": "node -e \"require('fs').cpSync('node_modules/three/examples/jsm/libs/basis', 'public/basis', { recursive: true })\""
  }
}

Then hand the runtime the folder, or your own loader:

TypeScript
import { loadPackage } from "@jami3d/three";
import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";

// The runtime makes a loader for this package and disposes it with the package.
const one = await loadPackage("/scene.jpkg", { renderer, ktx2: { transcoderPath: "/basis/" } });

// Or your own loader, shared by every package you hand it to and disposed by you, last.
const ktx2 = new KTX2Loader().setTranscoderPath("/basis/").detectSupport(renderer);
const other = await loadPackage("/other.jpkg", { renderer, ktx2: { loader: ktx2 } });
one.dispose();
other.dispose();
ktx2.dispose();

Without either option such a package is refused ktx2_unconfigured (so is a loader whose detectSupport was not called). A package without KTX2 pictures never reads the option.

A Vite build also emits three's own copy of the transcoder (about 0.6 MB, beside the KTX2Loader chunk), because three's loader names it beside itself; it is fetched only when a package needs it. The runtime does not read that copy: transcoderPath reads the folder you serve, so the copy above is still the one to make.

Exporting a package

A package is made in JAMI's Studio by anyone who may edit the project: select what it carries (nothing selected: the whole scene; one kit instance alone: that kit, as a prefab), then choose File › Export game package…. Before anything is written, the dialog shows the version, the size, what the package leaves out, the files kept out by their licence and the credits a game must give; once written, the file downloads from its page.

Scripts with a design access token, MCP clients and connected AI apps use two operations: export.preview with format: "jpkg" (what the package would be, writing nothing) and export.package (writes it and answers its version, its report and the page it downloads from; export.status follows it). Their package options:

OptionValuesDefault
nameThe package's nameThe target's name
tiershigh, medium, lowAll three
prefabsnone, kits (each kit placed, as a prefab too)none
licence{terms, holder}LicenseRef-All-Rights-Reserved
versionA semver at least what the change needsWhat the change needs
collidersproxies (collision proxies and zones), noneproxies
controlsmarked (what is marked for a host), allmarked
textureswebp, ktx2webp
audioambient (the scene's ambience loops), noneambient
compat{runtime, strict?}: the runtime level that must read itThe level its features need
clips{keep: [names]}: a model's own clips to carry; {performance: {fromMs, toMs}}: each character's performance as one clipNeither
prototypescarry, skip: a scatter's hidden prototype as an entityWhat the last version did
leaveOut{ids, tags, only?}: things to leave out, by object ID and by tag, added to what the package already leaves out; with only: true, exactly theseWhat the last version left out
putBack{ids, tags}: things and tags taken out of what the package leaves outNothing

Leaving things out

A package can leave out things of the scene its game does not need: characters, props, effects, lights. The package remembers what it leaves out, from version to version: an export that says nothing about it leaves out what the last version left out, and nothing is ever put back unasked.

In the export dialog, the section Leave out shows what the package leaves out now. Choose… lists the scene's things grouped as the Outliner groups them — untick a thing to leave it out, with everything under it — Everything tagged leaves out every thing that carries one of its tags, things tagged later too, and Put back returns one. What you untick is added to what the package leaves out, and what you tick back is taken out of it; a choice made elsewhere while the dialog is open (an app, a script, another tab) is kept and appears in the list. Exporting without touching the list changes nothing.

A script or an app changes the choice with two options:

  • leaveOut: {ids, tags} adds to what the package already leaves out. leaveOut: {ids: ["char-k7f3"]} also leaves out that character; what the last version left out stays out.
  • putBack: {ids, tags} takes things out of the choice. putBack: {tags: ["crowd"]} brings back what the tag crowd left out. A thing left out by a tag comes back only when the tag is put back; one that a tag or an ancestor still leaves out is named in leftOut.stillOut.
  • leaveOut: {ids, tags, only: true} sets the choice to exactly these. leaveOut: {tags: ["crowd"], only: true} leaves out only what is tagged crowd, and leaveOut: {only: true} leaves nothing out. (leaveOut: {} changes nothing.)

The preview and both answers carry leftOut: the whole choice after the call, where it came from (request, previous or both), the things chosen by name, how many things stay out in all, and what the package still carries that named one of them. They carry it whenever the call carried leaveOut or putBack, even when nothing is left out: a call that carried one and an answer without leftOut mean an older server ignored it.

A thing left out is, for the package, not in the scene. It and everything under it are not written; nothing the package carries reads it (the ground, wind, sky, places, sounds, effects); its files travel only when something the package still carries uses them too. Whatever still named it — a behaviour that follows it or waits for it, a visit to a place under it, an emitter shaped by it — loses that one thing, and the report says so by name (left_out, left_out_named) before anything is written.

  • In the game, a thing left out is not there: world.entity(key) answers undefined for it and world.find never names it. Leaving out what the last version carried is a major version, and the preview names the members removed.
  • Give an alias in JAMI to every entity your game names, so that its key does not change when it is renamed.
  • A kit exported as a prefab goes whole: leaveOut applies to a scene's worlds, never to a prefab's own things.

When a package does not play

What you seeWhat to do
fetch_failed from another originThe server must allow your page (CORS) and the Range header; reading by ranges also needs Access-Control-Expose-Headers: Content-Range, without which the file is fetched whole. See serving it from another origin.
fetch_failed ("Failed to fetch") in an everyday Chrome or Edge profileThose browsers refuse concurrent range reads of one cached file. From 1.2.0 the runtime asks every ranged read cache: "no-store": with a build older than 1.2.0, update it; with a fetch of your own, keep the options it is handed ({ ...init, … }). Or hand loadPackage the bytes (await (await fetch(url)).arrayBuffer()), or a fetch that sets cache: "no-store", as below.
runtime_outdatedThe package needs a newer runtime: update @jami3d/three, or ask for the package exported with compat: {runtime: <your level>}.
three_unsupported at load ("three.js r187 is newer than r186, …"; a Vite project), or "Export CubeUVReflectionMapping doesn't exist" when a build fails first (Next.js)Your three.js is outside the range this runtime supports: it runs on three.js 0.180 to 0.186; 0.187 and later are not supported yet (the runtime says so as a peer warning at install). Install a three within the range: npm install three@0.186. Older than r180, update it.
three_duplicate (a degraded event)Two copies of three.js are on the page: make your bundler resolve one.
ktx2_unconfiguredPass ktx2: { transcoderPath } or your own KTX2Loader: see KTX2 pictures.
package_unreadable ("not a package archive", or manifest.json: not JSON) right after a deploy or a renameThe address serves a page, not the file: Vite's server, and any host that falls back to your index.html, answers a wrong path with your page (200), not a 404. Check the URL first.
Everything is black, with no errorThe package carries no light and no sky (world.stats().scenery.sky is false): add a light of your own, as the quickstart shows.
Nothing showsAdd world.root to the scene you render, call world.update(dt, camera) every frame, and point the camera at the world.
Too dark, too bright or flatCall world.applyLook({ renderer, scene }): the package's tone mapping, exposure and sky light.
No shadowsSwitch on renderer.shadowMap.enabled.
Nothing pursues the playerName the target with world.host.setTarget, by a name of world.hostTargets, before the behaviour needs it.
world.entity(key) answers undefinedA key is the entity's alias, else its name with a short code that changes when it is renamed; or the thing was left out. world.find() lists the world's keys.
No soundCall world.setAudio(listener) after a person's gesture, and check the package was exported with audio: "ambient".
A world draws less than JAMI doesListen for degraded right after createWorld and read its reasons (what they mean), and read the export's report of what the package leaves out.
TypeScript
import { loadPackage } from "@jami3d/three";

// A build older than 1.2.0 does not ask it itself: read every range past the browser's cache.
const pkg = await loadPackage("/scene.jpkg", {
  renderer,
  fetch: (url, init) => fetch(url, { ...init, cache: "no-store" }),
});