빠른 시작: 간단한 게임 서버 생성하기
사전 준비 사항:
- Node.js v12 이상 설치
- Git SCM 설치
- Visual Studio Code 또는 기타 코드 편집기 설치
빈 프로젝트 생성
다음 명령어로 기초적인 Colyseus 서버 프로젝트를 생성합니다. 언어는 TypeScript(권장), JavaScript, Haxe 중 선택 가능합니다.
npm init colyseus-app ./my-colyseus-game
공식 예제 프로젝트 체험
또는 공식 예제 저장소를 복제하여 실습해 보세요.
git clone https://github.com/colyseus/colyseus-examples.git
cd colyseus-examples
npm install
로컬에서 서버를 실행하려면 다음을 입력하세요:
npm start
브라우저에서 http://localhost:2567에 접속하여 다양한 예제를 확인할 수 있습니다.
서버 동작 원리 개요
Colyseus는 웹 소켓 기반의 실시간 멀티플레이어 시스템으로, 클라이언트와 서버 간의 상태 동기화 및 메시지 전달을 효율적으로 관리합니다. 각 방(Room)은 독립된 상태 트리와 이벤트 처리 메커니즘을 갖습니다.
클라이언트 SDK 사용 방법
NPM 패키지 설치 (빌드 도구 사용 시)
npm install --save colyseus.js
직접 스크립트 포함 (빌드 도구 미사용 시)
<script src="https://unpkg.com/colyseus.js@^0.14.0/dist/colyseus.js"></script>
연결 및 방 참여
import * as Colyseus from 'colyseus.js';
const client = new Colyseus.Client('ws://localhost:2567');
client.joinOrCreate('arena', { player: 'hero' })
.then(room => {
console.log('방에 성공적으로 참여:', room.sessionId);
})
.catch(err => {
console.error('접속 실패:', err);
});
방 이벤트 핸들링
상태 업데이트 감지:
room.onStateChange((state) => {
console.log('새로운 상태:', state);
});
서버로부터의 메시지 수신:
room.onMessage('notify', (data) => {
console.log('알림 수신:', data);
});
연결 오류 발생 시:
room.onError((code, msg) => {
console.warn('오류 발생:', msg);
});
방 탈출 시:
room.onLeave((code) => {
console.log('방에서 탈출함 (코드:', code, ')');
});
Cocos Creator 3.0 통합 절차
- GitHub Releases에서
colyseus-js-client.zip다운로드 - 압축 해제 후
colyseus.js및colyseus.d.ts파일을 프로젝트의scripts폴더에 복사 - 에셋 패널에서
colyseus.js파일을 선택하고 "Import As Plugin" 활성화 - 타입스크립트 사용 시:
import Colyseus from './colyseus.js';
- 자바스크립트 사용 시:
const Colyseus = require('./colyseus.js');
지원되는 플랫폼
Colyseus는 다음과 같은 환경에서 클라이언트가 작동합니다:
- Unity (소스 코드 제공)
- JavaScript/TypeScript (웹, Node.js)
- Defold Engine
- Haxe
- Cocos2d-X
- Construct3
추가 지원 요청은 커뮤니티에서 제안 가능합니다.
클라이언트 인스턴스 초기화
import Colyseus from 'colyseus.js';
const client = new Colyseus.Client('ws://localhost:2567');
방 참여 관련 메서드
| 메서드 | 설명 |
|---|---|
joinOrCreate(name, options) |
존재하는 방에 참여하거나 새로 생성 |
create(name, options) |
새로운 방 생성 |
join(name, options) |
기존 방에 참여 |
joinById(roomId, options) |
방 고유 ID로 참여 (비공개 방도 가능) |
reconnect(roomId, sessionId) |
이전 세션 재연결 (서버 설정 필요) |
getAvailableRooms(name?) |
접근 가능한 방 목록 조회 |
consumeSeatReservation(reservation) |
예약된 자리로 참여 (고급 기능) |
방 객체 (Room API)
속성
state: 서버와 동기화된 현재 상태 객체sessionId: 클라이언트 고유 식별자id: 방 고유 ID (공유 가능)name: 방 핸들러 이름 (battle,lobby등)
메서드
send(type, message): 메시지 전송 (MsgPack 직렬화)leave(): 방에서 탈출removeAllListeners(): 모든 이벤트 리스너 제거
이벤트
onStateChange: 상태 변경 시 호출onMessage: 서버 메시지 수신 시 호출onLeave: 방 탈출 시 호출onError: 오류 발생 시 호출
고급 기능: 스케일링과 운영 최적화
향후 Google Agones 기반의 Kubernetes 배포 및 대규모 확장 전략 문서를 추가로 제공할 예정입니다. 클라우드 네이티브 아키텍처를 기반으로 한 확장성 있는 게임 서비스 설계를 추천합니다.