Android

Ren'Py는 스마트폰과 태블릿 등 Android 운영 체제를 실행하는 기기를 지원합니다. 이러한 기기에서 Ren'Py 기능을 100% 지원하는 것은 아니지만, 비주얼 노벨을 조금만 수정하면 패키지로 만들어 이식할 수 있습니다.

RAPT(Ren'Py Android Packaging Tool)는 테스트하거나 배포할 Android 패키지를 만드는 프로그램으로, Ren'Py와 별도로 다운로드합니다.

Ren'Py는 Android 5.0 이상에서 실행됩니다. 다만 오래된 기기는 규모가 큰 게임을 제대로 실행하는 데 필요한 자원이 부족할 수 있습니다.

반드시 포함해야 하는 문구

RAPT에서 사용하는 일부 라이브러리는 GNU Lesser/Library General Public License 조건에 따라 제공됩니다. Ren'Py를 배포하려면 이 라이선스의 조건을 준수해야 합니다. 앱 설명에 다음 문구를 포함하면 충분하다고 판단하지만, 확실한 확인을 위해 변호사에게 문의하세요.

이 프로그램에는 GNU Lesser General Public License를 비롯한 여러 라이선스에 따라 제공되는 자유 소프트웨어가 포함되어 있습니다. 전체 소프트웨어 목록은 https://www.renpy.org/l/license/에서 확인할 수 있습니다.

사용자 안내

Android에서 Ren'Py 게임을 실행하면 다음 키를 사용할 수 있습니다.

홈(Home)

Android 홈 화면으로 돌아가고 Ren'Py 게임을 일시 중단합니다. Ren'Py는 일시 중단하는 과정에서 게임을 자동으로 저장합니다. 사용자가 게임으로 돌아오면 필요한 경우 이 저장 데이터를 자동으로 불러옵니다.

볼륨 높이기(Volume Up), 볼륨 낮추기(Volume Down)

Android의 미디어 볼륨을 조절합니다.

플랫폼별 차이

터치 기반 Android 플랫폼과 Ren'Py가 지원하는 마우스 기반 플랫폼 사이에는 중요한 차이가 많습니다. Android 소프트웨어와 하드웨어로 인해 달라지는 점은 다음과 같습니다.

  • 터치스크린은 마우스처럼 처리됩니다. 다만 사용자가 화면을 직접 터치하고 있는 동안에만 마우스 이벤트가 발생합니다.

  • 텍스트 입력(renpy.input() 등)은 자동 완성 없이 작동하는 입력 방식으로 제한됩니다. (서구권 언어는 대체로 작동하지만 다른 언어는 작동하지 않을 수 있습니다.)

또한 사용 환경을 고려해 다음과 같은 변경이 필요할 수 있습니다.

  • Android 스마트폰의 화면은 컴퓨터 모니터보다 작을 수 있으므로 텍스트 크기를 키워야 할 수 있습니다.

  • 터치 입력은 마우스 입력보다 정확도가 낮으므로 터치용 버튼은 마우스용 버튼보다 커야 합니다.

이러한 차이에 쉽게 대응할 수 있도록 Android용 Ren'Py는 기기의 화면 크기와 기능에 따라 스크린 변형을 자동으로 선택합니다. 자세한 내용은 스크린 변형을 참조하세요.

모바일 기기의 보안 정책으로 인해 MultiPersistent 기능은 해당 게임과 그 업데이트에서만 사용할 수 있으며, 다른 게임과 공유할 수 없습니다.

테스트와 에뮬레이션

Ren'Py는 테스트를 위한 Android 에뮬레이션 모드 세 가지를 지원합니다. 런처의 Android 화면에서 사용할 수 있습니다.

휴대전화(Phone)

Android 휴대전화를 에뮬레이션합니다. 마우스로 터치를 에뮬레이션하며, 마우스 버튼을 누르고 있는 동안에만 작동합니다. Escape는 메뉴 버튼에, Page Up은 뒤로 버튼에 대응합니다.

태블릿(Tablet)

Android 태블릿을 에뮬레이션합니다. 마우스로 터치를 에뮬레이션하며, 마우스 버튼을 누르고 있는 동안에만 작동합니다. Escape는 메뉴 버튼에, Page Up은 뒤로 버튼에 대응합니다.

텔레비전(Television)

텔레비전 기반 Android 기기 콘솔을 에뮬레이션합니다. 키보드가 리모컨이나 컨트롤러 입력에 대응하며, 방향키로 이동합니다. Enter는 선택, Escape는 메뉴, Page Up은 뒤로 기능을 수행합니다.

이 모드에서는 텔레비전 표시 비보장 영역을 나타내는 오버레이도 표시합니다. 이 영역의 콘텐츠는 텔레비전에 따라 표시되지 않을 수 있습니다.

이 에뮬레이터로 프로젝트를 빠르게 테스트할 수 있지만 실제 하드웨어에서도 테스트하는 것이 좋습니다. 에뮬레이터는 사용자의 손가락 크기와 같은 일부 사용 환경상의 문제를 재현하지 못합니다.

Android 애플리케이션 빌드

Ren'Py는 패키징을 중심으로 Android 게임을 개발할 수 있도록 도구를 제공합니다. 이 방식에서는 PC로 Android 패키지를 빌드한 뒤 기기에 업로드합니다. 그러면 다른 Android 애플리케이션처럼 게임을 실행할 수 있습니다. 정상적으로 작동하면 만든 패키지를 Google Play나 다른 앱 스토어에 업로드할 수 있습니다.

Android 애플리케이션 빌드는 네 단계로 이루어집니다.

  1. Java Development Kit와 Android USB 드라이버를 다운로드하여 설치합니다. (링크는 아래에 있습니다.)

  2. 런처에서 Android SDK를 설치합니다.

  3. 런처에서 키를 생성합니다.

  4. 런처에서 Android 빌드를 구성합니다.

  5. 런처에서 Android 애플리케이션을 빌드합니다.

이 단계를 모두 마치면 실행 가능한 Android 패키지가 만들어집니다. 게임 구성을 변경하거나 새 게임을 처음 구성할 때만 3단계를 다시 수행하면 됩니다. 게임의 새 빌드를 만들 때마다 수행하는 4단계가 가장 자주 쓰입니다.

1단계: 의존 항목 설치

패키지를 빌드하기 전에 다음 세 항목을 직접 다운로드하여 설치해야 할 수 있습니다.

Java Development Kit. Java Development Kit(JDK)에는 키 생성과 패키지 서명 도구를 비롯하여 RAPT에서 사용하는 여러 도구가 들어 있습니다. 다음 주소에서 다운로드할 수 있습니다.

JDK 버전 21이 필요합니다.

개발자용 JDK는 사용자용 JRE와 다릅니다. Android 패키지를 만들려면 JDK가 필요합니다.

Android 기기. 기기도 개발용으로 설정해야 합니다. 기기에서 개발자 모드를 활성화하고 컴퓨터를 Android 개발에 맞게 설정하세요. 컴퓨터 설정 방법은 다음 주소에서 확인할 수 있습니다.

Android 에뮬레이터의 x86_64 이미지에서도 앱을 실행할 수 있습니다. (x86은 지원하지 않습니다.) 에뮬레이터 설정은 이 문서에서 다루지 않습니다.

2단계: Android SDK와 개발 환경 설정

다음으로 Android SDK와 나머지 개발 환경을 설정합니다. 이 단계에서는 다음 작업을 수행합니다.

  • JDK가 제대로 설치되었는지 확인합니다.

  • Android SDK를 설치합니다.

  • Android SDK로 필요한 개발 패키지를 설치합니다.

이 단계에는 인터넷 연결이 필요합니다.

Ren'Py 런처의 Android 화면에서 “SDK 설치(Install SDK)”를 선택하세요. RAPT가 진행 중인 작업을 알려 주며, 라이선스에 동의하라는 메시지도 표시합니다.

SDK를 매번 다운로드하지 않으려면 이미 설치된 SDK의 경로를 한 줄로 적은 sdk.txt 파일을 만들면 됩니다.

3단계: 키 생성

이어서 “키 생성(Generate Keys)”을 선택하여 패키지의 Android 키와 Bundle 키를 생성합니다.

경고

RAPT가 생성하는 키에는 표준 암호 구문이 사용됩니다. 이 파일들에 접근할 수 없게 되는 일이 없도록 해야 합니다.

android.keystore와 bundle.keystore 파일을 안전한 곳에 보관하세요. 키가 없으면 생성한 애플리케이션을 업로드할 수 없으므로 반드시 백업도 해 두세요.

이 파일들이 절대로 공개되지 않도록 주의하세요. 특히 버전 관리를 사용하는 경우 더욱 주의해야 합니다.

Ren'Py는 Android 키를 만들 때 스크립트 파일을 백업하는 위치에 키도 백업합니다. 그러나 이것만 믿지 말고 직접 백업도 해야 합니다.

4단계: 게임 구성

패키지를 빌드하기 전에 게임의 Android 빌드에 관한 정보를 Ren'Py에 제공해야 합니다. Ren'Py 런처의 Android 화면에서 “구성(Configure)”을 선택하세요.

정보를 변경해야 한다면 구성 명령을 다시 실행하면 됩니다. 이전에 선택한 내용은 기억됩니다.

5단계: 패키지 빌드와 설치

마지막으로 패키지를 빌드하여 설치합니다. 먼저 다음 두 배포 모드 중 하나를 선택하세요.

Play Bundle

Play 번들 배포물은 Android App Bundle(AAB) 형식이며 Google Play 스토어에 업로드하는 용도로만 적합합니다. 다만 Play를 지원하는 Android 기기에 설치할 수도 있습니다.

Play 번들은 최대 2 GB까지 만들 수 있지만, 이는 500MB 크기의 fast-follow 팩 파일 4개로 나뉘며 게임의 각 파일은 네 번들 중 하나에 배치됩니다. 파일 네 개라는 제한 때문에 문제가 생길 수 있습니다. 예를 들어 300 MB 파일 5개는 네 팩 파일에 하나씩만 들어갈 수 있으므로 모두 담을 수 없습니다.

Universal APK

Universal APK 배포물은 Ren'Py, ADB, Play 이외의 앱 스토어, 웹을 통한 사이드로딩 등으로 Android 기기에 직접 설치하기에 적합합니다.

Universal APK는 최대 2 GB까지 만들 수 있으며 내용물에 대한 제한은 없습니다.

패키지 빌드, 기기 설치, 테스트를 위한 애플리케이션 실행을 여러 방식으로 조합하여 수행하는 명령 세 가지가 제공됩니다.

배포 모드를 바꿀 때는 앱을 제거해야 할 수 있습니다.

매우 큰 게임

2 GB보다 큰 게임도 빌드할 수 있습니다. 대용량 모바일 게임용 다운로더를 사용하여 Play 번들이나 Universal APK에는 작은 게임만 포함하고, 나머지 게임 데이터는 이를 제공할 수 있는 웹 서버에서 다운로드하는 방식입니다.

아이콘과 프리스플래시 이미지

아이콘

Ren'Py는 게임의 기본 디렉터리에 있는 다음 두 파일로 앱 아이콘을 만듭니다.

android-icon_foreground.png

아이콘의 전경 레이어입니다. 432x432 픽셀 크기의 투명 이미지여야 합니다.

android-icon_background.png

아이콘의 배경 레이어입니다. 432x432 픽셀 크기의 불투명 이미지여야 합니다.

Android 적응형 아이콘은 두 레이어를 마스킹하여 중앙의 최소 132x132 픽셀 영역에 표시합니다. 이 안전 영역 밖의 부분도 표시될 수 있지만 마스크에 가려질 수도 있습니다. 이미지가 안전 영역 밖까지 이어지도록 만드는 것이 좋습니다. 아이콘을 드래그하면 두 레이어가 서로 조금씩 어긋나게 움직일 수 있습니다.

적응형 아이콘에 관한 자세한 내용은 다음을 참조하세요.

1dp는 실제 픽셀 4개에 해당합니다.

Ren'Py는 애플리케이션을 생성할 때 이 파일들을 각 기기에 적합한 크기로 변환하며, 적응형 아이콘을 지원하지 않는 기기용 정적 아이콘도 생성합니다.

프리스플래시

프리스플래시는 Ren'Py가 완전히 로드되기 전, 기본 스플래시 화면이 시작되기 전에 표시됩니다. Android에서는 특히 중요합니다. Ren'Py를 처음 실행할 때 지원 파일의 압축을 풀며, 이 작업에 시간이 걸릴 수 있기 때문입니다.

android-presplash.jpg

앱을 로드하는 동안 표시할 이미지입니다. 이미지 둘레에는 단색의 1px 테두리가 있어야 합니다. 표시할 때는 가로세로 비율을 유지하면서 사용 가능한 공간에 맞게 크기를 조절하며, 화면의 나머지 부분은 테두리 색으로 채웁니다.

android-downloading.jpg

앱이 Google Play Asset Delivery에서 에셋을 다운로드하는 동안 표시할 이미지입니다. 이미지 둘레에는 단색의 1px 테두리가 있어야 합니다. 표시할 때는 가로세로 비율을 유지하면서 사용 가능한 공간에 맞게 크기를 조절하며, 화면의 나머지 부분은 테두리 색으로 채웁니다.

화면의 아래쪽, 왼쪽, 오른쪽 가장자리에서 20px 떨어진 위치에 높이 20px의 진행률 표시줄을 표시하여 다운로드 진행 상황을 알려 줍니다.

Pyjnius

Android에서 실행할 때는 Pyjnius 라이브러리를 사용할 수 있습니다. 숙련된 제작자는 이 라이브러리로 Android 라이브러리를 호출할 수 있습니다.

메인 액티비티가 필요할 수 있습니다. org.renpy.android.PythonSDLActivity 클래스의 mActivity 필드에서 가져올 수 있습니다. 예를 들면 다음과 같습니다.

init python:
    if renpy.android:
        import jnius
        mActivity = jnius.autoclass("org.renpy.android.PythonSDLActivity").mActivity
    else:
        mActivity = None

권한

Ren'Py 자체는 실행에 추가 권한이 필요하지 않지만, 게임에서 Pyjnius로 Android 기능을 호출한다면 권한을 요청해야 할 수 있습니다. Ren'Py는 Android 권한 시스템과 상호 작용하는 변수 하나와 함수 두 개를 제공합니다.

build.android_permissions = [ ]

Android 권한의 전체 이름을 나타내는 문자열 목록입니다. 예를 들면 "android.permission.WRITE_EXTERNAL_STORAGE"입니다. 이 목록은 애플리케이션이 해당 권한을 요청할 수 있다고 선언할 뿐이므로, 실제로 권한이 필요할 때는 renpy.check_permission과 renpy.request_permission을 사용해 요청해야 합니다.

renpy.check_permission(permission)

이 애플리케이션에 Android 권한이 부여되었는지 확인합니다.

permission

권한 이름을 나타내는 문자열입니다. 예를 들면 "android.permission.WRITE_EXTERNAL_STORAGE"입니다.

권한이 부여되었으면 true를 반환합니다. 부여되지 않았거나 Android 이외의 플랫폼에서 호출하면 false를 반환합니다.

renpy.request_permission(permission)

Android에 이 애플리케이션의 권한 부여를 요청합니다. 사용자에게 권한 허용 여부를 묻는 메시지가 표시될 수 있습니다.

permission

권한 이름을 나타내는 문자열입니다. 예를 들면 "android.permission.WRITE_EXTERNAL_STORAGE"입니다.

권한이 부여되었으면 true를 반환합니다. 부여되지 않았거나 Android 이외의 플랫폼에서 호출하면 false를 반환합니다.