Godot 4.5 ile Google Play Games Entegrasyonu: Kesin ve Çalışan Rehber
Godot motorunda oyun geliştiriyorsanız ve oyuncularınıza "Liderlik Tabloları" (Leaderboards) veya "Başarımlar" (Achievements) sunmak istiyorsanız, Google Play Games Services (GPGS) entegrasyonu kaçınılmazdır. Ancak bu süreç, özellikle Android'in katı güvenlik kuralları ve "sessizce iptal etme" huyları yüzünden bir kabusa dönüşebilir.
Bu makalede, Godot 4.5 versiyonu ve Jacob Ibanez Sanchez tarafından yazılan GodotPlayGameServices eklentisini kullanarak sıfır hatalı, stabil bir entegrasyonun nasıl yapılacağını adım adım inceleyeceğiz. Ayrıca, haftalarca zaman kaybetmenize sebep olabilecek "Muhtemel Hatalar ve Tuzaklar" bölümüne de mutlaka göz atın!
1. Hazırlık ve Eklenti Kurulumu
İlk olarak Jacob Ibanez'in eklentisini projenizin addons/ klasörüne dahil edin ve Godot'un Project -> Project Settings -> Plugins sekmesinden aktifleştirin.
En Önemli Adım (App ID): Eklentiyi aktifleştirdikten sonra Godot'un alt panelinde "Godot Play Game Services" adında bir sekme (Dock) belirecektir. Buradaki Project ID kısmına Google Play Console'dan aldığınız 12 haneli oyun ID'nizi yazıp kaydetmeyi (Apply) unutmayın. Bu, ID'nizin Android'in strings.xml dosyasına gömülmesini sağlar.
⚠️ KRİTİK DÜZELTME: Eklentinin Dosya Yolu Hatası
Eklentiyi indirip kurduğunuzda, eklentinin kendi kaynak kodunda küçük bir hata bulunabilir. APK alırken Java (.aar) çekirdeğinin APK içine gömülememesi sorunuyla karşılaşabilirsiniz.
Bunu çözmek için res://addons/GodotPlayGameServices/export_plugin.gd dosyasını açın ve _get_android_libraries fonksiyonunu şu şekilde düzeltin (Başına res://addons/ ekliyoruz):
func _get_android_libraries(platform, debug):
if debug:
return PackedStringArray(["res://addons/" + _plugin_name + "/bin/debug/" + _plugin_name + "-debug.aar"])
else:
return PackedStringArray(["res://addons/" + _plugin_name + "/bin/release/" + _plugin_name + "-release.aar"])
2. Doğru Kod Mimarisi (Demo Standartı)
Eklentiyi kullanırken yapılan en büyük hata, doğrudan Java/Native metodları (_native_plugin.signIn()) çağırmaya çalışmaktır. Bunun yerine, eklentinin kendi GDScript Singleton'u (/root/GodotPlayGameServices) üzerinden "Initialization" (Başlatma) sırasını takip etmelisiniz.
İşte Game Manager veya benzeri bir ana betiğinizde kullanmanız gereken kesin yapı:
A. Değişkenleri Tanımlama
var _sign_in_client: PlayGamesSignInClient
var _leaderboards_client: PlayGamesLeaderboardsClient
var _is_gpg_initialized: bool = false
const LEADERBOARD_ID = "CgkI........" # Sizin Tablo ID'niz
B. Sistemi Başlatma (Initialization)
Oyun açıldığında (_ready içinde) eklentiyi uyandırmalıyız:
func _setup_gpg_services() -> void:
_sign_in_client = PlayGamesSignInClient.new()
_leaderboards_client = PlayGamesLeaderboardsClient.new()
add_child(_sign_in_client)
add_child(_leaderboards_client)
var gpgs_autoload = get_node_or_null("/root/GodotPlayGameServices")
if gpgs_autoload != null:
# Eklenti hazır olduğunda bize sinyal verecek
if gpgs_autoload.has_signal("on_initialization_complete"):
gpgs_autoload.connect("on_initialization_complete", _on_gpg_initialized)
# Eklentiyi başlat
gpgs_autoload.initialize()
C. Otomatik Giriş ve Sinyal
Eklenti hazır olduğunda, oturum açma işlemini tetikleriz. (Android v2 SDK zaten oyunu açarken ekranda otomatik "Merhaba" der, bu komut sadece bunu doğrular).
func _on_gpg_initialized() -> void:
_is_gpg_initialized = true
# Eklenti hazır, girişi doğrula
if _sign_in_client.has_method("sign_in"):
_sign_in_client.sign_in()
D. Liderlik Tablosunu Açma (Engelsiz Yapı)
Geliştiricilerin en çok yaptığı hata: if _is_logged_in == false: return şeklinde sahte engeller koymaktır. Android sistemi giriş işlemini kendi içinde hallettiği için, düğmeye basıldığında doğrudan açma komutu verilmelidir.
func on_leaderboard_pressed() -> void:
if not _is_gpg_initialized:
print("Sistem hazır değil.")
return
# ÖNEMLİ: Tabloyu açmadan önce güncel skoru mutlaka yollayın
# Puanı 0 olan veya hiç skor yollamamış oyunculara tablo AÇILMAZ!
var current_score = max(1, oyuncu_puani)
_leaderboards_client.submit_score(LEADERBOARD_ID, current_score)
# Tabloyu Göster
_leaderboards_client.show_leaderboard(LEADERBOARD_ID)
3. GPGS "Sessiz İptaller" ve Çözüm Rehberi (Karşılaşılan Tuzaklar)
Eğer her şeyi doğru yapmanıza rağmen, tablo butonuna bastığınızda hiçbir şey olmuyorsa (hata bile vermiyorsa), Android sistemi isteğinizi sessizce iptal ediyor demektir. İşte tecrübeyle sabitlenmiş 5 büyük tuzak ve çözümleri:
Tuzak 1: "Export With Debug" Tuzağı (SHA-1 Uyuşmazlığı)
Belirti: Oyun açılışında "Merhaba [Kullanıcı Adı]" yazar ama tablo bir türlü açılmaz. Neden: Google Play Console'a kendi ürettiğiniz release.keystore dosyasının SHA-1 parmak izini girdiniz. Ancak Godot'ta Export alırken çıkan dosya kaydetme penceresinin en altındaki "Export With Debug" tikini açık unuttunuz. Godot, kendi uyduruk debug şifresini kullandı. Google sahte şifreyi algılayıp tablo erişimini kilitledi. Çözüm: Godot üzerinden Android APK çıktısı alırken "Export With Debug" kutucuğundaki tiki kaldırarak APK alın.
Tuzak 2: Google Cloud "Test Kullanıcısı" Unutkanlığı
Belirti: Play Console'da her şey yeşil yanıyor ama hesaba giriş yapılamıyor. Neden: Play Games hizmeti yayınlanmadan (Taslak aşamasında) test ediliyorsa, Google sadece izin verilen E-Posta adreslerini kabul eder. Çözüm: Sadece Play Console'a değil, Google Cloud Console -> API'ler ve Hizmetler -> OAuth Onay Ekranı bölümüne giderek, telefonda oyunu oynadığınız E-Posta adresini "Test Kullanıcıları (Test Users)" listesine eklediğinizden emin olun.
Tuzak 3: ClassDB.class_exists() Hatası
Belirti: Eklentinin sınıfları kodda bulunamıyor veya yüklenmiyor. Neden: Eğer eklentinin sahnede olup olmadığını if ClassDB.class_exists("PlayGamesSignInClient"): ile denetlerseniz, kod her zaman iptal olur. Çünkü ClassDB, Godot'un sadece kendi gömülü (C++) sınıflarını okur, class_name ile tanımlanmış GDScript sınıflarını göremez. Çözüm: Bu tarz güvenlik denetimlerini silin. Node'u doğrudan PlayGamesSignInClient.new() ile örnekleyin.
Tuzak 4: "Görünmez Profil" Bug'ı
Belirti: Tüm ayarlar mükemmel. Eklenti "Tablo Açılıyor" diyor ama ekrana hiçbir şey gelmiyor. Neden: Google Play Games'te bir oyuncu, liderlik tablosuna hayatında ilk defa tıklıyorsa ve skoru "0" ise (veya hiç skor gönderilmemişse), Android işletim sistemi o tabloyu "Görüntülenecek veri yok" diyerek açmayı reddeder. Çözüm: Tabloyu aç (show_leaderboard) komutundan sadece milisaniyeler önce arka planda submit_score ile (en azından 1 puan bile olsa) bir skor gönderin. Bu, oyuncunun tablodaki profilini zorla oluşturur ve ekran %100 oranında açılır.
Tuzak 5: Boşluk ve Tab Karmaşası (Unindent Error)
Belirti: Godot Expected end of file veya Unindent doesn't match... hatası fırlatıyor. Neden: İnternetten (veya AI'dan) kod kopyalarken Godot editörüne Boşluk (Space) ve Tab (Sekme) karakterleri karışık girmiştir. Godot bu konuda çok hassastır. Çözüm: Hata veren dosyayı açın, tüm metni seçin (Ctrl+A), üst menüden Edit -> Convert Indent To Tabs seçeneğine tıklayıp kaydedin.
Son Söz
Google Play Games Services entegrasyonu, özellikle API'lerin test ortamındaki davranışları nedeniyle zorlayıcı olabilir. Ancak GodotPlayGameServices eklentisi ve yukarıdaki doğru başlatma mimarisi kullanıldığında, "Export With Debug" ve "SHA-1" tuzaklarına düşmediğiniz sürece sistem tamamen sorunsuz, stabil ve kararlı (production-ready) olarak çalışmaktadır.
Ek Bölüm: Tüm Kullanıcılar İçin Play Games Girişi ve Liderlik Tablosu Ayarları (Üretime Alma)
Oyununuzu test aşamasında (Internal/Closed Testing) denerken sadece Google Cloud üzerinde izin verdiğiniz e-posta adresleri (Test Kullanıcıları) Play Games'e giriş yapabilir. Oyununuzu Play Store'da herkese açık olarak yayınladığınızda, diğer tüm organik oyuncuların da sorunsuz giriş yapabilmesi ve Liderlik Tablosunu görebilmesi için aşağıdaki iki platformda "Üretime Alma" işlemlerini tamamlamanız şarttır.
1. Google Cloud Console: OAuth İzin Ekranını "Üretime" Almak
Google, güvenlik gereği yeni oluşturulan API projelerini varsayılan olarak "Test" modunda tutar. Bu modu kapatmadığınız sürece, harici oyuncular Google hesaplarıyla oyununuza yetki veremez ve giriş işlemi iptal edilir.
- Google Cloud Console'a (
console.cloud.google.com) gidin ve oyununuza ait Play Games projesini seçin. - Sol menüden API'ler ve Hizmetler > OAuth İzin Ekranı (OAuth consent screen) sekmesine tıklayın.
- Ekranda "Yayınlama durumu" (Publishing status) kısmında Test Aşamasında (Testing) yazdığını göreceksiniz.
- Hemen altındaki Uygulamayı Yayınla (Publish App) veya Üretime Taşı (Push to production) butonuna tıklayın.
- Gelen uyarı penceresini onaylayın. Artık durum Üretimde (In production) olarak görünecektir. Bu sayede uygulamanız, tanımlı olmayan cihazlardan ve hesaplardan gelen Play Games oturum açma isteklerini de kabul etmeye başlar.
2. Google Play Console: Play Games Hizmetlerini Yayınlamak
OAuth izinlerini genel erişime açmak tek başına yeterli değildir; Play Games Services altyapınızın da "Taslak" (Draft) durumundan çıkarılıp aktif hale getirilmesi gerekir. Aksi takdirde oyuncular giriş yapsa bile Liderlik Tablosu (Leaderboard) veya Başarımlar (Achievements) arayüzleri yüklenmez.
- Google Play Console'a giriş yapın ve oyununuzu seçin.
- Sol menüden aşağı inerek Play Games Hizmetleri > Kurulum ve Yönetim > Yayınlama (Publishing) sayfasına gidin.
- Sayfadaki adımları takip ederek Oyunu Yayınla (Publish Game) butonuna tıklayın.
- Önemli Not: Bu işlemi yapabilmek için uygulamanızın OAuth izin ekranının (1. adım) üretimde olması ve Play Games tarafında gerekli ikon, açıklama ve en az bir adet Liderlik Tablosu kaydının tamamlanmış olması gerekir.
3. Kritik Hatırlatma: Çift SHA-1 Sertifikası Mimarisi
Oyuncuların cihazlarında Liderlik Tablosunu açmaya çalışırken "Sürekli profil seçme ekranına geri atma" döngüsünü kalıcı olarak engellemek için, Google Cloud Console > Kimlik Bilgileri (Credentials) sayfanızda her zaman iki adet bağımsız Android OAuth İstemcisi bulunmalıdır:
- Geliştirici İstemcisi (Yerel Test ve Godot İçin): Oyun motorundan bilgisayarınızda derlediğiniz ve doğrudan telefona attığınız APK/AAB sürümünün çalışması için
debug.keystore(veya yerelrelease.keystore) SHA-1 kodunu içeren istemci.
- Üretim İstemcisi (Play Store İçin): Google Play Console'daki Kurulum > Uygulama Bütünlüğü (App Integrity) > Uygulama İmzalama (App signing) sekmesinde yer alan "Uygulama imzalama anahtarı sertifikası" altındaki SHA-1 kodunu içeren istemci. Mağazadan oyunu indiren tüm kullanıcıların kimlik doğrulamasını bu sertifika üstlenir.
İyi oyun geliştirmeler!
Yorumlar
Yorum Yaz