---
name: ferret-levels
description: Use to describe, load, validate or travel between Ferret levels: the manifest.json (scene, spawns, entities, zones, colliders, environment, physics), LevelService, level doors, streaming and environment. Not for building the level contents by commands; see ferret-level-editor.
---

# Levels and the manifest

## When to use
Writing or fixing `manifest.json`, registering levels, travelling, setting sun/fog/sky, or checking why a level loads wrong.

## The shape
A level is a folder (or `.ferret` package) with `scene.glb` and `manifest.json`: `scene`, `navmesh`, `collision`, `entities` (node + behaviour/components + params), `spawns` and `defaultSpawn`, `zones`, `movement`, `animGraphs`, `colliders` overrides, `environment`, `physics`. Entities refer to glTF nodes **by name**.

## Steps
1. Write the manifest; run `validateManifest` (returns path + message; empty list means usable). The same check runs at load time.
2. Register levels on `LevelService` with a `LevelDef` builder, or let `installPackages` play packages.
3. `travel(id)`: loading screen, old level removed, new built, player placed at a spawn, events `level:loading`, `level:loaded`.
4. A `LevelDoor` entity is the usual way into another level.
5. `applyEnvironment` builds sun, ambient light, fog, sky and effects; dispose what it returns on unload.

## Check afterwards
`validateManifest` returns no problems; the level loads headless; the spawn is where expected; leaving the level removes everything it created.

## What usually goes wrong
- A node name in `entities` that differs from the exported glTF (case, suffix `.001`).
- Missing `navmesh.bin` and no `navBuild`: NPCs cannot path.
- Putting physics settings at world scope instead of the level's `physics` block: they then outlive the level (see `reference/level-block.md`).
- A big mesh that is not solid: use the `colliders` override.

## Files

- `reference/levels.md` — The level manifest, the level registry and travel, environment, and the .ferret package format.
- `reference/level-block.md` — The `physics` block of a level manifest: capabilities, materials, pair and combine rules, gravity, constraints and pre-fractured bodies, and what happens when the level loads and unloads.
- `reference/api-levels.md` — every export of `@ferret/levels` with signature and doc comment
- `reference/api-levels-2.md` — every export of `@ferret/levels` with signature and doc comment
- `reference/commands.md` — 39 commands of these packages with their arguments