파이썬 게임을 링크로 공유하기, Pyxel 실행 링크와 HTML의 차이

세 줄 요약

Pyxel로 만든 게임은 GitHub 파일을 가리키는 실행 링크나 내보낸 HTML로 공유할 수 있다.
실행 링크는 최신 Pyxel을 쓴다. HTML은 변환에 사용한 버전을 불러오므로 인터넷 연결이 필요하다.
코드와 리소스를 패키지로 묶고, 휴대폰에 전달할 때는 가상 게임패드와 실제 조작을 확인한다.

빨리 공유하려면 실행 링크, 변환한 버전을 쓰려면 HTML

친구에게 작은 Python 게임을 보여 주는데 Python 설치부터 부탁해야 한다면 공유가 번거로워진다. Pyxel은 픽셀 그림과 사운드 편집기를 갖춘 레트로 게임 엔진이며, 만든 게임을 브라우저에서 실행하는 방법도 제공한다. 제작자가 10월 Hacker News에 다시 소개한 기능 중 하나다.

완성한 게임을 전달할 때의 대표적인 선택은 Web Launcher와 app2html이다. 공식 웹 사용 안내에서 두 방식의 차이는 파일 형태뿐 아니라 어떤 버전의 엔진으로 실행하느냐에 있다.

선택	전달할 것	실행할 Pyxel
Web Launcher	GitHub의 Python 파일 또는 .pyxapp을 가리키는 URL이다.	최신 버전을 사용한다.
app2html	코드와 리소스를 넣은 HTML 파일이다.	변환에 사용한 버전을 인터넷에서 불러온다.

저장소에 올린 게임을 곧바로 열게 하려면 Launcher가 간단하다. HTML 변환 때 사용한 엔진 버전으로 실행되는 파일을 배포하려면 HTML 내보내기가 맞는다. HTML 하나로 묶인다고 오프라인 게임이 되는 것은 아니다.

그림과 소리도 게임 폴더에 넣는다

로컬에서 제작할 때는 사용자 가이드 기준 Python 3.11 이상이 필요하다. 실행자에게 필요한 브라우저 환경과 제작자의 Python 환경은 다르다. Pyxel Editor로 만든 그림·소리 데이터는 .pyxres 파일에 저장한다.

게임 폴더의 코드와 필요한 리소스를 묶는 명령은 다음과 같다. APP_DIR에는 게임 폴더를, STARTUP_SCRIPT_FILE에는 시작할 Python 파일 경로를 넣는다. 대문자는 실제 파일명으로 바꿔야 하는 자리다.

pyxel package APP_DIR STARTUP_SCRIPT_FILE

생성된 .pyxapp 파일은 pyxel play로 열 수 있고 HTML 변환의 입력으로도 쓴다. 공식 안내는 여러 Python 파일로 구성한 앱을 패키지로 묶어 Launcher의 play로 실행하면 로딩이 빨라진다고 설명한다.

필요한 리소스와 추가 모듈은 게임 폴더 안에 둔다. 패키징에서는 GIF·ZIP, 숨김 파일과 디렉터리, __pycache__ 디렉터리를 제외한다. 필요한 게임 데이터가 제외 대상에 들어 있지 않은지 확인해야 한다.

파일 확장자를 뺀 경로로 실행한다

Web Launcher의 URL Builder에 GitHub 파일 정보를 넣으면 실행 링크를 만들 수 있다. Python 파일은 run, 패키지는 play를 사용한다. 다음은 공식 문서가 든 가상 저장소 예이며 실제 게임 배포 주소는 아니다.

https://kitao.dev/pyxel/launcher/?run=taro/my_repo/main/src/scenes/title
https://kitao.dev/pyxel/launcher/?play=taro/my_repo/main/dist/games/shooter

첫 URL은 title.py, 둘째는 shooter.pyxapp을 가리킨다. 파일명 끝의 확장자는 URL에서 뺀다. 브랜치 이름에 슬래시가 있거나 경로에 특수문자가 있다면 직접 이어 붙이기보다 Builder를 쓰는 편이 낫다. 공식 도구가 브랜치와 파일 경로의 경계를 처리한다.

Launcher는 최신 엔진을 사용하므로, 오래된 게임을 계속 공유할 때도 링크를 열어 동작을 확인할 필요가 있다. 지금 만든 파일에 사용한 버전과 연결된 실행 환경의 버전이 항상 같은 것은 아니다.

HTML 하나를 올려도 엔진을 받는 연결은 남는다

HTML로 배포하려면 생성한 패키지에 다음 명령을 적용한다. your_app.pyxapp은 자기 패키지 파일명으로 바꾼다.

pyxel app2html your_app.pyxapp

생성된 HTML에는 앱 코드와 리소스가 들어가므로 게시할 게임 파일은 하나다. 그러나 공식 문서의 HTML 설명에 따르면 실행 시 변환에 사용한 Pyxel 버전을 kitao.dev에서 내려받는다. 인터넷이 끊긴 환경에 전달할 파일로 이해하면 안 된다.

휴대폰용 가상 게임패드는 HTML 내보내기에서 기본으로 활성화되고 터치 기기에서 나타난다. Launcher에서는 URL에 gamepad=enabled를 추가한다. 실제 게임이 쓰는 입력을 휴대폰에서도 조작할 수 있는지는 보내기 전에 직접 확인해야 한다.

자기 웹페이지 안에 게임을 넣고 싶다면 HTML Custom Elements라는 별도 방법도 있다. 외부 파일을 읽는 이 방식은 브라우저 보안 제한 때문에 로컬 파일을 바로 여는 대신 웹서버를 사용한다. 단순 공유가 목적이면 실행 링크나 내보낸 HTML부터 고르면 된다. 받는 사람의 설치 부담을 줄이되, 엔진 버전과 네트워크 조건까지 맞추는 것이 배포의 마지막 단계다.