XiaAPI

🌟 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):

  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:

  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 (<gradient:#38ef7d:#11998e>Metin</gradient>) 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>, T provider) ve getService(Class<T>) 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:

# ==========================================================
#                   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

🛠️ Eklentiler İçin Geliştirici Kullanımı

Eklentilerimizin XiaAPI'yi temel alması için izlenen adımlar:

1. pom.xml Tanımı

<dependency>
    <groupId>org.Xia</groupId>
    <artifactId>XiaAPI</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

2. plugin.yml Bağımlılığı

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

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 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: [email protected]