Phaser 소개와 개발 환경 설정

웹 브라우저에서 게임을 만들 수 있는 Phaser 프레임워크의 기초를 배웁니다. Node.js 설치부터 Vite 프로젝트 생성, 그리고 첫 번째 게임 화면을 띄우기까지 단계별로 안내합니다.

---

목차

1. Phaser란_무엇인가
2. Phaser의_역사와_버전
3. Node.js와_npm_설치
4. Vite로_프로젝트_생성
5. Phaser_패키지_설치
6. 첫_번째_게임_화면_띄우기

---

1. Phaser란 무엇인가

김개발 씨는 어린 시절 즐겨 하던 2D 게임을 직접 만들어보고 싶었습니다. 하지만 Unity나 Unreal Engine은 너무 무겁고 복잡해 보였습니다.

"혹시 웹 개발자인 내가 익숙한 JavaScript로 게임을 만들 수 있는 방법은 없을까?" 바로 그때 선배가 Phaser를 소개해주었습니다.

Phaser는 HTML5 게임을 만들기 위한 오픈소스 JavaScript 프레임워크입니다. 마치 집을 지을 때 벽돌 하나하나 쌓는 대신 조립식 모듈을 사용하는 것처럼, Phaser는 게임 개발에 필요한 모든 도구를 미리 준비해둡니다.

스프라이트, 물리 엔진, 사운드, 입력 처리 등 게임의 핵심 기능을 손쉽게 구현할 수 있습니다.

다음 코드를 살펴봅시다.

// Phaser로 만든 가장 간단한 게임 구조
const config = {
    type: Phaser.AUTO,           // 렌더링 방식 자동 선택
    width: 800,                   // 게임 화면 너비
    height: 600,                  // 게임 화면 높이
    scene: {
        preload: preload,         // 리소스 로딩 함수
        create: create,           // 게임 오브젝트 생성 함수
        update: update            // 매 프레임 실행 함수
    }
};

// 게임 인스턴스 생성
const game = new Phaser.Game(config);

김개발 씨는 입사 1년 차 프론트엔드 개발자입니다. 평소 게임을 좋아하던 그는 주말마다 취미로 간단한 게임을 만들어보고 싶었습니다.

그런데 막상 게임 개발을 시작하려니 어디서부터 손대야 할지 막막했습니다. "Unity를 배워볼까?

아니면 Unreal Engine?" 김개발 씨는 여러 게임 엔진을 찾아보았지만, 새로운 언어와 도구를 처음부터 배워야 한다는 사실에 부담을 느꼈습니다. 그러던 어느 날, 게임 개발 경험이 있는 박시니어 씨에게 고민을 털어놓았습니다.

"JavaScript를 잘 알고 있다면서요? 그럼 Phaser를 써보세요.

웹 개발자에게 딱이에요." 그렇다면 Phaser란 정확히 무엇일까요? 쉽게 비유하자면, Phaser는 마치 레고 블록 세트와 같습니다.

레고로 집을 만들 때 벽돌부터 굽지 않아도 되듯이, Phaser를 사용하면 게임 엔진의 복잡한 내부 구조를 몰라도 게임을 만들 수 있습니다. 캐릭터 이동, 충돌 감지, 점수 계산 같은 기능이 이미 블록처럼 준비되어 있습니다.

Phaser가 없던 시절에는 어땠을까요? 개발자들은 Canvas API를 직접 다루며 모든 것을 처음부터 만들어야 했습니다.

화면에 이미지 하나 그리려면 수십 줄의 코드가 필요했고, 물리 법칙을 구현하려면 수학 공식을 직접 코딩해야 했습니다. 바로 이런 불편함을 해결하기 위해 Phaser가 등장했습니다.

Phaser를 사용하면 단 몇 줄의 코드로 스프라이트를 화면에 띄울 수 있습니다. 물리 엔진도 내장되어 있어 중력이나 충돌 처리를 쉽게 구현할 수 있습니다.

위의 코드를 살펴보겠습니다. config 객체가 게임의 기본 설정을 담고 있습니다.

type: Phaser.AUTO는 브라우저 환경에 따라 WebGL 또는 Canvas 중 최적의 렌더링 방식을 자동으로 선택합니다. scene 속성에는 게임의 생명주기를 관리하는 세 가지 핵심 함수가 들어갑니다.

preload 함수는 게임에 필요한 이미지, 사운드 파일을 미리 불러옵니다. create 함수는 게임 오브젝트를 생성하고 초기 설정을 합니다.

update 함수는 매 프레임마다 호출되어 게임 로직을 처리합니다. 실제 현업에서는 어떻게 활용할까요?

많은 기업들이 Phaser로 캐주얼 웹 게임, 교육용 게임, 마케팅 이벤트 게임을 개발합니다. 별도 앱 설치 없이 브라우저에서 바로 실행되기 때문에 사용자 접근성이 뛰어납니다.

박시니어 씨의 설명을 들은 김개발 씨는 눈이 반짝였습니다. "JavaScript만 알면 된다고요?

이거 해볼 만하겠는데요!" Phaser와 함께라면 여러분도 상상 속의 게임을 현실로 만들 수 있습니다.

실전 팁

💡 - Phaser 공식 문서와 예제를 자주 참고하세요

• 처음에는 간단한 게임부터 시작하여 점차 복잡도를 높여가세요

---

2. Phaser의 역사와 버전

김개발 씨가 Phaser를 설치하려고 npm을 검색했더니 여러 버전이 눈에 들어왔습니다. Phaser 2, Phaser CE, Phaser 3...

"도대체 뭘 설치해야 하는 거지?" 버전 선택에 혼란을 느낀 김개발 씨는 다시 박시니어 씨를 찾아갔습니다.

Phaser는 2013년 Richard Davey가 처음 만들었습니다. Phaser 2에서 시작해 커뮤니티 버전인 Phaser CE를 거쳐, 현재는 완전히 새로 설계된 Phaser 3가 표준입니다.

새 프로젝트를 시작한다면 반드시 Phaser 3를 선택해야 합니다.

다음 코드를 살펴봅시다.

// Phaser 버전 확인하기
console.log('Phaser Version:', Phaser.VERSION);

// Phaser 3의 새로운 Scene 시스템
class MainScene extends Phaser.Scene {
    constructor() {
        super({ key: 'MainScene' });  // Scene 고유 키
    }

    create() {
        // Phaser 3는 클래스 기반 Scene 지원
        this.add.text(100, 100, 'Hello Phaser 3!');
    }
}

// 설정에 Scene 클래스 등록
const config = {
    scene: MainScene
};

박시니어 씨가 웃으며 대답했습니다. "좋은 질문이에요.

버전 선택은 정말 중요하거든요." Phaser의 역사는 2013년 4월로 거슬러 올라갑니다. 영국의 개발자 Richard Davey가 Flixel이라는 ActionScript 게임 라이브러리에서 영감을 받아 JavaScript용 게임 프레임워크를 만들었습니다.

이것이 바로 Phaser의 시작입니다. 초기 Phaser는 Phaser 2라는 이름으로 빠르게 인기를 얻었습니다.

사용하기 쉽고 문서화가 잘 되어 있어 많은 개발자들이 선택했습니다. 하지만 시간이 지나면서 구조적인 한계가 드러났습니다.

2016년, Richard Davey가 Phaser 3 개발에 집중하면서 커뮤니티가 Phaser 2를 관리하기 시작했습니다. 이것이 바로 Phaser CE입니다.

CE는 Community Edition의 약자로, 버그 수정과 소소한 기능 개선이 이루어졌습니다. 그리고 2018년 2월, Phaser 3가 정식 출시되었습니다.

이것은 단순한 업그레이드가 아니라 완전히 새로 설계된 프레임워크였습니다. 코드 구조, API, 렌더링 시스템 모든 것이 바뀌었습니다.

Phaser 3에서 가장 큰 변화는 Scene 시스템입니다. 위 코드에서 볼 수 있듯이 ES6 클래스를 사용하여 깔끔하게 게임 화면을 관리할 수 있습니다.

각 Scene은 독립적인 게임 상태를 가지며, 여러 Scene을 동시에 실행하거나 전환할 수 있습니다. 또한 Phaser 3는 WebGL 렌더링이 기본입니다.

이전 버전보다 훨씬 빠르고 부드러운 그래픽을 구현할 수 있습니다. 모바일 기기에서도 좋은 성능을 보여줍니다.

현재 시점에서 Phaser 2나 CE를 사용할 이유는 거의 없습니다. 박시니어 씨가 강조했습니다.

"레거시 프로젝트 유지보수가 아니라면 무조건 Phaser 3를 쓰세요. 학습 자료도 3 버전이 훨씬 많고요." 김개발 씨는 고개를 끄덕였습니다.

"그러니까 npm install phaser 하면 Phaser 3가 설치되는 거죠?" 맞습니다. 현재 npm에서 phaser 패키지는 Phaser 3를 가리킵니다.

실전 팁

💡 - 인터넷에서 Phaser 튜토리얼을 찾을 때 버전을 꼭 확인하세요

• Phaser 2 코드는 Phaser 3에서 작동하지 않으니 주의하세요

---

3. Node.js와 npm 설치

이제 본격적으로 개발 환경을 구축할 시간입니다. 김개발 씨가 터미널을 열었습니다.

하지만 그전에 먼저 해야 할 일이 있습니다. 바로 Node.js와 npm을 설치하는 것입니다.

이것이 없으면 현대적인 웹 개발은 시작조차 할 수 없습니다.

Node.js는 JavaScript를 브라우저 밖에서 실행할 수 있게 해주는 런타임 환경입니다. npm은 Node Package Manager의 약자로, JavaScript 패키지를 설치하고 관리하는 도구입니다.

Node.js를 설치하면 npm도 함께 설치됩니다.

다음 코드를 살펴봅시다.

# Node.js 공식 사이트에서 LTS 버전 다운로드 후 설치
# https://nodejs.org

# 설치 확인
node --version
# 출력 예시: v20.10.0

npm --version
# 출력 예시: 10.2.3

# 또는 nvm으로 설치 (권장)
# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

박시니어 씨가 김개발 씨 옆에 앉았습니다. "먼저 Node.js부터 설치해야 해요.

이게 없으면 아무것도 못 해요." Node.js가 무엇인지 쉽게 설명해 드리겠습니다. 원래 JavaScript는 웹 브라우저 안에서만 실행되는 언어였습니다.

마치 물고기가 물 밖에서 살 수 없는 것처럼요. 그런데 Node.js가 등장하면서 JavaScript가 컴퓨터 어디서든 실행될 수 있게 되었습니다.

그렇다면 게임은 브라우저에서 실행되는데 왜 Node.js가 필요할까요? 좋은 질문입니다.

Node.js는 게임 자체가 아니라 개발 도구를 실행하는 데 필요합니다. 현대 웹 개발에서는 코드를 작성한 후 바로 브라우저에서 실행하지 않습니다.

먼저 여러 파일을 하나로 묶고, 최적화하고, 개발 서버를 띄우는 과정이 필요합니다. 이 모든 도구들이 Node.js 위에서 동작합니다.

npm은 Node.js와 함께 설치되는 패키지 관리자입니다. 마치 앱스토어에서 앱을 다운받듯이, npm으로 전 세계 개발자들이 만든 라이브러리를 설치할 수 있습니다.

Phaser도 npm을 통해 설치하게 됩니다. 설치 방법은 두 가지가 있습니다.

첫 번째는 공식 사이트에서 직접 다운로드하는 방법입니다. nodejs.org에 접속하면 LTS 버전과 Current 버전이 보입니다.

LTS는 Long Term Support의 약자로, 안정성이 검증된 버전입니다. 특별한 이유가 없다면 LTS를 선택하세요.

두 번째는 nvm을 사용하는 방법입니다. nvm은 Node Version Manager로, 여러 버전의 Node.js를 설치하고 전환할 수 있게 해줍니다.

프로젝트마다 다른 Node.js 버전이 필요할 때 유용합니다. 설치가 완료되면 터미널에서 버전을 확인해보세요.

node --version과 npm --version 명령어가 정상적으로 결과를 출력하면 성공입니다. 김개발 씨가 터미널에서 버전을 확인했습니다.

"v20.10.0이 나오네요!" 박시니어 씨가 만족스럽게 고개를 끄덕였습니다. "좋아요, 이제 프로젝트를 만들 준비가 됐네요."

실전 팁

💡 - 항상 LTS 버전을 사용하는 것이 안전합니다

• nvm을 사용하면 프로젝트별로 Node.js 버전을 관리할 수 있습니다

---

4. Vite로 프로젝트 생성

Node.js 설치가 완료되었습니다. 이제 프로젝트 폴더를 만들 차례입니다.

김개발 씨가 mkdir my-game이라고 입력하려는 순간, 박시니어 씨가 말렸습니다. "잠깐, 요즘은 그렇게 안 해요.

Vite를 써보세요."

Vite는 차세대 프론트엔드 빌드 도구입니다. 프랑스어로 '빠르다'라는 뜻처럼, 개발 서버 시작과 빌드 속도가 매우 빠릅니다.

Phaser 프로젝트도 Vite로 쉽게 세팅할 수 있습니다. 복잡한 설정 없이 명령어 한 줄로 프로젝트 구조가 완성됩니다.

다음 코드를 살펴봅시다.

# Vite로 프로젝트 생성
npm create vite@latest my-phaser-game

# 선택 옵션
# - framework: Vanilla
# - variant: JavaScript

# 프로젝트 폴더로 이동
cd my-phaser-game

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev
# 출력: Local: http://localhost:5173/

"Vite가 뭔가요?" 김개발 씨가 물었습니다. 박시니어 씨가 설명을 시작했습니다.

예전에는 웹 프로젝트를 시작하려면 Webpack이라는 도구를 복잡하게 설정해야 했습니다. 설정 파일만 수백 줄이 되기도 했고, 프로젝트가 커지면 빌드 시간도 몇 분씩 걸렸습니다.

개발자들의 큰 불만이었습니다. Vite는 이런 문제를 해결하기 위해 만들어졌습니다.

Vue.js의 창시자 Evan You가 개발했으며, 이름 그대로 '빠름'을 추구합니다. 개발 모드에서 ES 모듈을 그대로 사용하기 때문에 서버 시작이 거의 즉시 이루어집니다.

마치 레스토랑에서 음식을 주문할 때를 생각해 보세요. 기존 방식은 모든 재료를 미리 손질해두는 것과 같습니다.

주문이 들어오면 빨리 내보낼 수 있지만, 영업 시작 전 준비 시간이 오래 걸립니다. 반면 Vite는 주문이 들어올 때마다 필요한 재료만 손질합니다.

준비 시간이 거의 없고, 필요한 것만 처리하니 효율적입니다. 위 코드를 따라해 봅시다.

터미널에서 npm create vite@latest my-phaser-game을 입력합니다. 그러면 몇 가지 질문이 나옵니다.

먼저 framework를 선택하라고 합니다. React, Vue, Svelte 등 다양한 옵션이 있지만, 우리는 Vanilla를 선택합니다.

Vanilla란 순수 JavaScript를 의미합니다. Phaser 자체가 프레임워크이므로 React 같은 UI 프레임워크는 필요하지 않습니다.

다음으로 variant를 선택합니다. JavaScript와 TypeScript 중에서 선택할 수 있습니다.

처음 배우는 단계에서는 JavaScript가 더 간단합니다. 선택이 끝나면 프로젝트 폴더가 생성됩니다.

cd my-phaser-game으로 폴더에 들어간 후 npm install을 실행합니다. 이 명령어는 프로젝트에 필요한 기본 패키지들을 설치합니다.

마지막으로 npm run dev를 실행하면 개발 서버가 시작됩니다. 브라우저에서 http://localhost:5173에 접속하면 Vite 환영 페이지를 볼 수 있습니다.

김개발 씨가 브라우저를 열었습니다. "오, 진짜 빠르네요!

서버가 바로 뜨네요." 박시니어 씨가 웃었습니다. "이제 Phaser를 설치할 차례예요."

실전 팁

💡 - Vite는 파일을 수정하면 브라우저가 자동으로 새로고침됩니다

• 프로덕션 빌드는 npm run build 명령어로 실행합니다

---

5. Phaser 패키지 설치

프로젝트 폴더 구조가 만들어졌습니다. 이제 진짜 주인공인 Phaser를 설치할 시간입니다.

김개발 씨가 설레는 마음으로 터미널에 손가락을 올렸습니다. "드디어 Phaser를 설치하는 거군요!"

npm으로 Phaser를 설치하면 node_modules 폴더에 라이브러리가 다운로드됩니다. package.json에 의존성이 기록되어 다른 개발자와 프로젝트를 공유할 때도 같은 환경을 재현할 수 있습니다.

설치 후에는 import 문으로 Phaser를 불러와 사용합니다.

다음 코드를 살펴봅시다.

# Phaser 설치
npm install phaser

# package.json에 추가된 의존성 확인
# "dependencies": {
#   "phaser": "^3.70.0"
# }

# main.js에서 Phaser 불러오기
import Phaser from 'phaser';

// 버전 확인
console.log('Phaser', Phaser.VERSION, 'is ready!');

// 이제 Phaser의 모든 기능 사용 가능
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600
};

드디어 Phaser를 설치하는 순간이 왔습니다. 터미널에 npm install phaser를 입력하고 엔터를 누르세요.

잠시 후 설치가 완료됩니다. 이 과정에서 무슨 일이 일어나는지 살펴봅시다.

npm은 먼저 npm 레지스트리라는 거대한 온라인 저장소에 접속합니다. 그곳에서 phaser라는 이름의 패키지를 찾아 최신 버전을 다운로드합니다.

다운로드된 파일은 프로젝트 폴더의 node_modules 디렉토리에 저장됩니다. 이 폴더를 열어보면 phaser 외에도 수많은 폴더가 있을 것입니다.

Phaser가 내부적으로 사용하는 다른 라이브러리들까지 함께 설치되기 때문입니다. 동시에 package.json 파일도 업데이트됩니다.

dependencies 항목에 "phaser": "^3.70.0"과 같은 내용이 추가됩니다. 이것이 바로 의존성 기록입니다.

왜 이렇게 기록을 남길까요? 마치 요리 레시피와 같습니다.

레시피에 "소금 적당량"이라고 적으면 매번 맛이 달라집니다. 하지만 "소금 5g"이라고 적으면 누가 만들어도 같은 맛을 낼 수 있습니다.

package.json에 버전을 기록해두면, 다른 개발자가 프로젝트를 받아서 npm install만 실행해도 똑같은 환경이 구성됩니다. 팀 프로젝트에서 매우 중요한 부분입니다.

이제 설치된 Phaser를 코드에서 사용해 봅시다. src/main.js 파일을 열고 맨 위에 import Phaser from 'phaser'를 추가합니다.

ES6 모듈 문법으로 Phaser 라이브러리 전체를 불러오는 것입니다. 제대로 설치되었는지 확인하고 싶다면 console.log로 버전을 출력해 보세요.

브라우저 개발자 도구의 콘솔에서 Phaser 3.70.0 is ready! 같은 메시지가 보이면 성공입니다.

김개발 씨가 콘솔을 확인했습니다. "Phaser 3.70.0이라고 나와요!" 이제 모든 준비가 끝났습니다.

다음 단계에서 드디어 게임 화면을 띄워봅시다.

실전 팁

💡 - node_modules 폴더는 git에 커밋하지 마세요. .gitignore에 추가되어 있어야 합니다

• package-lock.json 파일은 정확한 버전 정보를 담고 있으니 함께 커밋하세요

---

6. 첫 번째 게임 화면 띄우기

모든 준비가 완료되었습니다. Node.js 설치, Vite 프로젝트 생성, Phaser 패키지 설치까지 마쳤습니다.

이제 대망의 순간입니다. 김개발 씨의 손이 떨립니다.

"드디어 게임 화면을 띄워보는 거죠?" 박시니어 씨가 고개를 끄덕였습니다. "코드 몇 줄이면 돼요."

Phaser 게임은 설정 객체와 Scene 클래스로 구성됩니다. config 객체에서 화면 크기와 Scene을 지정하고, Phaser.Game 생성자로 게임을 시작합니다.

Scene의 create 메서드에서 텍스트나 이미지를 화면에 추가할 수 있습니다.

다음 코드를 살펴봅시다.

// src/main.js
import Phaser from 'phaser';

// 메인 게임 Scene 정의
class MainScene extends Phaser.Scene {
    constructor() {
        super({ key: 'MainScene' });
    }

    create() {
        // 화면 중앙에 환영 텍스트 추가
        this.add.text(400, 300, 'Hello Phaser!', {
            fontSize: '48px',
            color: '#ffffff'
        }).setOrigin(0.5);  // 텍스트 중앙 정렬
    }
}

// 게임 설정
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#2d2d2d',
    scene: MainScene
};

// 게임 시작!
new Phaser.Game(config);

박시니어 씨가 키보드를 가리켰습니다. "자, 이제 main.js를 완전히 새로 작성해 볼까요?" 먼저 Vite가 자동으로 생성한 기존 코드를 모두 지웁니다.

그리고 import Phaser from 'phaser'로 시작합니다. 이 한 줄로 Phaser의 모든 기능을 사용할 준비가 됩니다.

다음으로 Scene 클래스를 만듭니다. Scene은 게임의 한 장면이라고 생각하면 됩니다.

영화로 치면 하나의 씬과 같습니다. 메인 메뉴, 게임 플레이, 게임 오버 화면 등을 각각 다른 Scene으로 만들 수 있습니다.

MainScene 클래스는 Phaser.Scene을 상속받습니다. 생성자에서 super({ key: 'MainScene' })을 호출하는데, 이 key는 Scene을 구분하는 고유한 이름입니다.

나중에 Scene을 전환할 때 이 이름을 사용합니다. create 메서드는 Scene이 시작될 때 한 번 호출됩니다.

여기서 게임에 필요한 오브젝트들을 생성합니다. this.add.text로 텍스트를 추가했습니다.

첫 번째, 두 번째 인자는 x, y 좌표입니다. 세 번째는 표시할 문자열, 네 번째는 스타일 옵션입니다.

**.setOrigin(0.5)**는 중요한 메서드입니다. 기본적으로 텍스트는 좌상단을 기준점으로 배치됩니다.

하지만 setOrigin(0.5)를 호출하면 텍스트의 중앙이 기준점이 됩니다. 따라서 (400, 300) 좌표에 텍스트 중앙이 위치하게 됩니다.

이제 config 객체를 살펴봅시다. type: Phaser.AUTO는 렌더링 방식을 자동으로 선택합니다.

WebGL을 지원하면 WebGL을, 아니면 Canvas를 사용합니다. width와 height는 게임 화면의 크기를 픽셀 단위로 지정합니다.

backgroundColor는 게임 배경색입니다. 16진수 색상 코드를 문자열로 입력합니다.

scene 속성에는 우리가 만든 MainScene 클래스를 넣습니다. 배열로 여러 Scene을 등록할 수도 있습니다.

마지막으로 new Phaser.Game(config)를 호출하면 게임이 시작됩니다. Phaser는 자동으로 index.html의 body에 canvas 요소를 추가하고 게임을 렌더링합니다.

터미널에서 npm run dev가 실행 중인 상태에서 브라우저를 새로고침해 보세요. 회색 배경에 'Hello Phaser!'라는 흰색 텍스트가 화면 중앙에 나타날 것입니다.

김개발 씨의 눈이 빛났습니다. "화면에 글자가 떴어요!

드디어 게임 개발을 시작한 거네요!" 박시니어 씨가 웃었습니다. "축하해요.

이제 여기에 이미지를 추가하고, 움직임을 넣고, 게임 로직을 만들면 되는 거예요." 첫 발을 내딛었습니다. 지금은 텍스트 하나뿐이지만, 이 구조 위에 캐릭터, 적, 아이템, 배경을 하나씩 추가하다 보면 어느새 완성된 게임이 될 것입니다.

여러분의 Phaser 여정이 시작되었습니다.

실전 팁

💡 - 브라우저 개발자 도구(F12)를 열어 에러 메시지를 확인하는 습관을 들이세요

• create 외에도 preload, update 메서드를 활용하면 더 복잡한 게임을 만들 수 있습니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!