# Overview

# Ferret

Ferret is a general-purpose game engine for **OS Beroun and ordinary web browsers**, built on top of [Babylon.js](https://www.babylonjs.com/). Babylon gives rendering, the scene graph, loaders and audio. Ferret adds the game layer Babylon does not have: characters and their movement, collisions and triggers, animation graphs, NPC behaviour, transformations, interactables, zones, levels and level travel, UI, media, networking, and a family of realistic-physics capabilities.

The same game build runs as an OS Beroun app (its web engine, its app packages, its Platform API) and as a web page on a desktop or phone, on screens from the console's 640×480 up to 4K.

The gate towers of a castle level.")

## See it run: a duel with a Dragon

The fight example (`examples/fight`) is a Viking against a Crusader Knight on a 1200 by 1200 m field of spruces, bushes and mountains, while Knight Lady Kira flies a Dragon that breathes fire over them. The fighters are played by the rules in `@ferret/combat` (blows, blocks, dodges, stamina, staggers, death), steered by an AI or by you; the Dragon is a flight model with its own AI. Everything is built from the asset library, and you can change who you are while it runs.

::app demo/fight/index.html media/fight-poster.jpg "The duel, running in this page (about 190 MB of models and animations, loaded only when you press the button; this page carries the mobile quality tier). Roles on the fly: 0 observer, 1 knight, 2 viking, 3 the Lady on the Dragon. Fighters: W A S D move, mouse looks, left button strikes (hold for the heavy blow), right button blocks, Space dodges, Shift runs. Dragon: W / S climb and dive, mouse or arrows steer, Space breathes fire, Q / Z speed. Observer: mouse looks, W A S D flies. The legend is on the screen."

The rules, the Dragon and the controls are in the combat guide (skill `ferret-combat`).

## See it run: the school courtyard

The School Outside example (`examples/school-outside`) is a level made in Unreal Engine 5 and brought over by Ferret's export pipeline: the castle courtyard with its towers, braziers and torches, walled in by collision that was built from the same scene. You walk it in first person with the original's movement values. The wooden door under the word SCHOOL is the one piece of game logic: step up to it and the player is hidden, the door's video plays on the doorway, the view blends to a cut-scene camera, the leaves open, and the player comes back at the start of the game.

::video media/school-outside-walk.mp4 media/school-outside-walk-poster.jpg "Two minutes in the courtyard, recorded with Ferret's scene recorder: a walk over the level, the notice board with the school's welcome page, and the exit door, whose video plays on the doorway before the player is back at the start."

::app demo/school-outside/index.html media/courtyard.jpg "The same example, running in this page (about 50 MB, loaded only when you press the button; this page carries the light quality tier, the full example has three). Walk: W A S D or the arrow keys. Look: mouse. Jump: Space. Run: Shift. Use: E. Menu: Esc. Walk to the door in the gate to see the exit."

The level package, the door behaviour and the rebuild steps are in `examples/school-outside/README.md`.

## See it run: a five-speed gearbox

The gearbox example (`examples/gearbox`) is generated from one file of numbers: 141 solid parts, checked for clashes, meshing and ratios, built into glTF models, then driven by Ferret's physics. Nothing in the picture is animated by hand: the shafts, free gears, sleeves, forks, the crown, the planets and the oil level move from the state of the machine, node by node. Below is a run through the demo, then the demo itself.

::video media/gearbox-demo.mp4 media/gearbox-demo-poster.jpg "Seventy-nine seconds with the controls: engine speed, clutch, gears by hand, housing opacity. A shift with the clutch engaged is refused by the box, as in a car."

::app demo/gearbox/index.html media/gearbox-demo-poster.jpg "The same demo, running in this page (about 19 MB, loaded only when you press the button). Engine: slider or Up / Down. Clutch: Space. Gear: N, 1 to 5, R or Left / Right. Brake: hold B (stop before reverse). Housing: slider or Esc. Drag to orbit, wheel to zoom."

How it is made, the shift, the limits and the wear are in the gearbox guide (skill `ferret`); the files and the rebuild steps are in `examples/gearbox/README.md`.

## What is in the box

| Area | What you get | Where to read |
|---|---|---|
| Runtime | A fixed-step `World`, entities with components, services, an event bus, a debug command channel | The world (skill `ferret`) |
| Platform | One interface over OS Beroun and the browser: saved state, suspend, exit, screen, quality tiers | Platform and display (skill `ferret-platform-display`) |
| Input and UI | Actions instead of devices; a responsive HTML overlay | Input and UI (skill `ferret-input-ui`) |
| Gameplay | Characters, animation graphs with random motion, NavMesh AI, interactables, zones, transformations (also by a record shared between players) | Gameplay packages (skill `ferret`) |
| Content | Levels as folders and `.ferret` packages with a validated manifest; packages that carry code and run it on demand | Levels and packages (skill `ferret-levels`) |
| Streaming | Levels and assets over HTTPS: catalogs, a persistent cache, cells that follow the camera, transitions a game defines | Streaming and catalogs (skill `ferret`), Writing a transition (skill `ferret`) |
| Networking | Replication over interchangeable transports, remote avatars, shared named records, gateways to a game's backend | Networking (skill `ferret-net-accounts`) |
| Physics | Two rigid-body kernels and sixteen capabilities that add realism only where a game switches it on, down to a transaxle with synchronisers, oil, heat and wear | Physics overview (skill `ferret`), Gearbox (skill `ferret`) |
| Presentation | Cutaway section planes with hatched caps, frame-exact capture to WebM or PNG, reflective environments for metal | Gameplay packages (skill `ferret`) |
| Tools | Unreal Engine 5 export pipeline (levels, characters, clips, animation blueprints, look and parity checks), a model viewer, the level editor commands, agent skills | Tools (skill `ferret-unreal-porting`), Agent skills |

## Where Ferret runs

| Target | Web engine | Input |
|---|---|---|
| OS Beroun on the console | WPE WebKit, WebGL2 | cursor, A, B, D-pad and sticks |
| OS Beroun on Android | the system WebView (Chromium 110 or newer) | the device's keys, pad, touch |
| Desktop browsers | their own, WebGL2 (WebGPU where present) | keyboard and mouse with Pointer Lock, gamepad |
| Mobile browsers | their own, WebGL2 | touch with virtual sticks, gamepad |

WebGL2 is the baseline renderer everywhere; nothing in Ferret depends on WebGPU. There is no mouse or Pointer Lock on the console, so games bind **actions**, and the engine maps devices to them.

## How the pieces depend on each other

Dependencies point one way. A game takes only what it needs; a single-player game never loads `net`.

```
core, platform
   ← assets, physics, input
      ← character, animation, ai
         ← transform, interaction, zones
            ← levels, ui, media, net
```

The physics capabilities sit on top of `physics` and are independent of each other. Where one capability's output is another's input, a small link in `physics-links` moves it, so no capability knows about the others.

## Where to read next

New here: [Getting started](getting-started.md), then The world (skill `ferret`). An overview to show others: the presentation (skill `ferret`) ([PDF](media/ferret-presentation.pdf)). Looking for something specific: the **API reference** lists every export of every package with its signature, and `/` searches guides and API together.