# 🌟 XiaAPI — Çekirdek Kütüphane & Framework

--- ## 📌 Genel Bakış (Overview) **XiaAPI**, eklentilerimizin sorunsuz, yüksek performanslı ve modern standartlarda çalışmasını sağlayan **merkezi kütüphane eklentisidir (Core Library & API)**. Eklentilerimizin kalbi konumundadır; ortak ihtiyaç duyulan veritabanı havuzlarını, sunucular arası Redis ağ iletişimini, envanter menülerini, dil dosyalarını ve asenkron görev yöneticilerini tek bir çatı altında toplar. Sunucu açılışında `STARTUP` aşamasında (`load: STARTUP`) yüklenerek dünyalar ve diğer tüm eklentiler başlamadan önce hazır hale gelir. Diğer eklentilerimiz sunucuda çalışabilmek için doğrudan XiaAPI'yi temel alır. --- ## 🚀 Dahili Modüller ve Mimari ``` ┌──────────────────────────────┐ │ XiaAPI │ │ (load: STARTUP, Core API) │ └──────────────┬───────────────┘ │ ┌──────────────────┬───────────────┼───────────────┬──────────────────┐ ▼ ▼ ▼ ▼ ▼ ┌───────────┐ ┌─────────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │ XiaMenu │ │ DatabaseMgr │ │ RedisMgr │ │ Language │ │ ItemBuilder │ │ GUI Eng. │ │ HikariCP │ │ Pub/Sub │ │ Manager │ │ MiniMessage │ └───────────┘ └─────────────┘ └───────────┘ └───────────┘ └─────────────┘ ▲ ▲ ▲ ▲ ▲ └──────────────────┴───────────────┼───────────────┴──────────────────┘ │ ┌─────────────────┴─────────────────┐ │ XiaPlugin Taban Sınıfı │ │ (Tüm Eklentilerimiz İçin) │ └───────────────────────────────────┘ ``` --- ### 1. 🛡️ `XiaPlugin` — Taban Sınıf ve Yaşam Döngüsü Eklentilerimizin miras aldığı temel soyut sınıftır (`extends XiaPlugin`). * **Güvenlik & Bağımlılık Doğrulaması:** Eklenti açılırken XiaAPI'nin aktifliğini ve hazır olup olmadığını denetler. XiaAPI bulunamazsa eklentinin hatalı çalışmasını önlemek için başlatmayı güvenle durdurur. * **Standart Yaşam Döngüsü:** * `onXiaEnable()`: Eklenti açılış işlemleri. * `onXiaDisable()`: Güvenli kapatma ve kaynak temizleme. * `onXiaReload()`: Yapılandırma ve dil dosyalarını anlık yenileme. * **Merkezi Kayıt:** Başlatılan her eklenti XiaAPI çekirdeğine kaydedilir ve çalışma durumu anlık olarak izlenebilir. --- ### 2. ⚡ `DatabaseManager` — HikariCP Veritabanı Motoru Yüksek hızlı JDBC bağlantı havuzlama altyapısı sunar. * **Çift Veritabanı Desteği:** * **SQLite:** Yerel dosya tabanlı, harici kurulum gerektirmeyen hafif yapı. * **MySQL / MariaDB:** Ağ ve kümeleme yapıları için kurumsal uzak veritabanı desteği. * **Performans Ayarları:** `cachePrepStmts`, `prepStmtCacheSize`, `useServerPrepStmts` ve `rewriteBatchedStatements` gibi endüstri standardı optimizasyonlar varsayılan olarak entegredir. * **Asenkron Kolaylık:** * `executeUpdateAsync(sql, params...)`: Ana sunucu iş parçacığını (main thread) dondurmadan arka planda INSERT/UPDATE/DELETE çalıştırır. * `executeQueryAsync(sql, handler, params...)`: SELECT sorgularını asenkron çalıştırıp sonuç kümesini işler. --- ### 3. 🌐 `RedisManager` & `RedisMessenger` — Çoklu Sunucu (Pub/Sub) Ağı Proxy (BungeeCord / Velocity) veya çoklu sunucu ağları için dağıtık mesajlaşma sağlar. * **Dirençli Arka Plan Dinleyicisi:** Bağlantı kesintilerinde sunucuyu kilitlemeden arka planda otomatik yeniden bağlanmayı dener (`auto-reconnect`). * **Pub/Sub Mesajlaşma:** Kanallar üzerinden olay tabanlı veri yayınlama (`publish`) ve dinleme (`subscribe`): ```java XiaAPI.getInstance().getRedisMessenger().subscribe("kanal:adi", (channel, message) -> { // Mesaj işleme mantığı }); ``` * **Asenkron İletim:** Ağ istekleri `CompletableFuture` ile tamamen bağımsız iş parçacıklarında yürütülür. --- ### 4. 🎨 `XiaMenu` — Envanter & GUI Motoru Özel sandık arayüzleri (GUI) oluşturmak için geliştirilmiş güvenli menü tabanıdır. * **Tıklama Koruması:** Eşyaların oyuncular tarafından çalınmasını veya sürüklenmesini varsayılan olarak engeller (`cancelClicks=true`). * **Fonksiyonel Butonlar (`MenuButton`):** Eşya tasarımı ile tıklama eylemini tek bir nesnede birleştirir: ```java setButton(13, MenuButton.of(item, event -> { // Tıklama olayı })); ``` * **Çerçeve ve Doldurma:** `fillBorder(glass)` ile menü kenarlıklarını, `fillEmpty(glass)` ile boş slotları tek satırda süsler. --- ### 5. 🗡️ `ItemBuilder` — Fluent Eşya Oluşturucu Minecraft eşyalarını modern Adventure ve PDC özellikleriyle hızlıca inşa eder. * **MiniMessage Renklendirmesi:** Hex (`<#38ef7d>`), gradient (`Metin`) ve klasik renk kodlarını doğrudan destekler. * **PersistentDataContainer (PDC):** Eşyalara kalıcı özel veri etiketleri ekler (`pdc(key, type, value)` ve `getPdc(key, type)`). * **Zengin Nitelikler:** Kafa sahibi atama (`skullOwner`), parıltı efekti (`glow`), deri zırh renklendirme (`leatherColor`), CustomModelData ve ItemFlag yönetimi. --- ### 6. 🌍 `LanguageManager` & `ConfigManager` — Dil ve Yapılandırma * **Çok Dilli Sistem:** `languages/` klasörü altındaki YAML dil dosyalarını yönetir (`messages_tr.yml`, `messages_en.yml` vb.). * **Dinamik Yer Tutucular:** Mesajlardaki `{0}`, `{1}` veya özel anahtarları otomatik olarak dönüştürür. * **Kolay Erişim:** `send(sender, "mesaj.anahtari", "{degisken}", deger)` ile tek satırda biçimlendirilmiş çıktı verir. --- ### 7. ⌨️ `XiaCommand` & `XiaSubCommand` — Komut Motoru * **Alt Komut Sistemi:** Ana komut altına kolayca hiyerarşik alt komutlar tanımlanmasını sağlar. * **Otomatik Tab Tamamlama:** Oyuncunun yetkisine göre sekme tamamlama önerilerini filtreler. * **Yetki & Oyuncu Denetimi:** `playerOnly` ve izin kontrollerini komut mantığı çalışmadan önce otomatik gerçekleştirir. --- ### 8. ⏱️ `XiaScheduler` — Görev Zamanlayıcısı * **Folia & Paper Uyumlu:** Senkron ve asenkron zamanlayıcı görevlerini (`runSync`, `runAsync`, `runTimerAsync`) basitleştirir. * **Otomatik Temizleme:** Eklenti kapandığında çalışan tüm zamanlayıcıları bellek sızıntısına yol açmadan güvenle iptal eder. --- ### 9. 🔌 `IXiaService` — Servis Kayıt Defteri * Eklentiler arasında doğrudan bağımlılık oluşturmadan servislerin paylaşılmasını sağlar (Service Locator Modeli). * `registerService(Class, T provider)` ve `getService(Class)` ile modüller arası gevşek bağlı (loosely coupled) iletişim kurulur. --- ## ⚙️ Yapılandırma Dosyası (`config.yml`) XiaAPI, veritabanı ve Redis bağlantı parametrelerini merkezi olarak yapılandırır: ```yaml # ========================================================== # XIA EKOSİSTEMİ - ÇEKİRDEK API # ========================================================== settings: # Varsayılan dil ('tr', 'en' veya languages klasöründeki özel dil kodu) language: "tr" # Konsolda detaylı hata ayıklama mesajları gösterilsin mi? debug: false # ---------------------------------------------------------- # Veritabanı Yapılandırması (SQLite, MySQL veya MariaDB) # ---------------------------------------------------------- database: # Desteklenen tipler: SQLITE, MYSQL, MARIADB type: "SQLITE" host: "localhost" port: 3306 database: "xia_database" username: "root" password: "" use-ssl: false pool: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 30000 max-lifetime: 1800000 # ---------------------------------------------------------- # Redis Yapılandırması (Cross-Server & Ağ Senkronizasyonu) # ---------------------------------------------------------- redis: # Çoklu sunucu senkronizasyonu için Redis kullanılsın mı? enabled: false host: "127.0.0.1" port: 6379 password: "" database: 0 timeout: 2000 ssl: false ``` --- ## 💻 Komutlar ve Yetkiler Ana komut: `/xiaapi` (Kısayol: `/xapi`) Yetki: `xiaapi.admin` | Komut | Kısayollar | Açıklama | |---|---|---| | `/xiaapi info` | `/xapi bilgi`, `/xapi version` | XiaAPI sürümünü, bağlı eklenti sayısını, DB ve Redis durumunu gösterir. | | `/xiaapi reload` | `/xapi yenile` | XiaAPI'yi ve bağlı tüm eklentilerin yapılandırmalarını yeniden yükler. | | `/xiaapi plugins` | `/xapi eklentiler`, `/xapi list` | XiaAPI çekirdeğine bağlı aktif eklentileri listeler. | | `/xiaapi database` | `/xapi db` | Veritabanı havuzunun bağlantı durumunu ve sağlığını denetler. | | `/xiaapi redis` | — | Redis bağlantısını test eder ve sunucu yanıt süresini (ping ms) ölçer. | --- ## 🛠️ Eklentiler İçin Geliştirici Kullanımı Eklentilerimizin XiaAPI'yi temel alması için izlenen adımlar: ### 1. `pom.xml` Tanımı ```xml org.Xia XiaAPI 1.0.0 provided ``` ### 2. `plugin.yml` Bağımlılığı ```yaml name: OzelEklenti version: 1.0.0 main: org.Xia.ozelEklenti.OzelEklenti api-version: '26.2' depend: [XiaAPI] # XiaAPI'nin önce başlamasını garanti eder ``` ### 3. Ana Sınıf Örneği ```java package org.Xia.ozelEklenti; import org.Xia.xiaAPI.api.XiaPlugin; public final class OzelEklenti extends XiaPlugin { @Override public void onXiaEnable() { // Eklenti açıldığında çalışacak kodlar getXiaLogger().info("Eklenti başarıyla başlatıldı!"); } @Override public void onXiaDisable() { // Kapatma ve temizlik kodları } @Override public void onXiaReload() { super.onXiaReload(); // Yapılandırma ve dil dosyalarını yeniler } } ``` --- ## 📦 Sistem Gereksinimleri * **Sunucu Motoru:** [PaperMC](https://papermc.io/) 1.20+ (Paper 26.2+ / Folia uyumlu) * **Java:** Java 21 LTS veya Java 25 LTS * **Veritabanı:** SQLite (yerel) ya da MySQL / MariaDB (uzak küme) * **Redis:** Redis 6.0+ (çoklu sunucu ağları için) ---

XiaAPI • Eklentilerimizin Kalbi & Merkezi Kütüphane Motoru
Developed with ❤️ by Xia Team
Support: xiaplugins@proton.me