> 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/contributor-pt/comunicacoes/archipelago.md).

# Archipelago

Archipelago é o serviço de realm que agrupa jogadores próximos em ilhas, reatribuindo-os à medida que se movem e fornecendo as informações necessárias para se conectar ao backend real que retransmitirá suas mensagens.

{% hint style="info" %}
Você pode ver o protocolo Archipelago em ação e experimentá-lo usando o open-source [Comms Station](https://decentraland.github.io/comms-station/).
{% endhint %}

Para usar o serviço, os clients devem se conectar ao endpoint websocket do Archipelago do seu realm e se autenticar para iniciar sua sessão. Depois, podem começar a enviar atualizações de posição e receber atribuições de ilha (veja o [ciclo de vida do client](https://github.com/decentraland/docs/tree/main/contributor/communications/overview/README.md#lifecycle)).

Todas as mensagens trocadas com o serviço Archipelago são codificadas usando protocol buffers, conforme definido no Decentraland [repositório do protocolo](https://github.com/decentraland/protocol).

### Conectando <a href="#connecting" id="connecting"></a>

Para começar, os clients devem abrir uma conexão websocket segura (`wss:`) para o `/archipelago/ws` endpoint do realm.

Uma vez conectados, os clients têm uma janela de tempo definida pela política do realm (60 segundos, por padrão) para enviar cada mensagem do fluxo [de autenticação](#authenticating) .

{% hint style="warning" %}
Enquanto os realms maiores executam o serviço Archipelago, os menores podem optar por fornecer uma string de conexão fixa com o backend para todos os players. A URI, se presente, pode ser encontrada na `comms.fixedAdapter` propriedade do realm's `/about`.
{% endhint %}

Nesses casos, a atribuição dinâmica de ilha não estará disponível, e a interface RPC do realm não deve ser usada para esse fim.

### Autenticando <a href="#authenticating" id="authenticating"></a>

Depois de abrir uma conexão com Archipelago, os clients devem começar solicitando e assinando um desafio do serviço para verificar sua identidade.

A primeira mensagem que um client envia é uma [`ChallengeRequestMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeRequestMessage/README.md) com o endereço Ethereum deles (isto é, sua chave pública). Eles receberão uma [`ChallengeResponseMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeResponseMessage/README.md) com uma string gerada aleatoriamente para assinar e devem responder com uma [`SignedChallengeMessage`](#SignedChallengeMessage).

O [`SignedChallengeMessage`](#SignedChallengeMessage) carrega uma cadeia de autenticação [serializada em JSON](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) que começa com o endereço fornecido e termina com a assinatura do desafio.

Se a assinatura for verificada com sucesso pelo serviço, o client será autenticado e receberá uma [`WelcomeMessage`](#WelcomeMessage).

```mermaid
sequenceDiagram
    participant Client
    participant Archipelago
    
    Note over Client,Archipelago: Conectar
    Client->>Archipelago: ChallengeRequestMessage
    Archipelago->>Client: ChallengeResponseMessage
    Client->>Archipelago: SignedChallengeMessage
    Archipelago->>Client: WelcomeMessage
```

### Enviando Heartbeat <a href="#heartbeat" id="heartbeat"></a>

Durante sua sessão, os clients devem enviar periodicamente uma [`Heartbeat`](#Heartbeat) mensagem para manter Archipelago atualizado com as informações necessárias para emitir atribuições de ilha.

{% hint style="info" %}
A frequência recomendada de Heartbeat para clients de comms é de cerca de uma atualização por segundo.
{% endhint %}

Se um client parar de enviar [`Heartbeat`](#Heartbeat) mensagens, Archipelago (dependendo de sua política atual) poderá encerrar a conexão.

### Obtendo Atribuições de Ilha <a href="#assignment" id="assignment"></a>

Pouco depois do primeiro Heartbeat, Archipelago enviará ao client sua primeira [`IslandChangedMessage`](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L17).

O campo principal é `conn_str`, que pode ser usado para inicializar um transport e conectar-se à ilha. Os valores normalmente se parecem com isto:

```
livekit:wss://comms.example.com?access_token=eyJhbGciOiJI...
```

O rótulo antes do primeiro `:` é o tipo de transport, o restante é uma URI especializada para ele. Ela pode incluir tokens pré-autorizados ou outros parâmetros.

Durante a sessão, Archipelago pode enviar uma nova atribuição a qualquer momento, por vários motivos:

1. Mudanças de posição: o client informou que se afastou dos outros na ilha.
2. Solicitações de ilha: o client solicitou ser atribuído a uma ilha específica.
3. Política do Archipelago: o serviço decidiu criar ou dividir ilhas para equilibrar melhor a população.

Os clients devem ouvir essas atribuições, fechando e abrindo conexões de transport conforme indicado, e alterando o tipo de transport em uso quando necessário.

### Mensagens do client

**`ChallengeRequestMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L54)

Enviada pelo client como a primeira mensagem de uma sessão, para iniciar o fluxo de autenticação.

| Campo     | Tipo     | Valor                  |
| --------- | -------- | ---------------------- |
| `address` | `string` | O endereço do usuário. |

O `address` o campo deve ser derivado da primeira chave privada da [serializada em JSON](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) que será apresentada.

***

**`SignedChallengeMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L58)

Enviada pelo client após receber uma [`ChallengeResponseMessage`](#ChallengeResponseMessage), para concluir o fluxo de autenticação.

| Campo             | Tipo     | Valor                                                                                                                                                                                              |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth_chain_json` | `string` | Uma cadeia de autenticação [serializada em JSON](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) serializada em JSON, terminando com a assinatura do desafio. |

A primeira chave na [serializada em JSON](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) deve corresponder ao endereço enviado na original [`ChallengeRequestMessage`](#ChallengeRequestMessage).

***

**`Heartbeat`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L62)

Enviada pelo client em intervalos regulares (normalmente uma vez por segundo), para atualizar Archipelago sobre sua posição e/ou solicitar uma atribuição de ilha.

| Campo          | Tipo       | Valor                                                      |
| -------------- | ---------- | ---------------------------------------------------------- |
| `position`     | `Position` | A posição 3D do client no mapa do mundo                    |
| `desired_room` | `string?`  | O ID de uma ilha à qual o client gostaria de ser atribuído |

A primeira `Heartbeat` mensagem que um client envia é rapidamente seguida por uma [`IslandChangedMessage`](#IslandChangedMessage) do Archipelago. No entanto, as atualizações subsequentes são independentes das atribuições de ilha. Os clients não devem esperar que uma `Heartbeat` mensagem seja respondida.

Quando o `desired_room` parâmetro é incluído, o serviço tentará atender à solicitação, mas uma reatribuição para essa ilha não é garantida. Isso depende da política do Archipelago (por exemplo, limites de população da ilha).

### Mensagens do Servidor

**`ChallengeResponseMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L8)

Enviada por Archipelago em resposta a uma [`ChallengeRequestMessage`](#ChallengeRequestMessage)

| Campo               | Tipo     | Valor                                                                                                                                                 |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `challenge_to_sign` | `string` | Uma string gerada para assinar e criar uma [serializada em JSON](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) |
| `already_connected` | `bool`   | Se uma conexão existente para a chave deste usuário                                                                                                   |

***

**`WelcomeMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L13)

Enviada por Archipelago após autenticação bem-sucedida.

| Campo     | Tipo     | Valor                                                                           |
| --------- | -------- | ------------------------------------------------------------------------------- |
| `peer_id` | `string` | Um identificador exclusivo para o client autenticado (normalmente seu endereço) |

***

**`IslandChangedMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L17)

Enviada por Archipelago quando o client é (re)atribuído a uma ilha.

Descrição.

| Campo            | Tipo                    | Valor                                                                                                                                         |
| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `island_id`      | `string`                | O ID da nova ilha                                                                                                                             |
| `from_island_id` | `string?`               | O ID da ilha antiga, se esta for uma reatribuição                                                                                             |
| `conn_str`       | `string`                | A string de conexão para a ilha [transporte](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md). |
| `peers`          | `map<string, Position>` | Descrição.                                                                                                                                    |

Os clients que receberem um `IslandChangedMessage` devem encerrar sua conexão com o backend da ilha e conectar-se ao que é fornecido em `conn_str`.

O `peers` o campo contém as identidades e posições atuais de todos os peers na ilha, para que os clients possam preencher seu conjunto inicial. Depois disso, devem confiar nas mensagens recebidas por meio da ilha [transporte](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md) para obter atualizações de posição.

***

**`KickedMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#LL37C1-L38C1)

Enviada por Archipelago antes de encerrar uma conexão.

| Campo    | Tipo           | Valor                                           |
| -------- | -------------- | ----------------------------------------------- |
| `reason` | `KickedReason` | O motivo de Archipelago para encerrar a conexão |

Os valores padrão para o `reason` campo são:

* `KR_NEW_SESSION`: outra conexão foi autenticada com a mesma chave.

***

**`JoinIslandMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L29)

Enviada por Archipelago quando um peer é atribuído à ilha do client.

| Campo       | Tipo     | Valor                                                        |
| ----------- | -------- | ------------------------------------------------------------ |
| `island_id` | `string` | O identificador da ilha                                      |
| `peer_id`   | `string` | O identificador exclusivo do peer (normalmente seu endereço) |

O `island_id` campo corresponderá à atribuição atual do client.

***

**`LeftIslandMessage`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L24)

Enviada por Archipelago quando um peer é removido da ilha do client.

| Campo       | Tipo     | Valor                                                        |
| ----------- | -------- | ------------------------------------------------------------ |
| `island_id` | `string` | O identificador da ilha                                      |
| `peer_id`   | `string` | O identificador exclusivo do peer (normalmente seu endereço) |

O `island_id` campo corresponderá à atribuição atual do client.


---

# 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/contributor-pt/comunicacoes/archipelago.md?ask=<question>&goal=<user_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.