함께 플레이하기

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

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

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

서버 작성하기

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

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"] } }

패키지로 업로드하세요. 간단한 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 서비스에만 연결됩니다.
플레이어는 로그인해야 합니다.
데이터베이스는 게임마다 하나이며, 버전이 바뀌어도 유지되고 크리에이터의 저장 공간에 포함됩니다. 데이터베이스 주소나 자격 증명을 브라우저로 절대 보내지 마세요.

브라우저에서 연결하기

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

join은 PlayDrop의 파티 자리와 로그인을 처리합니다. 온라인 파티를 참고하세요. 더 세밀하게 제어하려면 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 참조를 확인하세요.

테스트하기

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

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