Gerçek zamanlı masa oyunu sistemi: oyun kuralları, para hareketleri ve canlı arayüzün aynı durum etrafında birleşmesi
Rocks Game Hub, çok oyunculu Blackjack etrafında tasarlanmış bir oyun platformu çalışmasıdır. Sistemin zor kısmı kartları ekranda göstermek değil; aynı turda bulunan oyuncuların kart, sıra, bahis, süre ve bakiye bilgisini tek bir doğru kaynaktan yönetmektir. Bu projede React tabanlı istemci ile Laravel tabanlı API, bu nedenle ayrı iki uygulama olarak çalışır: istemci deneyimi üretir; API ise oyunun kurallarını ve kalıcı sonucunu belirler.
Platform; Blackjack için canlı masa, lobi, koltuk seçimi, ana bahis/yan bahisler, dealer mantığı, tur zamanlayıcısı, sonuç/payout, sohbet, izleyici modu, profil ve sosyal alanlar içerir. Poker, rulet ve Okey 101 için de genişlemeye açık lobi ve ürün yüzeyi bulunur.
1. Sistem neyi çözüyor?
Bir masa oyununda tek bir kullanıcı yoktur; aynı anda birden çok oyuncu, dealer ve izleyici aynı tabloyu görür. Bu tablo her aksiyonda değişir:
- Bir oyuncunun hit yapması, yalnızca onun elini değil sıradaki oyuncuyu da etkiler.
- Dealer’ın kapalı kartı herkese aynı anda açık edilmemelidir.
- Bahis, yalnızca doğru fazda kabul edilmelidir.
- Bakiye güncellemesi ile oyun sonucu birbirinden kopmamalıdır.
- Bağlantısı kısa süre kesilen oyuncu, yeniden bağlandığında güncel tabloyu alabilmelidir.
Bu nedenle projedeki ana ilke şudur:
İstemci oyunu çiziyor; sunucu oyunu kararlaştırıyor.
İstemci hiçbir zaman kart çekme, hand değeri, aksiyon uygunluğu veya payout sonucunda otorite değildir. API her isteği; oyuncunun masadaki yeri, mevcut oyun fazı, aktif eli, bahis durumu ve sıra bilgisiyle birlikte değerlendirir.
2. Oyun modeli ve durum makinesi
Blackjack masasını sürekli açık duran bir ekran değil, kurallı bir durum makinesi olarak ele aldım. Her durum, hangi işlemlerin mümkün olduğunu belirler.
Fazların arayüze etkisi
| Faz | API’nin sorumluluğu | Oyuncunun gördüğü |
|---|---|---|
| Bekleme / bahis | Limitleri ve uygun katılımcıları doğrular | Koltuk, chip dock ve bahis alanları görünür |
| Dağıtım | Kartları çeker, kapalı dealer kartını işaretler | Kartlar desteden hedef ele gider |
| Oyuncu aksiyonları | Sıradaki eli, timeout’u ve izinli aksiyonları tutar | Hit, Stand, Double, Split kontrolleri |
| Dealer turu | Dealer’ın hit/stand kuralını otomatik uygular | Dealer kartları açılır ve tamamlanır |
| Bitiş | Sonucu hesaplar, payout hareketini kaydeder | Sonuç, konfeti ve yeni oyun sayacı |
Bu ayrım, önemli bir arayüz hatasını da engeller: bitmiş turun countdown süresinde bahis alanı görünmez. Böylece oyuncu eski tur için bahis yerleştiremez; yeni masa hazır olduğunda temiz bir bahis durumu açılır.
3. Bir turun ayrıntılı akışı
3.1 Bahis ve masa katılımı
Oyuncu lobi üzerinden masayı seçer, uygun bir koltuğa katılır ve ana bahis ile seçili yan bahisleri girer. API bu noktada aşağıdaki kontrolleri yapar:
- Kullanıcı oturumunun ve masa erişiminin geçerliliği
- Masanın bahis fazında olup olmadığı
- Oyuncunun aktif mi, sırada mı, izleyici mi olduğu
- Koltuğun geçerliliği ve doluluk durumu
- Minimum/maksimum bahis limitleri
- Kullanılabilir bakiye
- Aynı tur için çifte ana bahis girişinin engellenmesi
Bahis onaylandıktan sonra, oyun turu ile ilişkili kayıt ve bakiye hareketi oluşturulur. Bu sayede “ekranda chip göründü” ile “bahis kalıcı olarak kabul edildi” farklı şeyler değildir.
3.2 Kart dağıtımı ve gizli dealer kartı
Kartlar API tarafında çekilir. Dealer’ın ikinci kartı, tur bitene kadar gizli işaretlenir. İstemci bu işareti herhangi bir kart değeri gibi yazmaz; kartın arka yüzünü render eder. Dealer turu başladığında aynı kart, artık açık veri olarak döner.
Bu iki temsil önemlidir: oyuncunun henüz bilmemesi gereken değer istemciye gönderilmemelidir. Gizleme yalnızca CSS ile yapılmış bir görünürlük tercihi değildir; durum verisinin parçasıdır.
3.3 Oyuncu eli ve sıra yönetimi
Her oyuncunun bir veya daha fazla eli olabilir. Split sonrası eller ayrı takip edilir; aktif el ayrıca işaretlenir. API, bu bilgiye göre izinli aksiyon listesini üretir.
| Aksiyon | Tipik koşul |
|---|---|
| Hit | Aktif el oynanabilir durumda |
| Stand | Aktif el oynanabilir durumda |
| Double | İlk iki kart, bakiye ve masa kuralı uygunsa |
| Split | İlk iki kart bölünebilir bir çiftse |
| Insurance | Dealer up-card senaryosu ve ilgili oyun fazı uygunsa |
Oyuncunun aksi yöndeki isteği arayüzden gelebilir; ancak geçerlilik sunucu tarafında yeniden kontrol edilir. Bu, arayüz gecikmesi veya kötü niyetli istekler nedeniyle oyun akışının bozulmasını önler.
3.4 Dealer, sonuç ve payout
Oyuncu elleri tamamlandığında API dealer turunu başlatır. Dealer’ın kart çekme kuralı, hand value ve soft hand değerlendirmesi backend’de uygulanır. Ardından her oyuncu eli için kazanç/kayıp/push sonucu hesaplanır ve ilgili payout işlemi kaydedilir.
4. Gerçek zamanlı senkronizasyon
Canlı masa iki kanaldan beslenir:
- REST durum sorgusu, masa açılışında ve bağlantı toparlanmasında güvenilir tam fotoğrafı verir.
- WebSocket olayları, kart dağıtımı, aksiyon, oyuncu katılımı, sohbet, payout ve durum değişimlerini gecikmeden iletir.
Bu hibrit yaklaşımın amacı, WebSocket bağlantısının geçici olarak kopmasını oyun deneyiminin sonu haline getirmemektir. İstemci yeniden bağlandığında veya periyodik kontrol yaptığında API’den yetkili güncel durumu tekrar alır.
Yayınlanan olay türleri
- Oyun oluşturuldu / oyun durumu güncellendi
- Oyuncu katıldı, ayrıldı veya sıraya alındı
- Bahis ve yan bahis yerleştirildi
- Kart dağıtıldı, dealer turu başladı/bitti
- Oyuncu sırası başladı/bitti veya timeout oldu
- Payout işlendi, bakiye değişti
- Sohbet mesajı gönderildi
Olay payload’ları küçük tutulur. Örneğin yeni oyun bildirimi, tüm ilişkileri ve büyük ayar verilerini taşımak yerine oyun kimliği, faz, limit ve countdown gibi gerekli özeti taşır. Bu karar, yayın sağlayıcısının payload sınırına takılmayı önler ve istemcinin ayrıntı gerektiğinde durum uç noktasına dönmesini sağlar.
5. API yüzeyi
API, kullanıcı, lobi, masa, oyun aksiyonu, bahis, sohbet ve yönetim ihtiyaçlarını ayrı uç noktalarla sunar. Örnek temel akış:
TXT
POST /api/register Hesap oluşturma
POST /api/login Oturum açma
GET /api/lobbies Aktif lobiler
POST /api/lobbies/find-or-create Uygun masa bulma/oluşturma
GET /api/games/{id}/state Yetkili güncel masa durumu
POST /api/games/{id}/join Koltukla masaya katılma
POST /api/games/{id}/bet Ana bahis
POST /api/betting/side-bet Yan bahis
POST /api/games/{id}/action Hit / Stand / Double / Split / Insurance
POST /api/lobbies/{id}/next-game Sonraki oyuna geçişAPI’nin döndürdüğü oyun durumu; oyun fazı, oyuncular, eller, kartlar, dealer verisi, aktif oyuncu, bahisler, masa sayımları, izinli aksiyonlar, countdown ve kullanıcıya özel yetkileri aynı bağlamda sunar. Böylece istemci ayrı ayrı tahminler yapmak yerine tek bir durum sözleşmesini render eder.
6. Veri modeli ve tutarlılık sınırları
Sistem mantıksal olarak şu ilişkiler etrafında şekillenir:
Bu modelde oyun, tur ve el seviyeleri bilinçli olarak ayrıdır:
- Oyun/Masa: lobi, limit, dealer ve katılımcı bağlamı.
- Tur: belirli bir dağıtım ve sonuç döngüsü.
- El: oyuncunun ana veya split eli.
- Kart: dealer veya oyuncu eline bağlı, sıra ve gizlilik bilgisi taşıyan kayıt.
- İşlem: bahis, payout veya ilişkili bakiye hareketi.
Bu ayrım, split gibi tek turda birden fazla el oluşan senaryolarda veya sonraki oyuna geçişte veri belirsizliğini azaltır.
7. Güvenlik ve operasyonel kararlar
Yetkilendirme ve istek sınırları
Kimlik doğrulama ve yetkilendirme, API ve canlı kanal katmanlarında uygulanır. API middleware zinciri; doğrulama, rate limit, hata yönetimi ve güvenlik kontrollerini içerir. İstemci tarafındaki butonun kapalı olması güvenlik kuralı değildir; oyun aksiyonu API’de bağlamıyla doğrulanır.
RNG ve denetlenebilirlik
Kart çekme için güvenli rastgelelik servisinden yararlanılır; RNG çağrıları denetlenebilir log akışı ile kayda alınır. Oyun işlemleri, payout ve kritik aksiyonlar için audit mantığı bulunur.
Hareketsiz masalar
Bekleme durumunda uzun süre işlem görmeyen Blackjack masaları zamanlanmış bir bakım komutuyla kapatılır. Amaç, lobiye artık geçerli olmayan bekleyen masa kartlarının birikmemesidir. Aktif turdaki para/kural durumuna müdahale edilmez; bu temizlik yalnızca bekleyen ve süre aşmış masalar için uygulanır.
8. Arayüz kararları
Arayüz, casino estetiğini durum okunabilirliğinin önüne koymamaya çalışır.
- Giriş ekranı, haber panosu görünümü yerine oyun salonuna giriş hissi ve doğrudan oturum açma akışı verir.
- Bahis arayüzü yalnızca bahis fazında görünür; oyuncu aksiyonları sırasında hit/stand alanını kaplamaz.
- Dealer’ın kapalı kartı kart arkası olarak temsil edilir;
hiddengibi ham veri kullanıcıya gösterilmez. - Kart dağıtımı, kart sayısı değiştiğinde desteden hedef ele yapılan kısa animasyonla açıklanır.
- Oyun bitişi sonrası yeni oyun countdown’u görünürken eski tura bahis girişi engellenir.
- Bildirimler işlem başarısını tekrar eden toast’larla doldurmak yerine hata durumlarına odaklanır.
- Sohbet alanı dar ekranlarda input ve gönderme düğmesini taşırmadan korur.
Bu kararların ortak noktası: kullanıcıya “şu an ne yapabilirim?” sorusunun cevabını vermek.
9. Kullandığım teknoloji seti
| Alan | Teknoloji | Rol |
|---|---|---|
| İstemci | React 18 + TypeScript | Oyun ekranı, lobi, hesap ve responsive UI |
| İstemci altyapısı | Vite, React Router, Axios, Zustand | Build, yönlendirme, API erişimi ve oturum durumu |
| Arayüz kalitesi | Özel CSS, Lucide React, Vitest, Testing Library, Oxlint | Tasarım, ikonlar, bileşen testi ve lint |
| API | PHP 8.2+ + Laravel 11 | REST API, middleware, veri erişimi ve domain akışı |
| Kimlik | Laravel Passport ve JWT tabanlı oturum akışı | Yetkili istekler ve oturum yenileme |
| Canlı iletişim | Laravel Broadcasting ve Reverb uyumlu WebSocket yapılandırması | Masa/sunum olayları |
| Çalışma zamanı | Laravel Octane + FrankenPHP | Uzun ömürlü HTTP worker modeli |
| Kalite | Pest, factories, migrations, Laravel Pint | Kural regresyonu, test verisi ve kod standardı |
10. Test yaklaşımı
Frontend tarafında bileşen davranışları Vitest ve Testing Library ile; backend tarafında domain/API davranışları Pest ile kontrol edilir. Özellikle oyun fazı, hidden dealer card, bahis kontrolleri, olay payload’ı ve hareketsiz masa temizliği için regresyon testleri eklenmiştir.
Testin rolü yalnızca “kod çalışıyor mu?” sorusu değildir. Oyun gibi durum geçişi yoğun bir üründe test, daha önce çözülen davranışların sonraki tasarım veya refactor çalışmalarında geri dönmesini engeller.
Sonuç
Rocks Game Hub, bir oyun ekranından çok; kurallı bir gerçek zamanlı sistem tasarlama çalışmasıdır. Proje boyunca frontend deneyimi, oyun kuralları, gerçek zamanlı olaylar, bakiye hareketleri ve bağlantı toparlama akışı aynı durum sözleşmesi etrafında tutuldu. Portföy açısından proje; full-stack geliştirme, domain modelleme, API tasarımı, canlı iletişim ve hata ayıklama yaklaşımını birlikte gösterir.
