Geliştirici Notları: Kelime Avı

Giriş ve Mimari Yaklaşım

Paira Kelime Avı (Kelime Kapanı), harf eşleştirme ve gizli ebeyi bulma mekaniklerine dayalı, tamamen tarayıcı tabanlı bir sosyal çıkarım ve kelime oyunudur. Oyun; merkezi bir veritabanı (Database) veya oyun sunucusu barındırmadan, doğrudan P2P (Peer-to-Peer) bağlantı mimarisi kullanılarak istemciler arasında koordine edilir. Paira Games platformunun diğer yapımlarında olduğu gibi, bu oyun da arkadaş gruplarının hiçbir kurulum veya üyelik gereksinimi duymadan anında oynayabilmesi için tasarlanmıştır.

Tüm oyun akışı, oda kurucusunun (Host) yerel tarayıcısındaki durum makinesi (state machine) ve WebRTC bağlantıları üzerinden gerçek zamanlı yönetilmektedir.

P2P Ağ Topolojisi ve Rol Dağılımı

Kelime Avı'nda oyuncular arasındaki iletişim, WebRTC veri kanalları (RTCDataChannel) kullanılarak Host-Client (Yönetici-Katılımcı) topolojisiyle sağlanır:

Host (Kurucu Düğüm): Oyunu başlatan tarayıcı, sunucu yetkilerini devralır. Başlangıçta rollerin (Ebe ve Masumlar) atanması, gizli kelimenin (targetWord) belirlenmesi, tur süreleri ve puanlama kuralları Host tarafından yönetilir.
Clients (Katılımcı Peer'lar): Oda koduyla bağlanan istemciler, doğrudan Host'a veri kanalları ile bağlanır. Oyuncular kelime tahminlerini ve ebe rollerindeki tahminleri Host'a gönderir; Host ise tüm bu verileri doğrulayarak senkronize durum paketi olarak tüm odaya geri yayınlar.
Signaling (Sinyalleşme): Peer'ların birbirlerinin IP adreslerini ve portlarını keşfedebilmeleri (ICE Candidate ve SDP teklif/yanıt süreçleri) için PeerJS aracı sinyalleşme sunucusu kullanılır. Bağlantılar sağlandıktan sonra bu sunucu ile iletişim kesilir ve oyun tamamen P2P olarak devam eder.

Gerçek Zamanlı Veri Senkronizasyonu ve Anti-Cheat Altyapısı

Kelime Avı'nda oyun içi senkronizasyon ve veri paketleri aşağıdaki gibi yapılandırılmıştır:

SYNC: Host, oyun durumunu (oyuncu puanları, aktif tur, girilen kelimeler) istemcilere güncel olarak aktarır. Güvenlik ve hile engelleme (Anti-Cheat) amacıyla, Host bu paketi gönderirken alıcı istemcinin rolünü kontrol eder. Eğer alıcı oyuncu "Ebe" değilse, gizli kelimenin (targetWord) yalnızca o ana kadar açılmış harflerini (targetWord.substring(0, revealedLetters)) görebilir. Bu sayede masum oyuncuların tarayıcı kodunu manipüle ederek kelimeyi erkenden öğrenmesi engellenir.
SUBMIT_MASUM: Masum oyuncuların girdikleri kelime ipuçları doğrudan Host'a iletilir. Host, girilen kelimelerin o ana kadar açılmış harf(ler) ile başlayıp başlamadığını doğrular.
SUBMIT_EBE: Ebe rolündeki oyuncunun masumların eşleşmeye çalıştığı kelimeyi tahmin etmek için yaptığı en fazla 5 kelimelik tahmin listesini Host'a gönderir.
SYNC_TIME: Host ve istemciler arasındaki süreyi milisaniye düzeyinde senkronize eder.
PLAY_SOUND: Eş zamanlı olarak oyun içi bildirim ve uyarı seslerini (correct, taboo, pass, tick) tüm oyuncuların tarayıcılarında tetikler.

Puanlama ve Doğrulama Protokolü

Kelime Avı'nda tahmin çiftlerinin ve eşleşmelerin doğrulanması tamamen Host tarafındaki KelimeAviGameEngine üzerinde koordine edilir:

Kelime Eşleşmesi (Fuzzy Match): Masum oyuncular birbirleriyle aynı kelimede buluşmak için kelime girdiklerinde, Host bir FuzzyMatcher sınıfı kullanarak kelimelerin fonetik/karakter benzerliğini (0.5 eşik değeri) değerlendirir. En az 2 masum oyuncunun benzer bir kelimede eşleşip eşleşmediği doğrulanır.
Jackpot Durumu: Masum oyuncular, ebe tarafından belirlenen ana hedef kelimeyi (targetWord) doğrudan tahmin edip girerlerse "Jackpot" tetiklenir. Bu durumda masumlar ekstra yüksek puan kazanarak turu anında bitirir.
Ebe Kazancı: Eğer masumlar kendi aralarında eşleşirse fakat Ebe bu eşleşen kelimeyi tahmin ettiği 5 seçenekten biriyle bulursa, Ebe turu kazanır ve ebeWinPts puanı alır.
Masum Kazancı: Masumlar kendi aralarında eşleşir ve Ebe bu kelimeyi bulamazsa, masumlar masumWinPts puanı alır ve bir sonraki harf açılır (revealedLetters++).

Oda Mantığı ve Oturum Kesintileri

Oyun, tarayıcının WebRTC soket adresi üzerinden ürettiği 6 karakterli benzersiz bir Peer ID oda koduna dayanır. Oyuncu katılımları ve olası kopmalar şu şekilde yönetilir:

Oyuncu Bağlantı Kopması: Oyun sırasında bir oyuncunun bağlantısı koptuğunda, Host removePlayer metoduyla bu oyuncuyu disconnected = true olarak işaretler.
Oyun Güvenliği: Aktif oyuncu sayısı 3'ün altına düşerse, oyun otomatik olarak 5 saniye içinde lobiye geri döndürülür. Eğer kopan oyuncu aktif turdaki "Ebe" ise, tur iptal edilir ve yeni bir tur başlatılır.

E-E-A-T & Güvenlik

Paira Kelime Avı, veri gizliliğine maksimum önem verecek şekilde tasarlanmıştır. Kullanıcıların isimleri, oyun içi sohbet içerikleri veya girilen kelimeler hiçbir merkezi sunucuya veya log sistemine gönderilmez. Tüm iletişim kanalları WebRTC'nin doğası gereği uçtan uca şifrelenmiştir (DTLS/SRTP). Sunucusuz altyapı sayesinde kullanıcıların verileri yalnızca kendi tarayıcılarında geçici olarak barındırılır.

Bu teknik dokümantasyon, P2P tabanlı web oyunu mimarisini incelemek isteyen geliştiriciler ve Paira Games altyapısına ilgi duyanlar için Ahmet Efe Yaşar tarafından hazırlanmıştır.