FERRETGame engine over Babylon.js
Ferret

Levels and the manifest

Skill ferret-levels · download all skills · SKILL.md

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