Docs / Best practices

Best practices

Cross-cutting advice that shows up across the guides, in one place. Each links to the guide that covers it in depth.

Keep the server authoritative

Treat every client message as untrusted. Validate and apply input in your Lua match logic; compute outcomes server-side and broadcast state, rather than trusting a client's claimed position or score. The client renders; the server decides.

Guard secrets, persist tokens

Keep peppers and keys out of source and out of Lua bundles - inject them as configuration via env or a secret manager. On the client, persist the refresh token and the guest device_secret in secure storage, and handle auth_expired by re-authenticating and reconnecting (see Authentication).

Deploy with hot reload

Ship new Lua without disconnecting players: in-flight matches finish on the old code, new matches pick up the new code. Lean on it for a tight loop locally (asobi dev) and in production (hot-reload tutorial). Keep bundles side-effect-safe so a reload mid-match is boring.

Shard at the app level

Asobi is single-node by design. Scale by running more nodes and partitioning work - game-per-node, region-per-node - not by clustering a single match across hosts. Clustering and Performance cover the sizing.

Fail closed, rate-limit early

Lean on the built-in per-IP and global limiters, and design new endpoints to deny by default when a control is absent - the way guest auth stays off unless both the game and the operator opt in. The security section documents the threat model and the limits Asobi does and doesn't cover.

Test against the real protocol

For clients and integrations, run the canonical test harness in CI so protocol drift breaks one test in one place, not silently in production.