Godot Android Build Environment (GABE): PC 없이 게임 Compile 및 Export하기

모든 인디 개발자들은 모바일 게임을 빌드할 때, 간단한 Android plugin이나 Google Play Services 연동을 테스트하기 위해 다시 데스크톱 PC로 돌아가야만 하는 좌절감을 잘 알고 있습니다. 최근까지도 Godot 사용자들은 Android 기기에서 씬을 디자인하고 로직을 작성할 수 있었지만, native code가 포함된 커스텀 Gradle release를 컴파일하려면 전체 데스크톱 워크스테이션이 필요했습니다. GABE (Godot Android Build Environment)의 릴리즈는 이러한 마찰을 해결하여 Android 기기 및 XR 헤드셋에서 직접 실행되는 안정적인 독립형 compilation environment를 제공합니다.

모바일 게임 개발에서의 PC 의존성 트랩

모바일 및 XR 플랫폼에서 직접 게임을 개발하는 것은 특히 1인 크리에이터와 이동 중에 작업하는 개발자들 사이에서 증가하는 트렌드입니다. 하지만 가장 큰 병목 현상은 항상 compilation과 packaging이었습니다. 커스텀 빌드 지원이 없으면 개발자는 미리 컴파일된 export templates에 의존해야 합니다. 이러한 템플릿은 게임의 에셋 패키지(.pck 또는 .zip)를 내부에 복사하고 파일에 서명하는 pre-built APK로, 기본적인 게임에는 잘 작동하지만 native 플랫폼 연동이 필요한 순간 바로 한계에 부딪힙니다.

프로젝트에 Google Play Billing, 커스텀 알림 채널 또는 심층적인 Quest SDK 연동이 필요한 경우 반드시 Gradle을 사용해야 합니다. Godot에서 "Use Gradle Build" 옵션을 활성화하면 엔진은 Android Java 또는 Kotlin 클래스를 소스에서 다운로드하고 구성 및 컴파일하도록 강제합니다. GABE 이전에는 에디터에 build tools를 가져오고, JDK tasks를 실행하며, 기기에서 native 라이브러리(.aar 파일)를 링크하는 환경이 없었기 때문에 이것이 불가능했습니다. 개발자들은 최종 빌드를 실행하기 위해 결국 PC로 돌아가야만 했습니다.

이러한 PC 의존성은 파이프라인 마찰을 크게 유발합니다. 개발자가 native plugin의 코드 한 줄을 수정할 때마다 프로젝트를 데스크톱 기기로 복사하고, 전체 Gradle sync를 실행한 뒤, 컴파일하고, APK를 다시 모바일 기기로 전송하여 설치해야 합니다. 이 루프는 30초짜리 로직 수정 작업을 컴파일 및 전송이라는 10분짜리 골칫거리로 쉽게 만들어 버립니다. GABE는 이 사이클을 제거하여 개발자가 모바일 하드웨어에서 로컬로 전체 compile pipeline을 처리할 수 있도록 지원합니다.

GABE 작동 원리: IPC, Sockets 및 Sandboxed Compilation

GABE는 메인 Godot Editor와 분리된 백그라운드 daemon 프로세스로 작동합니다. 이러한 격리는 Android의 엄격한 sandboxing 모델로 인해 강제된 중요한 디자인 선택입니다. 단일 Android 애플리케이션은 보안 매개변수를 위반하거나 메모리 실행 제한에 걸리지 않고 headless Gradle 컴파일러를 실행하고, OpenJDK 환경을 호스팅하며, native linker 명령을 실행하기 어렵습니다. GABE는 필요한 컴파일러 라이브러리를 보유하고 별도의 sandbox에서 compilation 작업을 실행하는 전용 헬퍼 앱 역할을 합니다.

Android 또는 Quest의 Godot Editor에서 커스텀 export를 트리거하면 에디터는 로컬 loopback port 또는 Android의 Binder 인터페이스를 통해 GABE와의 IPC 연결을 시작합니다. Godot는 타겟 SDK 버전, build configurations 및 keystore 경로와 같은 export 속성을 직렬화하여 GABE로 전송합니다. 이후 컴패니언 앱이 build pipeline의 제어권을 가져와 필요한 dependency resolution, SDK 관리, 컴파일 및 서명 작업을 수행합니다. 이를 통해 리소스를 많이 소모하는 build pipeline을 에디터 인터페이스로부터 격리 상태로 유지합니다.

안정적인 릴리즈를 통해 GABE는 socket 연결 끊김과 경로 해석 크래시가 빈번하던 실험적인 alpha 툴에서 프로덕션 환경에 적합한 컴파일러로 거듭났습니다. 버전 비교에 따르면 안정판은 task-handshake 실패를 95% 이상 줄였으며 Gradle 8.x를 사용하는 커스텀 플러그인을 완전히 지원하여 최신 Play Asset Delivery 표준과의 호환성을 보장합니다. 실질적으로 이는 PC라는 가교 없이도 Meta Quest 3 또는 Android 기기에서 릴리즈 APK를 직접 빌드하고, 서명하며, 스토어에 업로드할 수 있음을 의미합니다.

GABE는 백그라운드에서 실행 상태를 유지하는 Gradle daemon을 유지하므로, 이후 빌드는 훨씬 더 빨라집니다. 첫 컴파일 시에는 dependencies를 다운로드하고 모든 클래스를 처음부터 컴파일해야 하지만, incremental builds는 캐시된 클래스를 재사용하여 compile time을 몇 분에서 몇 초 단위로 단축시킵니다.

상세 가이드: 완전한 모바일 Export Pipeline 구축하기

로컬 모바일 빌드 파이프라인을 설정하려면 Godot와 GABE가 디렉터리 스코프를 올바르게 공유하도록 구성해야 합니다. 경로가 올바르지 않으면 Android의 scoped storage 제한으로 인해 GABE가 프로젝트 파일을 찾지 못하거나 최종 APK를 쓰지 못할 수 있습니다.

1단계: GABE 설치 및 Storage 구성

먼저 대상 기기의 Google Play Store 또는 Meta Horizon Store에서 안정적인 GABE 클라이언트를 설치합니다. GABE를 처음 실행하면 디렉터리 권한을 요청하는 메시지가 표시됩니다. Godot 프로젝트가 저장된 디렉터리(예: /Documents/GodotProjects/)에 대한 접근 권한을 GABE에 부여해야 합니다. 이 단계는 필수적이며, GABE가 프로젝트 소스 파일을 읽을 수 없으면 Gradle 템플릿을 컴파일할 수 없습니다.

2단계: Godot Editor Export 설정 구성

Android의 Godot Editor에서 프로젝트를 열고 Project > Export로 이동합니다. Android export 프리셋을 추가하고 필요한 매개변수를 구성합니다. 기본 사전 컴파일 템플릿을 사용하는 대신 "Use Custom Build" 옵션을 활성화하여 Gradle wrapper를 생성합니다. 타겟 export 경로가 GABE의 접근을 허용한 디렉터리와 일치하는지 확인하고 .debug.keystore 또는 릴리즈 keystore 파일을 지정합니다.

3단계: Export 실행 및 로그 모니터링

"Export Project"를 클릭하고 대상을 선택합니다. Godot는 빌드 요청을 GABE에 자동으로 전달합니다. Godot 에디터 콘솔에 GABE의 빌드 출력이 실시간으로 표시됩니다. Gradle tasks가 실행되는 것을 지켜보며 외부 기기 로그를 확인하지 않고도 구문 오류나 dependency 문제를 즉시 포착할 수 있습니다.

Native Android Plugins를 GDScript에 연결하기

GABE가 Gradle exports를 관리하게 되면 게임 코드에서 native Android plugins를 직접 활용할 수 있습니다. 다음 GDScript 예제는 native Google Play Billing 플러그인과 상호 작용하기 위한 프로덕션급 wrapper를 보여줍니다. 여기에는 PC 에디터 실행을 처리하기 위한 조건부 검사가 포함되어 있으며 Android 플랫폼 API에 필요한 비동기 콜백을 처리합니다.

# plugin_manager.gd
extends Node

signal purchase_completed(item_id: String, token: String)
signal purchase_failed(error_message: String)

var _billing_plugin: Object = null
const PLUGIN_NAME = "GodotGooglePlayBilling"

func _ready() -> void:
    _initialize_billing_plugin()

func _initialize_billing_plugin() -> void:
    # Check if the engine is running on Android and has the native singleton
    if Engine.has_singleton(PLUGIN_NAME):
        _billing_plugin = Engine.get_singleton(PLUGIN_NAME)
        
        # Connect Android native callbacks to GDScript functions
        _billing_plugin.connect("connected", Callable(self, "_on_billing_connected"))
        _billing_plugin.connect("disconnected", Callable(self, "_on_billing_disconnected"))
        _billing_plugin.connect("purchases_updated", Callable(self, "_on_purchases_updated"))
        _billing_plugin.connect("purchase_error", Callable(self, "_on_purchase_error"))
        
        # Start the billing connection
        _billing_plugin.startConnection()
        print("GABE Build verified: Native billing plugin loaded successfully.")
    else:
        # Fallback for PC editor debugging or non-Gradle exports
        print("Billing plugin not found. Running in mock/sandbox environment.")
        _billing_plugin = null

func purchase_item(item_id: String) -> void:
    if _billing_plugin:
        var sku_details = {
            "sku": item_id,
            "type": "inapp"
        }
        # In Godot 4.x, interacting with native Java arrays/dictionaries requires strict type mapping
        var query_result = _billing_plugin.querySkuDetails([item_id], "inapp")
        if query_result == 0: # OK code
            _billing_plugin.purchase(item_id)
        else:
            emit_signal("purchase_failed", "Failed to query item details from Google Play.")
    else:
        # Mock purchase behavior for local testing
        await get_tree().create_timer(1.0).timeout
        emit_signal("purchase_completed", item_id, "mock_token_12345_no_pc")

func _on_purchases_updated(purchases: Array) -> void:
    for purchase in purchases:
        if purchase.purchase_state == 1: # PURCHASED state
            # Acknowledge the purchase or consume it (mandatory in Google Play Billing Library v5+)
            if not purchase.is_acknowledged:
                _billing_plugin.acknowledgePurchase(purchase.purchase_token)
            emit_signal("purchase_completed", purchase.sku, purchase.purchase_token)

func _on_purchase_error(code: int, message: String) -> void:
    emit_signal("purchase_failed", "Billing error " + str(code) + ": " + message)

func _on_billing_connected() -> void:
    print("Successfully connected to Google Play Billing Service.")

func _on_billing_disconnected() -> void:
    print("Disconnected from Google Play Billing Service. Retrying connection...")

이 wrapper는 표준 에디터 viewport 내에서 디버깅하거나 native Android API를 사용할 수 없는 플랫폼에서 코드가 크래시되지 않도록 보장합니다. 로직을 분리함으로써 어느 기기에서나 안전하게 UI layout을 작성하고 테스트할 수 있으며, GABE 컴파일 exports에 전체 native 연동을 보존할 수 있습니다. 이 디자인은 모바일 결제 액션의 동적인 특성을 처리하기 위해 명시적인 signal mapping을 사용합니다.

하드웨어의 현실: ARM에서의 Thermal Throttling과 리소스 소모

데스크톱 PC에 존재하지 않는 하드웨어 병목 현상이 Android 기기에서 게임을 컴파일할 때 발생합니다. 이러한 물리적 한계를 이해하면 빌드를 최적화하고 크래시를 예방할 수 있습니다.

지속적인 CPU 부하와 Thermal Throttling

최신 모바일 프로세서(예: Snapdragon 8 Gen 2 또는 Gen 3)는 이기종 CPU 레이아웃(ARM big.LITTLE)을 사용합니다. 이들은 단기간의 성능 급증을 위해 설계된 소수의 고성능 코어와 여러 개의 전력 효율적인 코어를 갖추고 있습니다. 컴파일 작업은 지속적이고 고도로 병렬화된 multithreaded task로, 모든 big cores를 100% 용량으로 실행합니다.

무거운 빌드가 시작된 지 60~90초 이내에 기기의 thermal controller가 손상을 방지하기 위해 performance cores의 클럭 속도를 낮추게 됩니다(종종 40% 이상 감소). 이로 인해 컴파일 속도가 떨어집니다. 기기가 식었을 때 45초 걸리던 빌드가 이전 컴파일 직후에 실행하면 쉽게 3분을 넘어갈 수 있습니다.

스토리지 및 메모리 압박

Gradle은 메모리에 파일을 캐시하는 백그라운드 daemon을 실행하여 많은 리소스를 소모하는 것으로 악명이 높습니다. 8GB RAM 기기에서 Godot와 GABE를 동시에 실행하면 Android Out-Of-Memory (OOM) killer가 프로세스 중 하나를 종료할 수 있습니다. 이를 방지하려면 gradle.properties를 설정하여 Gradle의 메모리 풋프린트를 제한해야 합니다(예: 최대 힙을 2GB로 설정).

또한 Gradle의 dependency 캐시(.gradle/caches)와 SDK build tools는 스토리지를 빠르게 비대하게 만들 수 있습니다. 몇 개의 native plugins가 포함된 간단한 프로젝트도 3GB에서 5GB의 스토리지를 쉽게 소모합니다. 기기의 쓰기 수명이 제한되어 있거나 여유 공간이 적은 경우, 높은 I/O 대기 시간으로 인해 컴파일 속도가 현저히 느려집니다.

Backend 격차 해소: 로컬 서버 없이 Multiplayer 시스템 개발하기

Android 폰이나 XR 헤드셋에서 완전히 개발하는 것은 클라이언트 측 편집 문제를 해결하지만, 큰 아키텍처 문제를 야기합니다. 바로 Backend를 어떻게 실행하고 테스트할 것인가입니다. 데스크톱 컴퓨터에서 개발자는 보통 Docker compose를 사용하여 로컬 backend stack을 실행하고, 로컬 PostgreSQL 인스턴스를 호스팅하며, Redis 캐시를 실행하고, backend game servers를 배포합니다. Android에서는 Docker를 실행할 수 없으며, 백그라운드에서 여러 서버 데이터베이스를 실행하는 것은 OS 커널 보안 정책 및 메모리 제한으로 인해 차단됩니다.

Backend를 수동으로 빌드하고 실행하려 한다면 그 과정은 믿을 수 없을 정도로 지루합니다. 원격 virtual private server (VPS)를 구매 및 구성하고, reverse proxies를 설정하며, 모바일 터미널에서 SSH를 통해 코드를 배포하기 위한 shell scripts를 작성해야 합니다. 게다가 database schema가 변경될 때마다 불안정한 모바일 인터넷 연결을 통해 수동 migrations를 실행해야 합니다. 이러한 설정 과정은 게임 코드 한 줄을 작성하기도 전에 쉽게 4~6주의 인프라 작업을 추가합니다.

여기서 관리형 Backend-as-a-Service가 모바일 파이프라인의 핵심 도구가 됩니다. 원격 Linux VMs를 설정하고 관리하는 대신, horizOn은 Godot의 워크플로우에 직접 들어맞는 사전 구성된 backend를 제공합니다. 사용자 인증, 크로스 플랫폼 클라우드 저장, remote configs 및 실시간 leaderboards와 같은 공통 게임 기능이 클라우드에서 완전히 관리됩니다.

이들의 SDK를 Godot 프로젝트에 통합함으로써, 게임 클라이언트는 serverless backend endpoints에 직접 연결됩니다. 이 아키텍처를 통해 GABE로 컴파일된 빌드 내에서 직접 로그인 상태를 테스트하고, 플레이어 프로필을 동기화하며, leaderboard 데이터를 가져올 수 있습니다. 이를 통해 서버 하나조차 직접 관리할 필요 없이 모바일 기기나 VR 헤드셋만으로 완전하고 전문적인 게임 개발 라이프사이클을 실현할 수 있습니다.

PC 없는 Godot 개발을 위한 Best Practices

데스크톱 PC 없이 게임을 개발할 때 생산적인 워크플로우를 유지하려면 다음 최적화 가이드라인을 따르세요.

1. Gradle Daemon 메모리 사용량 제한: 프로젝트의 커스텀 gradle.properties에 org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m을 추가합니다. 이렇게 하면 대규모 컴파일 작업 중에 Android 메모리 관리자가 Godot나 GABE를 종료하는 것을 방지할 수 있습니다.
2. 로직 반복 작업을 위한 로컬 모킹 활용: native plugins를 테스트하거나 릴리즈 패키지를 준비할 때만 GABE Gradle 빌드를 실행하세요. 일상적인 게임플레이 스크립팅의 경우, mock configurations를 사용하여 Godot 에디터의 내장 플레이어를 통해 게임을 즉시 실행하십시오.
3. 내부 스토리지 정리 유지: 정기적으로 프로젝트 디렉터리로 이동하여 임시 .godot/ 폴더와 Gradle 빌드 폴더를 삭제하세요. 일주일에 한 번씩 이러한 캐시를 정리하면 수 기가바이트의 공간을 확보하고 불명확한 컴파일 캐시 버그를 해결할 수 있습니다.
4. 관리형 서비스 활용: 커스텀 데이터베이스 커넥터나 서버 루프를 직접 작성하는 것을 피하세요. 관리형 플랫폼 서비스를 통합하여 클라이언트 측 연동 코드를 단순하게 유지하고 컴파일 속도를 높이십시오.
5. 필요하지 않은 경우 Multi-dexing 비활성화: 게임이 64k method limit를 초과하지 않는 경우 빌드 파일에서 multi-dexing을 비활성화하세요. 이를 통해 보조 classes.dex 파일의 생성을 피해 컴파일 오버헤드를 줄이고 패키지 크기를 감소시킵니다.

GABE를 사용하여 프로젝트를 컴파일하면 Android 게임의 native 연동을 완전히 제어할 수 있습니다. 로컬 컴파일과 관리형 클라우드 backend를 결합하면 PC를 켤 필요 없이 프로토타입에서 최종 스토어 등록까지 진행할 수 있습니다.

Multiplayer backend를 확장할 준비가 되셨나요? horizOn을 무료로 체험해 보거나 API docs를 확인해 보세요.

---

Source: Creating games entirely on Android!