Ferret: where to start
Skill ferret · download all skills · SKILL.md
Ferret is a game engine in a pnpm workspace of packages (@ferret/core, game, levels, character, physics-* ...). A game is a canvas, createGame, a level and game.start(). Everything the engine does is also a named command on world.commands, so a person, a test and an agent drive the same things.
Pick the skill#
| Task | Skill |
|---|---|
| Install, build, first game, samples | ferret-getting-started |
| Entities, components, services, events, the fixed step | ferret-world |
| A level manifest, travel, environment | ferret-levels |
.ferret packages, signing, encryption, caches | ferret-packages |
| Screen, device class, quality tier, saved state | ferret-platform-display |
| Actions, bindings, touch, HUD, menus | ferret-input-ui |
| Player movement, camera | ferret-character |
| Animation graphs, montages, retargeting | ferret-animation |
| NavMesh, NPC walking, behaviour trees | ferret-ai-navigation |
| Doors, levers, pickups, zones | ferret-interaction-zones |
| Audio, video and web pages in the world | ferret-media |
| Swapping one character for another | ferret-transform |
| Replication, backends, voice, sign-in | ferret-net-accounts |
| Building or changing a level by commands | ferret-level-editor |
| Looking inside a running game, tests | ferret-debugging |
| A UE5 level into Ferret (plan, export, postprocess, Blueprints) | ferret-unreal-porting |
| A ported level that looks wrong; parity with the original | ferret-unreal-level-look |
| UE characters, NPCs, clips, Animation Blueprints | ferret-unreal-characters |
| Anything realistic: physics | start at ferret-physics-recipes (wish to capability), then ferret-physics-host |
First steps#
- Read
reference/getting-started.mdfor the build and the shape of a game. - Find the skill above; open its
SKILL.md, then only the reference file it points to. - For an exact signature use the
reference/api-<package>.mdof that skill; do not guess names.
Rules that hold everywhere#
- Game logic goes in
onFixedUpdate(fixed 60 Hz step); only presentation inonUpdate. The same inputs then give the same run. - Bind actions, never keys; the console has a cursor, A and B and no mouse look.
- A level's manifest refers to glTF nodes by name, so re-exports keep the wiring.
- Everything a level builder creates is removed when the level goes; do not keep references across levels.
- Check with the commands (
world.commands.list()) and the unit tests, not by guessing.
Check afterwards#
pnpm typecheck and pnpm test pass; the sample or level loads; the commands you used answer as expected.
What usually goes wrong#
Using a key instead of an action; keeping state in a component that a level unload removes; simulating in onUpdate; naming a manifest node that the export renamed.
Files#
reference/index.md— What Ferret is, what it runs on, and how this documentation is organised.reference/getting-started.md— Install, build, run the samples, write a first game, run the tests, build this documentation.