---
name: ferret-net-accounts
description: Use for multiplayer and backends in Ferret: NetService with transports (memory, HTTP poll, LiveKit), Replicated fields, remote avatars, Gateways to a game's own backend with safe fallbacks, voice rooms by zone, and AccountService with sign-in.
---

# Net, gateways, voice, accounts

## When to use
Showing other players, calling a game's server, voice by zone, sign-in and balances.

## The model
The game owns its backend; the engine owns the mechanism. A `Transport` moves entity state (`MemoryTransport` for tests, `HttpPollTransport` for a presence server, `LiveKitTransport`). A `Replicated` entity lists `fields` that travel; `bodyField` replicates a physics body (a body at rest sends only its pose); `replicateBreaks` replicates breakage by seed. `Gateways` holds backends behind interfaces (account, dialogue, occupancy, voice); `call(name, fn, fallback)` falls back when the backend is absent or down. Voice rooms follow zones (`LiveKitVoice`, `ZoneVoice`). `AccountService` keeps sign-in, a session and balances; `signInCard` is a ready form.

## Steps
1. Choose a transport; add `NetService`.
2. Mark entities `Replicated` with their fields; remote players appear as avatars from received state.
3. Implement the gateways you need; wrap every backend call in `Gateways.call` with a fallback.
4. Pass the LiveKit client in; the engine does not bundle it.
5. Test with two worlds on one `MemoryHub`.

## Check afterwards
Two headless worlds converge; unplugging the backend does not break the game; leaving a zone leaves its voice room.

## What usually goes wrong
- Calling a backend directly: no fallback when it is down.
- Replicating more fields than needed.
- Forgetting a breaking body needs the owner's seed on the remote copy (`BreakEvent.seed`).
- Secrets in game data: zone names can stay private via `zoneHash`.

## Files

- `reference/net.md` — Replication over pluggable transports, gateways to a game's backend, voice rooms and the player's account.
- `reference/api-net.md` — every export of `@ferret/net` with signature and doc comment
- `reference/api-accounts.md` — every export of `@ferret/accounts` with signature and doc comment