---
name: ferret-world
description: Use when writing Ferret game logic: the World, the fixed step, entities, components with onFixedUpdate/onUpdate, services, the event bus, the component registry and logging. Also for slow motion, pausing and deterministic tests.
---

# The world: entities, components, services

## When to use
Writing a component, a service, reacting to engine events, or driving a world in a test.

## The model in short
- `World` owns the scene, the clock and everything in it. Simulation runs at a **fixed rate** (60 Hz); `world.advance(realDt)` runs as many fixed steps as fit, frame time is capped (`maxFrame`).
- `Entity` wraps a Babylon `TransformNode` and carries components. `Component` has `onAttach`, `onStart`, `onFixedUpdate(dt)`, `onUpdate(dt)`, `onDetach`.
- `Service` is a world-wide singleton (`world.addService`, `world.service(name)`): input, levels, zones, physics, UI.
- `world.events` is a synchronous bus: `on`, `once`, `off`, `emit`.
- `world.components` / `world.behaviours` are `Registry`s: a level manifest names a class and gives plain `params`.

## Steps for a new component
1. Extend `Component<Params>`; keep `params` plain data so a manifest can set it.
2. Put game logic in `onFixedUpdate`, presentation in `onUpdate`.
3. Register once: `world.components.register('Name', Class)` (see the API reference for the exact call).
4. Find things with `entity.get(Cls)`, `require(Cls)`, `findByName`, `findByTag`, `entitiesWith`.

## Time controls
`timeScale` (slow motion), `paused`, `time`, `tickCount`, `alpha` (interpolation), `entity.timeDilation` (slow NPCs only).

## Check afterwards
Test without a renderer: drive the world with `world.step()` or `world.run(seconds)`; the same inputs must give the same result.

## What usually goes wrong
- Game logic in `onUpdate`: it runs per rendered frame, so results depend on frame rate.
- Component params holding class instances: a manifest cannot express them.
- Holding an entity reference across a level change: the level's entities are removed on unload.
- Registering a component class twice.

## Files

- `reference/world.md` — World, the fixed step, entities and components, services, the event bus and registries.
- `reference/api-core.md` — every export of `@ferret/core` with signature and doc comment
- `reference/commands.md` — 7 commands of these packages with their arguments