Minecraft Plugin Paketi Nasıl Kurulur? A'dan Z'ye Kurulum Rehberi

Bir Minecraft sunucusunu sıfırdan açan herkesin karşılaştığı ilk ciddi görev plugin paketini doğru şekilde yükleyip çalıştırmaktır. İnternette bulduğunuz rehberlerin çoğu ya 2014''te yazılmış eski Bukkit dönemine ait ya da versiyon bilgisi atlanmış YouTube videoları. Bu sayfa; 2026 itibarıyla Paper 1.20.x ve üstü sunucularda plugin paketinin nasıl kurulacağını, bağımlılıkların nasıl yönetileceğini, config ve permissions kısımlarının nasıl hazırlanacağını, sık karşılaşılan hataların nasıl çözüleceğini baştan sona anlatır.

Rehberi okumadan önce tek şeyden emin olmalısınız: elinizdeki plugin paketi sizin Minecraft sürümünüzle uyumlu olmalı. 1.8 için yapılmış bir paketin 1.20''de çalışma ihtimali neredeyse sıfırdır. Tersi de geçerli — 1.20 için yazılmış modern kütüphaneler 1.8 sunucuda NoClassDefFoundError hatası verir. Sürüm uyumu kontrol edilmeden yapılan kurulumun %90''ı başarısız olur.

# Spigot, Paper, Bukkit ve Folia Arasındaki Fark

Plugin paketinizi yüklemeden önce sunucu çekirdeğinizin ne olduğunu bilmelisiniz. Çünkü paket, belirli bir çekirdek için derlenmiş olabilir. Çekirdeği yanlış seçmek, pluginlerin %30''unun çalışmamasına ve fark edilmeyen performans kayıplarına neden olur.

# Bukkit

Bukkit, 2011''de çıkmış orijinal plugin API''sidir. Günümüzde artık bakımı yapılmıyor ve modern plugin''lerin büyük kısmı Bukkit sunucuda çalışmaz. Bir sunucu rehberinde hâlâ craftbukkit.jar görüyorsanız o rehber güncel değildir. Bukkit üzerinde plugin paketi kurmak bugün mantıksızdır.

# Spigot

Spigot, Bukkit''in çatallanarak geliştirilmiş halidir. 2012''den beri aktif ve pek çok ücretsiz plugin hâlâ Spigot için yazılıyor. Ancak performans açısından Paper''ın çok gerisinde kaldı. Küçük bir Survival sunucusu için çalışır ama 30+ oyunculu sunucularda TPS sorunları kaçınılmaz.

# Paper

Paper, 2026''da sunucu sahiplerinin %80''inin kullandığı fiilî standarttır. Spigot uyumlu olduğu için Spigot pluginleri de çalışır ama Paper, chunk yükleme, entity tick ve async IO konularında çok daha verimlidir. Paper üzerinde paper.yml, spigot.yml ve bukkit.yml olmak üzere üç yapılandırma katmanı vardır. Bir plugin paketi satın aldığınızda ilk tercihiniz Paper olmalı.

# Folia

Folia, Paper''ın 1.20''de tanıtılan multi-threaded sürümüdür. Her bir chunk''ı ayrı thread''de işler, bu yüzden 500+ oyunculu sunucularda inanılmaz performans farkı yaratır. Ancak bir plugin''in Folia uyumlu olması için özel olarak yeniden yazılmış olması gerekir. Normal Paper pluginleri Folia''da çalışmaz. Plugin paketinin Folia etiketi yoksa Folia''ya kurulum denemeyin — sunucu açılmaz.

# Plugin Paketinin İçeriği Neye Benzer?

Minecraft plugin paketi, bir .zip veya .rar arşividir. Açıldığında içinde tipik olarak şunlar bulunur: plugins klasörü (jar dosyaları), world klasörü (map kullanılıyorsa), config ön ayarları, server.properties hazır ayarları ve opsiyonel olarak bir KURULUM.txt dosyası. Profesyonel paketlerde kurulum talimatı ve bağımlılık listesi ayrı bir dokümanda belirtilir.

Kurulum öncesi arşivi açıp içeriğine göz gezdirin. Eğer sadece jar dosyaları varsa — ki bu en yaygın durumdur — config ayarlarını sıfırdan yapacaksınız demektir. Eğer tam bir klasör yapısı varsa (plugins/, world/, server.properties), tüm dosyaları sunucunuzun kök dizinine kopyalamanız yeterlidir.

# Adım 1: Sunucunuzu Durdurun

Sunucu çalışırken plugin eklemek her zaman risklidir. Birçok plugin, yüklenme anında diğer pluginlerin API''sini sorar; runtime''da eklendiğinde bağımlılık zinciri kurulmaz ve plugin ya çalışmaz ya da sunucu çökmesine neden olur. Kurulum yapmadan önce sunucuyu mutlaka durdurun.

Panel kullanıyorsanız (Pterodactyl, Plesk, aaPanel) sunucuyu arayüzden Stop düğmesiyle kapatın. Ctrl+C veya sunucuyu zorla öldürmek, chunk corruption''a yol açar — sonra saatlerce world onarmaya çalışırsınız.

# Adım 2: Plugins Klasörünü Bulun

Sunucu ilk defa çalıştırıldığında otomatik olarak plugins/ adında bir klasör oluşturur. Eğer bu klasör yoksa, sunucuyu en az bir kez çalıştırmanız gerekir. Sunucu çalışmıyorsa bile elle oluşturabilirsiniz; Minecraft sunucu çekirdeği klasörü bulunca içindeki jar dosyalarını tarayacaktır.

Klasör yapısı standart bir Paper sunucusunda şöyledir:

sunucu/
├── paper-1.20.4-XXX.jar     # Sunucu çekirdeği
├── server.properties          # Temel ayarlar
├── eula.txt                   # Lisans kabulü
├── world/                     # Ana dünya
├── world_nether/              # Nether boyutu
├── world_the_end/             # End boyutu
├── logs/                      # Log dosyaları
├── cache/                     # Mojang cache
├── plugins/                   # ← BURASI
│   ├── PluginAdi.jar
│   ├── BirBaskaPlugin.jar
│   └── PluginAdi/             # Plugin config klasörü (ilk çalıştırmada oluşur)
│       ├── config.yml
│       └── messages.yml
├── paper.yml                  # Paper ayarları
├── spigot.yml                 # Spigot ayarları
└── bukkit.yml                 # Bukkit ayarları

# Adım 3: Jar Dosyalarını Plugins Klasörüne Kopyalayın

Plugin paketinin içindeki tüm .jar uzantılı dosyaları, sunucunuzun plugins/ klasörüne kopyalayın. Alt klasörler (örneğin plugins/EssentialsX/) varsa onları da birlikte kopyalamanız gerekir — bunlar genelde plugin''in ön yapılandırılmış config dosyalarını içerir.

SSH ile VPS''e erişiminiz varsa scp veya rsync kullanmak en hızlı yöntemdir:

# Yerel bilgisayardan VPS''e plugin yükleme
scp -P 22 plugin-paketi.zip root@sunucu-ip:/home/minecraft/sunucu/

# Sunucuda açma
ssh root@sunucu-ip
cd /home/minecraft/sunucu
unzip plugin-paketi.zip -d plugins/

# Dosya izinlerini düzeltme
chown -R minecraft:minecraft plugins/
chmod -R 755 plugins/

Pterodactyl panel kullanıyorsanız File Manager üzerinden Upload butonuna tıklayın, jar dosyalarını plugins klasörüne sürükleyin. Aaron gibi paneller için arayüz benzerdir. FTP (FileZilla) kullanıyorsanız üst klasöre geçip plugins/ içine sürükleyip bırakın.

# Adım 4: Bağımlılıkları Yükleyin

Bir plugin paketini kurmanın en kritik adımı bağımlılık yönetimidir. Modern Minecraft pluginlerinin %70''i başka pluginlere bağımlıdır. Bu bağımlılıklar yüklenmezse plugin ya hiç çalışmaz ya da kritik özellikleri eksik çalışır. En yaygın bağımlılıklar:

Profesyonel plugin paketleri bağımlılıkları KURULUM.txt veya README.md dosyasında listeler. Paketin içinde bu dosya yoksa, her plugin''in plugin.yml dosyasını açarak depend: ve softdepend: satırlarını kontrol edin. depend zorunludur; yoksa plugin çalışmaz. softdepend opsiyoneldir; yoksa bazı özellikler çalışmaz ama plugin yine yüklenir.

# Adım 5: Sunucuyu Başlatın

Tüm pluginler ve bağımlılıklar yerine koyulduktan sonra sunucuyu başlatın. İlk başlatma, her plugin için config dosyalarının oluşturulmasına izin verir. Bu aşamada log''u dikkatle izleyin.

# VPS üzerinde doğrudan başlatma
java -Xms2G -Xmx4G -jar paper-1.20.4-XXX.jar nogui

# Veya Aikar''s flags ile (önerilen)
java -Xms4G -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true \
  -jar paper-1.20.4-XXX.jar nogui

Log akışında şu satırlara dikkat edin: [INFO] Loading PluginAdi v1.0.0 → plugin yüklendi. [ERROR] Could not load plugin → plugin yüklenemedi. Could not find dependency → bağımlılık eksik. Tüm ERROR satırlarını not alın; ilerleyen bölümde çözüm rehberi var.

# Adım 6: Config Dosyalarını Ayarlayın

İlk başlatma sonrası sunucu otomatik olarak her plugin için plugins/PluginAdi/config.yml oluşturur. Sunucuyu tekrar durdurup bu dosyaları teker teker açıp ihtiyacınıza göre düzenlemeniz gerekir. Varsayılan ayarlar sizin sunucu profilinize uymaz — ya çok gevşek ya çok sıkı olur.

Plugin paketlerinde çoğunlukla ön ayarlı config dosyaları gelir. Bu durumda kendi elinizle bir şey yapmanıza gerek yoktur; pakette zaten plugins/PluginAdi/config.yml hazır biçimde bulunur. Sunucu çalışınca bu var olan config''i üzerine yazmaz.

# Sık karşılaşılan config hataları

• YAML girintisi bozuk: YAML tab karakteri kabul etmez, yalnızca boşluk. Tek bir tab sunucuyu plugin''siz başlatır.
• UTF-8 BOM: Windows Notepad gibi editörler dosyanın başına BOM ekler; Linux sunucu bu karakteri tanımaz. VSCode veya Notepad++ kullanın.
• Apostrof/tırnak eksik: Türkçe karakter içeren mesajlarda message: 'Merhaba!' şeklinde tek tırnak içinde yazın. Çift tırnakta escape sorunları çıkar.
• Çakışan port/ID: Iki plugin aynı MySQL veritabanına aynı isimle tablo açmak isteyince çakışma çıkar. Her plugin''e ayrı table_prefix verin.

# Adım 7: Permissions Sistemi Kurun (LuckPerms)

Plugin''ler komutlar içerir. Bu komutların kimler tarafından kullanılabileceğini belirleyen sistem permissions''dır. Eski Bukkit günlerinde PermissionsEx vardı ama artık LuckPerms fiilî standarttır. Paketiniz içinde LuckPerms varsa sadece aşağıdaki komutlarla grup ve yetki kurgulamanız yeterli.

LuckPerms''in web editörü vardır: /lp editor yazıp çıkan linke tıklarsanız tarayıcıda tüm yetkileri sürükle-bırak ile düzenleyebilirsiniz. Değişiklikleri save ettikten sonra konsolda verdiği kodu yapıştırmanız yeterli.

# Adım 8: Veritabanı Bağlantısı (Varsa)

Büyük plugin paketleri verileri MySQL veya MariaDB veritabanında tutar. Bu yaklaşım dosya bazlı saklamaktan çok daha hızlı ve çoklu sunucu (proxy ağı) kullanımında zorunludur. Paketinizde veritabanı kullanan plugin varsa önce bir MySQL/MariaDB kurmanız gerekir.

# Ubuntu/Debian üzerinde MariaDB kurulumu
apt update && apt install -y mariadb-server
mysql_secure_installation

# Veritabanı ve kullanıcı oluşturma
mysql -u root -p

CREATE DATABASE mcserver CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mcuser'@'localhost' IDENTIFIED BY 'guclu-sifre-buraya';
GRANT ALL PRIVILEGES ON mcserver.* TO 'mcuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Plugin config dosyalarında MySQL bağlantısı genellikle şöyle tanımlanır:

database:
  enabled: true
  host: 127.0.0.1
  port: 3306
  name: mcserver
  username: mcuser
  password: 'guclu-sifre-buraya'
  table-prefix: 'plg_'
  useSSL: false

# Adım 9: Test ve Doğrulama

Sunucu başladı, loglar temiz, plugin config''ler hazır. Şimdi bir test oyuncusu olarak sunucuya girip her plugin''in kritik komutlarını test edin. Hepsi çalışmasa bile pek çoğunun çalışmadığını görürseniz bağımlılık veya permission sorunu vardır.

Eğer /plugins listesinde bir plugin kırmızı görünüyorsa, logs/latest.log dosyasını açıp o plugin''in yükleme anında verdiği hatayı okuyun. %95 ihtimalle ya bağımlılık eksik ya da sürüm uyumsuzluğu var.

# En Sık Yapılan 10 Kurulum Hatası

# 1. Yanlış Minecraft Sürümü

Plugin paketi 1.8 için yazılmış ama sunucunuz 1.20''de çalışıyor. Bu durumda pluginler ya yüklenmez ya da garip hatalar verir. Paketin desteklediği sürüm aralığını mutlaka satın almadan önce sorun.

# 2. Bağımlılık Eksik

EssentialsX yükledin ama Vault yok. Sonuç: ekonomi komutları çalışmaz. Log''da [ERROR] Could not find dependency: Vault yazar. Vault''u yükle, sunucuyu restart et.

# 3. Java Sürümü Uyumsuz

1.17+ Paper sunucusu Java 17 ister. 1.20.5+ artık Java 21 ister. Eski Java sürümünde açmak istersen UnsupportedClassVersionError alırsın. java -version ile kontrol et, gerekirse JDK 21 kur.

# 4. Plugins Klasörü Yanlış Yerde

Klasörü sunucu kök dizini yerine world/plugins gibi yanlış bir yere koymak. Pluginler yüklenmez. Klasör mutlaka sunucu jar''ıyla aynı dizinde olmalı.

# 5. Jar Dosyası Bozuk

İndirme sırasında dosya kırılmış ya da zip açma sırasında hata olmuş. Sunucu Invalid plugin file der. Paketi yeniden indir, MD5 sağlaması yap.

# 6. İki Plugin Çakışıyor

Aynı komutu veya event''i dinleyen iki plugin birbirine müdahale eder. Örnek: EssentialsX ve CMI aynı /home komutunu sağlar. İkisini birden çalıştıramazsın; birini seçmelisin.

# 7. Port Çakışması

Dynmap gibi kendi web sunucusunu açan pluginler 8123 portunu kullanır. Başka bir servis o portu tutuyorsa Dynmap çökertir. Config''ten portu değiştir.

# 8. Yetki Çakışması

Permission plugin''i pluginlerin izin node''larını tanımıyor. Oyuncular tüm komutlara no permission yanıtı alıyor. LuckPerms''i başa kurulan bağımlılıklardan biri olarak konumlandırın.

# 9. Eski Config Dosyası

Plugin''i güncelleyince eski config.yml yeni alanları içermiyor. Plugin default değerleri kullanır, bazen de çöker. Güncelleme öncesi config''i yedekleyin, yeni sürümün config''ini referans alarak elle güncelleyin.

# 10. Disk Alanı Yetmiyor

Özellikle ucuz VPS''lerde 20 GB disk hızla dolar. Loglar, world backup''ları, plugin cache''leri disk alır. df -h ile kontrol edin, dolu olan klasörleri du -sh * ile bulup temizleyin.

# Performansı İzleme

Kurulum sonrası sunucunun performansını izlemek, plugin paketinin sunucuya ağır gelip gelmediğini anlamanın tek yoludur. Spark profiler bu iş için standarttır.

TPS 20''nin altındaysa plugin paketiniz sunucunuza ağır geliyordur. Ya RAM/CPU artırmanız ya da hafif bir pakete geçmeniz gerekir. Spark, hangi plugin''in ne kadar tick süresi tükettiğini gösterir; bu bilgiyle doğru optimizasyonu yapabilirsiniz.

# Hazır Plugin Paketi mi, Sıfırdan mı?

Bu rehberi okumak size kurulum sürecinin ne kadar karmaşık olduğunu göstermiş olmalı. Küçük bir sunucu için 15-20 plugin, orta ölçekli bir sunucu için 40-60 plugin, rekabetçi bir sunucu için 80-120 plugin gerekir. Her birini tek tek yükleyip birbiriyle uyumlu hale getirmek, bir junior sunucu sahibinin ortalama 2-3 haftasını alır. Profesyonel olarak hazırlanmış bir plugin paketi aynı süreyi 2-3 saate indirir.

# Plugin Yükleme Sırasının Önemi

Paper, sunucu başlangıcında plugin''leri yüklemek için belirli bir sıra izler. Bu sıra plugin.yml''deki load, depend ve softdepend alanlarına göre belirlenir. Yüklemede sorunu en sık görülen nedeni, bir plugin''in ihtiyacı olan başka bir plugin henüz yüklenmemiş olmasıdır.

Yükleme kategorisi üç türdür:

• STARTUP: Plugin sunucu başlangıcında yüklenir (varsayılan)
• POSTWORLD: Plugin dünyalar yüklendikten sonra yüklenir; WorldGuard, WorldEdit gibi dünya verisi gerektiren plugin''ler bu modu kullanır
• startup: Özel senaryolar için; ProtocolLib gibi API seviyesinde başlatılanlar

Örnek bir plugin.yml''de karşılaşacağınız yapı:

name: ChestShop
version: 3.12.2
main: com.Acrobot.ChestShop.ChestShop
author: Acrobot
api-version: 1.13
load: POSTWORLD
depend: [Vault]
softdepend: [PlaceholderAPI, WorldGuard, Towny]

commands:
  chestshop:
    description: ChestShop admin komutları
    aliases: [cs, shopadmin]

Bu dosyayı okumak size birçok şey anlatır: ChestShop''un çalışması için Vault şarttır (depend), PlaceholderAPI/WorldGuard/Towny varsa ek özellikler açılır (softdepend), dünya yüklendikten sonra başlatılır (load: POSTWORLD). Bir plugin Could not load hatası verirse mutlaka plugin.yml''ini açıp bu alanları kontrol edin.

# Plugin İsimlendirme ve Klasör Organizasyonu

Büyük plugin paketlerinde plugins/ klasörü 60-100 jar''la dolu olabilir. Bu kaosta doğru plugini bulmak saatler alır. Profesyonel paket yöneticileri şu organizasyon sistemini kullanır:

• Jar adlarını kısa tutun: EssentialsX-2.20.1.jar yerine EssentialsX.jar (sürüm numarası yüklü, her update''te ismi değiştirmek gereksiz)
• plugins/disabled/ klasörü açın; geçici olarak devre dışı bırakmak istediğiniz jar''ları buraya taşıyın (Paper bunu taramaz)
• plugins/backup/ altında önceki sürümlerini saklayın
• Her güncelleme öncesi çift yedek alın: paketin tam hali ve plugins/ klasörü

# En İyi 5 Güncellik Kontrol Aracı

• PluginUpdater: Sunucu başlarken pluginlerin yeni sürümünü otomatik kontrol eder ve plugins/update/ klasörüne indirir
• AutoUpdater: Spigot''tan yeni sürüm varsa bildirim gönderir
• UpdateChecker: Kritik CVE açıkları için mail/webhook uyarısı
• McSpark: Performans metriklerini Discord''a otomatik post eder
• Prometheus exporter: TPS, MSPT, oyuncu sayısı — Grafana''ya bağlanır

# Sık Sorulan Sorular

# Plugin paketini kurdum ama /plugins listesinde bazıları gri renkte, neden?

Gri renk disabled (devre dışı) demektir. Plugin yüklendi ama config''indeki enabled: false ayarıyla veya başka bir plugin tarafından devre dışı bırakıldı. Config dosyasını açıp enabled alanını true yapın ve sunucuyu restart edin.

# Plugin güncelleme için /reload komutunu kullanmam zararlı mı?

Evet, zararlıdır. /reload komutu plugin''lerin onDisable metodunu doğru çağıramaz; event listener''lar hafızada kalır, scheduler task''ları duplicate olur, memory leak oluşur. Paper geliştiricileri bu komutu kullanmayın diyor. Her zaman tam restart yapın.

# İki plugin aynı isimde ama farklı sürümlerde, ikisini de yüklediğimde ne olur?

Paper ikisinden birini yükleyemez ve Ambiguous plugin name hatası verir. İkisinden birini plugins klasöründen çıkarın veya adını değiştirin. Çakışma durumunda daha yeni sürümü tercih edin.

# Plugin paketini başka bir sunucuya kopyalayınca lisans bozuluyor mu?

Profesyonel paketlerin çoğu lisansı sunucu IP''sine bağlı değil, KEYDAL ID''sine bağlıdır. Yani aynı lisansla farklı sunucularda çalıştırabilirsiniz ama tek anda tek sunucuda aktif olur. Kesin durum satıcıya sorulmalı; lisansı aktarmak için genelde satıcı onayı gerekir.

# Özet

Plugin paketi kurulumu dokuz adımda tamamlanır: sunucuyu durdur → plugins klasörünü bul → jar''ları kopyala → bağımlılıkları yükle → sunucuyu başlat → config''leri düzenle → permissions sistemi kur → veritabanı bağla → test et. Her adımda logları takip et, hata varsa çözmeden bir sonraki adıma geçme. Ön ayarlı bir pakete sahipsen bu adımların çoğu otomatik tamamlanır; sadece lisans bilgisi ve veritabanı bağlantısı için config''i açman yeter. Plugin.yml''i okumayı öğrenmek, plugin organizasyonunu doğru kurmak ve otomatik güncelleme araçlarını kullanmak uzun vadede zaman kazandırır. Sorun yaşarsanız iletişim formundan yazın; kurulum desteği Discord üzerinden anında sağlanır.