FERRETGame engine over Babylon.js
Ferret

Getting started with Ferret

Skill ferret-getting-started · download all skills · SKILL.md

When to use#

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

Do this first#

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#