Net, gateways, voice, accounts

Skill ferret-net-accounts · download all skills · SKILL.md

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