godot-kakao

Kakao SDK plugin for Godot 4.x — 카카오톡 공유(v1)부터 시작하는 모듈 추가형 우산 플러그인. Godot에는 카카오 SDK 바인딩이 없어서 만들었습니다.

현재 상태 (v0.1.0): ✅ 카카오톡 공유 — Android만 구현·검증됨. iOS와 카카오 로그인 등 나머지 SDK 모듈은 로드맵입니다(아래). API(Kakao.gd)는 플랫폼 무관 계약이라 iOS가 붙어도 게임 코드는 그대로입니다.

English: Kakao SDK bindings for Godot 4.x. v0.1.0 ships KakaoTalk share on Android only — iOS and Kakao Login are on the roadmap. Uploads a local image via Kakao's image server and opens the KakaoTalk friend picker with a branded feed template + app-launch button. Silent no-op everywhere Kakao isn't available (editor/desktop/unconfigured), so your desktop builds never break.

특징

• 카카오톡 공유 — 로컬 이미지(예: 게임 결과 카드)를 uploadImage(카카오 서버, 100일)로 올리고 피드 템플릿(제목/설명/이미지 + "나도 도전하기" 실행 버튼)으로 친구 픽커를 연다
• 딥링크 — 수신자가 버튼을 누르면 kakao{APP_KEY}://kakaolink 로 앱 실행 (get_launch_uri())
• 제로 설정 익스포트 — export 훅이 AAR·카카오 SDK 원격 의존·INTERNET·<queries>·intent-filter·앱키 meta-data 를 전부 자동 주입. 매니페스트 손편집 없음
• 안전한 휴면 — 앱키 미설정/데스크톱/에디터에선 전 API 가 조용한 no-op (is_share_available() == false)
• 우산 구조 — KakaoSdk.init·앱키·매니페스트 주입을 전 모듈이 공유하므로, 로그인(v2-user) 등이 와도 같은 AAR 에 의존+메서드만 추가

설치

1. 이 저장소의 addon/ 내용을 프로젝트의 res://addons/Kakao/ 로 복사 (또는 ./install.sh <프로젝트경로>)
2. Project → Project Settings → Plugins → Kakao 활성화
3. developers.kakao.com 앱 등록 → 네이티브 앱 키 를 Project Settings → Kakao → Native App Key (kakao/native_app_key) 에 입력
4. 플랫폼 → Android 등록: 패키지명 + 키 해시

   keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore \
     -storepass android -keypass android | openssl sha1 -binary | openssl base64

5. Android 익스포트 프리셋: Gradle 빌드 사용 = On (AAR 플러그인 필수)

사용법

var kakao := Kakao.new()   # addon/Kakao.gd — class_name Kakao 래퍼 노드
add_child(kakao)
kakao.share_succeeded.connect(func(): print("공유 완료(픽커 진입)"))
kakao.share_failed.connect(func(e): print("실패: ", e))

if kakao.is_share_available():          # 플러그인 + SDK init + 카카오톡 설치
    kakao.share_card("user://result.png", "제 7회차 인생 결산", "최종자산 ₩1.2억 · “고시원에서 시작해 전세로 죽다”")
else:
    pass  # OS 공유시트 등 자체 폴백 권장

API	설명
is_available()	네이티브 플러그인 로드 여부 (기기 + 익스포트 포함)
is_share_available()	지금 카카오톡 공유 가능 여부 (init + 카톡 설치)
share_card(image_path, title, desc)	이미지 업로드 → 피드 템플릿 → 친구 픽커. user:// 가능
get_launch_uri()	카카오 딥링크로 열렸을 때 그 URI ("" = 일반 실행)
시그널 share_succeeded / share_failed(reason)	완료(안드로이드는 "픽커 진입" 의미) / 실패 사유

카카오톡 미설치 기기는 웹 셰어러(커스텀탭)로 자동 폴백합니다.

AAR 빌드 (소스에서)

./build.sh        # JDK 17+ (Android Studio JBR 로 충분) · 산출물 → addon/bin/

핀 버전: Gradle 8.11.1 · AGP 8.6.1 · Kotlin 2.1.20 · compileSdk 35 · minSdk 24 · org.godotengine:godot:4.6.1.stable · com.kakao.sdk:v2-share:2.24.0 (카카오 SDK 는 AAR 에 번들하지 않음 — export 훅이 원격 의존으로 재선언. 버전 변경 시 android/build.gradle.kts 와 addon/kakao_export.gd 두 곳 동시 수정.)

아키텍처

Kakao.gd (class_name Kakao, 래퍼 노드)        ← 게임 코드가 만지는 층
  └─ Engine.get_singleton("KakaoPlugin")      ← Godot 플러그인 v2 (Kotlin, AAR)
       └─ com.kakao.sdk:v2-share              ← 카카오 공식 SDK (gradle 원격 해석)
kakao_export.gd (EditorExportPlugin)          ← AAR·의존·매니페스트 자동 주입 (앱키 없으면 전부 inert)

SDK init 은 카카오 문서의 Application#onCreate 요구를 만족시키기 위해 플러그인 onMainCreate 에서 수행합니다 — 앱키는 export 훅이 매니페스트 meta-data 로 주입하므로 런타임 GDScript init 이 없습니다.

로드맵 / 마일스톤

마일스톤	범위	상태
v0.1.0 — 카카오톡 공유 (Android)	이미지 업로드 → 피드 템플릿(실행 버튼) → 친구 픽커, export 자동 주입, 안전 휴면	✅ 완료
v0.2.0 — 카카오톡 공유 (iOS)	KakaoSDKShare(SPM) + Swift 플러그인. Kakao.gd 계약 그대로 → 게임 코드 무변경 · ios/README.md	⏳ 예정
v0.3.0 — 카카오 로그인	v2-user(Android)·KakaoSDKUser(iOS). 같은 우산 AAR 에 모듈 추가 — login()/토큰/사용자정보	⏳ 예정
v1.0.0 — 안정화 + AssetLib	데모 프로젝트, AssetLib 등록, API freeze, CI(AAR 빌드 검증)	⏳ 예정

세부 이슈는 GitHub Milestones 참조. 추가 예정: 딥링크 실행 파라미터 헬퍼, 카카오톡 채널/커스텀 템플릿.

라이선스

MIT