# PlayDrop의 실시간 게임 서버: Colyseus와 MongoDB

MongoDB 데이터베이스가 있는 호스팅 Colyseus 0.17 서버를 게임에 쓰고, SDK로 브라우저에서 연결하고, 플레이어 2명으로 테스트하고, 제한 사항을 알아보세요.

Source: https://www.playdrop.ai/ko/create/learn/game-servers

PlayDrop은 게임의 서버 쪽을 호스팅할 수 있습니다. 자체 MongoDB 데이터베이스가 있는 표준 Colyseus 서버로, 플레이어 인증까지 처리되며 직접 운영할 인프라가 없습니다. 실시간 대전, 턴제 게임, 공유 월드, 플레이어가 부정행위를 하면 안 되는 모든 것에 사용하세요. 서버는 선택 사항이며, 게임에서 직접 호스팅하는 서버를 호출해도 됩니다.

## 서버 작성하기

ES 모듈 하나에서 `rooms` 맵을 내보내세요. 서버는 PlayDrop이 시작합니다. PlayDrop이 `onJoin` 전에 각 플레이어를 인증하므로 `listen()`을 호출하거나 `onAuth`를 정의하지 마세요.

```js
import { Room, defineRoom } from "colyseus";
import { MongoClient } from "mongodb";

class GameRoom extends Room {
  maxClients = 8;
  async onCreate() {
    this.mongo = new MongoClient(process.env.PLAYDROP_MONGO_URL);
    await this.mongo.connect();
    this.onMessage("move", (client, move) => this.applyMove(client.auth.userId, move));
  }
  onJoin(client) {
    // client.auth is the verified PlayDrop player: userId, username, appRole, isTestPlayer…
  }
  async onDispose() { await this.mongo?.close(); }
}

export const rooms = { game: defineRoom(GameRoom) };
```

MongoDB 연결은 모듈 최상위가 아니라 방 수명 주기 안에서 하세요. `PLAYDROP_MONGO_URL`은 실행 중에만 존재합니다. 쿼리에 맞는 인덱스를 만드세요.

## 서버 선언하기

서버를 파일 하나로 번들링하고 카탈로그에서 그 파일을 가리키세요.

```json
{ "server": { "entry": "server/index.mjs", "rooms": ["game"] } }
```

[패키지](https://www.playdrop.ai/ko/create/learn/packaging)로 업로드하세요. 간단한 HTML 방식으로는 서버를 올릴 수 없습니다.

## 호스팅 런타임 규칙

- Node.js 24.22.1에서 Colyseus 0.17(`colyseus` 0.17.10, `@colyseus/schema` 4.0.30), MongoDB 드라이버 7.5.
- 최대 2 MiB의 독립 실행형 ES 모듈 하나. `colyseus`, `@colyseus/core`, `@colyseus/schema`, `mongodb`, `@playdrop/server`만 가져올 수 있으며, 나머지는 모두 번들에 넣으세요.
- 방 유형 최대 2개, 방당 플레이어 8명, 방당 4시간, 플레이어당 초당 메시지 30개, 메시지당 512 KiB.
- 인터넷에 접근할 수 없습니다. MongoDB와 PlayDrop 서비스에만 연결됩니다.
- 플레이어는 로그인해야 합니다.
- 데이터베이스는 게임마다 하나이며, 버전이 바뀌어도 유지되고 크리에이터의 저장 공간에 포함됩니다. 데이터베이스 주소나 자격 증명을 브라우저로 절대 보내지 마세요.

## 브라우저에서 연결하기

```js
const sdk = await playdrop.init();
const room = await sdk.multiplayer.join("game");
room.onStateChange((state) => render(state));
room.send("move", { x: 1 });
```

`join`은 PlayDrop의 파티 자리와 로그인을 처리합니다. [온라인 파티](https://www.playdrop.ai/ko/create/learn/online-party)를 참고하세요. 더 세밀하게 제어하려면 `sdk.multiplayer.getConnection()`이 `sdk.libs.colyseus.load()`의 공식 Colyseus 클라이언트용 `{ endpoint, token, expiresAt }`을 반환합니다.

## 서버 SDK

`@playdrop/server`는 신뢰할 수 있는 플랫폼 호출을 추가합니다. 친구와 게임 카드(`playdrop.social`), 구매 확인(`playdrop.shop`), 크리에이터가 비용을 내는 AI 생성(`playdrop.ai`), 방 음성 채팅(`playdrop.multiplayer.forRoom`)이 있습니다. 업로드한 게임에서만 작동합니다. [서버 SDK 참조](https://www.playdrop.ai/ko/create/learn/server-sdk)를 확인하세요.

## 테스트하기

개발 중에는 Colyseus 0.17과 MongoDB를 로컬에서 실행하고 로컬 클라이언트를 로컬 서버에 연결하세요. 호스팅 서버를 테스트하려면 비공개 버전을 업로드하고 `https://www.playdrop.ai/create/games/<slug>/test?v=<version>&player=1`을 연 다음, 두 번째 창에서 `player=2`로 바꾼 같은 링크를 여세요. 각 창은 내 계정의 서로 다른 테스트 플레이어로 플레이합니다. 잘 작동하면 테스트한 버전을 `publish_game_version`으로 게시하세요.

연결 끊김에 대비해 설계하세요. Colyseus 재연결은 잠시 동안 자리를 유지하며, 방의 상태는 돌아온 플레이어가 이어서 플레이할 수 있게 해야 합니다.

## 관련 가이드

- [온라인 파티와 음성 채팅](https://www.playdrop.ai/ko/create/learn/online-party): 친구들이 온라인에서 함께 플레이하게 하세요. 파티 인원수를 선언하고, PlayDrop 파티 창을 열고, sdk.multiplayer.join으로 예약된 방에 참가하고, 방 음성 채팅을 제어하세요.
- [서버 SDK](https://www.playdrop.ai/ko/create/learn/server-sdk): PlayDrop 호스팅 게임 서버 참조: 런타임 규칙, 검증된 PlayDropPlayer, playdrop.social, playdrop.shop, playdrop.ai, playdrop.multiplayer.
- [패키징과 .play](https://www.playdrop.ai/ko/create/learn/packaging): catalogue.json을 루트에 둔 빌드 폴더, ZIP 또는 .play를 구성하고, 등록 정보 미디어와 서버를 선언한 뒤 prepare_catalogue_upload로 업로드하세요.