Godot 게임을 안드로이드로 내보내기 — APK 테스트부터 서명한 AAB까지

PC에서 돌던 게임을 폰으로 옮길 때 저는 한 번에 AAB부터 만들려다 여러 번 돌아왔습니다. 두 단계로 나누는 쪽이 훨씬 빠릅니다. 먼저 테스트용 APK로 터치와 화면을 보고, 그다음에 제출용 AAB를 만듭니다.

AAB가 만들어졌다는 것은 파일이 생겼다는 뜻이지 폰에서 돌아간다는 뜻도, 스토어가 받아 준다는 뜻도 아닙니다. 이 둘을 같은 것으로 믿었다가 업로드 단계에서 막히면, 그때는 이미 versionCode 하나를 써 버린 뒤입니다.

대상은 Windows와 Godot 4 계열의 GDScript 프로젝트입니다. 공식 자료는 2026년 9월 15일에 확인했습니다. 절차를 적은 글이고, 특정 Godot·플러그인 조합에서 빌드가 된다고 보증하는 기록은 아닙니다.

직접 실행하며 배우려면: 20초 표적 게임 실습에서 프로젝트 ZIP, 전체 코드, 실제 실행 화면과 Android APK 빌드 오류 해결 과정을 확인하세요. 아래 글은 준비물과 절차를 정리한 안내이고, 연결된 실습은 특정 환경에서 수행한 기록입니다.

1. 준비물의 역할부터 구분합니다

Godot 안드로이드 내보내기 문서는 JDK와 SDK의 필요 패키지, 에디터 설정 경로를 제공합니다. SDK는 Android Studio 설치 안내를 통해 준비할 수 있습니다. 설치 폴더 이름을 추측하지 말고 SDK Manager가 표시하는 위치를 확인하세요.

2. 빌드 환경과 스토어 제출 요건을 따로 확인합니다

확인일 현재 Godot의 stable 내보내기 문서에는 Android SDK Platform 35를 사용하는 설치 예제가 있습니다. 반면 Google Play의 대상 API 수준 요구사항에는 일반 모바일 신규 앱과 업데이트가 2026년 8월 31일부터 Android 16, API 36 이상을 대상으로 해야 한다고 안내되어 있습니다. Google Play 공식 요구사항

그래서 오래된 설정 예제를 그대로 베끼고 "공식 문서대로 했으니 되겠지"라고 넘어가면 안 됩니다. 저는 이 자리에서 한 번 막혔습니다 — 빌드는 멀쩡히 끝났는데 콘솔이 거절했습니다. 사용하는 Godot 버전과 Gradle 설정이 필요한 SDK를 지원하는지 확인하고, 최종 번들의 대상 API를 Console에서도 확인하세요. 지원이 부족한 조합이라면 별도 브랜치에서 엔진·템플릿·플러그인 업그레이드를 검증합니다.

minSdk는 설치 가능한 안드로이드 버전의 하한, targetSdk는 앱이 대상으로 삼는 플랫폼 동작 기준입니다. compileSdk는 빌드에 사용하는 API 집합입니다. 세 숫자를 같은 이유로 바꾸지 마세요.

3. Godot에 경로와 프리셋을 설정합니다

에디터 설정에서 Android 항목의 Java SDK Path와 Android SDK Path를 지정합니다. SDK 경로 아래에서 platform-tools와 adb를 찾을 수 있어야 합니다. Project의 Export에서 Android 프리셋을 추가하세요.

패키지 이름은 표시 이름과 다릅니다. 예를 들어 소유한 도메인이 example.com이라면 com.example.mygame처럼 고유하게 정합니다. 이 문자열은 설명용 예시이므로 그대로 제출하지 마세요. 버전 이름은 사용자에게 보이는 1.0.0 같은 표기이고, 버전 코드는 업로드마다 증가시킬 정수입니다.

처음에는 화면 방향, 아이콘, 필요한 권한을 확인하세요. 플러그인을 추가하기 전 최소 구성으로 한 번 내보내면, 이후 실패가 게임 자체에서 왔는지 새 플러그인에서 왔는지 좁힐 수 있습니다.

4. APK를 실제 휴대폰에서 확인합니다

기기에서 개발자 옵션과 USB 디버깅을 켜고 연결 요청을 확인합니다. Android SDK의 platform-tools 폴더에서 다음 읽기 전용 명령으로 연결을 확인할 수 있습니다.

.\adb.exe devices

장치가 unauthorized로 뜨면 폰 화면에 승인 창이 떠 있을 겁니다. 목록에 아예 없으면 케이블부터 의심하십시오. 충전만 되는 케이블이 섞여 있으면 여기서 한참을 헤맵니다. 그다음이 USB 모드, 그다음이 드라이버입니다. 연결 확인 뒤 테스트용 APK를 설치해 실행하세요.

같은 패키지인데 서명이 다른 앱이 이미 설치돼 있으면 설치가 실패할 수 있습니다. 로그를 확인하고 서명 차이인지 구분하세요. 해결하려고 기존 앱을 제거하면 로컬 저장 데이터가 사라질 수 있으므로, 테스트 데이터 보존 여부부터 확인하는 편이 좋습니다.

실기기에서는 켜지는 것만 보고 넘어가지 마십시오. 데스크톱에서 절대 안 나오는 것들이 여기서 나옵니다. 홈 화면으로 나갔다가 복귀, 화면 잠금과 해제, 뒤로가기, 소리 재생, 한글 표시, 짧은 화면에서 버튼 잘림을 확인합니다. 광고를 쓴다면 게임 버튼·시스템 내비게이션과 광고 영역이 겹치지 않는지도 봅니다.

5. Gradle과 서명을 준비해 AAB를 만듭니다

Godot Gradle 빌드 안내에 따라 Android 빌드 템플릿을 설치하고, Android 내보내기 프리셋에서 Gradle 빌드를 사용하도록 설정합니다. 제출용 출력 형식은 AAB로 선택합니다.

릴리스에는 디버그 키가 아닌 서명 구성이 필요합니다. Godot 프리셋의 Release, Release User, Release Password에 사용하는 키 저장소와 별칭, 암호를 설정하고 Export With Debug를 해제합니다. 비밀번호를 스크립트나 공개 저장소에 적지 마세요.

Google Play App Signing을 사용할 때는 앱 서명 키와 업로드 키를 구분합니다. Google에 올리는 파일의 서명과 사용자에게 전달되는 앱의 서명이 같은 역할을 하는 것은 아닙니다. 키 관리와 분실 시 절차는 Android 앱 서명 문서를 기준으로 준비하세요.

6. 네이티브 라이브러리까지 확인합니다

Godot 게임은 엔진 자체의 네이티브 라이브러리를 포함합니다. GDScript만 썼다고 네이티브 요구사항이 사라지는 것은 아닙니다. 16KB 메모리 페이지 크기 지원은 엔진뿐 아니라 추가한 광고·결제 플러그인의 라이브러리도 확인해야 합니다. 검사 방법은 Android 16KB 페이지 크기 지원 문서에 있습니다.

같은 빌드에서 대상 API와 64비트 지원, 네이티브 호환성을 같이 보고 Console의 번들 분석까지 읽으십시오.

경고를 없애려고 숫자만 올리고 실행 검사를 건너뛰면 안 됩니다. 숫자는 통과했는데 게임이 안 켜지는 상태로 올라갑니다. 그리고 올라간 versionCode 는 돌아오지 않습니다 — 출시가 오류로 막혀도, 임시 출시를 지워도 그 번호는 영영 못 씁니다. 고쳐서 다시 구울 때는 번호도 같이 올려야 합니다.

다음 단계

손에 남아야 하는 것은 셋입니다. 서명한 AAB, 쓴 에디터·SDK·플러그인 버전 목록, 실기기 테스트 기록. 셋이 다 있으면 Google Play 출시 체크리스트로 넘어가 스토어 정보와 심사 자료를 준비하면 됩니다.

실기기에서 무엇을 어떻게 재는지는 성능·소리·입력 오류를 재현하고 검증하는 방법에 양식으로 적어 두었고, 처음부터 만드는 과정은 입문 과정에 있습니다.