Archipelago is the realm service that groups nearby players into islands, reassigning them as they move around and providing the information required to connect to the actual backend that will relay their messages.

You can see the Archipelago protocol in action and experiment with it using the open-source Comms Station .

To use the service, clients must connect to their realm’s Archipelago websocket endpoint and authenticate to begin their session. They can then start sending positional updates and receiving island assignments (see the client life-cycle ).

All messages exchanged with the Archipelago service are encoded using protocol buffers, as defined in the Decentraland protocol repository .

Connecting #

To begin, clients must open a secure websocket connection (wss:) to the /archipelago/ws endpoint of the realm.

Once connected, clients have a time window defined by realm policy (60 seconds, by default) to send each message of the authentication flow.

Fixed Adapters
!! !!While the larger realms run the Archipelago service, smaller ones may choose to provide a fixed backend connection string for all players. The URI, if present, can be found in the comms.fixedAdapter property of the realm’s /about.!!

In these cases, dynamic island assignment won’t be available, and the realm’s RPC interface should not be used for that purpose.

Authenticating #

After opening a connection to Archipelago, clients must begin by requesting and signing a challenge from the service to verify their identity.

The first message a client sends is a ChallengeRequestMessage with their Ethereum address (i.e. their public key). They will receive a ChallengeResponseMessage with a randomly generated string to sign, and must respond with a SignedChallengeMessage .

The SignedChallengeMessage carries a JSON-serialized authentication chain that begins with the provided address, and ends with the challenge signature.

If the signature is successfully verified by the service, the client is authenticated and will receive a WelcomeMessage .

A r c h i p e C W l h e a a l g l c o l o C e m h n S e a g i M l e g e l R n s e e e s n s d a g p C g e o h e R n a e s l q e l C u M e o e e n n s s g n t s e e M a M c e g e t s e s s s a a g g C e e l i e n t

Sending Heartbeat #

During their session, clients must periodically send a Heartbeat message to keep Archipelago updated with the necessary information to issue island assignments.

The recommended heartbeat frequency for comms clients is about one update per second.

If a client stops sending Heartbeat messages, Archipelago (depending on its current policy) may close the connection.

Getting Island Assignments #

Shortly after the first heartbeat, Archipelago will send the client their first IslandChangedMessage .

The main field is conn_str, which can be used to initialize a transport and connect to the island. Values typically look like this:


The label before the first : is the transport type, the rest is a specialized URI for it. It can include pre-authorized tokens or other parameters.

During the session, Archipelago may send a new assignment at any time, for a number of reasons:

  1. Position changes: the client reported moving away from others in the island.
  2. Island requests: the client requested being assigned to a specific island.
  3. Archipelago policy: the service decided to create or divide islands to better balance the population.

Clients must listen for these assignments, closing and opening transport connections as indicated, and changing the type of transport in use when required.

Client Messages #

ChallengeRequestMessage ↗ source #

Sent by the client as the first message of a session, to start the authentication flow.

Field Type Value
address string The user’s address.

The address field must be derived from the first private key of the authentication chain that will be presented.

SignedChallengeMessage ↗ source #

Sent by the client after receiving a ChallengeResponseMessage , to complete the authentication flow.

Field Type Value
auth_chain_json string A JSON-serialized authentication chain ending with the challenge signature.

The first key in the authentication chain must correspond to the address sent in the original ChallengeRequestMessage .

Heartbeat ↗ source #

Sent by the client at regular intervals (typically once per second), to update Archipelago on their position and/or request an island assignment.

Field Type Value
position Position The client’s 3D position in the world map
desired_room string? The ID of an island the client would like to be assigned to

The first Heartbeat message a client sends is quickly followed by an IslandChangedMessage from Archipelago. Subsequent updates, however, are independent of island assignments. Clients should not expect a Heartbeat to be responded.

When the desired_room parameter is included, the service will attempt to honor the request, but a reassignment to that island is not guaranteed. It depends on Archipelago’s policy (e.g. limits on island population).

Server Messages #

ChallengeResponseMessage ↗ source #

Sent by Archipelago in response to a ChallengeRequestMessage

Field Type Value
challenge_to_sign string A generated string to sign and create an authentication chain
already_connected bool Whether an existing connection for this user’s key

WelcomeMessage ↗ source #

Sent by Archipelago after successful authentication.

Field Type Value
peer_id string A unique identifier for the authenticated client (typically their address)

IslandChangedMessage ↗ source #

Sent by Archipelago when the client is (re)assigned to an island.


Field Type Value
island_id string The ID of the new island
from_island_id string? The ID of the old island, if this is a reassignment
conn_str string The connection string for the island transport .
peers map<string, Position> Description.

Clients that receive an IslandChangedMessage should end their connection to the island backend, and connect to the one given in conn_str.

The peers field contains the current identities and positions of all peers in the island, so that clients can populate their initial set. After this point, they should rely on messages received via the island transport to get positional updates.

KickedMessage ↗ source #

Sent by Archipelago before closing a connection.

Field Type Value
reason KickedReason Archipelago’s reason for closing the connection

The standard values for the reason field are:

  • KR_NEW_SESSION: another connection authenticated with the same key.

JoinIslandMessage ↗ source #

Sent by Archipelago when a peer is assigned to the client’s island.

Field Type Value
island_id string The identifier for the island
peer_id string The unique identifier for the peer (typically their address)

The island_id field will match the client’s current assignment.

LeftIslandMessage ↗ source #

Sent by Archipelago when a peer is removed from the client’s island.

Field Type Value
island_id string The identifier for the island
peer_id string The unique identifier for the peer (typically their address)

The island_id field will match the client’s current assignment.