> 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/photon-fusion-2-simple-fps.md).

# 포톤 퓨전 2 심플 FPS

Edgegap 전용 서버에서 Photon의 Simple FPS 샘플(Photon Fusion 2)을 호스팅하세요. 경기마다 하나의 배포를 사용하며, Edgegap Simple FPS 키트를 사용합니다.

Edgegap에서 Unity 프로젝트를 호스팅하는 방법을 다음의 기법을 사용해 살펴보세요 [Simple FPS 멀티플레이어 샘플](https://assetstore.unity.com/packages/templates/tutorials/simple-fps-multiplayer-photon-fusion-272941). 플레이어는 샘플의 **Party** 메뉴에서 배포 주소와 Photon 지역을 입력해 서버에 참여합니다.

{% hint style="info" %}
우리의 [Edgegap Simple FPS 키트](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps) 는 Simple FPS 프로젝트에 복사해 넣는 파일 집합입니다. 이것은 **Photon 라이선스 코드 자체를 변경하거나 포함하지 않으므로**, Unity Asset Store에서 본인 라이선스로 Simple FPS를 사용하게 됩니다.
{% endhint %}

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

* **전용 서버로서의 Simple FPS** - 매치당 하나의 배포, [플레이어 가까이에 배치](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#server-placement).
* **Party 메뉴 참여** - Join 카드가 배포 FQDN과 Photon 지역 코드를 받습니다, **게임 만들기** 는 변경되지 않습니다.
* **직접 연결** - 서버가 바인딩합니다 `0.0.0.0` 포트 `7777`, 따라서 클라이언트가 직접 연결합니다.
* **양쪽 모두를 위한 하나의 프로젝트** - 서버와 클라이언트 빌드는 동일한 씬 목록을 공유합니다.
* **서버 자체 중지** - 서버 프로세스가 스스로 종료되면 시작 스크립트가 배포를 중지합니다.

{% hint style="success" %}
참조 [Photon Fusion 2](https://docs.edgegap.com/ko/docs/sample-projects/unity-netcodes/photon-fusion-2-on-edgegap.md) 를 확인하여 **Edgegap에서 Photon Fusion 2를 사용하는 일반 가이드를 확인하세요**. 키트의 [README](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps) 에서 전체 파일 목록과 테스트 결과를 확인하세요.
{% endhint %}

## ✔️ 준비

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

* [Simple FPS 멀티플레이어 (Photon Fusion)](https://assetstore.unity.com/packages/templates/tutorials/simple-fps-multiplayer-photon-fusion-272941) - 새 Unity 프로젝트로 다운로드 및 가져오기.
  * 이 샘플은 자체 Project Settings를 포함합니다.
* [Edgegap Simple FPS 키트](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps),
* Linux 빌드 모듈이 아래에 포함된 Unity 6000.3과 **Windows Build Support (IL2CPP)** 클라이언트용 (Visual Studio의 C++ 워크로드 필요),
* Photon Fusion App ID - 다음에서 찾을 수 있습니다 [Photon 대시보드](https://dashboard.photonengine.com).

{% hint style="info" %}
프로젝트를 열고 다음에 따라 서버 빌드 도구를 설치하세요 [Unity](https://docs.edgegap.com/ko/unity.md) 준비 단계.
{% endhint %}

이 키트는 Windows에서 Simple FPS 2.1.1, Fusion 2.1.1 (빌드 2177), Unity 6000.3.11f1로 테스트되었습니다.

{% hint style="warning" %}
서버 **IL2CPP를 사용해야 합니다** (샘플의 기본값). Mono 서버는 런타임에서 복구 불가능하게 실패합니다.
{% endhint %}

☑️ Windows에서 Linux IL2CPP를 빌드하려면, Window / Package Manager / + / Add package by name:에서 Unity의 Linux 툴체인을 추가하세요:

* Unity 6000.3 이상: `com.unity.toolchain.win-x86_64-linux` 및 `com.unity.sdk.linux-x86_64`,
* 이전 버전: `com.unity.toolchain.win-x86_64-linux-x86_64`.

## ⚡ 배포 및 연결

### 1. 키트를 프로젝트에 추가

☑️ `Assets/EdgegapSimpleFPS`, `edgegap/`, `scripts/`, `.dockerignore` 및 `.gitattributes` 를 키트에서 프로젝트 루트의 `Assets/`.

☑️ Tools / Fusion / Realtime Settings에 Fusion App ID를 붙여넣으세요.

{% hint style="info" %}
클라이언트와 서버는 **동일한 App ID, App Version, Photon 지역을 사용해야 합니다**, 그렇지 않으면 서로를 찾을 수 없습니다.
{% endhint %}

{% hint style="warning" %}
Asset Store 패키지에도 `PhotonAppSettings` 에 있는 `Assets/AssetStoreTools/Resources/` 자산이 게시자의 App ID와 함께 포함됩니다. **여기에 본인의 App ID도 넣거나, 그 복사본을 삭제하세요.**
{% endhint %}

☑️ 설정 **Peer Mode** 를 `Single` 로 Tools / Fusion / Network Project Config에서 설정하세요.

☑️ Tools / Edgegap Simple FPS / Check Project를 실행하고 보고된 문제를 모두 수정하세요.

☑️ Tools / Edgegap Simple FPS / Set Up Project를 실행하세요. 이것은 씬과 빌드 설정만 변경하며, 다시 실행해도 안전합니다:

* 데스매치: `FusionBootstrap` 은 `EdgegapFusionBootstrap` (설정을 유지한 채)로 바뀌며, Start Mode는 **사용자 인터페이스**,
* 시작: Party 메뉴의 `FusionMenuUIParty` 은 `EdgegapPartyMenu` 가 됩니다(이 작업을 위해 메뉴 프리팹 인스턴스의 패킹이 해제됩니다),
* Join 카드의 코드 필드는 최대 30자(문자, 숫자 및 점)를 허용하며, 새 **Region** 필드가 옆에 추가됩니다,
* 빌드 프로필은 Startup (0), 그다음 Deathmatch (1)로 설정됩니다.

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

### 2. 서버 빌드 및 업로드

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

☑️ Edgegap 플러그인 또는 터미널에서 서버를 빌드하고 업로드하세요:

{% tabs %}
{% tab title="Edgegap 플러그인(권장)" %}
☑️ Tools / Edgegap Server Hosting을 엽니다. 단계 **3. 서버를 컨테이너화**에서 **Path To Dockerfile** 을 클릭하고 `edgegap/Dockerfile`을 선택하세요. 다음은 유지하세요 **Relative Build Path** 를 `Builds/EdgegapServer`로 설정한 뒤, 컨테이너화하고 업로드하세요.

☑️ 플러그인이 앱 버전을 생성할 때 포트 `7777` / UDP를 유지하세요.
{% endtab %}

{% tab title="터미널(에이전트용)" %}
☑️ 찾아보세요 [Container Registry](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 프로젝트 이름과 자격 증명을 찾은 다음, 다음으로 로그인하세요 `docker login registry.edgegap.com`.

☑️ 서버를 빌드한 다음, 이미지를 패키징하고 푸시하세요(Windows에서는 Git Bash가 작동합니다):

{% code collapsedlinecount="10" %}

```bash
scripts/build.sh server
scripts/package.sh registry.edgegap.com/<your-registry-project>/simplefps <new-tag>
```

{% endcode %}

`package.sh` 가 푸시한 새 태그를 출력합니다.

☑️ [애플리케이션을 생성하고](https://app.edgegap.com/application-management/applications/list) 이미지의 버전을 생성하세요. 또한 키트의 `examples/app-version.json` 를 `POST /v1/app/{app}/version`.
{% endtab %}
{% endtabs %}

첫 IL2CPP 서버 빌드는 약 13분이 걸립니다.

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

편집기에서도 Tools / Edgegap Simple FPS / Build Linux Server를 사용해 빌드할 수 있으며, 동일한 출력을 `Builds/EdgegapServer`에 생성합니다. [Unity](https://docs.edgegap.com/ko/unity.md) Unity 서버 빌드에 대해 더 알아보려면

{% hint style="warning" %}
Edgegap Unity 플러그인으로 서버를 패키징하는 경우, 해당 **Path To Dockerfile** 를 `edgegap/Dockerfile`.
{% endhint %}

☑️ [애플리케이션을 생성하고](https://app.edgegap.com/application-management/applications/list) 및 버전을 다음과 같이 설정하세요:

* 이미지와 태그,
* Container Registry 사용자 이름과 토큰,
* 시작용 자원 1 vCPU 및 2 GB,
* [포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) `7777`, 프로토콜 **UDP**, 포트 검사는 끈 상태로.

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

### 3. 로컬 테스트

☑️ 로컬 이미지를 빌드하고 Edgegap이 주입할 변수를 사용해 실행하세요:

{% code collapsedlinecount="10" %}

```bash
scripts/package.sh
scripts/run-local.sh
```

{% endcode %}

☑️ 로그 줄을 찾으세요 `[edgegap-simplefps] server started: session=f68e011bfb01.pr.edgegap.net photon_region=<code>` 를 찾은 다음, 다음 단계처럼 해당 세션과 지역으로 클라이언트에서 참여하세요.

{% hint style="info" %}
로컬 클라이언트 연결 **릴레이**, 같은 머신의 클라이언트는 Docker Desktop의 NAT 주소에 직접 도달할 수 없기 때문입니다. Edgegap에서는 동일한 이미지가 연결됩니다 **직접**.
{% endhint %}

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

### 4. 배포 및 연결

☑️ 플러그인, [대시보드](https://app.edgegap.com/deployment-management/deployments/list), 또는 `POST /v2/deployments`에서 배포를 시작하세요. 플레이어의 공인 IP를 [그들에게 가까이 배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#server-placement).

☑️ 찾기 `server started: session=<fqdn> photon_region=<code>` 를 배포 로그에서.

☑️ `scripts/build.sh client` (또는 평소 사용하는 Windows 빌드)로 클라이언트를 빌드하고 실행한 다음, **Party Menu** 를 메인 메뉴에서 클릭하세요.

☑️ Join 카드에서 배포 FQDN(예: `f68e011bfb01.pr.edgegap.net`)을 코드 필드에, 지역 코드(예: `cae`)을 **Region** 필드에 입력한 다음, **Join**.

{% hint style="info" %}
를 클릭하세요. 클라이언트가 연결되지 않으면, 지역이 서버 로그와 일치하지 않을 가능성이 큽니다.
{% endhint %}

🙌 Edgegap에서 첫 배포를 성공한 것을 축하합니다!

## 🔄 매치 생명주기

1. 서버 빌드는 Startup 메뉴를 건너뛰고 Deathmatch를 로드합니다.
2. `EdgegapFusionBootstrap` 다음에서 Fusion 서버를 시작합니다 `ARBITRIUM_PORT_GAMEPORT_INTERNAL` (`7777` 기본값), 바인딩 대상 `0.0.0.0`, 그리고 세션 이름은 배포 FQDN, `<ARBITRIUM_REQUEST_ID>.pr.edgegap.net`.
3. 을 따릅니다. 서버는 세션 이름과 Photon 지역을 로그에 남기며, 플레이어는 이를 Party 메뉴의 Join 카드에 입력해 배포에 Direct로 연결합니다.
4. 서버 프로세스가 스스로 종료되면, `edgegap/start-server.sh` 는 `ARBITRIUM_DELETE_URL` 을 호출해 배포를 중지합니다.

{% hint style="info" %}
시작 스크립트는 환경을 절대 출력하지 않으므로, **삭제 토큰은 로그에 남지 않습니다**.
{% endhint %}

참조 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md) 자세히 알아보려면.

## ⚙️ 환경 변수

| 변수                                               | 설정 주체        | 효과                                                                                            |
| ------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------- |
| `ARBITRIUM_REQUEST_ID`                           | Edgegap      | 세션 이름은 다음이 됩니다 `<request id>.pr.edgegap.net`, 배포의 FQDN입니다.                                    |
| `ARBITRIUM_PORT_GAMEPORT_INTERNAL`               | Edgegap      | 서버가 바인딩하는 UDP 포트(`7777` 기본값). 서버는 `0.0.0.0`, 따라서 클라이언트는 Direct로 연결합니다.                        |
| `PHOTON_REGION`                                  | 당신(버전 또는 배포) | 고정된 Photon 지역, 예를 들어 `us`. 설정되어 있지 않으면 서버는 실행 위치에서 가장 핑이 좋은 지역을 사용합니다. 이 재정의는 아직 테스트되지 않았습니다. |
| `ARBITRIUM_DELETE_URL`, `ARBITRIUM_DELETE_TOKEN` | Edgegap      | 서버 프로세스가 스스로 종료되면, 시작 스크립트가 이를 사용해 배포를 중지합니다.                                                 |

참조 [주입된 변수](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#injected-environment-variables) 자세히 알아보려면.

## 🔌 직접 연결

Simple FPS의  `IP` 및 `포트` 서버가 **바인딩하는 주소를** 설정하세요. 키트는 `0.0.0.0:7777`, Fusion은 배포의 공인 주소를 스스로 찾으며, 클라이언트는 연결합니다 **직접** - Edgegap이 플레이어에게 다른 [외부 포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping).

| 서버 `IP`          | 결과                                                                                       |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `0.0.0.0` (이 키트) | **직접** Edgegap에서.                                                                        |
| `127.0.0.1`      | 서버는 시작되지만, 클라이언트는 **릴레이** Photon을 통해 연결되므로 지연이 추가됩니다. 컨테이너 외부의 어떤 것도 루프백 주소에 도달할 수 없습니다. |
| 배포의 공인 IP        | 서버는 **시작하지 않습니다** (`소켓 바인딩 실패`), 컨테이너가 해당 주소를 소유하지 않기 때문입니다. 클라이언트는 `GameNotFound`.      |

## 🎬 서버 씬

Fusion은 클라이언트에게 다음을 통해 로드할 씬을 알려줍니다 **빌드 인덱스**. Deathmatch만 포함해 빌드된 서버는 Deathmatch가 인덱스 0이 되지만, 클라이언트는 Startup이 인덱스 0입니다. 그러면 클라이언트는 게임 오브젝트를 결코 찾지 못하고 다음 예외를 발생시킵니다 `NullReferenceException` 에서 `Player.FixedUpdateNetwork` 매 틱마다. 그래서 두 빌드 모두 Startup (0)과 Deathmatch (1)을 사용하고, 서버는 Startup을 건너뜁니다.

같은 이유로, 서버는 Deathmatch를 **로드 시 활성화**, 샘플 자체 호스트처럼. 이것이 없으면 클라이언트는 Deathmatch를 로드하지만 Startup을 활성 상태로 유지하며, 동일한 예외가 발생합니다.

## ⚠️ 알려진 문제

* 매치를 끝까지 진행하는 것과, 매치 후 서버가 종료되는지는 아직 테스트되지 않았습니다 - 키트의 [README](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps).
* `PHOTON_REGION` 재정의는 아직 테스트되지 않았습니다.

## 🚨 문제 해결

<details>

<summary><code>MethodAccessException ... CheckInvokeRpc</code> 서버 로그에서</summary>

* 서버가 Mono로 빌드되었습니다. IL2CPP로 다시 빌드하세요.

</details>

<details>

<summary><code>호스트 플랫폼용 툴체인을 찾을 수 없음</code> 또는 <code>Linux sysroot를 찾을 수 없음</code></summary>

* Linux 툴체인 패키지가 누락되었습니다. 다음을 참조하세요 [준비](#preparation).

</details>

<details>

<summary>클라이언트가 받는 <code>GameNotFound</code></summary>

* App Version 또는 Photon 지역이 클라이언트와 서버 간에 다릅니다. 서버의 `photon_region=` 로그 줄과 비교하세요.

</details>

<details>

<summary>클라이언트가 받는 <code>InvalidAuthentication</code></summary>

* 빌드에서 Fusion App ID가 잘못되었거나 누락되었습니다.

</details>

<details>

<summary>Tab 오버레이가 CT Relayed를 표시합니다</summary>

* 서버는 `127.0.0.1`, 다음을 참조하세요 [직접 연결](#direct-connection).

</details>
