Room Lifecycle
Create
A room is created via the CreateRoom API endpoint. The endpoint requires a region parameter to specify where the room should be created, and responds with a roomId.
A room should generally be created when your players request a match. Note that the CreateRoom endpoint is an admin endpoint, meaning it can only be called via a developer token, and thus can't be invoked directly by a client. Instead, the CreateRoom call typically happens within the context of a lobby or matchmaking service backend.
When CreateRoom is called, Hathora will either schedule a room in an existing process if it has capacitiy, or will spin up a new process for the room.
The time it takes to spin up a new process depends on your container size and server startup speed but should generally be quick. A process is considered started once it binds to the port specified in your deployment configuration. The process must bind to the port within 100 seconds, otherwise it will be terminated.
Connect
The GetConnectionInfo endpoint takes a roomId and returns the transportType, host, and port that should be used for connecting.
A process will be in an "idle" state if there are no active connections to the room. After a process is in "idle" state for 5 minutes, we automatically terminate the process to help reduce your costs.
Destroy
A room is destroyed via the DestroyRoom endpoint, which simply takes the roomId as a parameter.
A room should be destroyed when the match/session is complete. By destroying a room you free up space in the process for other rooms. Hathora automatically destroys all rooms in a process when a container exits cleanly (with exit code 0).