Geliştirici Notları: Katiplik Düellosu

Giriş ve Mimari Yaklaşım

Paira Katiplik Düellosu, kullanıcıların klavye yazma hızlarını, doğruluk oranlarını ve on parmak yeteneklerini gerçek zamanlı olarak test edebilmeleri veya arkadaşlarıyla düello yapabilmeleri için tasarlanmış tamamen tarayıcı tabanlı bir web oyunudur. Uygulama, merkezi bir oyun sunucusu veya veritabanı (Database) barındırmaz. Bunun yerine, oyun verilerini ve oyuncuların durumlarını eş zamanlı tutmak amacıyla tamamen istemci tarafında (Client-Side) çalışan WebRTC (Peer-to-Peer) ağ altyapısını kullanır.

Oyunun temel amacı, belirlenen Türkçe metni en yüksek kelime/dakika (WPM) hızında ve minimum hata ile tamamlamaktır. Farklı klavye düzenleri (F klavye, Türkçe Q klavye, İngilizce klavye) ve imlalı/imlasız mod seçenekleri sunan oyun, yerel tarayıcı düzeyinde gelişmiş girdi doğrulama algoritmaları barındırır.

P2P Ağ Topolojisi (Host-Client Mimarisi)

Katiplik Düellosu, multiplayer oyun deneyimini gecikmesiz ve sıfır sunucu maliyetiyle sunabilmek için bir Host-Client (Kurucu-Katılımcı) ağ modeli kullanır:

Host (Kurucu Node): Oyunu başlatan ve odayı kuran oyuncudur. Host, tr.json dosyasından metin kategorilerini yükler, arama/filtreleme işlemlerini gerçekleştirir, düelloda yazılacak metni, klavye düzenini ve imla modunu belirler. Belirlenen metin parametrelerini katılımcıya aktararak oyun döngüsünün başlatılmasını koordine eder.
Client (Katılımcı Peer): Oda koduyla bağlanan oyuncudur. Bağlantı kurulduğunda, Host'tan gelen oyun ayarları ve hedef metin verisi doğrultusunda oyuna başlar. Girdileri yerel olarak analiz edip ilerlemesini Host'a iletir.
Sinyalleşme Altyapısı (Signaling): Oyuncuların ağ adreslerini (ICE Candidates) ve oturum detaylarını değiş tokuş edebilmesi için başlangıçta PeerJS tabanlı bir sinyal sunucusu kullanılır. Doğrudan veri kanalı (Data Channel) kurulduktan sonra bu sinyal sunucusu aradan çekilir.

Gerçek Zamanlı Veri Senkronizasyonu (Data Synchronization)

Düello esnasında, rakiplerin birbirlerinin durumunu canlı olarak izleyebilmesi ve aralarındaki rekabet hissinin güçlendirilmesi için RTCDataChannel üzerinden yüksek sıklıkta veri paketleri gönderilir. Aşağıdaki değişkenler ve aksiyonlar gerçek zamanlı olarak eş zamanlanır:

Yazma Hızı (WPM): Oyuncunun dakikada yazdığı kelime sayısı dinamik olarak hesaplanır. Formül, ((Doğru Karakter Sayısı / 5) / Geçen Süre (dakika)) biçimindedir. Karakterlerin kelime başına düşen ortalama uzunluğu 5 kabul edilmektedir. Bu veri her kelime tamamlandığında veya metin girdisi değiştikçe hesaplanarak karşı tarafa gönderilir.
Doğruluk Oranı (Accuracy): Oyuncunun bastığı toplam tuş vuruşları (Keystrokes) ile doğru bastığı tuşlar arasındaki yüzde oranıdır. (Doğru Tuş Vuruşları / Toplam Tuş Vuruşları) * 100 şeklinde hesaplanır ve oyun sonu durum paketinde gönderilir.
Metin İlerleme Yüzdesi (Progress): Oyuncunun metindeki hangi kelimede olduğu, (Mevcut Kelime İndeksi / Toplam Kelime Sayısı) * 100 oranıyla hesaplanır ve progress_update veri paketi aracılığıyla karşı tarafa aktarılır. Bu oran, arayüzdeki ilerleme çubukları (p1-progress ve p2-progress) aracılığıyla canlı grafiklerle eşlenerek görselleştirilir.
Anlık Rakip İmleç Pozisyonu: Yazı alanında rakibin hangi kelime üzerinde odaklandığı, ilerleme yüzdesi ve kelime işaretlemeleriyle anlık olarak takip edilir.

Metin İşleme ve Doğrulama Algoritması

Oyunun yazma doğrulama motoru, Türkçe karakterlerin ve klavye düzenlerinin yarattığı farklılıkları en aza indirmek için özelleştirilmiş bir normalizasyon fonksiyonu (normalizeWord) barındırır:

İmlasız Mod: Etkinleştirildiğinde, metindeki tüm noktalama işaretleri ve özel karakterler Regex (/[^\p{L}\p{N}]/gu) kullanılarak temizlenir ve metin tamamen küçük harfe dönüştürülür.
İngilizce Klavye Modu: Türkçe karakterleri barındırmayan fiziksel klavyelere sahip oyuncular için ı, ş, ğ, ç, ö, ü gibi harfler otomatik olarak i, s, g, c, o, u harflerine map edilerek eşleştirilir.
Mobil Duyarlılık: Masaüstü bilgisayarlarda kelime tamamlamaları Space tuşuyla tetiklenirken, mobil cihazlardaki sanal klavyelerin boşluk karakteri davranışları input olayları ve kelime sonu boşluk kontrolleri ile asenkron biçimde koordine edilir.

Oda Mantığı ve Oturum Yönetimi

Her oyun oturumu 6 karakterden oluşan benzersiz bir oda koduyla yönetilir. Oturum akışı ve olası senaryolar aşağıdaki kurallara göre işler:

Oda Keşfi ve Eşleşme: Host'un Peer ID'si oda kodu olarak kullanılır. İstemci bu kodu yazıp katıldığında, el sıkışma işlemi tamamlanır ve ekranlar otomatik olarak lobiye ve oyun alanına geçiş yapar.
Bağlantı Kesintileri (Disconnection): Düello sırasında oyunculardan biri sayfayı kapattığında veya bağlantısı koptuğunda onPlayerLeave olayı tetiklenir. `KatiplikNetwork` bunu yakalayarak oyuncuya "Rakip ayrıldı" uyarısı verir ve 3 saniye sonra otomatik olarak ana lobiye yönlendirir.
Tekrar Oyna (Rematch) Döngüsü: Oyun bittiğinde, Host yeni bir metin seçerek play_again paketi gönderir. Bu paket istemcideki oyun durumunu sıfırlar, böylece sayfayı yenilemeden yeni bir düello başlatılabilir.

E-E-A-T & Güvenlik

Katiplik Düellosu, gizlilik odaklı (privacy-first) bir mimariye sahiptir. Oyuncuların bastığı tuş vuruşları, yazdığı kelimeler veya tarayıcı detayları hiçbir sunucuya kaydedilmez. WebRTC veri kanalları, protokol standartları gereğince DTLS ve SRTP ile uçtan uca şifreli (End-to-End Encrypted) olarak çalışır. Oyun içi performans analizleri yalnızca tarayıcı belleğinde tutulur ve oturum kapatıldığında tamamen imha edilir.

Bu teknik dokümantasyon, tarayıcı tabanlı eş zamanlı oyun geliştirme mimarilerini inceleyen geliştiriciler için Ahmet Efe Yaşar tarafından hazırlanmıştır.