게임만들기-구현: 벽돌깨기 게임 실행 파일 만들기

step08.py로 완성한 벽돌깨기 게임을 PyInstaller로 패키징(packaging)하여, 파이썬이 설치되지 않은 컴퓨터에서도 실행할 수 있는 배포용 파일로 만든다.

---

1. 학습 목표

이 장에서는 파이썬과 pygame으로 제작한 벽돌깨기 게임을 실행 파일로 만드는 방법을 학습한다. 지금까지 작성한 step08.py는 파이썬 실행 환경에서 동작하는 소스 코드이다. 그러나 완성된 게임을 다른 사람에게 전달하려면 사용자가 직접 파이썬을 설치하고, 필요한 라이브러리를 설치하고, 터미널에서 명령을 입력하여 실행하여야 한다.

이번 장에서는 이러한 과정을 줄이기 위하여 PyInstaller를 사용한다. PyInstaller는 파이썬 프로그램과 실행에 필요한 파일들을 하나의 배포 묶음으로 만들어 주는 도구이다. 이를 활용하면 학생은 자신이 만든 게임을 실행 파일 형태로 저장하고, 다른 사람에게 전달할 수 있다. 

실행 파일 만들기는 단순히 파일 확장자를 바꾸는 작업이 아니다. 파이썬 코드, 필요한 라이브러리, 이미지 파일, 사운드 파일을 함께 묶어 하나의 실행 가능한 프로그램으로 만드는 과정이다. 이러한 과정을 패키징(packaging)이라고 한다.

• 첫째, 파이썬 파일과 실행 파일의 차이를 설명할 수 있다.
• 둘째, 게임 배포에 필요한 asset 폴더의 역할을 이해할 수 있다.
• 셋째, PyInstaller를 설치하고 기본 빌드 명령을 실행할 수 있다.
• 넷째, step08.py를 실행 파일로 변환할 수 있다.
• 다섯째, 배포 과정에서 발생하는 대표적인 오류를 점검할 수 있다.

---

2. 프로젝트 폴더 구조 확인

실행 파일을 만들기 전에 프로젝트 폴더 구조를 확인하여야 한다. 이번 실습의 기본 폴더 구조는 다음과 같다.

brick_game/
├─ step08.py
└─ asset/
   ├─ background.png
   ├─ bgm.mp3
   ├─ hit.wav
   ├─ paddle.wav
   ├─ miss.wav
   ├─ game_over.wav
   └─ clear.wav

여기서 step08.py는 게임의 소스 코드이고, asset 폴더는 게임에 사용되는 이미지와 사운드 파일을 보관하는 폴더이다. 벽돌깨기 게임은 배경 이미지와 여러 효과음을 사용하므로, 실행 파일을 만들 때 asset 폴더도 함께 포함하여야 한다.

---

3. 가상환경 준비하기

실습에서는 프로젝트별로 독립된 파이썬 실행 환경을 사용하는 것이 좋다. 이를 가상환경(virtual environment)이라고 한다. 가상환경을 사용하면 다른 수업이나 다른 프로젝트에서 설치한 라이브러리와 충돌하지 않고, 현재 게임에 필요한 라이브러리만 관리할 수 있다.

VS Code 터미널에서 프로젝트 폴더로 이동한 뒤 다음 명령을 입력한다.

py -m venv .venv

가상환경을 실행하려면 다음 명령을 입력한다.

.venv\Scripts\activate

가상환경이 실행되면 터미널 앞쪽에 (.venv)와 같은 표시가 나타난다. 이 상태에서 설치하는 라이브러리는 현재 프로젝트의 가상환경 안에 설치된다.

---

4. 필요한 라이브러리 설치하기

벽돌깨기 게임을 실행하려면 pygame이 필요하다. 또한 실행 파일을 만들기 위하여 PyInstaller가 필요하다.

py -m pip install pygame pyinstaller

설치가 끝나면 다음 명령으로 PyInstaller가 정상적으로 설치되었는지 확인한다.

pyinstaller --version

버전 번호가 출력되면 설치가 완료된 것이다.

---

5. 먼저 step08.py 실행 확인하기

패키징하기 전에 반드시 원본 파이썬 파일이 정상적으로 실행되는지 확인하여야 한다.

py step08.py

이 단계에서 게임이 실행되지 않으면 실행 파일을 만들어도 정상 동작하지 않는다. 따라서 패키징 전에 다음을 확인한다.

• 첫째, 게임 창이 열리는가.
• 둘째, 배경 이미지가 출력되는가.
• 셋째, BGM이 재생되는가.
• 넷째, 공과 패들이 정상적으로 동작하는가.
• 다섯째, 게임 오버와 게임 클리어 화면이 정상적으로 출력되는가.

---

6. 배포용 경로 처리 함수 추가하기

파이썬 파일을 직접 실행할 때와 실행 파일로 묶어서 실행할 때는 파일을 찾는 기준 위치가 달라질 수 있다. 따라서 이미지나 사운드 파일을 안정적으로 찾기 위한 경로 처리 함수가 필요하다.

step08.py를 복사하여 step09.py로 저장한 뒤, 상단에 다음 코드를 추가한다.

from pathlib import Path  # ADDED

그리고 전역변수 위쪽에 다음 함수를 추가한다.

# ADDED 실행 파일 배포 시에도 asset 경로를 찾기 위한 함수
def resource_path(relative_path):
    base_path = Path(__file__).resolve().parent
    return str(base_path / relative_path)

이 함수는 현재 실행 중인 파이썬 파일의 위치를 기준으로 asset 폴더 안의 파일을 찾도록 도와준다.

• 기존의 이미지 불러오기 코드는 다음과 같이 수정한다.

background_img = pygame.image.load(resource_path("asset/background.png")).convert()

• BGM과 효과음 파일도 다음과 같이 수정한다.

pygame.mixer.music.load(resource_path("asset/bgm.mp3"))

hit_sound = pygame.mixer.Sound(resource_path("asset/hit.wav"))
paddle_sound = pygame.mixer.Sound(resource_path("asset/paddle.wav"))
miss_sound = pygame.mixer.Sound(resource_path("asset/miss.wav"))
game_over_sound = pygame.mixer.Sound(resource_path("asset/game_over.wav"))
clear_sound = pygame.mixer.Sound(resource_path("asset/clear.wav"))

이처럼 경로를 함수로 처리하면, 소스 코드로 실행할 때와 실행 파일로 실행할 때 모두 같은 방식으로 파일을 찾을 수 있다.

---

7. 폴더 방식으로 실행 파일 만들기

처음 실습에서는 하나의 실행 파일 방식보다 폴더 방식으로 배포하는 것이 좋다. 폴더 방식은 실행 파일과 필요한 내부 파일들이 하나의 폴더 안에 함께 들어 있는 구조이다.

다음 명령을 입력한다.

pyinstaller --windowed --name BrickBreaker --add-data "asset:asset" step09.py

각 옵션의 의미는 다음과 같다.

• --windowed는 게임 실행 시 콘솔 창이 함께 뜨지 않도록 하는 옵션이다. pygame 게임처럼 별도의 창을 사용하는 프로그램에 적합하다.
• --name BrickBreaker는 만들어질 실행 파일의 이름을 BrickBreaker로 지정한다.
• --add-data "asset:asset"은 현재 프로젝트의 asset 폴더를 배포 파일 안에도 asset 폴더로 포함하라는 의미이다.
• step09.py는 실행 파일로 만들 파이썬 소스 파일이다.

명령 실행이 끝나면 다음과 같은 폴더가 생성된다.

dist/
└─ BrickBreaker/
   ├─ BrickBreaker.exe
   └─ _internal/

• 실제 실행 파일은 다음 위치에 있다.

dist/BrickBreaker/BrickBreaker.exe

---

8. 실행 파일 테스트하기

실행 파일이 만들어졌다면 dist 폴더 안으로 이동하여 BrickBreaker.exe를 실행한다.

테스트할 때는 다음 항목을 확인한다.

• 첫째, 실행 파일을 더블클릭하였을 때 게임 창이 열리는가.
• 둘째, 배경 이미지가 출력되는가.
• 셋째, BGM이 재생되는가.
• 넷째, 벽돌 충돌 효과음과 패들 충돌 효과음이 재생되는가.
• 다섯째, 게임 오버와 게임 클리어 효과음이 재생되는가.
• 여섯째, R 키로 재시작하고 ESC 키로 종료할 수 있는가.

이 과정을 통하여 자신이 만든 프로그램이 개발 환경 밖에서도 실행될 수 있음을 확인할 수 있다.

---

9. 하나의 실행 파일로 만들기

폴더 방식이 정상적으로 동작하면, 하나의 실행 파일 방식도 시도할 수 있다.

pyinstaller --onefile --windowed --name BrickBreaker --add-data "asset:asset" step09.py

이 명령은 dist 폴더 안에 하나의 실행 파일을 만든다.

dist/
└─ BrickBreaker.exe

하나의 파일로 만들어지면 전달하기는 편리하지만, 실행할 때 내부 파일을 임시 위치에 풀어서 실행하므로 처음 실행 속도가 느릴 수 있다. 또한 이미지나 사운드 파일 경로 문제가 발생하면 원인을 찾기 어려울 수 있다. 따라서 실습에서는 먼저 폴더 방식으로 성공한 뒤, 하나의 실행 파일 방식을 추가로 실습하는 것이 좋다.

---

10. 자주 발생하는 오류와 해결 방법

이미지나 사운드가 나오지 않는 경우

가장 흔한 원인은 asset 폴더가 배포 파일에 포함되지 않은 경우이다. 이때는 빌드 명령에 다음 옵션이 포함되어 있는지 확인한다.

--add-data "asset:asset"

• 또한 코드에서 파일 경로를 직접 문자열로만 쓰고 있지 않은지 확인한다.

잘못된 예는 다음과 같다.

pygame.image.load("asset/background.png")

배포를 고려한 예는 다음과 같다.

pygame.image.load(resource_path("asset/background.png"))

실행 파일을 클릭하여도 아무 반응이 없는 경우

--windowed 옵션을 사용하면 오류 메시지가 콘솔 창에 표시되지 않는다. 이 경우에는 임시로 --windowed 옵션을 제거하고 다시 빌드하여 오류 메시지를 확인할 수 있다.

pyinstaller --name BrickBreaker --add-data "asset:asset" step09.py

이렇게 하면 실행 시 콘솔 창이 함께 열리므로 오류 메시지를 확인하기 쉽다.

다른 운영체제에서 실행되지 않는 경우

Windows에서 만든 .exe 파일은 Windows용 실행 파일이다. macOS나 Linux에서 실행하려면 해당 운영체제에서 다시 빌드하여야 한다. 실행 파일은 운영체제에 따라 다르게 만들어지기 때문이다.