개발 환경은 게임을 실행하는 출발선이다
앞 장에서는 Phaser가 브라우저에서 실행되는 2D 게임 프레임워크라는 큰 그림을 살펴보았다. 이제는 그 설명을 실제 화면으로 확인할 차례다. 게임 개발은 머릿속에서만 이해하면 금방 흐릿해진다. 작은 사각형 하나라도 브라우저에 띄우고, 키보드로 움직여 보면 Phaser가 어떤 방식으로 일하는지 훨씬 분명해진다.
이 장의 목표는 거창하지 않다. 개발 도구를 준비하고, Phaser 프로젝트를 하나 만들고, 브라우저에서 첫 화면을 실행하는 것이다. 아직 물리 엔진, 애니메이션, 충돌 같은 기능은 깊게 다루지 않는다. 먼저 "내 컴퓨터에서 Phaser 게임이 돌아가는 상태"를 만드는 것이 중요하다.
처음 환경을 만들 때는 낯선 단어가 많이 나온다. Node.js, npm, Vite, 개발 서버 같은 말이 한꺼번에 등장한다. 하지만 모두를 깊게 이해해야 시작할 수 있는 것은 아니다. 지금은 각각을 다음처럼 생각하면 충분하다.
Node.js: 개발 도구를 실행하기 위한 자바스크립트 실행 환경
npm: Phaser와 개발 도구를 설치하고 실행하는 패키지 관리자
Vite: 코드를 수정하면 빠르게 브라우저에 반영해 주는 개발 서버 도구
브라우저: 완성된 게임이 실제로 실행되는 장소
AI 생성 이미지
무엇을 설치해야 할까
Phaser 자체는 브라우저에서 실행되지만, 개발할 때는 몇 가지 도구가 필요하다. 가장 기본적인 준비물은 다음과 같다.
최신 브라우저
코드 편집기
Node.js와 npm
터미널 또는 명령 프롬프트
브라우저는 Chrome, Edge, Firefox 같은 최신 브라우저면 충분하다. 코드 편집기는 Visual Studio Code를 많이 사용하지만, 익숙한 편집기가 있다면 그것을 써도 된다. 중요한 것은 프로젝트 폴더를 열고, 파일을 수정하고, 터미널 명령을 실행할 수 있으면 된다는 점이다.
Node.js는 가능하면 LTS 버전을 설치하는 것이 좋다. LTS는 장기 지원 버전이라는 뜻으로, 실험적인 최신 기능보다 안정성을 우선한다. Node.js를 설치하면 보통 npm도 함께 설치된다. 설치가 끝난 뒤 터미널에서 다음 명령을 입력해 보자.
node -v
npm -v각각 버전 번호가 나오면 기본 준비는 된 것이다. 예를 들어 v22.0.0처럼 Node.js 버전이 나오고, 그 아래에 npm 버전이 표시되면 정상이다. 만약 "명령을 찾을 수 없다"는 메시지가 나온다면 설치가 제대로 끝나지 않았거나, 터미널을 설치 전에 열어 둔 상태일 수 있다. 이럴 때는 터미널을 닫았다가 다시 열어 보고, 그래도 안 되면 Node.js 설치를 다시 확인하면 된다.
프로젝트를 만드는 가장 쉬운 방법
Phaser를 시작하는 방법은 여러 가지다. HTML 파일에 CDN 스크립트를 직접 넣어도 되고, npm으로 phaser 패키지만 설치해도 된다. 하지만 처음 시작할 때는 공식 프로젝트 생성 도구를 쓰는 편이 가장 편하다. Phaser 공식 문서에서도 빠르게 시작하는 방법으로 Create Phaser Game 앱을 안내한다.1
터미널에서 작업할 폴더로 이동한 뒤 다음 명령을 실행해 보자.
npm create @phaserjs/game@latest phaser-first-game여기서 phaser-first-game은 새로 만들 프로젝트 폴더 이름이다. 다른 이름을 써도 된다. 명령을 실행하면 몇 가지 질문이 나올 수 있다. 처음이라면 다음 방향으로 선택하면 무난하다.
프로젝트 종류는 기본 Phaser 게임 또는 Web Bundler 계열 선택
번들러는 Vite 선택
언어는 JavaScript 선택
예제 게임보다는 빈 템플릿 또는 기본 템플릿 선택
공식 튜토리얼에서도 처음 사용하는 사람에게 Web Bundler와 Vite 조합을 추천한다.2 TypeScript는 뒤에서 따로 다룰 예정이므로, 지금은 JavaScript로 시작하는 편이 흐름을 따라가기 쉽다.
프로젝트가 만들어졌다면 폴더 안으로 들어간다.
cd phaser-first-game그다음 의존성을 설치하고 개발 서버를 실행한다.
npm install
npm run dev생성 도구나 템플릿에 따라 이미 설치가 끝나 있을 수도 있다. 그래도 npm install을 한 번 실행해 두면 빠진 패키지를 확인할 수 있어 안전하다. npm run dev를 실행하면 터미널에 보통 다음과 비슷한 주소가 표시된다.
Local: http://localhost:5173/브라우저에서 이 주소를 열면 Phaser 프로젝트의 첫 화면이 나타난다. 포트 번호는 환경에 따라 5173이 아닐 수도 있다. 터미널에 표시된 주소를 그대로 여는 것이 가장 정확하다.
개발 서버는 왜 필요할까
처음 웹을 배울 때는 HTML 파일을 더블 클릭해서 브라우저로 열어 본 경험이 있을 수 있다. 간단한 정적 문서는 그렇게 열어도 보이는 경우가 많다. 하지만 Phaser 프로젝트는 보통 여러 자바스크립트 모듈과 에셋 파일을 함께 사용한다. 이때 파일을 직접 여는 file:// 방식은 모듈 불러오기나 이미지 로딩에서 예상치 못한 문제를 만들 수 있다.
개발 서버는 내 컴퓨터 안에서 작은 웹 서버를 띄워 주는 역할을 한다. http://localhost:5173/ 같은 주소로 접속하지만, 이것은 외부 인터넷에 공개된 사이트가 아니다. 내 컴퓨터에서만 확인하는 개발용 주소라고 생각하면 된다.
개발 서버의 또 다른 장점은 수정 사항을 빠르게 확인할 수 있다는 점이다. Vite를 사용하면 코드를 저장했을 때 브라우저가 자동으로 갱신되거나, 변경된 부분이 빠르게 반영된다. 게임을 만들 때는 "조금 수정하고, 바로 실행해 보고, 다시 고치는" 과정이 매우 많다. 개발 서버는 이 반복을 훨씬 편하게 만들어 준다.
프로젝트 폴더를 처음 보는 법
생성된 프로젝트를 코드 편집기로 열면 여러 파일과 폴더가 보인다. 템플릿에 따라 이름은 조금씩 다를 수 있지만, 대체로 다음 구조를 만난다.
phaser-first-game/
package.json
index.html
src/
main.js
public/
node_modules/package.json은 프로젝트의 설정표에 가깝다. 어떤 패키지를 쓰는지, 어떤 명령으로 개발 서버를 실행하는지 같은 정보가 들어 있다. npm run dev가 동작하는 이유도 이 파일 안에 dev 명령이 정의되어 있기 때문이다.
index.html은 브라우저가 처음 여는 HTML 문서다. Phaser 게임도 결국 웹페이지 안에서 실행되므로 HTML 파일이 필요하다. 다만 실제 게임 로직은 대부분 src 폴더 안의 자바스크립트 파일에 들어간다.
src/main.js는 게임이 시작되는 입구 역할을 하는 경우가 많다. 템플릿에 따라 src/game.js, src/scenes 같은 구조가 있을 수도 있다. 지금은 파일 구조를 완벽히 외울 필요가 없다. "HTML이 자바스크립트를 불러오고, 그 자바스크립트에서 Phaser 게임을 시작한다"는 흐름만 잡으면 된다.
public 폴더는 이미지나 사운드 같은 정적 파일을 넣는 용도로 자주 사용된다. node_modules는 npm이 설치한 패키지들이 들어가는 폴더다. 이 폴더는 직접 수정하지 않는다. 문제가 생겼을 때 지우고 다시 설치할 수는 있지만, 게임 코드를 작성하는 곳은 아니다.
가장 작은 게임 코드로 바꿔 보기
이제 화면에 글자와 사각형을 띄우고, 방향키로 사각형을 움직이는 아주 작은 예제를 만들어 보자. 생성된 템플릿의 구조가 다를 수 있으므로, 먼저 src/main.js 또는 게임을 시작하는 파일을 찾는다. 연습용 프로젝트라면 그 파일 내용을 잠시 다음 코드로 바꿔도 괜찮다.
import Phaser from 'phaser';
class MainScene extends Phaser.Scene {
constructor() {
super('MainScene');
}
create() {
this.add.text(400, 70, 'Hello Phaser!', {
fontFamily: 'Arial',
fontSize: '40px',
color: '#ffffff'
}).setOrigin(0.5);
this.add.text(400, 125, '방향키로 네모를 움직여 보세요.', {
fontFamily: 'Arial',
fontSize: '20px',
color: '#cbd5e1'
}).setOrigin(0.5);
this.player = this.add.rectangle(400, 260, 64, 64, 0x4ade80);
this.cursors = this.input.keyboard.createCursorKeys();
}
update() {
const speed = 4;
if (this.cursors.left.isDown) {
this.player.x -= speed;
} else if (this.cursors.right.isDown) {
this.player.x += speed;
}
if (this.cursors.up.isDown) {
this.player.y -= speed;
} else if (this.cursors.down.isDown) {
this.player.y += speed;
}
}
}
const config = {
type: Phaser.AUTO,
width: 800,
height: 450,
backgroundColor: '#111827',
scene: [MainScene]
};
new Phaser.Game(config);파일을 저장하고 브라우저를 확인해 보자. 개발 서버가 계속 실행 중이라면 화면이 자동으로 갱신될 것이다. 짙은 배경 위에 Hello Phaser!라는 글자가 보이고, 초록색 네모가 나타나야 한다. 방향키를 누르면 네모가 위, 아래, 왼쪽, 오른쪽으로 움직인다.
이 예제는 매우 작지만 Phaser 게임의 기본 흐름을 이미 포함하고 있다.
Phaser.Scene을 상속한MainScene이 하나의 게임 장면이 된다.create()에서 처음 화면에 필요한 글자와 사각형을 만든다.update()에서 매 프레임 키 입력을 확인하고 사각형 위치를 바꾼다.config에 화면 크기와 실행할 Scene을 적는다.new Phaser.Game(config)로 게임을 시작한다.
지금은 각 줄을 모두 외우지 않아도 된다. 중요한 것은 코드를 바꾸면 브라우저 화면이 바뀐다는 경험이다. Phaser를 배운다는 것은 결국 이 과정을 반복하는 일이다. 화면에 무언가를 만들고, 입력에 반응하게 하고, 규칙을 붙이고, 점점 게임처럼 다듬어 간다.
코드가 바로 보이지 않을 때 확인할 것
처음 프로젝트를 실행하면 작은 문제를 자주 만난다. 대부분은 Phaser 자체의 어려움이라기보다 개발 환경이 아직 익숙하지 않아서 생기는 문제다. 당황하지 말고 다음 순서로 확인해 보자.
먼저 터미널을 확인한다. npm run dev를 실행한 터미널에 빨간색 오류가 있는지 본다. 패키지가 설치되지 않았다는 메시지가 보이면 npm install을 다시 실행한 뒤 개발 서버를 다시 켠다.
브라우저 화면이 하얗게 비어 있다면 개발자 도구의 Console 탭을 확인한다. Chrome이나 Edge에서는 보통 F12를 누르면 개발자 도구가 열린다. 자바스크립트 문법 오류, import 경로 오류, 파일을 찾을 수 없다는 오류가 여기에 표시된다. 오류 메시지는 처음에는 불친절해 보이지만, 대개 어떤 파일의 몇 번째 줄에서 문제가 생겼는지 알려 준다.
브라우저 주소도 확인해야 한다. 파일을 더블 클릭해서 연 주소가 아니라, 개발 서버가 알려 준 http://localhost:... 주소로 접속해야 한다. 또 터미널에서 개발 서버를 종료하면 브라우저를 새로고침해도 프로젝트가 제대로 열리지 않는다. 개발 중에는 npm run dev를 실행한 터미널을 계속 열어 둔다.
마지막으로 파일 이름의 대소문자를 조심하자. 어떤 운영체제에서는 Player.png와 player.png를 같은 파일처럼 취급하지만, 배포 환경에서는 다르게 취급될 수 있다. 지금 예제는 이미지 파일을 쓰지 않지만, 뒤에서 에셋을 불러올 때 이런 차이가 문제를 만들 수 있다.
CDN으로도 시작할 수 있을까
가능하다. Phaser는 CDN 스크립트로도 사용할 수 있다. HTML 파일에 Phaser 스크립트를 넣고, 그 아래에 게임 코드를 작성하면 된다. 아주 작은 실험이나 코드 공유에는 이 방식이 편할 때도 있다.
하지만 이 책에서는 기본적으로 npm과 Vite를 사용하는 흐름을 중심으로 진행한다. 이유는 간단하다. 게임이 조금만 커져도 파일을 나누고, 이미지를 관리하고, 빌드하고, 배포하는 과정이 필요해진다. npm 기반 프로젝트는 이런 작업으로 자연스럽게 이어진다. 특히 뒤에서 TypeScript, 프로젝트 구조화, 빌드와 배포를 다룰 때 같은 흐름을 유지할 수 있다.
CDN 방식이 틀린 것은 아니다. 다만 학습 초반부터 실제 프로젝트에 가까운 구조를 익히는 편이 나중에 덜 헷갈린다.
이 장에서 기억할 것
이 장에서는 Phaser 프로젝트를 만들고, 개발 서버를 실행하고, 브라우저에서 첫 게임 화면을 확인했다. 아직 만든 것은 글자와 네모 하나뿐이지만, 중요한 첫 단계를 넘었다. 이제 여러분의 컴퓨터에는 Phaser 코드를 수정하고 바로 결과를 볼 수 있는 작업 공간이 생겼다.
앞으로의 예제는 이 환경 위에서 진행된다. 새 기능을 배울 때마다 완전히 다른 준비를 반복하는 것이 아니라, 지금 만든 흐름 위에 이미지를 올리고, 입력을 붙이고, 충돌을 만들고, 장면을 나누게 된다.
다음으로는 방금 사용한 config, Scene, preload, create, update가 서로 어떤 관계인지 차근차근 살펴본다. 첫 실행이 끝났다면 이제 Phaser 게임의 기본 구조를 이해할 준비가 된 것이다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.