Geri Dön / Back to Lobby

Geliştirici Notları: Hızlı İsim Şehir

Giriş ve Mimari Yaklaşım

Paira Hızlı İsim Şehir, geleneksel isim şehir oyununun temposunu ve heyecanını zirveye çıkaran, tamamen tarayıcı tabanlı çalışan bir P2P (Peer-to-Peer) kelime oyunudur. Klasik modun aksine, bu sürümde oyuncular her turda tek bir kategori ve harf için sıra tabanlı olarak yarışırlar. Veriler doğrudan oyuncuların cihazları arasında aktarılır; merkezi bir veritabanı veya aracı bir oyun sunucusu kullanılmaz.

Bütün durum yönetimi, tur geçişleri, otomatik API entegrasyonlu kelime doğrulamaları, oylama süreçleri ve süre takipleri, istemciler arasında senkronize bir şekilde Host-Client yapısı üzerinden koordine edilmektedir.

P2P Ağ Topolojisi (Host-Client Mimarisi)

Çok oyunculu altyapı, WebRTC (Web Real-Time Communication) tabanlı bir Host-Client (Kurucu-Katılımcı) modeli ile kurulmuştur:

• Host (Kurucu Node): Odayı açan oyuncu, oyun motorunun lideri ve hakemidir. Oyun ayarlarını (kategori listesi, tur sayıları, cevaplama süreleri), aktif oyuncuların durumlarını ve tur sıralarını yerel tarayıcı belleğinde yönetir. Sırası gelen oyuncu için rastgele harf ve kategori atar. Oyuncu cevabını gönderdiğinde kelime doğrulama motorunu tetikler ve skoru diğer istemcilere dağıtır.
• Clients (Katılımcı Peer'lar): Odaya katılan diğer oyuncular, Host ile doğrudan RTCDataChannel üzerinden eşler arası bağlantı kurar. Katılımcılar verdikleri cevapları, itirazlarını ve oylarını Host'a iletir; Host ise güncel oyun durumunu, süreleri ve oylamaları katılımcılara yayınlar (broadcast).
• Sinyalleşme (Signaling): Eşlerin birbirlerini bulması ve SDP/IP el sıkışmalarını gerçekleştirmesi için aracı bir PeerJS sinyalleşme sunucusu kullanılır. Bağlantı sağlandıktan sonra bu sunucu aradan çekilir ve tüm iletişim doğrudan cihazlar arasında P2P olarak sürer.

Gerçek Zamanlı Veri Senkronizasyonu ve İletişim Protokolü

Hızlı İsim Şehir oyununda tüm eylemler RTCDataChannel üzerinden JSON paketleri şeklinde aktarılır. Bu paketteki veri tipleri ve senkronizasyon modelleri şu şekildedir:

• CONFIG_UPDATE: Lobi ayarları (seçilen kategoriler, tur süreleri) güncellendiğinde Host tarafından istemcilere senkronize edilir.
• TIMER_SYNC: Süre takibinin tüm istemcilerde milisaniye hassasiyetinde senkron kalmasını sağlar. Sırası gelen oyuncunun süresi başladığında kalan süre Host tarafından hesaplanarak tüm eşlere bildirilir.
• SUBMIT_ANSWERS: Oyuncu kelimesini girip butona bastığında veya süresi dolduğunda, cevabı Host'a ulaştırır.
• TURN_RESULT: Host, gönderilen kelimeyi doğrulama motorunda işledikten sonra sonucu (kelimenin doğruluğu, kazanılan puan, itiraz edip edemeyeceği) tüm oyunculara yayınlar.
• APPEAL: Sıradaki oyuncunun cevabı 0 puan aldığında, oyuncunun yerel ekranında 3 saniyelik bir itiraz butonu belirir. Oyuncu bu süre içinde butona basarsa Host'a itiraz sinyali gider.
• START_VOTE, VOTE_UPDATE ve VOTE_RESULT: İtiraz yapıldığında Host, 10 saniyelik zaman odaklı hızlı oylama sürecini başlatır. Oyuncuların evet/hayır oyları gerçek zamanlı olarak senkronize edilir ve çoğunluğun kararına göre kelime kabul edilir veya reddedilir.
• SHOW_SCORES: Tur sonlarında hesaplanan güncel skor tablosunu tüm istemcilerin ekranına yansıtır.

Hibrit Doğrulama ve Değerlendirme Motoru

Oyuncunun gönderdiği kelime, Host üzerinde çalışan çok aşamalı bir hibrit değerlendirme motoru tarafından analiz edilir:

1. Yerel Kelime Sözlüğü (Offline Dictionary Check): İlk olarak, platform genelindeki statik kelime dosyaları (../IsimSehir/data/${catId}.json) yüklenir. Kelime sözlükte bulunursa ve istenen harfle başlıyorsa doğrudan geçerli kabul edilir.
2. Üçüncü Parti API Sorgulamaları (Real-Time Web Services): Sözlükte bulunamayan kelimeler için kategorilerine uygun gerçek zamanlı API'ler sorgulanır. Örneğin:
   • sehir: Nominatim (OpenStreetMap) ve Wikipedia coğrafi API'leri.
   • ulke: RestCountries API ve Wikipedia veri sorguları.
   • film_dizi ve muzik: iTunes API entegrasyonu.
   • sarkici: MusicBrainz ve Wikipedia aramaları.
   • yazar: OpenLibrary yazar dizini.
3. Gemini Yapay Zeka Hakemi (LLM Validation Fallback): Kelimenin geçerliliği yukarıdaki yöntemlerle saptanamazsa, Host tarayıcısı /api/ai/generate uç noktası üzerinden gemini-1.5-flash modeline bir doğrulama talebi gönderir. Yapay zeka modeli, kelimenin kategoriye ve harfe uygunluğunu saniyeler içinde analiz ederek son kararı verir.

Hız ve Kelime Uzunluğu Puanlaması

Klasik oyundan farklı olarak Hızlı İsim Şehir modunda kelime uzunluğuna dayalı dinamik bir puanlama ve hızlı karar mekanizması mevcuttur:

• Uzunluk Odaklı Puanlama: Doğrulanan kelimenin harf sayısı (uzunluğu), oyuncunun o turda kazandığı net puanı belirler (Örn: "Zonguldak" kelimesi 9 puan kazandırır). Bu durum, oyuncuları daha uzun ve yaratıcı kelimeler bulmaya teşvik eder.
• Zaman Kısıtlı İtiraz Penceresi: Hızı ve tempoyu korumak amacıyla, yanlış kabul edilen kelimeler için itiraz penceresi sadece 3 saniye açık kalır. İtiraz durumunda açılan oylama ise 10 saniye ile sınırlandırılmıştır.

Oda Yönetimi ve Güvenlik Protokolü

Oyun odaları, 6 karakterli benzersiz bir Oda Kodu ile kurulur. Host tarayıcısı sinyalleşme ağında hizliisimsehir-host-${roomCode} kimliğiyle yer alırken, katılımcı istemciler de kendi benzersiz ID'leri ile Host'a bağlanır.

WebRTC altyapısının sağladığı DTLS/SRTP şifrelemesi sayesinde, paylaşılan cevaplar, oylar ve oyuncu kimlikleri tamamen koruma altındadır. Sunucu tarafında hiçbir oyun verisi tutulmadığı için maksimum gizlilik ve sıfır gecikmeli oyun deneyimi sağlanmış olur.

Bu teknik dokümantasyon, Paira platformunun tarayıcı tabanlı çok oyunculu kelime oyunu altyapısını ve P2P veri senkronizasyon modellerini merak eden geliştiriciler için Ahmet Efe Yaşar tarafından hazırlanmıştır.