# ⚡ Relay

Endüstri Standardı Reaktif Servis Kaydı, Eklentiler Arası İletişim (Pub/Sub) ve Ekosistem Çatısı
Modern Paper, Purpur ve Çok Çekirdekli Folia Sunucuları İçin Yeni Nesil Altyapı Motoru.

--- ## 🌟 Relay Nedir? **Relay**, modern Minecraft sunucularında (Paper, Purpur ve özellikle çok iş parçacıklı **Folia**) eklentiler arası entegrasyonu ve sunucu servislerini endüstri standartlarına taşıyan açık kaynaklı bir altyapı motorudur. Eski Bukkit mimarisindeki senkron ve ana iş parçacığını (Main Thread) donduran çağrılar yerine; **%100 Non-Blocking asenkron mimari**, **mikroservis tipi Pub/Sub mesajlaşması**, **Folia bölgesel iş parçacığı güvenliği (Region-Safe)** ve **otomatik bellek temizliği (Zero-Leak)** sunar. --- ## 🚀 Dahili Servisler (Features at a Glance) Relay, bir sunucunun ve eklentilerin ihtiyaç duyduğu 8 temel alt sistemi tek bir çatı altında eksiksiz sunar: | Modül / Servis | Açıklama | Öne Çıkan Özellikler | | :--- | :--- | :--- | | **ServiceRegistry** | Reaktif servis keşfi ve kayıt defteri | `HIGHEST` ➔ `FALLBACK` öncelik basamakları, yüklenme sırasından bağımsız `onServiceReady` Promise mimarisi. | | **RelayMessenger** | Bağımsız Pub/Sub ve RPC iletişim veri yolu | Eklentiler birbirinin `.jar` dosyasına bağımlı olmadan kanallara abone olabilir veya asenkron istek-cevap (`request`) yapabilir. | | **EconomyService** | Çoklu para birimi ve finans motoru | IEEE 754 kayan noktalı sayı hatalarını önleyen `BigDecimal` aritmetiği, sınırsız para birimi, atomik transferler. | | **CooldownService** | Evrensel bekleme süresi yöneticisi | Yetenek, büyü ve komutlar için thread-safe bekleme süreleri, ActionBar dolum yüzdesi (`getProgress()`), otomatik TTL tahliyesi. | | **SharedDataService** | Tip güvenli paylaşımlı veri havuzu | `DataKey` ile veri doğrulama, süreli geçici veriler (`setTemporary`), reaktif canlı gözlemciler (`observe`). | | **PermissionService** | Asenkron yetki ve rütbe kontrolü | TPS düşüşlerini engelleyen asenkron yetki sorgulama, LuckPerms/Vault uyumluluğu, ön ek ve rütbe ağırlığı. | | **PartyService** | Takım ve dost ateşi yöneticisi | Combat anında thread dondurmayan sıfır-bellek tahsisli `isFriendlySync` kontrolleri, zindan grupları. | | **MetricsService** | Performans telemetrisi & lag alarmı | Nanosaniye hassasiyetinde süre ölçümü, P50/P95/P99 yüzdelikleri, TPS düşüşlerinde otomatik `LagSpikeEvent` alarmı. | | **HologramService** | Display Entity tabanlı hologram motoru | Minecraft 1.20+ `TextDisplay` native mimarisi, sıfır ArmorStand lag, Folia region-safe `spawnAsync`, MiniMessage ve gölge. | | **MenuService** | Folia güvenli sanal sandık GUI motoru | Üst envanter tıklamalarını ve sürüklemelerini kilitleyen anti-dupe koruması, 150ms anti-macro debounce, sayfalama (pagination). | --- ## 🛡️ Folia Multi-Threading & Zero-Leak Mimarisi Relay, çok çekirdekli Minecraft sunucu yazılımı **Folia** için sıfırdan tasarlanmıştır: * **Region-Safe Scheduling:** Hologram ve menü işlemleri, hedef koordinatın veya oyuncunun ait olduğu bağımsız iş parçacığına otomatik iletilir. * **Lock-Free Veri Yapıları:** Tüm dahili önbellekler `ConcurrentHashMap`, `CopyOnWrite` ve atomik sayaçlar ile donatılmıştır; kilitlenme (deadlock) yaşanmaz. * **Zero-Leak Yaşam Döngüsü:** Bir eklenti kapandığında veya sunucu yeniden yüklendiğinde, o eklentiye ait tüm dinleyiciler, hologramlar, menüler ve bekleme süreleri sunucudan otomatik tahliye edilir (`setPersistent(false)`). --- ## 📦 Geliştiriciler İçin Projeye Ekleme (Dependency) Eklenti geliştiricileri yalnızca 40 KB'lık hafif, harici kütüphane içermeyen **`relay-api`** modülünü çeker: ### Gradle (Kotlin DSL) ```kotlin repositories { mavenCentral() maven("https://jitpack.io") } dependencies { compileOnly("com.github.Kriscra.Relay:relay-api:v1.3.0") } ``` ### Maven (`pom.xml`) ```xml jitpack.io https://jitpack.io com.github.Kriscra.Relay relay-api v1.3.0 provided ``` --- ## 🛠️ Hızlı Kod Örnekleri ### 1. Reaktif Servis Keşfi (`onServiceReady`) Yüklenme sırasını dert etmeyin. İlgili eklenti sizden sonra yüklense bile servis kaydedildiği anda geri çağrılır: ```java RelayAPI.getServiceRegistry().onServiceReady(EconomyService.class, economy -> { getLogger().info("Ekonomi sistemi bağlandı! Para birimi: " + economy.getDefaultCurrency().displayName()); }); ``` ### 2. Eklentiler Arası Mesajlaşma (Pub/Sub) Kendi aralarında doğrudan `.jar` bağımlılığı olmadan eklentilerin haberleşmesini sağlayın: ```java // Yayıncı Eklenti: RelayAPI.getMessenger().publish("clan:levelup", new ClanLevelPayload("Akıncılar", 10), this); // Dinleyici Eklenti: RelayAPI.getMessenger().subscribe("clan:levelup", ClanLevelPayload.class, this, ctx -> { getLogger().info(ctx.getPayload().clanName() + " seviye atladı!"); }); ``` ### 3. TextDisplay Hologram Oluşturma (Folia Region-Safe) ```java Hologram hologram = RelayAPI.getHolograms().createBuilder(plugin, location) .appendLine("✦ RELAY NETWORK ✦") .appendLine("Folia & Paper Uyumlu") .setBillboard(Billboard.CENTER) .setTextShadow(true) .build(); hologram.spawnAsync(); ``` ### 4. Folia Uyumlu Sandık Menüsü (Anti-Dupe & Debounce) ```java Menu menu = RelayAPI.getMenus().createBuilder(plugin) .titleMiniMessage("Işınlanma Menüsü") .pattern( "#########", "# W #", "#########" ) .bindKey('#', MenuButton.of(new ItemStack(Material.BLACK_STAINED_GLASS_PANE))) .bindKey('W', MenuButton.builder() .item(new ItemStack(Material.COMPASS)) .sound(Sound.ENTITY_ENDERMAN_TELEPORT) .debounce(250L) // 250ms makro koruması .onClick(ctx -> ctx.getPlayer().teleport(spawnLocation)) .build()) .build(); menu.open(player); ``` --- ## ⚙️ Yönetici Komutları Sunucudaki aktif servisleri, telemetriyi ve oturumları anlık izleyin: | Komut | Açıklama | | :--- | :--- | | `/relay status` | Aktif servis, konu, hologram, menü ve çalışma ortamı bilgilerini gösterir. | | `/relay services` | Sunucuda kayıtlı tüm servisleri ve öncelik derecelerini listeler. | | `/relay topics` | Aktif Pub/Sub iletişim kanallarını ve dinleyici sayılarını listeler. | | `/relay metrics` | Ortalama işlem sürelerini, P95 gecikmelerini ve sayaçları gösterir. | | `/relay metrics reset`| Tüm telemetri ve performans sayaçlarını sıfırlar. | | `/relay holograms` | Aktif TextDisplay hologramlarını ve konumlarını listeler. | | `/relay menus` | Aktif sanal menü oturumlarını ve görüntüleyen oyuncu sayılarını listeler. | **Yetki:** `relay.admin` (Varsayılan: OP) --- ## 🔗 Bağlantılar & Kaynaklar * 🌐 **Canlı Dokümantasyon Sitesi:** [kriscra.github.io/Relay](https://kriscra.github.io/Relay/) * 💻 **GitHub Kaynak Kodu:** [github.com/Kriscra/Relay](https://github.com/Kriscra/Relay) * 📦 **JitPack SDK Deposu:** [jitpack.io/#Kriscra/Relay](https://jitpack.io/#Kriscra/Relay) * 📜 **Lisans:** MIT License