Skip to main content

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.

note

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).

Suspend

Hathora has a special feature that allows "suspending" rooms instead of destroying them. SuspendRoom deallocates the room from the process it was running on, but allows for re-allocating the room in the future onto a potentially different process. A suspended room is reallocated if GetConnectionInfo is called with its roomId .

This is useful for certain game types, for example asynchronous games, where there could be a period of realtime activity followed by a period of inactivity. By suspending the room when it's not actively being used, you can minimize wasteful spend without losing the ability to reconnect to the room in the future.