Geliştiriciler

Mantığını takip edebileceğin bir oyun sunucusu

Puzzle Crash, sunucu otoriteli bir HTTP API üzerinde çalışır. Aynı saf oyun motoru sunucuda (karar vermek için) ve istemcide (animasyon için) çalışır. Bu sayfa bir özettir; tam referans depoda yer alır.

Tam API referansı (Markdown)

Mimari

Motor

Saf TypeScript, deterministik, G/Ç yok. İstemcinin efektlerini yöneten anlamsal olaylar üretir (PIECE_PLACED, LINES_CLEARED, LEVEL_COMPLETED, CASHOUT…).

Sunucu

Fastify, PostgreSQL ve Redis. Her aksiyon, oturum kilidi altında tek bir işlemde çalışır: doğrula → uygula → defter → geçmişe ekle.

İstemci

Beklenen sürüm ve idempotency anahtarıyla niyet gönderir; geri gelen otoriter durumu ve olayları çizer.

Kurallar

Kimlik: POST /v1/players’tan alınan Authorization: Bearer <token> (demo kimliği)
İdempotency: Durum değiştiren her çağrı Idempotency-Key taşır. Aynı anahtarla tekrar, ilk sonucu döndürür ve asla iki kez uygulanmaz.
Eşzamanlılık: Aksiyonlar expectedVersion taşır. Eski sürüm, güncel oturumla birlikte 409 VERSION_CONFLICT döndürür.
Doğrulama: Katı JSON şemaları; bilinmeyen alanlar, yanlış tipler ya da aralık dışı değerler reddedilir. Tip dönüştürme yok.
Hız sınırları: Oyuncu başına (yoksa IP başına), Redis tabanlı; 429 RATE_LIMITED.

Uç noktalar

Metot	Yol	Amaç
POST	/v1/players	Başlangıç demo kredili bir demo oyuncu oluşturur
GET	/v1/me	Bakiye ve bekleyen oturum bildirimi
POST	/v1/sessions	Tur başlatır: bahsi düşer, sunucu seed’ini taahhüt eder, 0. eli dağıtır
GET	/v1/sessions/active	Yenileme ya da çökme sonrası canlı turu kurtarır
POST	/v1/sessions/:id/actions	PLACE · CONTINUE · CASHOUT
POST	/v1/sessions/:id/heartbeat	Varlık: ekrandayken turu canlı tutar
POST	/v1/sessions/:id/leave	Bilinçli çıkış: 5 dakikalık bekleme süresini başlatır
GET	/v1/sessions/:id/verification	Açıklanan seed, dağıtılan eller, tekrar ve hash zinciri kontrolleri
GET	/v1/sessions	Tur geçmişi
GET	/v1/config	Yayımlanmış kurallar: çarpan tabloları, cashout level’ları, parça olasılıkları

Oturum yaşam döngüsü

Bir tur az sayıda durum arasında hareket eder. Onu yalnızca sunucu hareket ettirir.

Örnek

Bir oyuncu oluştur, tur başlat ve ilk parçayı yerleştir:

API=https://puzzlecrash.urbanrats.com
TOKEN=$(curl -s -X POST $API/v1/players | jq -r .token)

S=$(curl -s -X POST $API/v1/sessions \
  -H "authorization: Bearer $TOKEN" -H "idempotency-key: start-$(date +%s)" \
  -H 'content-type: application/json' -d '{"difficulty":"medium","stake":100}')
ID=$(echo $S | jq -r .session.id)

curl -s -X POST $API/v1/sessions/$ID/actions \
  -H "authorization: Bearer $TOKEN" -H "idempotency-key: a1-$(date +%s)" \
  -H 'content-type: application/json' \
  -d '{"type":"PLACE","slot":0,"x":0,"y":0,"expectedVersion":0}'

Operasyon

Sağlık: /healthz (canlılık) ve /readyz (veritabanı + Redis)
Hata, gecikme, kilit çekişmesi ve ödeme anomalileri için alarm kurallı Prometheus metrikleri
Gizli bilgileri maskelenmiş yapılandırılmış JSON denetim logları
Sunucu ve web için Docker imajları; migration’lar otomatik çalışır