---
name: ferret-getting-started
description: Use to set up the Ferret repository, build and run the samples, and write a first game with createGame, a character and a level. Covers the pnpm commands, what a build produces, and where each sample (greybox, npc, showcase, physics) is useful.
---

# Getting started with Ferret

## When to use
Starting a new game on Ferret, running a sample, or finding out what a build produces.

## Do this first
```bash
pnpm install
pnpm typecheck
pnpm test
pnpm build        # dist/web, dist/beroun, dist/lib
pnpm serve        # static server for dist/web
```
Open `dist/web/<sample>/index.html` through `pnpm serve`. Samples: `greybox` (a character in a grey-box level), `npc` (NavMesh walkers, doors, levers), `showcase` (media, UI, transformations), `physics` (the realism capabilities).

## The steps of a first game
1. `createGame({ canvas, storageKey, input: { actions, bindings } })` gives `world`, `platform`, `scene`, `display`, `input`, physics.
2. Build the level's meshes into `scene`; static meshes with `checkCollisions` are solid.
3. `spawnCharacter(world, 'hero', position)` then add `PlayerController`.
4. `game.display.trackCamera(player.rig.camera)` so the field of view follows the screen.
5. `game.start()`.
Anything else a game uses (levels, zones, UI, net) is a service you add to the world.

## What a build gives
`dist/web/<sample>` for browsers; `dist/beroun/<sample>` as an OS Beroun app (manifest, icon, page, bundle); `dist/lib/ferret.js` exposes `Ferret` and `BABYLON` globals; `dist/lib/ferret/` is the release for apps that load the engine from the OS's shared library.

## Check afterwards
The page opens, the character moves with the bound actions, `pnpm test` passes. `pnpm docs` builds the documentation, `pnpm skills` these skills.

## What usually goes wrong
- Opening `index.html` from disk instead of through `pnpm serve`.
- One `storageKey` shared by two games in a browser: give each its own.
- Expecting the first frame to hold all assets: they are loaded after the loading screen is up.

## Files

- `reference/getting-started.md` — Install, build, run the samples, write a first game, run the tests, build this documentation.
- `reference/index.md` — What Ferret is, what it runs on, and how this documentation is organised.
- `reference/api-game.md` — every export of `@ferret/game` with signature and doc comment