> 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 Archipelago는 인근 플레이어들을 섬으로 묶고, 이동에 따라 재할당하며, 메시지를 중계할 실제 백엔드에 연결하는 데 필요한 정보를 제공하는 레름 서비스입니다. {% hint style="info" %} 오픈 소스를 사용해 Archipelago 프로토콜이 실제로 동작하는 모습을 보고 직접 실험해 볼 수 있습니다 [Comms Station](https://decentraland.github.io/comms-station/). {% endhint %} 이 서비스를 사용하려면 클라이언트는 자신의 레름의 Archipelago 웹소켓 엔드포인트에 연결하고 인증하여 세션을 시작해야 합니다. 그런 다음 위치 업데이트를 보내고 섬 할당을 받기 시작할 수 있습니다(참조: [클라이언트 라이프사이클](https://github.com/decentraland/docs/blob/main/contributor/communications/overview/README.md#lifecycle)). Archipelago 서비스와 주고받는 모든 메시지는 Decentraland에서 정의한 대로 프로토콜 버퍼를 사용해 인코딩됩니다 [프로토콜 저장소](https://github.com/decentraland/protocol). ### 연결 시작하려면 클라이언트는 보안 웹소켓 연결(`wss:`)을 `/archipelago/ws` 레름의 엔드포인트로 열어야 합니다. 연결되면 클라이언트는 레름 정책에 의해 정의된 시간 창(기본값 60초) 동안 다음의 각 메시지를 보낼 수 있습니다: [인증](#authenticating) 흐름. {% hint style="warning" %} 더 큰 레름들은 Archipelago 서비스를 실행하지만, 더 작은 레름들은 모든 플레이어에게 고정된 백엔드 연결 문자열을 제공하도록 선택할 수 있습니다. URI가 있다면 다음에서 찾을 수 있습니다: `comms.fixedAdapter` 레름의 `/about`. {% endhint %} 이 경우 동적 섬 할당은 사용할 수 없으며, 그 목적을 위해 레름의 RPC 인터페이스를 사용해서는 안 됩니다. ### 인증 Archipelago에 연결을 연 후, 클라이언트는 자신의 신원을 확인하기 위해 먼저 서비스에 챌린지를 요청하고 서명해야 합니다. 클라이언트가 보내는 첫 번째 메시지는 [`ChallengeRequestMessage`](https://github.com/decentraland/docs/blob/main/contributor/communications/ChallengeRequestMessage/README.md) 자신의 이더리움 주소(즉, 공개 키)를 사용한 것입니다. 그러면 다음을 받게 됩니다: [`ChallengeResponseMessage`](https://github.com/decentraland/docs/blob/main/contributor/communications/ChallengeResponseMessage/README.md) 서명할 무작위로 생성된 문자열이 포함되며, 이에 대해 다음으로 응답해야 합니다: [`SignedChallengeMessage`](#SignedChallengeMessage). 이 [`SignedChallengeMessage`](#SignedChallengeMessage) JSON 직렬화된 [인증 체인](https://github.com/decentraland/docs/blob/main/contributor/auth/authchain/README.md) 으로, 제공된 주소로 시작해 챌린지 서명으로 끝납니다. 서명이 서비스에 의해 성공적으로 검증되면, 클라이언트는 인증되고 다음을 받게 됩니다: [`WelcomeMessage`](#WelcomeMessage). {% @mermaid/diagram content="sequenceDiagram participant Client participant Archipelago ``` Note over Client,Archipelago: Connect Client->>Archipelago: ChallengeRequestMessage Archipelago->>Client: ChallengeResponseMessage Client->>Archipelago: SignedChallengeMessage Archipelago->>Client: WelcomeMessage" %} ``` ### 하트비트 전송 세션 동안 클라이언트는 주기적으로 다음을 보내야 합니다: [`Heartbeat`](#Heartbeat) 메시지를 보내어 Archipelago가 섬 할당을 발급하는 데 필요한 정보로 최신 상태를 유지하도록 해야 합니다. {% hint style="info" %} comms 클라이언트에 권장되는 하트비트 주기는 대략 초당 한 번의 업데이트입니다. {% endhint %} 클라이언트가 다음 전송을 중지하면 [`Heartbeat`](#Heartbeat) 메시지를 보내지 않으면, Archipelago는(현재 정책에 따라) 연결을 닫을 수 있습니다. ### 섬 할당 받기 첫 번째 하트비트 직후, 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/blob/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/blob/main/contributor/auth/authchain/README.md) 챌린지 서명으로 끝납니다. | 의 첫 번째 키는 [인증 체인](https://github.com/decentraland/docs/blob/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` | `위치` | 월드 맵에서 클라이언트의 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/blob/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/blob/main/contributor/communications/transports/README.md). | | `peers` | `map` | 설명. | 다음을 받는 클라이언트는 `IslandChangedMessage` 섬 백엔드와의 연결을 종료하고, 다음에 제시된 연결로 연결해야 합니다: `conn_str`. 이 `peers` 필드에는 섬 내 모든 피어의 현재 식별자와 위치가 포함되어 있어, 클라이언트가 초기 집합을 채울 수 있습니다. 이 시점 이후에는 섬을 통해 수신한 메시지에 의존해야 합니다 [전송](https://github.com/decentraland/docs/blob/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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/contributor/contributor-ko/communications/archipelago.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.