웹 / HTML5
Ren'Py는 웹 브라우저에서 게임을 실행할 수 있습니다. WebAssembly로 컴파일한 Ren'Py를 사용하여 가능한 많은 기능을 브라우저 안에서 실행합니다. 이 페이지에서는 브라우저 실행 환경의 제약, 원활하게 실행되는 게임을 설계하는 방법, 웹용 게임을 빌드하는 방법을 설명합니다.
제약 사항
웹 브라우저에서 실행되는 다른 게임과 마찬가지로 Ren'Py 게임에도 여러 제약이 있습니다. 일부는 브라우저의 샌드박스가 부과하는 제약이고, 일부는 게임 시작 전에 다운로드해야 하는 데이터의 양을 줄이기 위해 정한 제약입니다.
주요 제약 사항은 다음과 같습니다.
동영상은 브라우저의 내장 동영상 재생 기능으로 재생합니다. 따라서 해당 브라우저가 지원하는 형식만 재생할 수 있으며,
renpy.movie_cutscene()만 지원합니다.오디오 재생에는 빠른 브라우저 오디오 기능을 사용하거나, 속도는 느리지만 더 많은 형식을 지원하는 Ren'Py 내장 오디오 재생 기능을 사용할 수 있습니다. 아래 설명을 참조하세요.
웹 버전은 멀티스레딩을 지원하지 않으므로
renpy.invoke_in_thread()같은 함수와 Python의threading모듈을 사용할 수 없습니다. 이 때문에 일부 게임의 성능이 제한될 수도 있습니다. 데스크톱 및 모바일용 Ren'Py에서는 백그라운드에서 이미지를 미리 로드할 수 있지만 웹 버전에서는 불가능하므로, 이미지를 로드할 때 프레임 속도가 일시적으로 불안정해질 수 있습니다.네트워킹은 지원하지 않습니다. 의외일 수 있지만 브라우저 샌드박스는 Ren'Py가 임의의 네트워크 요청을 보내지 못하게 합니다. 따라서 웹 브라우저에서 소켓이나 requests 라이브러리를 사용하면 오류가 발생합니다.
또한 게임의 호스팅 위치에 따라 제약이 생길 수 있습니다. 일부 호스팅 업체는 게임 크기나 프로젝트에 포함할 수 있는 파일 수를 제한합니다. 예를 들어 itch.io는 이러한 제한을 문서로 안내합니다. 브라우저 자체의 제한도 있습니다. 크기가 50MB보다 큰 파일은 캐시되지 않으므로 게임을 실행할 때마다 다시 다운로드합니다.
지원 브라우저
Ren'Py는 Chrome, Edge, Firefox, Safari처럼 지속적으로 업데이트되는 브라우저의 최신 버전과 iOS 및 Android용 모바일 버전에서 실행되도록 유지하고 있습니다. 다른 브라우저에서도 작동할 수 있지만, WebAssembly와 Ren'Py에 필요한 기타 기능의 지원 여부에 따라 달라집니다.
Ren'Py에는 여러 최신 웹 기능이 필요하므로 이러한 기능이 차단되거나 비활성화되어 있으면 실행되지 않습니다.
Ren'Py가 계속 작동하도록 노력하고 있지만, 브라우저 기능의 한계에 가까운 부분까지 사용하기 때문에 브라우저 변경으로 게임을 실행할 수 없게 될 가능성이 있습니다. 브라우저 공급업체와 협력하여 호환성을 유지하고 있으나, 브라우저 변경에 맞춰 게임을 업데이트해야 할 수 있습니다.
게임 패키징
런처의 “웹(베타)(Web (Beta))” 항목에서 Ren'Py 게임을 웹용으로 패키징할 수 있습니다. 여기에는 주요 옵션 네 가지가 있습니다.
- 웹 애플리케이션 빌드(Build Web Application)
게임을 웹용으로 패키징합니다. 전체 게임이 들어 있는 web.zip 파일과 게임을 구성하는 개별 파일이 들어 있는 폴더를 생성합니다. (게임에는 웹 서버 호스팅이 필요하므로 이 폴더에서 직접 실행하는 것은 지원하지 않습니다.)
- 빌드 후 브라우저에서 열기(Build and Open in Browser)
게임을 웹용으로 패키징한 뒤 테스트할 수 있도록 로컬 웹 브라우저에서 엽니다. 컴퓨터에서 게임을 제공하는 웹 서버를 실행하고, 그 웹 서버에 접속하는 브라우저를 엽니다.
일반적으로 이 방법으로 게임을 테스트합니다.
- 브라우저에서 열기(Open in Browser)
전체 빌드 과정을 거치지 않고 컴퓨터의 웹 서버에 접속하는 로컬 웹 브라우저를 엽니다.
- 빌드 디렉터리 열기(Open build Directory)
빌드 과정에서 생성한 파일이 들어 있는 폴더를 엽니다.
생성되는 폴더
예를 들어 프로젝트가 renpy/projects/main/yourproject 폴더에 있다면, renpy/projects/main/yourproject-1.0-dists 폴더가 새로 만들어집니다. 이 폴더에는 yourproject-1.0-web 하위 폴더와 이를 압축한 yourproject-1.0-web.zip 파일이 들어 있습니다.
게임 업로드
게임을 빌드한 다음에는 공개 웹 서버에 업로드해야 합니다. itch.io와 같은 게임 호스팅 서비스에는 모든 파일이 들어 있는 web.zip 파일을 업로드합니다. 다른 방식으로 호스팅한다면 생성된 web 디렉터리의 모든 파일을 업로드해야 합니다.
직접 게임을 호스팅한다면 웹 서버가 .wasm 파일을 application/wasm MIME 형식으로 제공하도록 설정하세요. 이렇게 하면 게임 로딩이 빨라지고 경고도 발생하지 않습니다.
일부 웹 호스트는 game.zip 파일을 허용하지 않을 수 있습니다. 이 경우 파일 이름을 game.data로 바꾸고 index.html에서도 game.zip을 game.data로 변경하세요.
프리스플래시
웹 플랫폼은 기본 프리스플래시 이미지를 사용합니다. 이를 바꾸려면 web-presplash라는 이름에 .jpg, .png 또는 .webp 확장자를 붙인 이미지를 제공하면 됩니다.
프리스플래시에 애니메이션이 필요하다면 .webp 형식을 사용할 수 있습니다.
아이콘
프로젝트의 기본 디렉터리에 web-icon.png라는 이미지 파일을 넣으면 웹 페이지 아이콘을 바꿀 수 있습니다. 이미지 해상도는 최소 512x512여야 하며 너비와 높이가 같아야 합니다. 사용자 지정 이미지가 없으면 기본 Ren'Py 아이콘을 사용합니다.
점진적 다운로드
Ren'Py는 점진적 다운로드 기능을 지원합니다. 프로젝트의 기본 디렉터리에 있는 progressive_download.txt 파일을 편집하여 설정합니다. 이 파일이 없으면 게임을 처음 웹용으로 패키징할 때 생성됩니다. 기본 내용은 다음과 같습니다.
# RenPyWeb progressive download rules - first match applies"
# '+' = progressive download, '-' = keep in game.data (default)
# See https://www.renpy.org/doc/html/build.html#classifying-and-ignoring-files for matching
#
# +/- type path
- image game/gui/**
+ image game/**
+ music game/audio/**
+ voice game/voice/**
이 파일은 게임 시작 전에 다운로드할 파일과 필요할 때 다운로드할 파일을 정합니다. #으로 시작하는 줄은 주석입니다. -로 시작하는 줄은 게임 시작 시 다운로드할 파일과 일치하며, 대개 첫 화면에서 사용하는 파일을 지정합니다. +로 시작하는 줄은 필요할 때 다운로드할 파일과 일치합니다.
두 번째 열은 파일 형식과 Ren'Py의 처리 방식을 지정합니다. 형식은 다음과 같습니다.
- image
이미지 파일은 먼저 픽셀화된 버전으로 대체되며, 로드가 끝나면 원래 이미지로 바뀝니다. 대부분 Ren'Py가 이미지를 예측하여 실제로 필요해지기 전에 로드할 수 있으므로, 제때 로드를 마치지 못했을 때만 픽셀화된 이미지가 보입니다.
원래 이미지가 끝내 로드되지 않는다면 웹 서버의 데이터가 잘못되었을 가능성이 큽니다.
- music
음악 파일은 무음으로 대체되며, 로드가 끝나면 재생됩니다.
- voice
음성 파일은 무음으로 대체되며, 로드가 끝나면 재생됩니다.
마지막 열은 일치시킬 경로입니다.
오디오와 동영상
브라우저에는 광고의 오디오 재생을 막기 위한 제한이 있으므로, 사용자가 게임 안을 한 번 이상 클릭하기 전에는 소리와 음악 파일이 재생되지 않습니다.
Ren'Py는 두 가지 방식으로 오디오 파일을 재생합니다. 첫 번째는 브라우저의 webaudio 시스템을 사용하는 것이고, 두 번째는 자체 오디오 재생 시스템을 사용하는 것입니다. webaudio 시스템이 더 빠르지만 Safari에서는 OGG 형식을 지원하지 않습니다.
config.webaudio_required_types 변수는 브라우저가 지원하는 형식을 확인하여 사용할 오디오 시스템을 정합니다. 게임에서 mp3만 사용한다면 다음과 같이 변경할 수 있습니다.
define config.webaudio_required_types = [ "audio/mpeg" ]
동영상 재생도 지원합니다. 다음 두 변수로 제어합니다.
config.web_video_base동영상 파일명 앞에 붙여 재생할 전체 URL을 만드는 URL입니다. 디렉터리도 포함할 수 있으므로 “https://share.renpy.org/movies-for-mygame/” 같은 값도 사용할 수 있습니다.
동영상을 나머지 게임 데이터와 다른 서버에서 호스팅할 때 유용합니다.
config.web_video_promptiOS의 Mobile Safari에서는 기본적으로 소리가 있는 동영상을 재생하려면 플레이어가 클릭해야 합니다. 이 변수는 플레이어에게 클릭을 안내할 메시지를 지정합니다.
Safari 관련 기능이 하나 더 있습니다. Safari는 webm과 같은 최신 형식을 지원하지 않으므로 웹 동영상 지원에는 대체 재생 기능이 있습니다. 첫 URL이 실패하면 확장자를 .mp4로 바꾼 URL을 시도합니다. Safari에서는 먼저 https://share.renpy.org/oa4_launch.webm을 시도하다가 지원되지 않아 실패한 뒤, 파일이 있다면 https://share.renpy.org/oa4_launch.mp4를 시도합니다.
Javascript
Ren'Py는 emscripten 모듈의 함수 세 개로 Javascript를 실행할 수 있습니다. 웹 플랫폼에서 실행할 때 이 모듈은 renpy.emscripten으로 제공됩니다. 웹 플랫폼이 아니면 renpy.emscripten은 False입니다.
- renpy.emscripten.run_script(script)
주어진 Javascript 스크립트를 실행합니다. 결과는 반환하지 않습니다.
- renpy.emscripten.run_script_int(script)
주어진 Javascript 스크립트를 실행하고 결과를 정수로 반환합니다.
- renpy.emscripten.run_script_string(script)
주어진 Javascript 스크립트를 실행하고 결과를 문자열로 반환합니다.
web/index.html 파일을 편집하여 Ren'Py가 호출할 스크립트를 포함하면 게임에 Javascript 함수를 추가할 수 있습니다. Ren'Py를 업데이트할 때 이 파일이 교체될 수 있으므로 주의하세요.
Javascript에서도 window.renpy_exc, window.renpy_get, window.renpy_set 함수로 Ren'Py를 호출할 수 있습니다. 이 함수들의 설명은 web/renpy-pre.js를 참조하세요.