> For the complete documentation index, see [llms.txt](https://kinematicsoup.gitbook.io/reactor/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kinematicsoup.gitbook.io/reactor/architecture/connection-process.md).

# Client Connection Process

## Summary

How a Reactor client finds a room, connects, and joins it, from the developer-facing API to the connected state. It is part of the [Reactor Technical Overview](/reactor/architecture.md).

## Starting a Connection

Most projects connect through the **`ksConnect`** component on the room object. It exposes:

* **Connect mode**: `ONLINE` (fetch the public room list from the backend, then connect), `REMOTE` (connect to a host and port you supply), or `LOCAL` (connect to a local server for testing).
* **Protocol**: TCP or Reliable UDP. WebGL builds force WebSockets.
* **Events**: `OnGetRooms`, `OnConnect`, and `OnDisconnect`.

You can also drive the flow in code. `ksConnect.BeginConnect()` starts it, and `room.Connect(authArgs)` connects to a specific room. In `ONLINE` mode the client first calls the backend for a room list (surfaced through `OnGetRooms`), then connects to a chosen `ksRoomInfo`.

> *If no `OnGetRooms` handler is registered, the client connects to the first room in the list. Register a handler when you want to choose the room yourself.*

## Authentication

A client authenticates with optional **authentication arguments** you pass to `Connect`. The server receives them in its `OnAuthenticate` handler, which can accept or reject the join and return custom data.

## Connection Outcomes

The connect result carries a `ConnectStatus`. `SUCCESS` means the client joined. Failures fall into groups:

* **Network**: timeout, refused, reset, aborted, invalid address, unsupported protocol.
* **Authentication**: protocol mismatch, connection limit reached, handler timeout, or a value your server's authentication handler returned.
* **Discovery**: the room list could not be fetched in `ONLINE` mode.

Your `OnConnect` handler receives the status and the authentication result (its code and any data the server returned), so a rejected join can report why.

## Disconnecting and Reconnecting

`room.Disconnect()` closes the connection. A graceful disconnect flushes queued messages first; an immediate disconnect drops the connection at once. Reactor does not reconnect on its own: handle `OnDisconnect`, clean up the old room, and call `Connect` again to retry.

## Where to Go Next

* [The Backend](/reactor/architecture/architecture-backend.md): how the room list comes from the online services.
* [Ownership and Authority](/reactor/architecture/ownership-and-authority.md): what a joined player is allowed to change.
* [Authentication](/reactor/tutorials/authentication.md): sign players in and verify them on join.
* [Running Rooms Locally and Online](/reactor/tutorials/basics.md): connect a first room end to end.