Geliştirici Notları: Gizli Kelimeler

Giriş ve Mimari Yaklaşım

Gizli Kelimeler (Ajan Kelimeler), popüler casusluk ve kelime tahmin oyunu Codenames konseptine dayalı, tamamen tarayıcı tabanlı çalışan ve herhangi bir sunucu veritabanına ihtiyaç duymayan çok oyunculu (multiplayer) bir kelime oyunudur. Oyun, Paira Games platformunun genel vizyonuna uygun şekilde, WebRTC teknolojisiyle Peer-to-Peer (P2P) olarak tasarlanmıştır. Bu sayede tüm veriler doğrudan oyuncuların tarayıcıları arasında aktarılır, gecikme süresi en aza indirgenir ve tam veri gizliliği sağlanır.

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

Gizli Kelimeler, P2P mimarisinde Host-Client modelini benimser:

Host (Kurucu Düğüm): Oyunu başlatan kullanıcı yerel tarayıcısında sunucu görevi görür. Kelime havuzunu karıştırır, rollerin atanmasını doğrular, oyun tahtasını (kart matrisini) oluşturur ve tur geçişleri ile zamanlayıcıyı (timer) kontrol eder.
Clients (İstemci Peer'lar): 6 karakterli oda kodu aracılığıyla doğrudan Host ile WebRTC RTCDataChannel bağlantısı kurarlar. İstemciler oyun durumunu Host'tan alır ve yaptıkları eylemleri (kart işaretleme, tahmin vb.) Host'a iletirler.
Sinyalleşme (Signaling): Oyuncuların birbirlerini internet üzerinde bulabilmesi için ICE Adayları ve SDP tekliflerini ileten hafif bir PeerJS sinyalleşme sunucusu kullanılır. Bağlantı kurulduktan sonra veri alışverişi doğrudan peer'lar arasında gerçekleşir.

Kart Matrisi ve Rol Dağılımı Kuralları

Oyun başladığında Host, oyuncu listesini analiz ederek her iki takımda da (Takım A ve Takım B) en az bir Ajan (Spymaster) ve en az bir Tahminci (Guesser) bulunup bulunmadığını kontrol eder. Bu koşul sağlanmadığı sürece oyun başlatılamaz. Oyun başlatıldığında şu adımlar izlenir:

Kelime Yükleme: Kelime veritabanı ../Tabu/tr.json dosyasından dinamik olarak çekilir. Eğer bu dosya yüklenemezse yerel bir yedek dizi (fallbackWords) devreye girer.
Dinamik Grid Yapısı: Lobi ayarlarındaki seçime göre 16'lık (4x4), 25'lik (5x5) veya 36'lık (6x6) gridler oluşturulur. Başlayan takıma 1 kart avantajı verilir. Örneğin, 25'lik standart gridde; başlayan takımın 9 kartı, rakip takımın 8 kartı, 7 tarafsız (neutral) kart ve 1 suikastçı (assassin) kartı bulunur.

Rol Tabanlı Güvenli Bilgi Maskeleme (Security & Anti-Cheat)

Codenames tarzı oyunların doğası gereği, Tahminci (Guesser) rolündeki oyuncuların hangi kartın hangi renkte (takımda) olduğunu veya suikastçının konumunu görmemesi gerekir. Gizli Kelimeler, istemci taraflı hileleri (Inspect Element ile HTML/JS durumunu okuma vb.) tamamen önlemek için benzersiz bir **rol tabanlı veri maskeleme** mekanizması kullanır:

Host, oyun durumunu (state) istemcilere gönderen broadcastState fonksiyonunda, her bir peer'ın rolünü tek tek kontrol eder. Eğer hedef oyuncunun rolü GUESSER ise, oyun durumunun kopyasını oluşturarak henüz açılmamış (revealed: false) tüm kartların takım bilgisini HIDDEN olarak değiştirir. Bu sayede tahmincilerin tarayıcı belleğine rakip veya suikastçı kartlarının gerçek renk bilgisi asla ulaşmaz.

Gerçek Zamanlı Veri Senkronizasyonu (Data Sync)

Oyun döngüsü boyunca aşağıdaki aksiyon paketleri RTCDataChannel üzerinden anlık olarak aktarılır:

SYNC: Host'un güncel tahta durumunu, puanları, süreleri ve aktif fazı istemcilere dağıtmasını sağlar.
SWITCH_TEAM / SWITCH_ROLE: Lobi aşamasında oyuncuların kırmızı/mavi takımlar ve Ajan/Tahminci rolleri arasında geçiş yapmasını sağlar.
SUBMIT_CLUE: Ajanın verdiği tek kelimelik ipucunu ve bu ipucuyla ilişkili kart sayısını (count) sisteme kaydeder, oyunu tahmin fazına (GUESS) geçirir.
MARK_WORD: Tahmincilerin üzerinde tartıştıkları kartları geçici olarak işaretlemesini sağlar. Bu işaretler neon mavi çerçeve olarak aynı takımdaki diğer tahmincilere anlık gösterilir.
GUESS_WORD: Bir tahmincinin işarete tıklayarak kelimeyi açma hamlesidir. Kart rengine göre puan düşer, tur sonlanır ya da suikastçı açıldıysa oyun anında kaybedilir.
END_TURN: Tahmincilerin hakları kalmadığında veya riske girmek istemediklerinde turu manuel olarak rakibe devretmelerini sağlar.
PLAY_SOUND: Doğru tahmin, yanlış tahmin, suikastçı veya süre dolumu seslerinin tüm istemcilerde eş zamanlı çalınmasını sağlar.

Oturum Yönetimi ve Süre Takibi

Süre senkronizasyonunda istemciler ile Host arasındaki gecikmeleri tolere etmek için window.PairaTime.now() zaman damgaları kullanılır. Host'un gönderdiği durationLeft verisi yerel zaman farkına eklenerek requestAnimationFrame/setTimeout yardımıyla her tarayıcıda pürüzsüz akan bir geri sayım gösterilir.

Bir oyuncunun ağ bağlantısı kesildiğinde (handlePlayerLeave), kopan oyuncu aktif turdaki Ajan veya Tahminci ise oyunun kilitlenmesini önlemek adına Host turu otomatik olarak sonlandırır (switchTurn) ve sırayı diğer takıma geçirir.

Bu teknik dokümantasyon, P2P tabanlı web oyunları mimarisini açıklamak amacıyla Ahmet Efe Yaşar tarafından Paira Games projesi kapsamında hazırlanmıştır.