Core concepts
The handful of ideas behind everything in SpawnWeaver.
Project
A registered game. It owns a public key (shipped in your client) and a secret key (server-side). All realtime connections authenticate with the public key.
Player & session
Connecting mints a stable player identity and a reconnect token, so a player keeps the same id across reconnects. A session is one live connection (one WebSocket), visible in the dashboard with its own timeline.
Room
A group of connected players. Players create a room (getting a short code) and others join by code. Members are notified of joins and leaves.
Lobby
A room with developer attributes: a name, visibility (public lobbies are listed), a max-player cap, and metadata. Use lobbies for pre-game waiting rooms and ready checks.
Matchmaking queue
Players enter a queue by game mode + region + match size. When a bucket fills, the server creates a room and notifies the matched players.
Event relay
Send a game event to a room and the server relays it to the other members. Events are fire-and-forget — great for inputs, chat, and actions.
Room state vs entity state
State sync keeps connected players aligned right now:
- Room state — a shared key-value map for the whole room (phase, round, timer). Only the room host may change it.
- Entity state — per-entity key-value state owned by its creator (a player's position, hp). Only the owner may change or delete it.
A player who joins late receives a full snapshot of the current room + entity state, so they don't miss what happened before they arrived.
Persistence vs state sync
These solve different problems:
- State sync is live and in-memory — it disappears when the room ends. Use it for positions, scores, and phases during a session.
- Persistence is durable key-value storage that outlives sessions. Use it for profiles, progression, and inventory between sessions.
Debugging
Every session has a timeline, errors are aggregated with suggested fixes, and the SDK can produce a copyable debug report. See Debug a failed connection.