ArceniaHesapEşle

ArceniaHesapEsle, Minecraft sunucunuzdaki oyuncu hesaplarini Discord hesaplariyla eslestiren kapsamli bir Spigot eklentisidir. Oyuncular oyun icinde /hesapesle komutuyla benzersiz bir sayisal dogrulama kodu alir, bu kodu Discord'daki belirlenen kanala yazarak hesaplarini baglar. Eklenti ayrica Minecraft izinlerine dayali otomatik Discord rol senkronizasyonu, hesap esleme odulleri, Discord Nitro Boost odul sistemi, Discord slash komutlari, PlaceholderAPI entegrasyonu ve detayli embed loglama ozellikleri sunar.

Temel

• Kod Tabanli Hesap Esleme: Oyuncular /hesapesle komutuyla benzersiz bir sayisal dogrulama kodu alir ve bunu Discord'da belirlenen kanala yazarak hesaplarini esler. Kodlar yapilandirabilir sure sonunda otomatik olarak gecersiz olur.
• Otomatik Rol Senkronizasyonu: Minecraft permission'larina dayali olarak Discord rolleri otomatik olarak eklenir veya kaldirilir. Sunucu girisinde, hesap esleme aninda ve opsiyonel periyodik zamanlayici ile senkronizasyon yapilir.
• Esleme Rolu: Hesabini esleyen tum oyunculara otomatik olarak belirlenen bir Discord rolu verilir.
• Discord Nickname Degistirme: Hesap eslendiginde Discord sunucusundaki kullanici adi Minecraft oyuncu adiyla guncellenir.
• Odul Sistemi: Hesap esleme sonrasinda yapilandirabilir konsol komutlari ile oyunculara oduller verilir. (%player%, %uuid%, %discord_id%, %discord_tag% yer tutuculari desteklenir)
• Discord Nitro Boost Odulleri: Sunucuya boost basan kullanicilara otomatik olarak ozel oduller verilir. Boost kaldirildiginda oduller geri alinir. Sezon bazli sifirlama destegi vardir. Hesabi esli olmayan booster'lara DM ile bildirim gonderilir ve hesabini esledigi anda odul otomatik olarak verilir.
• Discord Slash Komutlari: /oyuncu <isim> komutuyla oyuncu bilgileri embed olarak goruntulenir. /hesap komutuyla kendi esleme durumunuz kontrol edilebilir. Admin olmayan kullanicilar yalnizca kendi hesaplarini gorebilir.
• PlaceholderAPI Entegrasyonu: Scoreboard, tab list, hologram ve chat formatter gibi eklentilerde esleme verilerini gostermek icin placeholder destegi sunar.

Guvenlik ve Performans

• Rate Limiting: /hesapesle komutunda yapilandirabilir cooldown suresi ile spam onlenir.
• Thread-Safe Veritabani: Tum veritabani islemleri senkronize edilmistir; coklu thread erisiminde veri butunlugu korunur.
• In-Memory Cache: Bagli hesap sorgulamalari RAM'den yapilir, veritabanina gereksiz erisim onlenir.
• Toplu Rol Guncelleme: Discord rolleri tek bir API cagrisiyla topluca guncellenir, rate limit riski azaltilir.
• Multi-Guild Destegi: Birden fazla Discord sunucusunda calisan botlar icin hedef sunucu config uzerinden belirlenebilir.
• Periyodik Kod Temizligi: Suresi dolmus dogrulama kodlari zamanlayici ile duzenli olarak temizlenir.

Yonetim

• Admin Komutlari: Hesap eslemelerini silme (onay adimli), manuel rol senkronizasyonu, bagli hesap kontrolu, boost odullerini test etme ve sifirlama, yapilandirmayi yeniden yukleme imkanlari sunar.
• Config Reload ile Bot Yeniden Baslatma: Token veya guild ID degistiginde Discord botu async olarak yeniden baslatilir; sunucu kastirilmaz.
• Plugin Bilgi Komutu: Versiyon, bot durumu, bagli hesap sayisi ve sunucu bilgilerini goruntuleyin.
• Detayli Discord Loglama: Hesap esleme, esleme kaldirma, rol guncelleme, kod olusturma, boost olaylari ve hatalar Discord kanalina renkli embed mesajlarla loglanir.
• DM Bildirimleri: Basarili esleme, boost odulu, gecersiz kod ve hata durumlarinda kullanicilara Discord DM ile embed bildirim gonderilir.
• SQLite Veritabani: Tum veriler yerel SQLite veritabaninda saklanir. Ek veritabani kurulumu gerekmez.
• Tab Tamamlama: Tum Minecraft komutlari icin akilli tab tamamlama destegi bulunur.
• Tamamen Yapilandirabilir Mesajlar: Tum oyuncu, admin ve Discord DM mesajlari config.yml uzerinden ozellestirilebilir.

• Minecraft Sunucusu: Spigot veya Paper 1.21.4+ (API surumu 1.21)
• Java: 21 veya uzeri
• Discord Bot: Discord Developer Portal uzerinden olusturulmus bir bot tokeni
• Discord Bot Izinleri: Mesaj okuma, mesaj silme, rol yonetimi, nickname degistirme, uyeleri goruntuleme
• Discord Gateway Intent'leri: GUILD_MESSAGES, MESSAGE_CONTENT, GUILD_MEMBERS
• PlaceholderAPI: Opsiyonel. Placeholder destegi icin gereklidir.
• Maven: Kaynak koddan derleme icin gereklidir (istege bagli; hazir JAR dosyasi kullanilabilir)

1. Derlenmis ArceniaHesapEsle-1.0.0.jar dosyasini sunucunuzun plugins/ klasorune kopyalayin.
2. Sunucuyu baslatin; eklenti ilk calistirmada plugins/ArceniaHesapEsle/config.yml dosyasini olusturacaktir.
3. Sunucuyu durdurun ve config.yml dosyasini duzenleyin:
   • discord.bot-token alanina Discord bot tokeninizi yazin.
   • discord.guild-id alanina Discord sunucu ID'nizi yazin (bos birakilirsa ilk sunucu kullanilir).
   • discord.link-channel-id alanina hesap esleme kanalinin ID'sini yazin.
   • discord.log-channel-id alanina log kanalinin ID'sini yazin.
   • discord.admin-role-ids listesine admin rol ID'lerini ekleyin.
   • role-sync.linked-role-id alanina hesabini esleyen herkese verilecek rolun ID'sini yazin.
   • role-sync.mappings altinda Minecraft permission'larini Discord rol ID'leriyle eslestirin.
4. Sunucuyu tekrar baslatin. Konsol ciktisinda ArceniaLink basariyla yuklendi! ve Discord bot basariyla baglandi mesajlarini gordugunuzde eklenti hazirdir.

Guvenlik Notu: Bot tokeninizi asla kaynak kodda veya herkese acik bir yerde birakmayin. config.yml dosyanizi .gitignore ile koruma altina alin.

Discord Bot Kurulumu

1. Discord Developer Portal adresine gidin.
2. New Application ile yeni bir uygulama olusturun.
3. Bot sekmesinde bot tokenini kopyalayin ve config.yml dosyasindaki discord.bot-token alanina yapistirin.
4. Privileged Gateway Intents bolumunde Server Members Intent ve Message Content Intent seceneklerini etkinlestirin.
5. OAuth2 > URL Generator bolumunden botu sunucunuza davet edin. Gerekli izinler:
   • Manage Roles (Rolleri Yonet)
   • Manage Nicknames (Takma Adlari Yonet)
   • Send Messages (Mesaj Gonder)
   • Read Messages / View Channels (Mesajlari Oku)
   • Read Message History (Mesaj Gecmisini Oku)

Minecraft Komutlari

Not: Normal oyuncular yalnizca /hesapesle komutunu kullanabilir. Diger tum komutlar admin yetkisi gerektirir.

Discord Slash Komutlari

Izin Dugumleri

Discord Ayarlari

discord:
  bot-token: "BOT_TOKEN_BURAYA"          # Discord bot tokeni
  guild-id: ""                            # Discord sunucu ID (bos = ilk sunucu)
  link-channel-id: "123456789"            # Hesap esleme kanali ID'si
  log-channel-id: "123456789"             # Log kanali ID'si
  admin-role-ids:                         # /oyuncu komutu icin admin rolleri
    - "123456789"

Genel Ayarlar

settings:
  code-length: 6                          # Dogrulama kodu uzunlugu (sadece rakam)
  code-expiry-minutes: 5                  # Kodun gecerlilik suresi (dakika)
  delete-code-message: true               # Discord'da yazilan kod mesajini otomatik sil
  code-cooldown-seconds: 60              # /hesapesle cooldown suresi (saniye, 0 = devre disi)

Rol Senkronizasyonu

role-sync:
  enabled: true                           # Rol senkronizasyonunu etkinlestir/devre disi birak
  linked-role-id: "123456789"             # Hesabini esleyen herkese verilecek rol
  mappings:                               # Minecraft permission -> Discord rol ID eslemesi
    "arcenia.role.vip": "123456789"
    "arcenia.role.mod": "987654321"
  sync-on-join: true                      # Sunucu girisinde rolleri kontrol et
  sync-on-link: true                      # Hesap eslendiginde rolleri senkronize et
  change-nickname: true                   # Discord nickini Minecraft ismine cevir
  periodic-sync-minutes: 0               # Periyodik senkronizasyon araligi (dakika, 0 = devre disi)

mappings bolumunde Minecraft permission node'lari ile Discord rol ID'leri eslestirilir. Oyuncuda ilgili permission varsa karsilik gelen Discord rolu verilir; permission yoksa rol kaldirilir. Bu ozellik LuckPerms gibi izin eklentileriyle birlikte kullanilmak uzere tasarlanmistir. Ornek: /lp group vip permission set arcenia.role.vip true

periodic-sync-minutes degeri 0'dan buyuk ayarlandiginda, tum online oyuncularin rolleri belirtilen araliklarda otomatik olarak kontrol edilir ve guncellenir. Bu, oyun icinde permission degisikliklerinin Discord'a gecikmeden yansitilmasini saglar.

Odul Sistemi

rewards:
  enabled: true                           # Odul sistemini etkinlestir/devre disi birak
  commands:                               # Hesap eslendiginde calistirilacak komutlar
    - "give %player% diamond 5"
    - "eco give %player% 1000"

Kullanilabilir yer tutucular: %player%, %uuid%, %discord_id%, %discord_tag%

Boost Odulleri

boost:
  enabled: true                           # Boost odullerini etkinlestir/devre disi birak
  commands:                               # Boost basildiginda calistirilacak komutlar (tek seferlik)
    - "lp user %player% parent add booster"
    - "give %player% diamond_block 16"
    - "eco give %player% 10000"
  remove-commands:                        # Boost kaldirildiginda calistirilacak komutlar
    - "lp user %player% parent remove booster"

Boost odulleri her kullaniciya sezon basina bir kez verilir. /boostreset komutuyla tum kayitlar sifirlanarak yeni bir sezon baslatilabilir.

Mesajlar

Tum oyuncu, admin ve Discord DM mesajlari config.yml dosyasindaki messages bolumunden ozellestirilebilir. Minecraft renk kodlari (&a, &b, &c, &e, &l vb.) ve yer tutucular desteklenir.

messages:
  prefix: "&8[&bArcenia&8] &7"

  # Genel
  no-permission: "&cBu komutu kullanma yetkiniz yok!"
  player-only: "&cBu komutu sadece oyuncular kullanabilir!"
  player-not-found: "&cOyuncu bulunamadi!"
  cooldown: "&cLutfen %seconds% saniye bekleyin!"

  # Hesap esleme
  code-generated: "..."                   # Kod olusturuldugunda (%code%, %expiry%)
  already-linked: "..."                   # Hesap zaten eslenmisse
  link-success: "..."                     # Esleme basarili
  invalid-code: "..."                     # Gecersiz veya suresi dolmus kod
  code-error: "..."                       # Kod olusturma hatasi
  not-linked: "..."                       # Hesap eslenmemisse

  # Admin
  check-linked: "..."                     # /hesapkontrol esli sonucu (%player%, %discord_tag%, %discord_id%, %date%)
  check-not-linked: "..."                 # /hesapkontrol esli degil
  admin-unlinked: "..."                   # /hesapsil basarili (%player%)
  admin-synced: "..."                     # /hesapsync basarili (%player%)
  unlink-confirm: "..."                   # Esleme kaldirma onay istegi (%player%)
  unlink-confirm-expire: "..."            # Onay suresi uyarisi
  config-reloaded: "..."                  # Config yeniden yuklendi

  # Boost
  boost-reward: "..."                     # Boost odulu alindi
  boost-already-claimed: "..."            # Odul zaten alinmis
  boost-test-given: "..."                 # Boost test verildi (%player%)
  boost-test-removed: "..."               # Boost test kaldirildi (%player%)
  boost-reset-success: "..."              # Boost sifirlama basarili (%count%)

  # Kullanim
  usage-hesapsil: "..."                   # /hesapsil kullanim bilgisi
  usage-hesapsync: "..."                  # /hesapsync kullanim bilgisi
  usage-boosttest: "..."                  # /boosttest kullanim bilgisi

  # Discord
  discord-dm: "..."                       # Esleme basarili DM'i (%player%, %roles%)
  dm-failed: "..."                        # DM gonderilemedi

Sunucunuzda PlaceholderAPI yukluyse asagidaki placeholder'lar otomatik olarak kullanilabilir hale gelir:

Bu placeholder'lar scoreboard, tab list, hologram, chat formatter ve PlaceholderAPI destekleyen diger tum eklentilerde kullanilabilir.

Hesap Esleme Akisi

1. Oyuncu Minecraft sunucusunda /hesapesle komutunu yazar.
2. Cooldown kontrolu yapilir (varsayilan: 60 saniye). Gecerliyse benzersiz bir 6 haneli sayisal dogrulama kodu olusturulur ve veritabanina kaydedilir.
3. Oyuncuya kod, sure bilgisi ve Discord kanalina yonlendirme mesaji gosterilir.
4. Oyuncu Discord sunucusundaki belirlenen esleme kanalina (link-channel-id) bu kodu yazar.
5. Discord botu mesaji alir, kodu veritabaninda dogrular ve suresinin dolup dolmadigini kontrol eder.
6. Dogrulama basarili olursa:
   • Hesaplar veritabaninda kalici olarak eslenir ve in-memory cache guncellenir.
   • Yapilandirmaya bagli olarak Discord rolleri tek bir API cagrisiyla toplu senkronize edilir.
   • Discord kullanici adi Minecraft oyuncu adiyla guncellenir.
   • Odul komutlari konsoldan calistirilir.
   • Oyuncuya Minecraft'ta basari mesaji, Discord'da ise embed DM bildirimi gonderilir.
   • Esleme log kanalina embed olarak kayit atilir.
   • Eger kullanici zaten sunucuya boost basmissa, boost odulleri de otomatik olarak verilir.
7. Kod mesaji gizlilik icin Discord'dan otomatik olarak silinir (yapilandirabilir).

Rol Senkronizasyonu

• Oyuncu sunucuya her girdiginde (sync-on-join etkinse), hesap eslendiginde (sync-on-link etkinse) ve periyodik zamanlayici ile (periodic-sync-minutes > 0 ise) calisir.
• config.yml dosyasindaki role-sync.mappings bolumunde tanimlanan her permission-rol cifti kontrol edilir.
• Oyuncuda permission varsa karsilik gelen Discord rolu eklenir; permission yoksa rol kaldirilir.
• linked-role-id ile tanimlanan rol, hesabi esli olan tum oyunculara otomatik olarak verilir.
• Roller tek bir modifyMemberRoles API cagrisiyla topluca guncellenir; Discord rate limit riski minimuma indirilir.
• LuckPerms veya benzeri izin eklentileriyle entegre calisir.

Boost Odul Sistemi

• Discord sunucusuna boost basan bir kullanicinin esli Minecraft hesabi varsa, boost.commands altindaki odul komutlari otomatik olarak calistirilir.
• Esli hesabi olmayan booster'lara DM ile hesabini eslemesi gerektigi bildirilir; hesabini esledigi anda odul otomatik olarak verilir.
• Her kullaniciya sezon basina yalnizca bir kez odul verilir.
• Boost kaldirildiginda boost.remove-commands altindaki komutlar calistirilarak oduller geri alinir.
• /boostreset komutuyla tum odul kayitlari sifirlanarak yeni bir sezon baslatilabilir.
• /boosttest komutuyla gercek boost gerektirmeden oduller test edilebilir.

Veritabani Yapisi

Eklenti SQLite kullanir (WAL modu etkin) ve plugins/ArceniaHesapEsle/data.db dosyasinda asagidaki tablolar olusturulur:

Performans icin pending_codes.player_uuid, linked_accounts.minecraft_uuid ve linked_accounts.discord_id alanlarinda indeksler olusturulur. Bagli hesaplar baslangicta in-memory cache'e yuklenir ve sorgular oncelikli olarak cache uzerinden yapilir.

Suresi dolmus dogrulama kodlari her 5 dakikada otomatik olarak temizlenir.

ArceniaHesapEsle/
├── pom.xml                                          # Maven yapilandirmasi
├── src/main/
│   ├── java/dev/arcenia/link/
│   │   ├── ArceniaLink.java                         # Ana eklenti sinifi (yasam dongusu, zamanlayicilar)
│   │   ├── commands/
│   │   │   ├── HesapEsleCommand.java                # /hesapesle (kod olusturma, reload, bilgi, cooldown)
│   │   │   ├── HesapKontrolCommand.java             # /hesapkontrol (admin - esleme durumu sorgulama)
│   │   │   ├── HesapSilCommand.java                 # /hesapsil (admin - onay adimli esleme kaldirma)
│   │   │   ├── HesapSyncCommand.java                # /hesapsync (admin - manuel rol sync)
│   │   │   ├── BoostResetCommand.java               # /boostreset (boost kayitlarini sifirla)
│   │   │   ├── BoostTestCommand.java                # /boosttest (boost odullerini test et)
│   │   │   └── CommandTabCompleter.java             # Tum komutlar icin tab tamamlama
│   │   ├── database/
│   │   │   └── DatabaseManager.java                 # SQLite yonetimi (thread-safe, cache, CRUD)
│   │   ├── discord/
│   │   │   ├── DiscordBot.java                      # JDA bot yonetimi (multi-guild, toplu rol, async)
│   │   │   ├── LinkListener.java                    # Discord mesaj dinleyici (kod dogrulama ve esleme)
│   │   │   ├── SlashCommandListener.java            # Discord slash komut dinleyici (/oyuncu, /hesap)
│   │   │   └── BoostListener.java                   # Discord boost olaylari dinleyici
│   │   ├── hooks/
│   │   │   └── PlaceholderAPIHook.java              # PlaceholderAPI entegrasyonu
│   │   ├── listeners/
│   │   │   └── PlayerJoinListener.java              # Minecraft giris olayi (otomatik rol sync)
│   │   └── managers/
│   │       ├── ConfigManager.java                   # Yapilandirma dosyasi yonetimi ve mesaj isleme
│   │       ├── RoleSyncManager.java                 # Permission-rol senkronizasyon mantigi
│   │       ├── RewardManager.java                   # Hesap esleme odul komutlari yonetimi
│   │       └── LogManager.java                      # Discord embed log yonetimi
│   └── resources/
│       ├── plugin.yml                               # Spigot eklenti tanimlayicisi
│       └── config.yml                               # Varsayilan yapilandirma dosyasi
└── target/
    └── ArceniaHesapEsle-1.0.0.jar                  # Derlenmis eklenti dosyasi

SSS (Sıkça Sorulan Sorular)

• Hesabımı nasıl eşleyebilirim? Oyun içinde /hesapesle komutunu kullanarak aldığınız kodu, Discord sunucusundaki belirlenen kanala yazarak eşleme işlemini tamamlayabilirsiniz.
• Eşleme kodu ne kadar süre geçerli? Kodlar yapılandırılabilir bir süre sonunda otomatik olarak geçersiz olur.
• Discord rolüm neden güncellenmiyor? Eklenti, Minecraft izinlerinize (permission) dayalı olarak rolleri otomatik senkronize eder. Senkronizasyon sunucu girişi, eşleme anı veya periyodik zamanlayıcı ile gerçekleşir.
• Discord'da ismim neden değişti? Hesap eşlendiğinde, Discord sunucusundaki kullanıcı adınız otomatik olarak Minecraft oyuncu adınızla güncellenir.
• Discord Nitro Boost ödüllerini nasıl alırım? Sunucuya boost bastığınızda ödüller otomatik tanımlanır. Hesabınız eşli değilse, eşleme yaptığınız anda ödülleriniz hesabınıza tanımlanır.
• Eşleme sonrası ödül alabilir miyim? Evet, hesap eşleme işlemini tamamlayan oyunculara yapılandırılabilir konsol komutları aracılığıyla ödüller verilir.

Eklenti ile ilgili sorun yaşıyorsanız aşağıdaki adımları kontrol edebilirsiniz:

• Java Sürümü: Sunucunuzun Java 21 ile çalıştığından emin olun; eski sürümler eklentinin çalışmamasına neden olur.
• Kod Geçersizliği: /hesapesle komutuyla alınan kodlar yapılandırmada belirlenen süre sonunda zaman aşımına uğrar, yeni bir kod almayı deneyin.
• Rol Senkronizasyonu: Discord rollerinin eklenti tarafından yönetilebilmesi için botun rol hiyerarşisinde ilgili rollerin üzerinde olduğundan emin olun.
• Boost Ödülleri: Nitro Boost ödüllerinin tetiklenmesi için oyuncunun Discord hesabının Minecraft hesabıyla eşli olması şarttır; eşli olmayan booster'lara DM üzerinden bildirim gidip gitmediğini kontrol edin.
• PlaceholderAPI: Eğer yer tutucular çalışmıyorsa, sunucunuzda PlaceholderAPI eklentisinin yüklü ve güncel olduğunu doğrulayın.
• Loglama: Hataları tespit etmek için konsol çıktılarını ve eklenti tarafından oluşturulan embed loglarını inceleyin.