> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/communications/overview.md).
# Overview
The Decentraland communications system, or simply *comms*, is the real-time messaging protocol that handles interaction between players in a realm.
Some of these interactions are initiated by players, others are automatically handled by clients under the hood. Some examples:
* Text and voice chat
* Position updates as players move around
* Avatar updates when players change their appearance
{% hint style="info" %}
You can see the comms protocol in action and experiment with it using the open-source [Comms Station](https://decentraland.github.io/comms-station/).
{% endhint %}
Since most of this functionality requires broadcasting messages to all nearby players, they are automatically grouped into proximity-based clusters named *islands*. Each player is assigned to a single island at a time, which changes as they travel the world and move relative to others.
The realm service that manages and assigns players to islands is called *Archipelago*. It takes care of creating islands as they are needed, keeping their population at a reasonable number and dynamically reassigning players in response to their movements.
```mermaid
flowchart LR
subgraph Realm
Players["Players
⭐⭐⭐⭐⭐⭐⭐⭐⭐"]
Archipelago["Archipelago"]
subgraph Islands
Island1["Island 1
⭐⭐⭐⭐"]
Island2["Island 2
⭐⭐⚪⚪"]
IslandN["Island n
⭐⭐⭐⚪"]
end
Players --> Archipelago
Archipelago --> Island1
Archipelago --> Island2
Archipelago --> IslandN
end
```
When assigned to an island, clients are given an island-specific URI to connect to the actual backend that will relay messages between them. This connection lasts until Archipelago reassigns the client to a different island.
This means that, in addition to the [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) protocol, clients must implement a number of *transports*, each wrapping one of the supported backends in a unified interface.
### Client Life-cycle
The life-cycle of a comms client can be summarized in a few steps:
1. **Select a realm**: obtain a URI for the [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) service.
2. **Join Archipelago**: open a persistent connection with the service.
3. **Get an island (re)assignment**: report the current position and obtain an island-specific URI.
4. **Connect a transport**: open a second connection to the island-specific backend.
5. **Repeat**: continue going through steps 3 and 4, periodically reporting new positions.
When the client ends their session, they simply disconnect from the Archipelago service. They will be automatically removed from their current island.
```mermaid
sequenceDiagram
participant Archipelago
participant Client
participant IslandBackend as Island Backend
Note over Client: Connect to Archipelago
Client->>Archipelago: Authenticate
Archipelago->>Client: Accept
Note over Client: Report position
Client->>Archipelago: Report position
Archipelago->>Client: Assign island
Note over Client: Connect to island
Client->>IslandBackend: Connect transport
Client->>IslandBackend: Authenticate
IslandBackend->>Client: Accept
Note over Client,IslandBackend: Exchange messages
Client->>IslandBackend: Player messages…
IslandBackend->>Client: Player messages…
Note over Client: Update position
Client->>Archipelago: Update position
Archipelago->>Client: Reassign island
Note over Client: Disconnect from old island
Client->>IslandBackend: Disconnect transport
Note over Archipelago,IslandBackend: Repeat cycle
```
### Connections
Comms connections are mainly websocket-based, although some transports may use other strategies.
Go to the [Transports](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md) or [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) sections to learn more, or a specific transport page for details about it.
### Authentication
Connections to comms are authenticated by having clients sign a server-provided challenge, using the scheme described in the [authentication chain](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) section.
Head over to the [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) page or see a specific transport to learn more about authentication flows.
### Islands
Islands are highly dynamic groups of players that can broadcast messages among themselves, created and maintained by [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) in response to their movements in the world.
There is no predefined area or central point for an island. They are not stable geographical features, only temporary associations of nearby players. If an island can be said to cover a region, it's only because its members are currently spread in that zone.
There can be zero islands in a region without players, and several overlapping islands in densly populated areas, where assigning everyone to the same group would make real-time broadcasting impossible.
Each server in the Decentraland network can configure the maximum island population and the distance at which players are considered to be nearby. By default, islands can host up to 100 players within 100 meters of each other.
The flow for getting assigned to an island and joining it is detailed in the [Archipelago](https://github.com/decentraland/docs/tree/main/contributor/communications/archipelago/README.md) section.
### Messages
Messages in the comms protocol are binary blobs serialized using [protocol buffers](https://github.com/protocolbuffers/protobuf), wrapped in a [Packet](https://github.com/decentraland/docs/tree/main/contributor/communications/messages/README.md#Packet) structure.
{% hint style="info" %}
When using the word *message* in the context of comms, we'll always be referring to the binary message protocol, not to chat messages exchanged between players.
{% endhint %}
There are several different message types, for a variety of real-time interaction flows. Head over to the [messages](https://github.com/decentraland/docs/tree/main/contributor/communications/messages/README.md) section to learn more.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.decentraland.org/contributor/communications/overview.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.