Minecraft Oyun Modu ve Ranks Sistemi

Manhunt Ranked — Teknik Mimari Planı
Sistemin 4 Parçası
Minecraft Plugin — sunucuda çalışan, oyun modlarını ve rank mantığını gerçek zamanlı uygulayan kod.
Backend + Veritabanı — hesapları, maç geçmişini, rank'leri tutan tek doğruluk kaynağı. Diğer üç parçanın da konuştuğu merkez.
Masaüstü Client (Launcher) — kendi arayüzü olan, oturumu siteyle paylaşan, Minecraft'ı başlatan uygulama.
Website — pixel temalı, hesap/profil/leaderboard gösteren tanıtım + yönetim sitesi.
Kimlik Doğrulama Akışı

Minecraft hesapları zaten Microsoft hesabı olduğu için ayrı bir kullanıcı/şifre sistemi kurmaya gerek yok — "Microsoft ile giriş yap" tek kimlik kaynağınız olur, hem sitede hem launcher'da hem de doğrudan Minecraft'ın kendisinde.

Kullanıcı sitede **"Microsoft ile Giriş Yap"**a basar → Microsoft OAuth ekranı → onay sonrası backend, Xbox Live → XSTS → Minecraft Services zincirinden geçip kullanıcının Minecraft UUID/kullanıcı adını doğrular → backend kendi oturum token'ını (JWT) verir, tarayıcıda saklanır.
Launcher açıldığında "Giriş Yap" butonuna basılınca, launcher yerel bir sunucu açar (localhost:PORT) ya da cihaz kodu akışı kullanır; tarayıcı otomatik açılır, aynı Microsoft girişi tekrar istenir, tamamlanınca token launcher'a düşer. (Discord, Prism Launcher gibi uygulamalar bunu böyle yapıyor.)
Launcher artık backend'e bu token'la konuşabilir (profil, rank, maç geçmişi çeker) ve aynı token zincirinden gerçek bir Minecraft access token'ı üretip oyunu doğrudan o hesapla başlatıp sunucuya bağlayabilir.

Bloke edici adım: Yeni oluşturulan Azure uygulamaları artık Minecraft API'yi kullanmak için Microsoft'un onay formunu doldurup geçmek zorunda — bu otomatik değil ve süre alabilir. Eski (onay süreci öncesi oluşturulmuş) uygulamalar sorunsuz çalışmaya devam ediyor ama yeni bir uygulama kaydı bu onaya tabi. Launcher'ı yazmaya başlamadan önce bu başvuruyu yapın; projenin en büyük olası gecikme noktası burası.

Teknik referans: minecraft.wiki/w/Microsoft_authentication ve wiki.vg/Microsoft_Authentication_Scheme — akışın tüm adımları (OAuth2 authorization code / device code flow, XboxLive.signin scope, XSTS token, api.minecraftservices.com/authentication/login_with_xbox) burada dokümante.

1. Minecraft Plugin

Platform: Paper (Spigot/Bukkit tabanlı).

Fabric/Forge yerine bunu öneriyorum çünkü Paper server-side bir plugin'dir — oyuncular hiçbir mod yüklemeden, vanilla Minecraft client'ıyla bile bağlanabilir. Fabric bir mod olduğu için oyuncunun client'ına da yüklenmesi gerekirdi, bu da giriş engelini artırır. İleride HUD/UI için hafif bir client-side mod eklemek isterseniz bu ayrı bir karar olarak sonra değerlendirilebilir.

Sorumlulukları:

Lobi/kuyruk yönetimi — oyuncuları modlara göre gruplama, rolleri (Runner / Hunter / Killer) atama
Oyun modu mantığı — Manhunt (runner + hunter'lar), Killer modu (6 kişi, gizli katil)
Olay takibi — kim kimi öldürdü, ejderha öldü mü, maç ne kadar sürdü, oyuncu ayrıldı mı
Rank'e göre zorluk — runner'ın güncel Hunter-sayısı kademesini backend'den çekip lobiyi ona göre kurma
Backend'e raporlama — maç bittiğinde ham sonucu POST etmek (kim hangi rolde, kim kazandı, süre)

Önemli tasarım kararı: RP hesaplamasını plugin değil backend yapmalı. Plugin sadece ham olayı bildirir ("bu maçta X runner'dı, Y ve Z hunter'dı, runner kazandı, 14 dakika sürdü"). Formülü değiştirmek istediğinizde (örneğin bonus katsayılarını ayarlamak) sunucuyu yeniden derleyip deploy etmeniz gerekmez, sadece backend'i güncellersiniz.

2. Backend + Veritabanı

Stack önerisi: Node.js + TypeScript (Fastify veya Express) ya da Python + FastAPI — ikisi de bu ölçek için uygun; hangisine daha yatkınsanız o. Veritabanı için PostgreSQL.

Ana tablolar (basitleştirilmiş):

Tablo Alanlar
accounts id, mc_uuid, mc_username, created_at
player_ranks account_id, track (runner / hunter / killer), rp, wins, losses
matches id, mode, participants (JSON: kim hangi rol), outcome, duration, timestamp
sessions token, account_id, expires_at, issued_to (website / launcher)

Ana uçlar:

POST /auth/microsoft/callback — OAuth tamamlama, oturum verme
POST /session/exchange — launcher'ın website oturumunu kendi token'ına çevirmesi
GET /profile/:uuid — rank'ler, istatistikler
GET /leaderboard?track=runner — sıralama
POST /matches — plugin'den ham maç sonucu; RP burada hesaplanıp kaydedilir
GET /matches/:uuid — maç geçmişi

Gerçek zamanlı ihtiyaçlar (canlı leaderboard, maç durumu) için başta basit polling yeterli — WebSocket'e geçiş sonradan, ihtiyaç oldukça yapılabilir.

3. Masaüstü Client (Launcher)

Stack önerisi: Electron + React. Gerçek launcher'ların çoğu (HeliosLauncher ve benzerleri) bunu kullanıyor; site ile aynı bileşenleri/pixel tasarımı paylaşabilirsiniz. Daha hafif bir alternatif Tauri (Rust tabanlı) — daha küçük dosya boyutu ama ekosistemi Electron kadar olgun değil.

Ekranlar: Giriş → Profil (rank'ler, istatistikler) → Oyun Modu Seçici (Manhunt / Killer) → "Oyna" (gerçek Minecraft'ı bu hesapla başlatır, sunucuya bağlar).

4. Website

Pixel temalı, hesap girişi + profil + leaderboard + (ileride) mağaza. Bu kısmın statik/frontend prototipini chat içinde gerçek bir HTML/React artifact olarak kurabiliriz — backend'e bağlanmadan önce görünümü test etmeniz için.

Fazlı İnşa Planı

Hepsini aynı anda kurmaya çalışmak riski büyütür. Her faz tek başına bir şeye yarar:

Faz İçerik
0 (şu an) RP tracker artifact'i — içerik üretmeye devam, sistemin kurallarını test eder
1 Paper plugin — temel Manhunt + rank hesaplama, backend olmadan sadece in-game komutlarla
2 Backend + basit genel-erişime-açık leaderboard sayfası (launcher yok, sadece web'den bakılır)
3 Website'e Microsoft girişi + profil sayfaları eklenir
4 Masaüstü launcher (en son — en çok bağımlılığı olan parça)
5 Monetizasyon (kozmetik mağaza)
Dikkat Edilmesi Gerekenler
Azure uygulama onayı — yukarıda bahsedildi, en başta başvurun.
Minecraft EULA / pay-to-win riski — ranked/rekabetçi bir sistem olduğu için rol erişimi satmak risklidir; kozmetik yönde kalın.
Hosting — backend + veritabanı için küçük bir VPS başlangıçta yeterli (Minecraft sunucusuyla aynı makinede bile olabilir); trafik büyüdükçe ayırırsınız.
Java/Kotlin bilgisi — plugin geliştirme bunu gerektirir. Bu ve backend/launcher kodu gerçek bir proje ortamında (örn. Claude Code) yazılmalı; tek bir chat mesajıyla üretilemeyecek kadar büyük.