> 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-es/comunicaciones/archipelago.md).

# Archipelago

Archipelago es el servicio de realm que agrupa a los jugadores cercanos en islas, reasignándolos a medida que se mueven y proporcionando la información necesaria para conectarse al backend real que retransmitirá sus mensajes.

{% hint style="info" %}
Puedes ver el protocolo de Archipelago en acción y experimentarlo usando el código abierto [Comms Station](https://decentraland.github.io/comms-station/).
{% endhint %}

Para usar el servicio, los clientes deben conectarse al endpoint websocket de Archipelago de su realm y autenticarse para comenzar su sesión. Luego pueden empezar a enviar actualizaciones de posición y a recibir asignaciones de islas (consulta el [ciclo de vida del cliente](https://github.com/decentraland/docs/tree/main/contributor/communications/overview/README.md#lifecycle)).

Todos los mensajes intercambiados con el servicio de Archipelago se codifican usando protocol buffers, tal como se define en el Decentraland [repositorio de protocolos](https://github.com/decentraland/protocol).

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

Para comenzar, los clientes deben abrir una conexión websocket segura (`wss:`) al `/archipelago/ws` endpoint del realm.

Una vez conectados, los clientes tienen una ventana de tiempo definida por la política del realm (60 segundos, por defecto) para enviar cada mensaje del [autenticación](#authenticating) flujo.

{% hint style="warning" %}
Aunque los realms más grandes ejecutan el servicio de Archipelago, los más pequeños pueden optar por proporcionar una cadena de conexión fija al backend para todos los jugadores. La URI, si está presente, se puede encontrar en la `comms.fixedAdapter` propiedad del realm's `/about`.
{% endhint %}

En estos casos, la asignación dinámica de islas no estará disponible, y no se debe usar la interfaz RPC del realm para ese propósito.

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

Después de abrir una conexión con Archipelago, los clientes deben comenzar solicitando y firmando un desafío del servicio para verificar su identidad.

El primer mensaje que envía un cliente es un [`ChallengeRequestMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeRequestMessage/README.md) con su dirección de Ethereum (es decir, su clave pública). Recibirán un [`ChallengeResponseMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeResponseMessage/README.md) con una cadena generada aleatoriamente para firmar, y deben responder con un [`SignedChallengeMessage`](#SignedChallengeMessage).

El [`SignedChallengeMessage`](#SignedChallengeMessage) lleva una [cadena de autenticación](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) que comienza con la dirección proporcionada y termina con la firma del desafío.

Si la firma se verifica correctamente por el servicio, el cliente queda autenticado y recibirá un [`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 su sesión, los clientes deben enviar periódicamente un [`Heartbeat`](#Heartbeat) mensaje para mantener a Archipelago actualizado con la información necesaria para emitir asignaciones de islas.

{% hint style="info" %}
La frecuencia de Heartbeat recomendada para los clientes de comms es de aproximadamente una actualización por segundo.
{% endhint %}

Si un cliente deja de enviar [`Heartbeat`](#Heartbeat) mensajes, Archipelago (dependiendo de su política actual) puede cerrar la conexión.

### Obteniendo asignaciones de islas <a href="#assignment" id="assignment"></a>

Poco después del primer Heartbeat, Archipelago enviará al cliente su primer [`IslandChangedMessage`](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L17).

El campo principal es `conn_str`, que se puede usar para inicializar un transporte y conectarse a la isla. Los valores suelen verse así:

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

La etiqueta antes del primer `:` es el tipo de transporte; el resto es una URI especializada para él. Puede incluir tokens preautorizados u otros parámetros.

Durante la sesión, Archipelago puede enviar una nueva asignación en cualquier momento, por varias razones:

1. Cambios de posición: el cliente informó que se alejó de otros en la isla.
2. Solicitudes de isla: el cliente solicitó ser asignado a una isla específica.
3. Política de Archipelago: el servicio decidió crear o dividir islas para equilibrar mejor la población.

Los clientes deben escuchar estas asignaciones, cerrando y abriendo conexiones de transporte según se indique, y cambiando el tipo de transporte en uso cuando sea necesario.

### Mensajes del cliente

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

Enviado por el cliente como el primer mensaje de una sesión, para iniciar el flujo de autenticación.

| Campo     | Tipo     | Valor                     |
| --------- | -------- | ------------------------- |
| `address` | `string` | La dirección del usuario. |

El `address` field debe derivarse de la primera clave privada de la [cadena de autenticación](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) que se presentará.

***

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

Enviado por el cliente después de recibir un [`ChallengeResponseMessage`](#ChallengeResponseMessage), para completar el flujo de autenticación.

| Campo             | Tipo     | Valor                                                                                                                                                                          |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auth_chain_json` | `string` | Una serialización JSON de [cadena de autenticación](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) que termina con la firma del desafío. |

La primera clave en la [cadena de autenticación](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) debe corresponder a la dirección enviada en el original [`ChallengeRequestMessage`](#ChallengeRequestMessage).

***

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

Enviado por el cliente a intervalos regulares (normalmente una vez por segundo), para informar a Archipelago sobre su posición y/o solicitar una asignación de isla.

| Campo          | Tipo       | Valor                                                          |
| -------------- | ---------- | -------------------------------------------------------------- |
| `position`     | `Position` | La posición 3D del cliente en el mapa del mundo                |
| `desired_room` | `string?`  | El ID de una isla a la que al cliente le gustaría ser asignado |

El primer `Heartbeat` mensaje que envía un cliente va seguido rápidamente por un [`IslandChangedMessage`](#IslandChangedMessage) de Archipelago. Las actualizaciones posteriores, sin embargo, son independientes de las asignaciones de islas. Los clientes no deberían esperar una `Heartbeat` respuesta.

Cuando el `desired_room` parámetro está incluido, el servicio intentará atender la solicitud, pero no se garantiza una reasignación a esa isla. Depende de la política de Archipelago (por ejemplo, límites en la población de la isla).

### Mensajes del servidor

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

Enviado por Archipelago en respuesta a un [`ChallengeRequestMessage`](#ChallengeRequestMessage)

| Campo               | Tipo     | Valor                                                                                                                                                     |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `challenge_to_sign` | `string` | Una cadena generada para firmar y crear un [cadena de autenticación](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) |
| `already_connected` | `bool`   | Si una conexión existente para la clave de este usuario                                                                                                   |

***

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

Enviado por Archipelago después de una autenticación exitosa.

| Campo     | Tipo     | Valor                                                                         |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `peer_id` | `string` | Un identificador único para el cliente autenticado (normalmente su dirección) |

***

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

Enviado por Archipelago cuando el cliente es (re)asignado a una isla.

Descripción.

| Campo            | Tipo                    | Valor                                                                                                                                            |
| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `island_id`      | `string`                | El ID de la nueva isla                                                                                                                           |
| `from_island_id` | `string?`               | El ID de la isla anterior, si se trata de una reasignación                                                                                       |
| `conn_str`       | `string`                | La cadena de conexión para la isla [transporte](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md). |
| `peers`          | `map<string, Position>` | Descripción.                                                                                                                                     |

Los clientes que reciben un `IslandChangedMessage` deben finalizar su conexión con el backend de la isla y conectarse al indicado en `conn_str`.

El `peers` El campo contiene las identidades y posiciones actuales de todos los peers en la isla, de modo que los clientes puedan poblar su conjunto inicial. A partir de ese momento, deben confiar en los mensajes recibidos a través de la isla [transporte](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md) para obtener actualizaciones de posición.

***

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

Enviado por Archipelago antes de cerrar una conexión.

| Campo    | Tipo           | Valor                                            |
| -------- | -------------- | ------------------------------------------------ |
| `reason` | `KickedReason` | El motivo de Archipelago para cerrar la conexión |

Los valores estándar para el `reason` campo son:

* `KR_NEW_SESSION`: otra conexión se autenticó con la misma clave.

***

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

Enviado por Archipelago cuando un peer es asignado a la isla del cliente.

| Campo       | Tipo     | Valor                                                      |
| ----------- | -------- | ---------------------------------------------------------- |
| `island_id` | `string` | El identificador de la isla                                |
| `peer_id`   | `string` | El identificador único del peer (normalmente su dirección) |

El `island_id` coincidirá con la asignación actual del cliente.

***

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

Enviado por Archipelago cuando un peer es eliminado de la isla del cliente.

| Campo       | Tipo     | Valor                                                      |
| ----------- | -------- | ---------------------------------------------------------- |
| `island_id` | `string` | El identificador de la isla                                |
| `peer_id`   | `string` | El identificador único del peer (normalmente su dirección) |

El `island_id` coincidirá con la asignación actual del cliente.


---

# 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-es/comunicaciones/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.