Project · Case

Kart Oyunları API / Game Hub

1 Şubat 2026

Proje Client ve Server olarak ayrı projeleridir. Client'ta laravel ve html-css seçimi sebebi hızlı çıktı alınmasını amaçlamaktır. Server projesi üzerinde pratikte DDD, Repositories, DTO ve OOP prensipleri kullanılmıştır.

Kart Oyunları API / Game Hub

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.

flowchart LR P[Oyuncu] --> UI[React arayüzü] UI -->|REST aksiyonu| API[Laravel API] API --> RULES[Blackjack kural motoru] RULES --> DB[(Oyun, el, kart, işlem kayıtları)] RULES --> WS[Canlı olay yayını] WS --> UI API -->|Güncel durum / bağlantı sonrası toparlama| UI

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.

stateDiagram-v2 [*] --> Waiting: Masa oluşturulur / yeni tur açılır Waiting --> Dealing: Geçerli bahisler tamamlanır Dealing --> PlayerActions: Başlangıç kartları dağıtılır PlayerActions --> PlayerActions: Hit / Double / Split PlayerActions --> DealerTurn: Tüm eller tamamlanır DealerTurn --> Finished: Dealer değerlendirmesi ve payout Finished --> Waiting: Sonraki oyun oluşturulur Waiting --> Finished: Uzun süre hareketsiz masa kapatılır

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.

sequenceDiagram actor Player as Oyuncu participant UI as Masa arayüzü participant API as Oyun API'si participant Rules as Kural motoru participant Ledger as İşlem kayıtları participant Live as Canlı yayın Player->>UI: Chip seçer ve Bahis Yap'a basar UI->>API: Bahis isteği API->>Rules: Faz, limit, koltuk ve bakiye doğrulama Rules->>Ledger: Bahsi / bakiye hareketini kaydet Rules->>Live: Bahis ve güncel durum olayını yayınla API-->>UI: Güncel oyun durumu Live-->>UI: Diğer katılımcılar için canlı güncelleme

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.

flowchart TD A[Tüm oyuncu elleri tamamlandı] --> B[Dealer kapalı kartını aç] B --> C{Dealer hit çekmeli mi?} C -->|Evet| D[Kart çek ve eli güncelle] D --> C C -->|Hayır| E[Her oyuncu eli ile karşılaştır] E --> F[Win / Lose / Push / Blackjack sonucu] F --> G[Payout ve bakiye hareketi] G --> H[Sonuç ve güncel durum yayını]

4. Gerçek zamanlı senkronizasyon

Canlı masa iki kanaldan beslenir:

  1. REST durum sorgusu, masa açılışında ve bağlantı toparlanmasında güvenilir tam fotoğrafı verir.
  2. 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:

erDiagram USER ||--o{ GAME_PARTICIPANT : joins LOBBY ||--o{ GAME : hosts GAME ||--o{ GAME_ROUND : contains GAME_ROUND ||--o{ PLAYER_HAND : has PLAYER_HAND ||--o{ DEALT_CARD : contains GAME_ROUND ||--o{ DEALT_CARD : dealer_cards USER ||--o{ BET : places GAME_ROUND ||--o{ BET : records USER ||--o{ TRANSACTION : owns GAME_ROUND ||--o{ TRANSACTION : settles

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; hidden gibi 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.

Proje Özeti

Tamamlanma

1 Şubat 2026

Etiketler

PhpLaravelPipelineCasino Standards RNGWebsocketJavascriptPestDDDRest API
görüşürüzMesajınızı bekliyorum[email protected]