배포 파일 만들기

Ren'Py는 게임 배포판 빌드를 지원합니다. 런처에서 “배포판 빌드(Build Distributions)”를 선택하면 Ren'Py 자체와 프로젝트를 검사하여 배포판에 포함할 파일을 결정하고, 필요한 아카이브를 생성한 뒤 패키지와 업데이트 파일을 빌드합니다.

별도로 설정하지 않아도 다음 종류의 패키지를 빌드할 수 있습니다.

PC: Windows 및 Linux: Windows x86_64와 Linux x86_64용 zip 파일입니다.
Linux: Linux x86_64용 tar.bz2 파일입니다. 32비트 및 64비트 ARM 버전의 Ren'Py가 있으면 함께 포함합니다. (이 버전은 Ren'Py의 sdkarm 패키지에 있습니다.)
Macintosh: Intel 및 Apple Silicon 프로세서의 macOS OS X용 Macintosh 애플리케이션이 들어 있는 zip 파일입니다. 게임 데이터는 애플리케이션 안에 포함되며 사용자에게는 파일 하나로 보입니다. 이 패키지는 업데이터를 지원하지 않습니다.
Windows: Windows x86_64용 zip 파일입니다.
스토어용 Windows, Mac 및 Linux: itch.io와 Steam 같은 소프트웨어 스토어에서 실행하는 데 필요한 정보가 들어 있는 배포판입니다. 직접 실행하는 용도가 아니며(Mac에서는 아마 실행되지 않습니다), 앱 스토어의 업로드 절차에 전달해야 합니다.

경고

Ren'Py가 생성하는 zip 및 tar.bz2 파일에는 Linux와 Macintosh에서 실행하는 데 반드시 필요한 권한 정보가 들어 있습니다.

Windows에서 zip 파일의 압축을 풀었다가 다시 압축한 뒤 Linux나 Macintosh에서 실행하는 것은 지원하지 않습니다.

기본 설정

build 네임스페이스의 변수를 설정하고 함수를 호출하여 빌드 과정을 구성할 수 있습니다. 반드시 init python 블록 안에서 수행해야 합니다. 이 설정들의 기본값은 options.rpy에 지정되어 있습니다.

여러 게임에서 사용하는 기본 변수와 함수는 다음과 같습니다.

build.name = "...": build.directory_name과 build.executable_name이 모두 설정되지 않았을 때 두 값을 자동 생성하는 데 사용합니다. 공백, 콜론, 세미콜론을 포함해서는 안 됩니다.

build.directory_name = "..."

아카이브 파일 안의 디렉터리 이름을 정하는 데 사용합니다. 예를 들어 "mygame-1.0"으로 설정하면 Linux 버전 프로젝트는 "mygame-1.0-linux" 디렉터리에 압축 해제됩니다.

패키지 파일을 저장할 디렉터리 이름도 정합니다. 예를 들어 build.directory_name을 mygame-1.0으로 설정하면 아카이브 파일은 기본 디렉터리의 상위 디렉터리에 있는 mygame-1.0-dists에 저장됩니다.

공백, 콜론, 세미콜론 같은 특수 문자를 포함해서는 안 됩니다. 설정하지 않으면 build.name에 하이픈과 버전을 붙인 값이 기본값입니다. 버전은 build.version이 설정되어 있으면 그 값을, 없으면 config.version을 사용합니다.

build.executable_name = "..."

사용자가 클릭하여 게임을 시작할 실행 파일의 이름을 정합니다.

공백, 콜론, 세미콜론 같은 특수 문자를 포함해서는 안 됩니다. 설정하지 않으면 기본값은 build.name입니다.

예를 들어 "mygame"으로 설정하면 Windows에서는 mygame.exe, Macintosh에서는 mygame.app, Linux에서는 mygame.sh를 실행할 수 있습니다.

특수 파일

게임의 기본 디렉터리에 다음 두 파일을 넣어 빌드를 사용자 지정할 수 있습니다.

icon.ico: Windows에서 사용하는 아이콘입니다.
icon.icns: Macintosh에서 사용하는 아이콘입니다.

아이콘 파일은 정해진 형식이어야 합니다. 프로그램이나 웹 서비스(https://anyconv.com/png-to-ico-converter/, https://anyconv.com/png-to-icns-converter/ 등)로 변환해야 합니다.

파일 분류와 제외

빌드 과정에서는 먼저 Ren'Py 배포판과 게임의 파일을 파일 목록으로 분류합니다. 그다음 이 목록들을 패키지 파일에 추가합니다.

분류에는 build.classify 함수를 사용합니다. 패턴과 공백으로 구분한 파일명 목록을 받습니다. 패턴은 처음부터 끝까지 순서대로 검사하며 처음 일치한 것이 우선합니다. (뒤에 더 구체적인 패턴이 있어도 같습니다.) 경로 앞에 /가 있는 경우와 없는 경우를 모두 검사합니다. 패턴에는 다음 특수 문자를 사용할 수 있습니다.

/: 디렉터리 구분자입니다.
*: 디렉터리 구분자를 제외한 모든 문자와 일치합니다.
**: 모든 문자와 일치합니다.

예를 들면 다음과 같습니다.

**.txt: 모든 txt 파일과 일치합니다.
game/*.txt: game 디렉터리의 txt 파일과 일치합니다.

기본적으로 파일을 분류할 수 있는 파일 목록은 일곱 가지입니다. (Ren'Py 자체 파일은 이 중 처음 여섯 목록에 들어갑니다.)

all: 모든 패키지와 Android 빌드에 포함합니다.
linux: Linux용 패키지에 포함합니다.
mac: Macintosh용 패키지에 포함합니다.
windows: Windows용 패키지에 포함합니다.
renpy: Ren'Py 엔진 파일이 필요한 패키지(Linux, Macintosh, Windows)에 포함합니다.
android: Android 빌드에 포함합니다.

build.classify()의 file_list 인수로 새 이름을 전달하면 유효한 파일 목록의 집합을 확장할 수 있습니다.

파일을 아카이브로 분류할 수도 있습니다. 기본적으로 "archive" 아카이브가 선언되어 있습니다.

archive: archive.rpa 아카이브에 포함합니다.

build.archive() 함수로 아카이브 집합을 확장할 수도 있습니다.

별도로 분류되지 않은 파일은 "all" 파일 목록에 들어갑니다.

배포에서 제외할 파일은 None 또는 빈 문자열로 분류하세요. 이 경우 패턴 끝의 *와 **는 적어도 한 문자와 일치해야 합니다.

예를 들면 다음과 같습니다.

# Include README.txt
build.classify("README.txt", "all")

# But exclude all other txt files.
build.classify("**.txt", None)

# Add png and jpg files in the game directory into an archive.
build.classify("game/**.png", "archive")
build.classify("game/**.jpg", "archive")

문서

패턴을 인수로 build.documentation 함수를 호출하면 해당 패턴과 일치하는 파일을 문서로 지정합니다. Macintosh 애플리케이션에서는 문서 파일이 애플리케이션 내부와 외부에 각각 한 번씩, 총 두 번 포함됩니다.

예를 들어 기본 디렉터리의 모든 txt와 html 파일을 문서로 지정하려면 다음을 호출합니다.

build.documentation("*.txt")
build.documentation("*.html")

패키지

Ren'Py 빌드 과정에 새 패키지 종류를 추가할 수도 있습니다. build.package 함수에 패키지 이름, 종류, 포함할 파일 목록들을 담은 문자열을 전달하여 호출합니다.

예를 들어 일반 버전과 보너스 자료 포함 버전을 빌드하려면, 보너스 파일을 "bonus" 파일 목록으로 분류한 뒤 다음과 같이 all-premium 패키지를 선언하면 됩니다.

# Declare a new archive belonging to a new "bonus" file list.
build.archive("bonus_archive", "bonus")

# Put the bonus files into the new archive.
build.classify("game/bonus/**", "bonus_archive")

# Declare the package.
build.package("all-premium", "zip", "windows mac linux renpy all bonus")

지원하는 패키지 종류는 각 형식의 파일을 만드는 "zip"과 "tar.bz2", 그리고 파일이 들어 있는 디렉터리를 만드는 "directory"입니다.

아카이브

Ren'Py는 파일들을 간단한 아카이브 형식으로 묶는 기능을 지원합니다. 보안성이 높지는 않지만 쉽게 복사하는 것은 방지할 수 있습니다.

기본적으로 "archive" 파일 목록으로 분류한 모든 파일은 archive.rpa 아카이브에 들어가며, 이 아카이브는 all 파일 목록에 포함됩니다.

build.archive를 호출하여 새 아카이브와 이를 포함할 파일 목록을 선언할 수 있습니다. (다만 all 이외의 목록을 사용하는 경우는 드뭅니다.) 아카이브를 사용하려면 해당 이름의 목록으로 파일을 분류하세요.

예를 들어 다음은 이미지를 images.rpa에, 게임 스크립트를 scripts.rpa에 넣습니다.

# Declare two archives.
build.archive("scripts", "all")
build.archive("images", "all")

# Put script files into the scripts archive.
build.classify("game/**.rpy", "scripts")
build.classify("game/**.rpyc", "scripts")

# Put images into the images archive.
build.classify("game/**.jpg", "images")
build.classify("game/**.png", "images")

비어 있는 아카이브 파일은 빌드하지 않습니다.

게임을 아카이브로 묶을지는 신중하게 생각하세요. 파일을 개방해 두면 다른 사람들이 미래의 플랫폼에서 게임을 실행하는 데 도움이 됩니다. 여러분이 세상을 떠난 뒤에야 등장할 플랫폼도 있을 수 있습니다.

old-game 디렉터리

Ren'Py는 게임을 빠르게 실행하기 위해 컴파일된 스크립트 파일(.rpyc 파일)을 사용합니다. 여기에는 대사나 장면의 각 줄에 대한 고유 ID처럼 저장 파일이 의존하는 중요한 정보도 들어 있습니다. 게임이 업데이트되어 .rpy 스크립트가 바뀌면 게임 실행 시 대응하는 .rpyc 파일을 갱신하거나 생성합니다.

.rpyc 파일이 이렇게 갱신되는 특성은 얼리 액세스나 Patreon 같은 플랫폼을 통해 여러 버전을 배포하는 개발자, 또는 여러 개발자가 참여하는 대형 게임의 제작자에게 어려움이 될 수 있습니다. 개발 중 .rpy 파일을 여러 번 수정하다 보면 생성된 .rpyc 파일의 ID가 현재 안정판의 ID와 달라지기 쉽습니다. 팀에서는 여러 개발자가 같은 .rpy 파일을 수정할 수 있어 문제가 더 커집니다. 기준이 되는 단일 .rpyc 파일 없이 Ren'Py가 어떻게 ID를 유지할 수 있을까요?

이러한 변경으로 저장 게임 호환성이 깨지는 것을 막으려면 old-game 디렉터리를 사용하세요. 프로젝트 폴더에서 game 디렉터리 옆에 두는 특수 폴더이며, 이전 릴리스의 .rpyc 파일 사본을 보관합니다. 구조는 game 디렉터리와 같아야 합니다. 예를 들어 game/scripts/day1.rpyc를 old-game/scripts/day1.rpyc로 옮깁니다. old-game 안에서 .rpyc가 아닌 파일은 무시됩니다.

old-game 디렉터리에 이전 릴리스의 .rpyc 파일이 있으면, Ren'Py는 변경된 .rpy 스크립트의 새 .rpyc 파일을 만들 때 이를 참고합니다. 변경되지 않은 스크립트 부분의 ID를 유지하므로 이전 저장 파일도 제대로 불러올 수 있습니다.

`old-game` 디렉터리를 효과적으로 활용하는 방법:

게임을 실행할 때 .rpy 파일이 변경되었고 old-game에 대응하는 .rpyc 파일이 있으면, Ren'Py는 그 .rpyc 파일을 사용하여 game의 파일을 갱신합니다. 이전 릴리스와 ID를 일치시켜 저장 호환성을 최대한 유지합니다.
새 릴리스를 빌드하기 전에 Ren'Py SDK의 빌드 페이지에서 “강제 재컴파일(Force Recompile)”을 활성화하고, “빌드(Build)”를 누르기 전에 “old-game 업데이트(Update old-game)”를 클릭하세요. old-game의 파일을 기준으로 모든 .rpyc 파일을 재컴파일한 뒤, 다음 릴리스에 사용할 새롭고 안정된 .rpyc 파일로 old-game을 갱신합니다.
게임을 이미 출시했더라도 최신 릴리스의 game 디렉터리에 있는 .rpyc 파일을 같은 폴더 구조로 프로젝트의 old-game 디렉터리에 복사하면 old-game의 이점을 활용할 수 있습니다.

변경된 게임에서 저장 데이터를 불러올 때 .rpyc 파일이 어떤 역할을 하는지 자세히 알아보려면 다음을 참조하세요.

시스템 요구 사항

일부 스토어는 Ren'Py 애플리케이션 실행에 필요한 시스템 사양을 요청합니다. 게임마다 다르지만 일반적인 비주얼 노벨의 최소 사양은 다음과 같습니다.

Windows

버전: Windows 10 이상.
CPU: 2.0 Ghz 64비트 Intel 호환
RAM: 2.0 GB
그래픽: OpenGL 3.0 또는 DirectX 11

macOS

버전: 10.10+
CPU: 2.0 Ghz 64비트 Intel 호환 또는 M1+
RAM: 2.0 GB
그래픽: OpenGL 3.0

Linux

버전: Ubuntu 20.04+
CPU: 2.0 Ghz 64비트 Intel 호환
RAM: 2.0 GB
그래픽: OpenGL 3.0

필요한 디스크 공간은 전적으로 게임 에셋에 따라 결정되며 CPU와 RAM 요구량도 달라질 수 있습니다. 특정 확장 기능이 있으면 OpenGL 2에서도 실행할 수 있습니다.

빌드 함수

build.archive(name, file_list='all')

아카이브를 선언합니다. name을 사용 가능한 아카이브 이름 목록에 추가하며, 이 이름은 build.classify()에 전달할 수 있습니다.

파일이 하나 이상 name으로 분류되면 name.rpa 아카이브를 빌드하고, 여기서 지정한 file_list를 포함하는 패키지에 넣어 배포합니다.

build.archive("secret", "windows")

build.classify() 함수로 파일을 "secret" 아카이브에 포함하면 Windows 빌드의 secret.rpa 아카이브 안에 들어갑니다.

build.classify()와 마찬가지로 file_list에 지정한 이름의 파일 목록이 없으면 생성하여 유효한 파일 목록 집합에 추가합니다.

build.classify(pattern, file_list)

pattern과 일치하는 파일을 file_list로 분류합니다. 아카이브 이름을 지정할 수도 있습니다.

file_list에 지정한 이름의 아카이브나 파일 목록이 없으면 생성하여 유효한 파일 목록 집합에 추가합니다.

build.clear(): 파일 분류에 사용하는 패턴 목록을 비웁니다.

build.documentation(pattern): 문서와 일치하는 패턴을 선언합니다. Mac 앱 빌드에서는 해당 패턴과 일치하는 파일을 앱 패키지 내부와 외부에 각각 한 번씩 저장합니다.

build.executable(pattern): 지원 플랫폼(Linux 및 Macintosh)에서 파일을 실행 가능으로 표시하는 패턴을 추가합니다.

build.package(name, format, file_lists, description=None, update=True, dlc=False, hidden=False, update_only=False)

패키징 도구가 빌드할 수 있는 패키지를 선언합니다.

name

패키지 이름입니다.

format

패키지 형식입니다. 다음 값을 공백으로 구분하여 나열한 문자열입니다.

zip: zip 파일입니다.
tar.bz2: tar.bz2 파일입니다.
directory: 파일이 들어 있는 디렉터리입니다.
dmg: 파일이 들어 있는 Macintosh DMG입니다.
app-zip: Macintosh 애플리케이션이 들어 있는 zip 파일입니다. Ren'Py 업데이터를 지원하지 않습니다.
app-directory: Mac 앱이 들어 있는 디렉터리입니다. Ren'Py 업데이터를 지원하지 않습니다.
app-dmg: dmg가 들어 있는 Macintosh 드라이브 이미지입니다. (Mac 전용입니다.) Ren'Py 업데이터를 지원하지 않습니다.
bare-zip: 맨 앞에 build.directory_name을 붙이지 않은 zip 파일입니다.
bare-tar.bz2: 맨 앞에 build.directory_name을 붙이지 않은 zip 파일입니다.
null: 본 패키지 없이 업데이트만 생성할 때 사용합니다.

빈 문자열이면 어떤 패키지 형식도 빌드하지 않습니다. (이를 통해 DLC를 만들 수 있습니다.)

file_lists

패키지에 포함할 파일 목록들을 담은 목록입니다.

description

빌드할 패키지에 대한 선택적 설명입니다.

update

true이고 업데이트를 빌드 중이면 이 패키지의 업데이트도 빌드합니다.

dlc

true이면 zip 또는 tar.bz2 파일을 업데이트 디렉터리가 없는 독립형 DLC 모드로 빌드합니다.

hidden

true이면 런처의 패키지 목록에서 숨깁니다.

빌드 정보

빌드 정보를 제공하는 변수는 두 가지입니다. 이 정보는 Ren'Py 시작 시 로드되는 game/cache/build_info.json 파일을 생성하는 데 사용합니다.

build.time = None: 기본값은 None이지만 게임을 빌드했다면 빌드 시각으로 설정됩니다. 값은 1970년 1월 1일 이후 경과한 초입니다.

build.info = { }

빌드된 게임의 game/cache/build_info.json 파일에 넣을 정보를 저장하는 변수입니다. 빌드된 게임을 시작하면 game/cache/build_info.json을 로드하여 내용을 이 변수에 넣습니다.

일반적으로 setdefault를 사용하여 필드가 없을 때만 값을 설정하는 것이 좋습니다.

예를 들어 다음은 게임을 빌드한 컴퓨터 이름을 build_info.json 파일에 저장합니다.

python hide:
    import socket
    build.info.setdefault("build_host", socket.gethostname())

이 변수의 정보는 JSON 파일에 넣을 수 있는 자료형이어야 합니다. (None, 불리언, 문자열, 숫자, 목록, 딕셔너리입니다.)

고급 설정

다음 변수로 빌드 과정을 더 세밀하게 제어할 수 있습니다.

build.allow_integrated_gpu = True: 내장 GPU와 외장 GPU가 모두 있는 플랫폼에서 내장 GPU로 Ren'Py를 실행할 수 있도록 합니다. 현재는 Mac OS X만 지원합니다.

build.destination = "{directory_name}-dists"

아카이브 파일을 저장할 디렉터리 경로입니다. 절대 경로나 상대 경로를 사용할 수 있습니다. 상대 경로는 프로젝트 디렉터리를 기준으로 합니다.

다음 값은 Python의 str.format 함수로 치환됩니다.

{directory_name}: build.directory_name 값입니다.
{executable_name}: build.executable_name 값입니다.
{version}: build.version 값입니다.

build.change_icon_i686 = True: True이고 icon.ico가 있으면 32비트 Windows 실행 파일의 아이콘을 변경합니다. False이면 변경하지 않습니다. False로 설정하면 일부 바이러스 백신이 게임을 잘못 탐지하는 문제를 피할 수 있습니다.

build.exclude_empty_directories = True: true이면 파일을 아카이브에 넣어 비게 된 디렉터리를 포함하여 빈 디렉터리를 생성된 패키지에서 제거합니다. false이면 빈 디렉터리도 포함합니다.

build.game_only_update = False: true이면 build.include_update를 활성화하고 “모바일용 게임 데이터만 업데이트(Game-Only Update for Mobile)” 패키지를 사용할 수 있게 합니다.

build.include_i686 = True: true이면 32비트 x86 프로세서 실행에 필요한 파일을 Linux 및 Mac 빌드에 포함합니다. False이면 포함하지 않습니다.

build.include_old_themes = True

true이면 Ren'Py 6.99.9 이전의 테마를 지원하는 데 필요한 파일을 빌드에 포함합니다. false이면 제외합니다.

gui.init()을 호출하면 False로 설정됩니다.

build.include_update = False: true이면 업데이터 작동에 필요한 파일을 생성합니다.

build.itch_project = None

이 값을 설정하면 Ren'Py 런처에서 프로젝트를 itch.io에 업로드할 수 있습니다. itch에 등록한 프로젝트 이름을 지정해야 합니다. (예: "renpytom/the-question")

설정한 뒤 배포판 빌드를 마치면 “배포판 빌드(Build distributions)”, “itch.io에 업로드(Upload to itch.io)”를 클릭하여 업로드할 수 있습니다.

build.itch_channels = { ... }

파일명 패턴(예: "*-win.zip")을 파일을 업로드할 itch 채널 이름 문자열에 대응시킵니다. 기본값은 다음과 같습니다.

{
    "*-all.zip" : "win-osx-linux",
    "*-market.zip" : "win-osx-linux",
    "*-pc.zip" : "win-linux",
    "*-win.zip" : "win",
    "*-mac.zip" : "osx",
    "*-linux.tar.bz2" : "linux",
    "*-release.apk" : "android",
}

build.mac_info_plist = { }: 문자열을 문자열에 대응시키는 딕셔너리입니다. Mac의 Info.plist 파일에 키를 추가하거나 기존 키를 재정의할 수 있습니다.

build.update_formats = [ "rpu" ]: 업데이터가 빌드할 형식 목록입니다. 기본값인 "rpu"는 Ren'Py 7.7 및 8.2부터 지원합니다. 이전의 zsync 기반 업데이트로 갱신하는 기능이 필요하면 목록에 "zsync'를 추가하세요.

build.version = None: 빌드 과정에서 사용할 빌드 버전입니다. None이면 config.version을 기본값으로 사용합니다. 주로 config.version에 파일명이나 디렉터리 이름으로 사용할 수 없는 문자를 넣을 수 있도록 하는 데 사용합니다.