> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ko/docs/sample-projects/unity-netcodes/megacity-metro.md).

# 유니티 ECS 메가시티 메트로

최대 150명의 플레이어를 지원하는 Netcode for Entities 슈팅 게임인 Unity의 Megacity Metro를 Edgegap에서 전용 서버, 매치메이킹, 백필과 함께 호스팅하세요.

다음의 기법을 사용해 Edgegap에서 Unity DOTS 프로젝트를 호스팅하는 방법을 살펴봅니다 [Megacity Metro 샘플](https://github.com/Unity-Technologies/megacity-metro), Netcode for Entities 기반의 모바일 및 데스크톱 슈팅 게임으로, 서버당 최대 150명의 플레이어를 지원합니다.

플레이어는 **매치 찾기**, [Edgegap Matchmaker](https://docs.edgegap.com/ko/learn/matchmaking.md) 가 플레이어 근처에서 전용 서버를 시작하고, 나중에 검색한 플레이어는 실행 중인 서버에 다음 기능으로 합류합니다 [백필](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#backfill-match). 아무도 플레이하지 않으면 서버는 자체 배포를 중지합니다.

이 샘플은 다음을 보여줍니다:

* **Unity 6000.1.0f1** 프로젝트의 **Netcode for Entities** (DOTS) 프로젝트를 Linux 전용 서버로 빌드한 것,
* **직접 연결** 매치메이커 없이 테스트하기 위해 데스크톱 클라이언트에서 배포본으로 연결하는 것,
* **Edgegap Matchmaker** 와의 통합 [Edgegap Unity SDK](https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser) - 클라이언트가 티켓을 큐에 넣고 할당된 서버에 연결합니다,
* **백필** - 실행 중인 서버는 매치메이커에 빈 자리를 유지하므로 새 플레이어는 새 서버를 시작하는 대신 그 서버에 합류하며, 최대 150명까지 가능합니다,
* **서버 자동 중지** - 아무도 참여하지 않거나 모두 떠난 뒤 서버가 자체 배포를 중지합니다.

게임의 넷코드는 변경되지 않았습니다. 매치메이커 URL이 없고, Edgegap 배포 외부에서 실행되며, 직접 연결 대상이 없으면 게임은 업스트림과 동일하게 동작합니다.

{% hint style="info" %}
Windows 데스크톱 클라이언트로 Edgegap에서 검증됨: 서버 배포, 직접 연결, 그리고 백필이 있는 매치메이킹(한 서버에 3명). 모바일 릴리스 빌드는 Connect 옵션을 숨기므로, 휴대폰은 **매치 찾기**.
{% endhint %}

{% hint style="success" %}
참조 [EDGEGAP.md](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro/blob/master/EDGEGAP.md) Edgegap 파일과 서버 설정의 전체 목록은 샘플 저장소의
{% endhint %}

## ✔️ 준비

시작하기 전에 다음이 필요합니다:

* [Unity `6000.1.0f1`](https://unity.com/releases/unity-6) - Unity Hub를 사용해 다운로드하고, 아래 모듈과 클라이언트 플랫폼 모듈(테스트한 클라이언트의 경우 Windows Build Support (IL2CPP))을 포함합니다,
* [Megacity Metro Sample 프로젝트](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro) (Edgegap용으로 수정됨), 다음으로 클론됨 [Git LFS](https://git-lfs.com/) (약 415MB의 LFS 콘텐츠).

<details>

<summary>Unity Linux 빌드 지원 모듈 설치</summary>

* Unity Hub를 사용하여 탭 선택 **설치합니다**, 액세스 **설정** 지역화된 인터넷 서비스 제공업체(ISP)가 일시적으로 사고를 해결하고 있을 수 있습니다, **모듈 추가** Edgegap 플랫폼에서 사용하려는 각 Unity 버전에 대해:

<figure><img src="https://1562312210-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FylRG4r8orenZrw5ijjpJ%2Fimage.png?alt=media&amp;token=fb981825-8a15-4c07-9180-0f79a6a77a91" alt=""><figcaption></figcaption></figure>

* 아래로 스크롤하여 다음 Unity 모듈을 선택하고 설치하세요:
  * **Linux 빌드 지원 (IL2CPP),**
    * **Linux 빌드 지원 (Mono),**
    * **Linux 전용 서버 빌드 지원**

<figure><img src="https://1562312210-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FuXtyqoLhBOk8CZJ4WdzA%2Fimage.png?alt=media&amp;token=19e956ed-a731-420d-b911-130c334794fc" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Docker Desktop(또는 Docker CLI) 설치</a></summary>

* [공식 소스에서 Docker Desktop을 설치하세요](https://www.docker.com/products/docker-desktop/) (계정이 필요하지 않습니다).
* 설치를 완료한 후 컴퓨터를 다시 시작하세요.

</details>

## ⚡ 배포 및 연결

### 1. 빌드 및 푸시

☑️ 시작하려면 다음이 필요합니다. [Edgegap에서 무료 계정을 생성하세요](https://app.edgegap.com/auth/register). 신용카드는 필요하지 않습니다.

☑️ 에디터 플러그인에서 빌드하거나 CLI로 빌드합니다:

{% tabs %}
{% tab title="Unity Servers Quickstart Plugin (권장)" %}
☑️ Tools / Edgegap / Build Linux Dedicated Server를 선택합니다.

☑️ Edgegap Plugin 단계인 Containerize and Upload를 완료합니다.
{% endtab %}

{% tab title="명령줄 인터페이스(에이전트용)" %}
☑️ Unity Editor에서 프로젝트를 닫은 뒤, 프로젝트 루트에서 Linux 전용 서버를 빌드합니다:

{% code collapsedlinecount="10" %}

```bash
Unity -batchmode -quit -buildTarget Linux64 -standaloneBuildSubtarget Server -projectPath . -executeMethod EdgegapServerBuild.Build -logFile build.log
```

{% endcode %}

{% hint style="warning" %}
유지하세요 `-buildTarget Linux64 -standaloneBuildSubtarget Server`, 그렇지 않으면 Entities 콘텐츠 빌드가 다음 오류로 실패합니다 `현재 구성으로 빌드할 수 없습니다`.
{% endhint %}

☑️ 다음 항목을 찾습니다: [컨테이너 레지스트리](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 프로젝트 이름과 자격 증명을 확인한 후 Docker로 로그인합니다:

{% tabs %}
{% tab title="Bash (리눅스)" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell (윈도우)" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

☑️ 이미지를 빌드하고 푸시합니다:

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/megacity-metro:<tag> .
docker push registry.edgegap.com/<project>/megacity-metro:<tag>
```

{% endcode %}
{% endtab %}
{% endtabs %}

빌드가 다음 위치에 저장됩니다 `Builds/EdgegapServer/` (약 3.4GB이며, 대부분 Burst 디버그 정보와 IL2CPP 백업 폴더입니다). 샘플의 `.dockerignore` 제외합니다 `*_BurstDebugInformation_DoNotShip` 및 `*_BackUpThisFolder_ButDontShipItWithYourGame`, 따라서 이미지 크기는 약 537MB입니다.

{% hint style="danger" %}
:x: **금지 - 기존 태그를 덮어쓰거나 다음을 사용하지 마세요. `latest`  태그** - 이렇게 하면 오래된 캐시가 배포됩니다.\
:white\_check\_mark: **권장 - 버전 태그를 항상 올리고** 새 빌드를 배포하세요.
{% endhint %}

서버는 다음 포트를 수신합니다 `0.0.0.0:7979` 를 UDP로. 추가 서버 인수는 다음에 전달하세요 `UNITY_COMMANDLINE_ARGS` 앱 버전의 환경 변수에.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 2. 앱 버전 만들기

☑️ [애플리케이션을 만들고](https://app.edgegap.com/application-management/applications/list) 다음과 같은 버전을 만듭니다:

* 다음의 `registry.edgegap.com/<project>/megacity-metro:<tag>` 이미지,
* 컨테이너 레지스트리 사용자 이름과 토큰을 사용하지 않으면 배포가 이미지를 가져오지 못해 실패합니다,
* 리소스 1 vCPU 및 2GB 메모리(테스트 결과 유휴 서버는 CPU 약 18%와 323MB를 사용했습니다),
* [포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) `7979`, 이름은 `gameport`, 프로토콜 **UDP**.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 3. 직접 연결

매치메이커를 추가하기 전에 서버가 제대로 작동하는지 확인해 봅시다.

☑️ [앱 버전을 배포하세요](https://app.edgegap.com/deployment-management/deployments/list) 플러그인이나 대시보드에서. 서버 로그에는 다음이 표시됩니다 `Edgegap에서 실행 중 ... UGS 세션 건너뛰는 중`.

☑️ [새 배포의 세부 정보를 열고](https://app.edgegap.com/deployment-management/deployments/list) 고유한 일회성 연결 정보를 확인하세요:

* **호스트 URL** 형식 `780aa4260e83.pr.edgegap.net` (또는 IP),
* **외부 포트** 의 `gameport` 형식 `30854` (5자리, 다음이 아님 `7979`).

☑️ 다음 정보로 데스크톱 클라이언트를 시작합니다:

{% code collapsedlinecount="10" %}

```bash
<client executable> -edgegapConnect <host>:<external port>
```

{% endcode %}

또한 다음을 설정할 수도 있습니다 `EDGEGAP_CONNECT=<host>:<external port>` 클라이언트를 실행하기 전에. 직접 연결 대상이 있으면 클라이언트는 Unity Gaming Services(UGS) 로그인을 건너뛰므로 UGS 프로젝트가 필요하지 않습니다. **매치 찾기** 해당 대상에 연결됩니다.

☑️ 찾습니다 `[Edgegap] Connected players: 1` 클라이언트가 합류하면 서버 로그에 표시됩니다.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 4. 매치메이커 만들기

☑️ 다음을 설정합니다 `application.name` 및 `application.version` 샘플의 애플리케이션과 버전에 `matchmaker-config.json`.

설정에는 하나의 `metro` 프로필이 있으며, 2명에서 150명까지의 한 팀을 지원합니다. 두 플레이어가 함께 검색하면 대기열에 들어간 후 약 10초 뒤 서버를 받고, 혼자 검색한 플레이어는 30초 후에 서버를 받습니다. 테스트에는 적합하지만 실제 매치에서는 최소값을 높이세요.

☑️ 다음을 엽니다 [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 페이지에서 클릭합니다 **Matchmaker 만들기**, 업로드한 뒤 `matchmaker-config.json`, 그런 다음 클릭합니다 **만들기 및 시작**.

☑️ 매치메이커의 다음 항목을 복사합니다 **API URL** 및 **인증 토큰** 표시되면 **ONLINE**.

* **무료 클러스터(공유)** 모든 기능을 테스트하고 디자인과의 시너지를 탐색하려면,
  * 3시간 후 자동으로 종료되며 테스트를 계속하려면 재시작이 필요합니다.
* **프라이빗 클러스터** **(전용)** 프로덕션 요구에 맞는 안정적인 환경을 보장하려면,
  * 지역을 선택하고 24시간 연중무휴 라이브 게임 지원을 받아 안심하고 출시하세요.

대시보드에서 매치메이커를 다시 시작해도 API URL과 인증 토큰은 유지됩니다.

✅ 이제 다음 단계로 진행할 수 있습니다.

### 5. 매치 찾기

☑️ API URL과 인증 토큰을 다음 위치에 붙여넣습니다 `Assets/Resources/EdgegapMatchmakerSettings.asset`.

{% hint style="danger" %}
**Edgegap API 엔드포인트를 게임 클라이언트에 통합하지 마세요. API 토큰은 계정에 무제한 액세스를 제공하기 때문입니다. 다음을 참조하세요** [통합](https://docs.edgegap.com/ko/docs/api/integration.md) **안전한 클라이언트용 API 엔드포인트와 기능은**
{% endhint %}

{% hint style="info" %}
매치메이킹 인증 토큰은 해당 매치메이커에만 범위가 지정되므로 게임 클라이언트에 포함해 배포해도 안전합니다.
{% endhint %}

☑️ 서버와 클라이언트를 다시 빌드하세요 - 클라이언트는 이 에셋을 읽어 매치를 찾고, 서버는 이를 읽어 백필을 생성합니다. 새 서버 이미지를 푸시하고 앱 버전과 `matchmaker-config.json` 을 그쪽으로 지정합니다.

실행 시 다음으로 에셋을 재정의할 수 있습니다 `-edgegapMatchmakerUrl`, `-edgegapMatchmakerToken` 및 `-edgegapMatchmakerProfile` (또는 `EDGEGAP_MM_URL`, `EDGEGAP_MM_TOKEN`, `EDGEGAP_MM_PROFILE`).

☑️ 클라이언트 두 개를 시작하고 다음을 클릭합니다 **매치 찾기** 두 클라이언트 모두에서. 상태는 다음에서 `검색 중...` 다음으로 `매치가 발견되어 서버를 시작하는 중...`, 그러면 클라이언트가 연결됩니다.

☑️ 세 번째 클라이언트를 시작하고 다음을 클릭합니다 **매치 찾기** 매치가 실행 중일 때. 백필을 통해 동일한 서버에 합류합니다.

🙌 Edgegap에서 첫 번째 매치메이킹 배포를 축하합니다!

## 🔄 매치 라이프사이클

1. 클라이언트가 다음과 함께 솔로 티켓을 큐에 넣습니다 `metro` 프로필. 그 `backfill_group_size` 속성 값은 `["new", "1"]` - 새로운 매치 또는 실행 중인 서버의 한 자리.
2. 매치메이커가 플레이어 근처에서 배포를 시작하거나, 실행 중인 서버의 백필과 티켓을 매칭합니다.
3. 클라이언트가 서버의 IP와 외부 포트에 연결한 뒤, 티켓 ID를 서버로 전송합니다.
4. 매치메이커 배포에서는 서버가 다음에서 매치를 읽습니다 [`MM_*` 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables) 그리고 매칭된 각 플레이어에게 연결할 60초를 제공합니다. 빈 자리가 있는 동안 최대 3개의 백필을 열어 두며, 해당 플레이어가 떠나거나 아예 오지 않으면 자리를 해제합니다.
5. 서버는 백필을 닫고 다음 조건에서 배포를 중지합니다 `ARBITRIUM_DELETE_URL` - 아무 플레이어도 연결되지 않으면 시작 후 300초 뒤, 또는 마지막 플레이어가 떠난 후 60초 뒤.

앱 버전의 환경 변수로 이러한 제한을 변경할 수 있습니다:

* `EDGEGAP_MAX_PLAYERS` - 서버당 좌석 수(기본값 `150`),
* `EDGEGAP_MAX_OPEN_BACKFILLS` - 동시에 열려 있는 백필 수(기본값 `3`),
* `EDGEGAP_FIRST_PLAYER_TIMEOUT_S` - 아무도 합류하지 않은 서버가 자동 중지되기까지의 시간(초, 기본값 `300`),
* `EDGEGAP_EMPTY_TIMEOUT_S` - 마지막 플레이어가 떠난 뒤 서버가 자동 중지되기까지의 시간(초, 기본값 `60`).

{% hint style="warning" %}
배포가 외부에서 중지되면(대시보드, API 또는 최대 지속 시간), 서버는 백필을 닫지 않고 종료됩니다. **만료될 때까지** (`ticket_expiration_period`, 30초), **그들은 플레이어를 중지된 서버로 보낼 수 있습니다.** 해당 플레이어의 연결은 시간 초과되고, 다음 연결 시도는 **매치 찾기** 작동합니다.
{% endhint %}

참조 [매치메이킹](https://docs.edgegap.com/ko/learn/matchmaking.md), [심층 살펴보기](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md) 및 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md) 자세한 내용을 알아보세요.

## ⚠️ 알려진 문제

* Android 및 iOS 클라이언트는 아직 테스트되지 않았으며, 데스크톱의 창 모드 플레이테스트도 마찬가지입니다.
* 서버는 알 수 없는 티켓 ID의 연결을 로그에 기록하지만, 그래도 입장을 허용합니다(아직 티켓 검증은 없습니다).
* Vivox와 UGS 로그인은 영향을 받지 않습니다. Edgegap Matchmaker와 직접 연결 경로에서는 이를 사용하지 않습니다.
