> 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/web-games/fal-ai-relic-rumble.md).

# fal.ai Relic Rumble

edgegap으로 fal.ai 게임을 멀티플레이어 게임으로 만들어 보세요. 코딩 에이전트가 작성한 three.js 게임으로, fal이 생성한 3D 캐릭터, 소품, 사운드, 매치메이킹 기능과 매치당 하나의 권한 있는 node.js 서버를 갖춥니다.

다음으로 빌드한 게임의 [fal.ai](https://fal.ai/) 에셋을 Edgegap에서 온라인 멀티플레이어로 만드는 방법을 알아보세요.

![Relic Rumble: 매치에서 만난 fal 생성 캐릭터 4명](https://raw.githubusercontent.com/edgegap/netcode-sample-fal-relic-rumble/main/docs/images/gameplay.jpg)

Relic Rumble은 [three.js](https://threejs.org/) 로 만든 4인 파티 게임입니다. 유물을 집어 자기 코너로 가져가고, 같은 걸 노리는 상대를 밀쳐내세요. 코딩 에이전트가 코드를 작성했으며, fal.ai가 화면과 소리에 등장하는 모든 것을 생성했습니다. 걷기와 달리기 애니메이션이 적용된 리깅 캐릭터 4명과 소품, 바닥, 사운드가 포함됩니다.

* **fal.ai**: 게임을 빌드할 때 에셋을 생성하는 데 사용합니다.
* **Edgegap**: 게임을 플레이하는 동안 매치메이킹과 매치별 전용 서버 제공에 사용하며, 서버는 플레이어와 가까운 곳에 배치됩니다.

이 샘플에서는 다음을 확인할 수 있습니다.

* **하나의 파일로 관리하는 규칙**: `client/rules.js` 에는 브라우저 코드가 없으므로, 페이지에서 솔로 플레이에 사용하고 게임 서버에서도 온라인 플레이에 동일한 파일을 사용합니다.
* **페이지에 그대로 두는 에셋**: 서버는 캐릭터를 원으로, 기둥을 상자로 처리합니다. 서버 이미지에는 모델, 텍스처, 사운드를 복사하지 않으며, 새 아트를 추가해도 서버를 다시 릴리스할 필요가 없습니다.
* **모든 에셋은 선택 사항**: 비어 있는 `client/assets.js` 를 사용하면 게임은 단순한 도형을 그립니다. 이 샘플은 에셋을 생성하기 전에 이 방식으로 빌드하고 온라인에서 테스트했습니다.
* **fal 파이프라인**: 캐릭터마다 콘셉트 이미지를 하나씩 만든 다음, 이미지-3D 변환과 리깅을 진행합니다. 모든 프롬프트, 모델, 가격은 샘플의 `PROMPTS.md`.
* **페이지에서 매치 찾기** 및 [Edgegap JavaScript SDK](https://www.npmjs.com/package/@edgegap/sdk)를 사용합니다. 매치당 플레이어는 2\~4명이며, 빈 자리는 봇이 채웁니다.

{% hint style="info" %}
게임, fal 스크립트와 프롬프트, 게임 서버, 전체 흐름을 확인하는 엔드투엔드 테스트는 [샘플 저장소](https://github.com/edgegap/netcode-sample-fal-relic-rumble) 에서 확인하세요.
{% endhint %}

## ✔️ 준비

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

* [fal.ai Relic Rumble 샘플](https://github.com/edgegap/netcode-sample-fal-relic-rumble)을 본인의 GitHub 저장소에 푸시합니다.
* [Node.js](https://nodejs.org/) 22 이상. 서버와 페이지를 로컬에서 실행하는 데 필요합니다.
* 직접 에셋을 생성하려면 [fal.ai 계정](https://fal.ai/dashboard) 과 몇 달러 상당의 크레딧, 그리고 fal의 `genmedia` CLI 또는 [fal MCP 서버](https://fal.ai/mcp) 를 코딩 에이전트에 연결해야 합니다. 샘플에 에셋이 포함되어 있으므로 이 과정은 선택 사항입니다.

☑️ 먼저 로컬에서 게임을 실행해 보세요.

{% code collapsedlinecount="10" %}

```bash
npm install
npm run test:local
npm run client
```

{% endcode %}

`npm run test:local` 은 로컬 서버에서 헤드리스 플레이어 두 명으로 전체 매치를 진행합니다. 다음을 엽니다. `http://localhost:8080` 를 클릭해 **봇과 대전** 을 선택하면 혼자 플레이할 수 있습니다.

☑️ 자신의 컴퓨터에서 온라인으로 플레이하려면 두 번째 터미널에서 `npm run server` 를 실행한 다음, 브라우저 탭 두 개에서 **로컬 서버 :7777** 을 클릭하세요.

## 🎨 fal.ai로 에셋 생성하기

### 1. 캐릭터, 소품 및 사운드

☑️ 캐릭터마다 콘셉트 이미지를 하나씩 생성하세요. 캐릭터를 자동으로 리깅할 수 있도록 양팔을 몸에서 벌리고 손은 비운 A-포즈의 전신 이미지를 요청하세요:

{% code collapsedlinecount="10" %}

```bash
bash art/gen-concepts.sh
```

{% endcode %}

☑️ 각 이미지를 리깅된 3D 모델로 변환하세요. 결과물에는 모델과 별도의 걷기 및 달리기 애니메이션이 포함됩니다:

{% code collapsedlinecount="10" %}

```bash
genmedia run meshy/v7.1/image-to-3d --image_url "<concept url>" --enable_rigging true --pose_mode "a-pose" --target_polycount 12000 --async --json
genmedia status meshy/v7.1/image-to-3d <request_id> --result --json
```

{% endcode %}

☑️ 각 모델을 다운로드하고 웹에 적합하도록 텍스처 크기를 줄인 다음, `client/assets.js`:

{% code collapsedlinecount="10" %}

```bash
python art/fetch.py raider-blue
bash art/build.sh raider-blue
```

{% endcode %}

소품, 바닥 텍스처와 사운드도 같은 방식으로 처리하며, 다음 스크립트를 사용합니다: `art/gen-props.sh` 및 `art/gen-sfx.sh`.

{% hint style="success" %}
**에셋은 게임 서버에 전송되지 않습니다.** 충돌, 도달 거리 및 속도는 `client/rules.js`에 숫자로 설정되어 있습니다. 렌더러는 각 모델을 월드 단위 크기로 조정하므로 규칙을 바꾸지 않고도 모델을 교체할 수 있습니다.
{% endhint %}

{% hint style="warning" %}
**리깅된 모델의 크기가 잘못 표시됨** 스켈레톤 자체에 스케일이 적용되어 있어 three.js의 기본 바운딩 박스는 모델 크기를 제대로 측정하지 못합니다. 대신 스키닝된 정점을 측정하세요. 다음 함수가 이 방식을 사용합니다: `fit()` 는 `client/render.js`에 있으며, 이를 적용하지 않으면 캐릭터가 지나치게 작게 렌더링됩니다.
{% endhint %}

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

## ⚡ 배포 및 연결

### 2. 서버 이미지 빌드하기

☑️ 시작하려면 먼저 [Edgegap 무료 계정을 만드세요](https://app.edgegap.com/auth/register). 신용카드는 필요하지 않습니다.

☑️ [Container Registry](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md) 프로젝트 이름과 자격 증명을 찾으세요.

☑️ GitHub 리포지토리에서 **Settings**를 연 다음, **Secrets and variables**를 연 다음, **Actions**를 선택하고 다음을 추가하세요:

* 변수 `EDGEGAP_REGISTRY_PROJECT` - 레지스트리 프로젝트 이름,
* 보안 비밀 `EDGEGAP_REGISTRY_USERNAME` - 레지스트리 사용자 이름,
* 보안 비밀 `EDGEGAP_REGISTRY_TOKEN` - 레지스트리 토큰.

☑️ 다음을 실행합니다: **서버 이미지** 워크플로를 **Actions** 탭에서 실행합니다. 로컬 매치 테스트를 진행한 다음 `registry.edgegap.com/<project>/relic-rumble:<tag>`, 빌드 시간으로 태그를 지정해 빌드하고 푸시합니다. 태그는 실행 요약에 표시됩니다.

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

### 3. 앱 버전 만들기

☑️ [애플리케이션을 만들고](https://app.edgegap.com/application-management/applications/list) 이름을 `relic-rumble`로 지정한 후, 태그를 이름으로 사용하는 버전을 하나 만듭니다:

* **이미지**: 레지스트리 `registry.edgegap.com`, 리포지토리 `<project>/relic-rumble`, 태그 `<tag>`,
* **리소스**: 0.25 vCPU 및 메모리 512MB,
* **포트**: `7777`, 이름 `gameport`, 프로토콜 **WS**, 다음을 **TLS 업그레이드** 사용으로 설정,
* **재시작 정책**: 사용 안 함,
* **환경 변수**:
  * `EMPTY_TIMEOUT_S` - `15`, 모두 떠난 서버를 중지하도록 설정,
  * `FIRST_JOIN_TIMEOUT_S` - `60`, 아무도 참가하지 않은 서버를 중지하도록 설정,
  * `RESULTS_SECONDS` - `8`,
  * `IDLE_TIMEOUT_S` - `75`, 페이지가 사라진 플레이어를 내보내도록 설정,
* **최대 실행 시간**: 안전장치로 30분을 설정합니다. 서버가 자동으로 중지됩니다.

{% hint style="warning" %}
**TLS 업그레이드** 브라우저가 `https` 페이지에서 다음 주소로 연결할 수 있게 합니다. `wss://<id>.pr.edgegap.net:<port>`. Edgegap은 TLS를 종료하고 일반 WebSocket 트래픽을 포트로 전달합니다. `7777`.
{% endhint %}

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

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

☑️ 설정 `application.version` 샘플의 `matchmaker/rumble.json` 에서 버전을 자신의 버전으로 바꾸고, 페이지 주소를 `allowed_cors_origins`.

☑️ 대시보드에서 [매치메이커](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 페이지를 열고 **만들기**를 클릭한 다음 설정 파일을 업로드하고 **만들고 시작**.

을 클릭합니다. `rumble` 프로필은 2\~4명의 플레이어를 매칭합니다. 20초가 지나면 혼자 기다리는 플레이어에게 서버가 할당되고, 봇이 빈 자리를 채웁니다.

☑️ 매치메이커에 **온라인**이 표시되면 **API URL** 과 **인증 토큰** 을 `client/config.local.js`에 복사합니다. 이 파일은 `client/config.js`.

{% hint style="success" %}
의 복사본입니다. **매치메이커 인증 토큰은 웹 페이지에 포함해도 안전합니다**: 이 토큰은 매치를 요청하는 데만 사용할 수 있습니다. Edgegap API 토큰은 페이지나 서버 이미지에 절대 넣지 마세요.
{% endhint %}

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

### 5. 매치 찾기

☑️ 브라우저 탭 두 개에서 페이지를 열고 20초 이내에 두 탭 모두에서 **매치 찾기** 를 클릭합니다.

각 페이지는 다음을 수행합니다.

1. 매치메이커에 참여하고 다음 상태가 될 때까지 기다립니다. `HOST_ASSIGNED`,
2. 다음 주소에 연결하고 `wss://<fqdn>:<port>` 티켓 ID를 전송합니다.
3. 게임을 플레이합니다. 입력을 전송하고 서버에서 받은 상태를 렌더링합니다. 솔로 플레이와 동일한 렌더러 및 에셋을 사용합니다.

게임 서버는 다음을 수행합니다.

1. 매칭된 플레이어를 기다린 다음 봇으로 빈 자리를 채웁니다.
2. 실행합니다 `client/rules.js` 초당 60회 실행되고 위치를 초당 20회 전송하며,
3. 결과 화면이 표시된 후 자체 배포를 중지합니다.

🙌 이제 두 플레이어가 자신들과 가까운 곳에 배치된 서버에서 같은 매치에 참가합니다.

☑️ 브라우저 없이 전체 흐름을 테스트하려면 엔드투엔드 테스트를 실행하세요. 헤드리스 플레이어 두 명을 대기열에 넣고, 매치를 진행한 뒤 배포가 자체적으로 중지될 때까지 기다립니다:

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> node tests/e2e.mjs rumble 2
```

{% endcode %}

## 📦 게임 출시하기

* 페이지를 원하는 곳에 호스팅하세요: `client/` 에는 빌드 단계가 필요 없는 정적 파일이 들어 있습니다. 샘플에는 GitHub Pages 워크플로가 포함되어 있습니다.
* 게시하기 전에 `client/assets/` 의 크기를 확인하세요. 샘플의 캐릭터 4종, 소품 3개, 바닥 및 사운드를 모두 합치면 7MB입니다.
* 나중에 같은 스타일로 에셋을 더 생성할 수 있도록 fal 프롬프트를 보관하세요.
* 출시 전에 매치메이커 설정에서 `inspect` 를 끄세요.
* 새 규칙을 배포하려면 새 이미지 태그를 푸시하고 앱 버전이 이를 가리키도록 설정하세요. 새 매치에는 새 버전이 적용되고, 진행 중인 매치는 이전 빌드를 계속 사용합니다. 새 에셋을 적용하려면 페이지만 다시 게시하면 됩니다.

{% hint style="info" %}
코딩 에이전트를 사용하시나요? `edgegap-fal` 스킬은 [Edgegap의 에이전트 스킬](https://github.com/edgegap/llm-agent-skills) 에 포함되어 있으며, 게임 개요, fal 에셋 파이프라인, 서버 템플릿 및 테스트를 제공하고 에이전트가 여러분의 게임에도 같은 단계를 수행하도록 안내합니다.
{% endhint %}
