> 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-ko/communications/archipelago.md).

# 아키펠라고

Archipelago는 인근 플레이어들을 섬으로 묶고, 이동에 따라 다시 배정하며, 실제 백엔드에 연결하는 데 필요한 정보를 제공하여 그들의 메시지를 중계하는 영역 서비스입니다.

{% hint style="info" %}
Archipelago 프로토콜이 실제로 동작하는 모습을 보고 오픈 소스로 실험해 볼 수 있습니다 [Comms Station](https://decentraland.github.io/comms-station/).
{% endhint %}

서비스를 사용하려면, 클라이언트는 해당 영역의 Archipelago 웹소켓 엔드포인트에 연결하고 세션을 시작하기 위해 인증해야 합니다. 그런 다음 위치 업데이트를 전송하고 섬 할당을 받을 수 있습니다(참조: [클라이언트 수명 주기](https://github.com/decentraland/docs/tree/main/contributor/communications/overview/README.md#lifecycle)).

Archipelago 서비스와 주고받는 모든 메시지는 Decentraland [프로토콜 저장소에 정의된 대로](https://github.com/decentraland/protocol).

### 연결 <a href="#connecting" id="connecting"></a>

시작하려면, 클라이언트는 보안 웹소켓 연결(`wss:`)을 `/archipelago/ws` 영역의 엔드포인트로 열어야 합니다.

연결되면, 클라이언트는 영역 정책에 의해 정의된 시간 창(기본값으로 60초) 내에 각 메시지를 보내기 위한 [인증](#authenticating) 흐름의

{% hint style="warning" %}
더 큰 영역은 Archipelago 서비스를 실행하지만, 더 작은 영역은 모든 플레이어에게 고정된 백엔드 연결 문자열을 제공하도록 선택할 수 있습니다. URI가 있다면, 다음에서 찾을 수 있습니다. `comms.fixedAdapter` 영역의 `/about`.
{% endhint %}

이러한 경우 동적 섬 할당은 사용할 수 없으며, 해당 목적에는 영역의 RPC 인터페이스를 사용해서는 안 됩니다.

### 인증 중 <a href="#authenticating" id="authenticating"></a>

Archipelago에 연결을 연 후, 클라이언트는 먼저 서비스로부터 도전 과제를 요청하고 서명하여 자신의 신원을 검증해야 합니다.

클라이언트가 처음 보내는 메시지는 [`ChallengeRequestMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeRequestMessage/README.md) 이며, 자신의 이더리움 주소(즉, 공개 키)를 포함합니다. 그러면 [`ChallengeResponseMessage`](https://github.com/decentraland/docs/tree/main/contributor/communications/ChallengeResponseMessage/README.md) 를 받게 되며, 무작위로 생성된 서명 문자열을 포함합니다. 그리고 다음으로 응답해야 합니다. [`SignedChallengeMessage`](#SignedChallengeMessage).

그 [`SignedChallengeMessage`](#SignedChallengeMessage) JSON으로 직렬화된 [인증 체인](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) 을 담고 있으며, 제공된 주소로 시작해 도전 과제 서명으로 끝납니다.

서비스가 서명을 성공적으로 검증하면, 클라이언트는 인증되며 다음을 받게 됩니다. [`WelcomeMessage`](#WelcomeMessage).

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

### 하트비트 전송 <a href="#heartbeat" id="heartbeat"></a>

세션 동안, 클라이언트는 주기적으로 [`Heartbeat`](#Heartbeat) 메시지를 보내 Archipelago가 섬 할당을 발급하는 데 필요한 정보로 최신 상태를 유지하도록 해야 합니다.

{% hint style="info" %}
comms 클라이언트에 권장되는 하트비트 빈도는 대략 초당 한 번입니다.
{% endhint %}

클라이언트가 [`Heartbeat`](#Heartbeat) 메시지 전송을 중단하면, Archipelago는(현재 정책에 따라) 연결을 종료할 수 있습니다.

### 섬 할당 받기 <a href="#assignment" id="assignment"></a>

첫 하트비트 직후, Archipelago는 클라이언트에게 첫 번째 [`IslandChangedMessage`](https://github.com/decentraland/protocol/blob/9a568b16b2eafb134177329ba670c1451be8a169/proto/decentraland/kernel/comms/v3/archipelago.proto#L17).

주요 필드는 `conn_str`이며, 이를 사용해 전송을 초기화하고 섬에 연결할 수 있습니다. 값은 일반적으로 다음과 같습니다:

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

첫 번째 `:` 앞의 레이블은 전송 유형이며, 나머지는 이를 위한 특수 URI입니다. 사전 승인된 토큰이나 기타 매개변수를 포함할 수 있습니다.

세션 동안 Archipelago는 여러 이유로 언제든지 새 할당을 보낼 수 있습니다.

1. 위치 변경: 클라이언트가 섬 내 다른 이들로부터 멀어졌다고 보고함.
2. 섬 요청: 클라이언트가 특정 섬에 할당되기를 요청함.
3. Archipelago 정책: 서비스가 인구를 더 잘 균형 맞추기 위해 섬을 만들거나 분할하기로 결정함.

클라이언트는 이러한 할당을 수신하도록 대기하며, 지시에 따라 전송 연결을 닫고 열고, 필요할 때 사용하는 전송 유형을 변경해야 합니다.

### 클라이언트 메시지

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

세션의 첫 번째 메시지로 클라이언트가 보내며, 인증 흐름을 시작합니다.

| 필드        | 타입       | 값           |
| --------- | -------- | ----------- |
| `address` | `string` | 사용자의 주소입니다. |

그 `address` 필드는 [인증 체인](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) 제공될 첫 번째 개인 키에서 파생되어야 합니다.

***

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

다음을 수신한 후 클라이언트가 보내며, [`ChallengeResponseMessage`](#ChallengeResponseMessage)인증 흐름을 완료합니다.

| 필드                | 타입       | 값                                                                                                                         |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `auth_chain_json` | `string` | JSON으로 직렬화된 [인증 체인](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) 도전 과제 서명으로 끝납니다. |

의 첫 번째 키는 [인증 체인](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) 원래 보낸 주소와 일치해야 합니다. [`ChallengeRequestMessage`](#ChallengeRequestMessage).

***

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

클라이언트가 정기 간격(일반적으로 초당 한 번)으로 보내며, 자신의 위치를 Archipelago에 업데이트하고/하거나 섬 할당을 요청합니다.

| 필드             | 타입         | 값                       |
| -------------- | ---------- | ----------------------- |
| `position`     | `Position` | 세계 지도에서 클라이언트의 3D 위치    |
| `desired_room` | `string?`  | 클라이언트가 할당받고 싶어 하는 섬의 ID |

첫 번째 `Heartbeat` 클라이언트가 보내는 메시지는 곧바로 [`IslandChangedMessage`](#IslandChangedMessage) Archipelago의 응답이 이어집니다. 그러나 이후의 업데이트는 섬 할당과 무관합니다. 클라이언트는 다음을 기대해서는 안 됩니다. `Heartbeat` 응답되기를

해당 `desired_room` 매개변수가 포함되면, 서비스는 요청을 수용하려 시도하겠지만, 해당 섬으로의 재할당이 보장되지는 않습니다. 이는 Archipelago의 정책(예: 섬 인구 제한)에 따라 달라집니다.

### 서버 메시지

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

다음에 대한 응답으로 Archipelago가 보냄 [`ChallengeRequestMessage`](#ChallengeRequestMessage)

| 필드                  | 타입       | 값                                                                                                 |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `challenge_to_sign` | `string` | 서명하고 [인증 체인](https://github.com/decentraland/docs/tree/main/contributor/auth/authchain/README.md) |
| `already_connected` | `bool`   | 이 사용자의 키에 대한 기존 연결이                                                                               |

***

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

성공적인 인증 후 Archipelago가 보냅니다.

| 필드        | 타입       | 값                              |
| --------- | -------- | ------------------------------ |
| `peer_id` | `string` | 인증된 클라이언트의 고유 식별자(일반적으로 해당 주소) |

***

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

클라이언트가 섬에 (재)할당될 때 Archipelago가 보냅니다.

설명.

| 필드               | 타입                      | 값                                                                                                               |
| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| `island_id`      | `string`                | 새 섬의 ID                                                                                                         |
| `from_island_id` | `string?`               | 이전 섬의 ID, 재할당인 경우                                                                                               |
| `conn_str`       | `string`                | 섬의 연결 문자열 [전송](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md). |
| `peers`          | `map<string, Position>` | 설명.                                                                                                             |

다음을 받는 클라이언트는 `IslandChangedMessage` 해야 하며, 섬 백엔드에 대한 연결을 종료하고, 다음에 주어진 것으로 연결해야 합니다. `conn_str`.

그 `peers` 필드에는 섬의 모든 피어의 현재 신원과 위치가 포함되어 있어, 클라이언트가 초기 집합을 채울 수 있습니다. 이 시점 이후에는 섬 [전송](https://github.com/decentraland/docs/tree/main/contributor/communications/transports/README.md) 를 통해 수신한 메시지에 의존하여 위치 업데이트를 받아야 합니다.

***

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

연결을 닫기 전에 Archipelago가 보냄.

| 필드       | 타입             | 값                      |
| -------- | -------------- | ---------------------- |
| `reason` | `KickedReason` | 연결을 닫는 Archipelago의 사유 |

다음의 표준 값은 `reason` 필드는 다음과 같습니다:

* `KR_NEW_SESSION`: 다른 연결이 동일한 키로 인증되었습니다.

***

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

피어가 클라이언트의 섬에 할당될 때 Archipelago가 보냅니다.

| 필드          | 타입       | 값                       |
| ----------- | -------- | ----------------------- |
| `island_id` | `string` | 섬의 식별자                  |
| `peer_id`   | `string` | 피어의 고유 식별자(일반적으로 해당 주소) |

그 `island_id` 필드는 클라이언트의 현재 할당과 일치합니다.

***

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

피어가 클라이언트의 섬에서 제거될 때 Archipelago가 보냅니다.

| 필드          | 타입       | 값                       |
| ----------- | -------- | ----------------------- |
| `island_id` | `string` | 섬의 식별자                  |
| `peer_id`   | `string` | 피어의 고유 식별자(일반적으로 해당 주소) |

그 `island_id` 필드는 클라이언트의 현재 할당과 일치합니다.


---

# 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-ko/communications/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.