Geliştirici Notları: İsim Şehir

Giriş ve Mimari Yaklaşım

Paira İsim Şehir, klasik harfe göre kelime bulma oyununu dijital ortama taşıyan, verileri depolamak için hiçbir merkezi veritabanı (Database) veya aracı oyun sunucusu barındırmayan, tamamen tarayıcı tabanlı çalışan bir P2P (Peer-to-Peer) kelime oyunudur. Oyun, sıfır sunucu maliyeti ve uçtan uca şifrelenmiş veri kanalları ile oyuncuların hızlıca lobilere katılıp yarışabilmesi üzerine tasarlanmıştır.

Geleneksel sunucu tabanlı çok oyunculu oyunların aksine, İsim Şehir'de tüm durum yönetimi, tur geçişleri, kelime doğrulama süreçleri ve puanlama sistemi, tarayıcılar üzerinde koordine edilen Host-Client yapısı vasıtasıyla işletilmektedir.

P2P Ağ Topolojisi (Host-Client Yapısı)

Paira İsim Şehir'in çok oyunculu yapısı, WebRTC (Web Real-Time Communication) tabanlı bir Host-Client (Kurucu-Katılımcı) mimarisi üzerine kuruludur:

Host (Kurucu Node): Odayı oluşturan oyuncu, oyunun koordinatörü ve hakemidir. Oyun odasının kurucusu, yerel tarayıcı hafızasında oyun ayarlarını (kategoriler, süre sınırlaması, oyun sonlanma koşulu), aktif tur verilerini tutar. Harf belirleme sürecini yönetir, süre bittiğinde tüm istemcilerden gelen cevapları toplar ve kelime doğrulama motorunu çalıştırarak puanlama matrisini istemcilere sunar.
Clients (Katılımcı Peer'lar): Oda kodu ile bağlanan diğer istemciler, doğrudan Host ile peer-to-peer RTCDataChannel bağlantısı açarlar. Katılımcılar cevapları, oyları ve itirazları Host'a iletir; Host ise güncel oyun durumunu, oylama matrislerini ve skor tablosunu tüm istemcilere dağıtır (broadcast).
Sinyalleşme (Signaling): WebRTC bağlantısının kurulabilmesi (IP, port ve SDP alışverişi) için aracı bir PeerJS sinyalleşme sunucusu kullanılır. Bağlantı bir kez sağlandıktan sonra, bu sunucu devre dışı kalır ve tüm veri akışı doğrudan cihazlar arasında gerçekleşir.

Gerçek Zamanlı Veri Senkronizasyonu ve Mesajlaşma Protokolü

Oyun içerisindeki tur geçişleri, harf belirleme, girilen kelimeler, itirazlar ve puanlamalar RTCDataChannel üzerinden JSON formatında paketler halinde gönderilir. Bu iletişim protokolünde aşağıdaki mesaj tipleri kullanılır:

CONFIG_UPDATE: Host, lobi ayarlarını (kategoriler, tur süreleri, tur sonlanma kuralları) değiştirdiğinde bu güncellemeyi tüm istemcilere yayınlar.
START_ROUND & END_ROUND: Host tarafından turun başlatıldığını veya sonlandırıldığını bildiren durum tetikleyicileridir.
CHANGE_LETTER: Seçilen aktif tur harfini istemcilere deklare eder.
TIMER_SYNC: Süre takibinin tüm istemcilerde milisaniye hassasiyetinde senkron kalmasını sağlar.
PLAYER_FINISHED: Bir oyuncunun turu bitirdiğini (veya süresinin dolduğunu) ve cevaplarını Host'a göndermeye hazır olduğunu bildirir.
FINAL_ANSWERS: İstemciler tarafından doldurulan tüm kategorilerin cevaplarını (kelimeleri) Host'a ulaştırır.
START_VOTING & SYNC_LIVE_VOTES: Host'un cevap doğrulama sonuçlarını sunmasıyla oylama ekranını açar ve oyuncuların itiraz oylarını (SINGLE_VOTE) canlı olarak diğer oyuncularla senkronize eder.
SHOW_SCORES: Oylama tamamlandığında hesaplanan resmi puanları ve güncel sıralamayı istemcilere iletir.

Otomatik Kelime Doğrulama ve Hibrit Değerlendirme Motoru

İsim Şehir oyununda puanlama doğruluğunu artırmak ve yazım hatalarını önlemek için Host tarayıcısında çalışan çok katmanlı, hibrit bir doğrulama motoru geliştirilmiştir:

Yerel Sözlük Kontrolü (Offline Dictionary): İlk olarak, her kategori için hazırlanmış yerel sözlük verileri (data/${catId}.json) yüklenir. Girilen kelimenin sözlükte birebir bulunması durumunda kelime doğrudan geçerli kabul edilir.
Üçüncü Parti API Sorgulamaları (Real-time APIs): Kelime sözlükte bulunamazsa, kategorisine özel harici API'ler sorgulanarak kelimenin gerçekliği denetlenir:
- sehir: OpenStreetMap (Nominatim API) ve Wikipedia araması ile coğrafi doğrulama yapılır.
- ulke: RestCountries API ve Wikipedia araması ile ülke isimleri doğrulanır.
- film_dizi & muzik: iTunes API ve Wikipedia arama entegrasyonu kullanılır.
- sarkici: MusicBrainz ve Wikipedia API'leri aracılığıyla sanatçı/grup sorgulanır.
- yazar: OpenLibrary API ve Wikipedia araması.
- hastalik & spor: Wikipedia API üzerinden semantik kelime araması gerçekleştirilir.
Yapay Zeka Destekli Hakem (LLM Validation): Geleneksel API'lerin ve sözlüklerin yetersiz kaldığı durumlarda (örneğin özel kategoriler veya yerel popüler kelimeler), Host tarayıcısı /api/ai/generate uç noktasını kullanarak gemini-1.5-flash modeline bir batch istek gönderir ve kelimenin kategoriye ve harfe uygunluğunu yapay zeka hakemliğiyle değerlendirir.

Puanlama Matrisi ve Canlı İtiraz Sistemi

Doğrulama motorundan geçen kelimeler için ilk etapta şu puanlar önerilir:

10 Puan: Benzersiz kelimeler (Diğer hiçbir oyuncu tarafından yazılmamış ve geçerli kelimeler).
5 Puan: Aynı kelimeler (Birden fazla oyuncu tarafından yazılmış geçerli kelimeler).
0 Puan: Geçersiz, boş bırakılan veya yanlış harfle başlayan kelimeler.

Sistem öneriyi sunduktan sonra Canlı İtiraz ve Oylama (Interactive Voting) süreci başlar. Tüm oyuncular, diğerlerinin yazdığı kelimelerin yanındaki 10, 5, 0 butonlarına basarak oylarını gerçek zamanlı olarak değiştirebilirler. Bu oylar SINGLE_VOTE paketiyle Host'a iletilir ve Host tarafından anlık olarak tüm ekranlara SYNC_LIVE_VOTES ile yansıtılır. Oylama bittiğinde Host, çoğunluk oyunu ve eşitlik durumunda adil ara puanı (5) baz alarak nihai puanları hesaplar.

Oda Mantığı ve Güvenlik

Her oyun odası, 6 karakterli benzersiz bir Oda Kodu üzerinden tanımlanır. Host, isimsehir-host-${roomCode} adresiyle sinyalleşme ağında beklerken; katılımcılar ise isimsehir-client-${randomId} biçiminde kimlik edinerek doğrudan Host'a bağlanır.

WebRTC mimarisi gereği oyun sırasında paylaşılan tüm veri paketleri DTLS/SRTP şifreleme katmanı ile korunmaktadır. Oyun verileri hiçbir uzak sunucuda tutulmadığı için yüksek güvenlik, veri gizliliği ve sıfır gecikmeli oyun deneyimi bir arada sunulmaktadır.

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 kaleme alınmıştır.