FiveM Sunucusuna Script Nasıl Eklenir? Adım Adım Rehber

FiveM'de script eklemek, bir klasörü sunucuya atıp yeniden başlatmaktan ibaret değildir. Script'ler FiveM'de resource (kaynak) olarak çalışır ve bir resource'un çalışabilmesi için doğru klasörde olması, geçerli bir fxmanifest.lua dosyası bulundurması, bağımlılıklarının kendisinden önce yüklenmesi ve gerekiyorsa veritabanı tablolarının içe aktarılmış olması gerekir. Bu dört şarttan biri eksikse script sessizce çalışmaz ya da konsolu hatalarla doldurur. Bu rehberde ESX ve QBCore için script ekleme sürecini sıfırdan, hata ayıklamasıyla birlikte anlatıyoruz.

FiveM'de "Script" Aslında Nedir?

FiveM'de her şey bir resource'tur: framework'ünüz, haritalar, araç modelleri, envanter sistemi ve indirdiğiniz o iş script'i. Bir resource, içinde en az bir fxmanifest.lua dosyası bulunan klasördür.

Bu dosya sunucuya şunları söyler: hangi oyun için yazıldığı, hangi dosyaların istemcide, hangilerinin sunucuda çalışacağı ve hangi resource'lara bağımlı olduğu. Tipik bir manifest şöyle görünür:

• fx_version 'cerulean' — API sürümü
• game 'gta5' — hedef oyun
• client_scripts { 'client/*.lua' } — istemcide çalışacak dosyalar
• server_scripts { '@oxmysql/lib/MySQL.lua', 'server/*.lua' } — sunucuda çalışacak dosyalar
• shared_scripts { 'config.lua' } — her iki tarafta da yüklenecek dosyalar
• dependencies { 'es_extended', 'ox_lib' } — bağımlılıklar

Bir klasörde fxmanifest.lua yoksa sunucu o klasörü resource olarak görmez; konsola uyarı basar ve devam eder. "Script'i attım ama hiçbir şey olmadı" şikayetlerinin bir kısmının kaynağı budur.

Başlamadan Önce: Doğru Sürümü İndirdiğinizden Emin Olun

Script'i indirdiğinizde ilk kontrol edeceğiniz şey, hangi framework için yazıldığıdır. ESX için yazılmış bir envanter script'i QBCore sunucusunda çalışmaz — çalışsa bile oyuncu verilerini bulamaz. Script sayfasında genellikle şu etiketlerden biri yazar: ESX, QBCore, Qbox veya Standalone. Standalone olanlar framework'ten bağımsızdır ve her sunucuda çalışır.

İkinci kontrol: arşivin içindeki README.md dosyası. Bağımlılıklar burada yazar ve çoğu kişi bu dosyayı okumadan kuruluma başladığı için saatlerini kaybeder.

Adım 1: Klasörü Doğru Yere Koyun

Script klasörünü sunucunuzun resources dizinine yerleştirin. Düzenli bir sunucuda kategori klasörleri kullanılır:

server-data/resources/[scripts]/script-adi/

Köşeli parantezli klasörler ([scripts], [esx], [maps]) FiveM'de kategori anlamına gelir. Bunları tek satırla toplu başlatabilirsiniz: ensure [scripts].

Üç kritik kural:

• Klasör adını değiştirmeyin. Manifest içindeki referanslar ve diğer script'lerin çağrıları bu isme bağlıdır.
• Türkçe karakter ve boşluk kullanmayın. banka sistemi yerine banka-sistemi.
• Büyük/küçük harfe dikkat edin. Linux sunucularda MyScript ile myscript farklı iki şeydir. Windows'ta çalışan bir yapılandırma Linux'ta "Could not find resource" hatası verebilir.

Arşivi açtığınızda içinde tek bir klasör daha çıkıyorsa (örneğin script-adi/script-adi/fxmanifest.lua) iç klasörü dışarı alın. fxmanifest.lua dosyası, resource klasörünün doğrudan içinde olmalıdır.

Adım 2: SQL Dosyasını İçe Aktarın

Script oyuncu verisi saklıyorsa (banka, envanter, ev, araç sistemi) arşivde bir .sql dosyası bulunur. Bu tabloları veritabanınıza aktarmadan script çalışmaz.

phpMyAdmin ile: Veritabanınızı seçin → İçe Aktar sekmesi → dosyayı seçin → Başlat.

Komut satırı ile: mysql -u kullanici -p veritabani < script.sql

Aktarmadan önce veritabanınızın yedeğini alın. Bazı SQL dosyaları DROP TABLE komutu içerir ve mevcut tablolarınızı silebilir — bu, oyuncu verilerinizin tamamen kaybolması demektir.

Adım 3: Veritabanı Bağlantısını Kontrol Edin

FiveM'de veritabanı erişimi oxmysql üzerinden yapılır. Sunucunuzda kuruluysa server.cfg içinde şuna benzer bir satır olmalıdır:

set mysql_connection_string "mysql://kullanici:sifre@localhost:3306/veritabani"

Alternatif olarak DSN biçimi de kullanılabilir:

set mysql_connection_string "user=kullanici;password=sifre;host=localhost;port=3306;database=veritabani"

İki pratik not: şifrenizde ; , / ? : @ & = + $ # karakterleri varsa bağlantı bozulabilir — böyle bir durumda diğer biçimi deneyin veya şifreyi sadeleştirin. Ayrıca oxmysql, kaynak listesinin en üstünde başlatılmalıdır.

Adım 4: server.cfg'ye Doğru SIRAYLA Ekleyin

Bu adım, script eklemenin en çok hata yapılan kısmıdır. FiveM resource'ları server.cfg'deki sırayla yükler ve bir script, bağımlı olduğu resource'tan sonra gelmelidir.

Doğru sıralama şöyledir:

• ensure oxmysql — veritabanı katmanı, her şeyden önce
• ensure ox_lib — yaygın yardımcı kütüphane
• ensure es_extended (ESX) veya ensure qb-core (QBCore) — framework
• ensure [scripts] veya tek tek ensure script-adi — sizin script'leriniz

ensure ile start arasındaki fark şudur: start resource'u yalnızca başlatır, ensure ise zaten çalışıyorsa yeniden başlatır. Sunucu yapılandırmasında her zaman ensure kullanın.

Script'i eklerken tek seferde bir tane ekleyin ve sunucuyu yeniden başlatın. Beş script'i aynı anda eklerseniz hata çıktığında hangisinin sorumlu olduğunu bulmak çok daha zor olur.

Adım 5: Config Dosyasını Sunucunuza Göre Ayarlayın

Çoğu script config.lua veya shared/config.lua dosyasıyla gelir. Burada ayarlamanız gerekenler genellikle şunlardır: framework seçimi ('esx' / 'qb'), dil/locale ayarı, meslek (job) isimleri, koordinatlar ve fiyatlar.

Framework seçimi yanlışsa script sorunsuz başlar ama hiçbir şey yapmaz — çünkü oyuncu verisine erişemez. "Script çalışıyor ama komutlar tepki vermiyor" durumunda ilk bakılacak yer burasıdır.

Adım 6: Test Edin ve Hataları Okuyun

Sunucuyu yeniden başlatın veya konsoldan restart script-adi komutunu çalıştırın. Ardından iki yeri kontrol edin:

• txAdmin konsolu / sunucu konsolu — sunucu tarafı hataları, SQL hataları ve yükleme sırası sorunları burada görünür.
• Oyun içinde F8 konsolu — istemci tarafı Lua hataları burada görünür.

Hata mesajını okumadan tahmin yürütmeyin. FiveM'in hata çıktıları genellikle dosya adını ve satır numarasını verir; sorunun yerini doğrudan söyler.

ESX ve QBCore Arasındaki Pratik Farklar

Kurulum adımları iki framework'te de aynıdır, ancak dikkat etmeniz gereken birkaç fark vardır.

ESX tarafında: Framework resource'unun adı es_extended'dir. Script'ler oyuncu nesnesine ESX.GetPlayerFromId() gibi çağrılarla erişir. ESX'in eski (1.1) ve yeni (Legacy) sürümleri arasında fonksiyon isimleri değiştiği için, indirdiğiniz script'in hangi ESX sürümü için yazıldığına bakın — "ESX Legacy uyumlu" ibaresi yoksa eski sürüm için yazılmış olabilir ve nil value hataları alırsınız.

QBCore tarafında: Framework resource'unun adı qb-core'dur ve çoğu resmi script qb- önekiyle gelir (qb-inventory, qb-banking). QBCore ekosisteminde script'ler birbirine ESX'e göre daha sıkı bağlıdır; bir envanter script'ini değiştirdiğinizde ona bağlı diğer script'lerin de güncellenmesi gerekebilir.

Ortak nokta: Her iki framework de artık ox_lib ve oxmysql ekosistemine yaslanıyor. Yeni script'lerin çoğu bu ikisini bağımlılık olarak istiyor, dolayısıyla sunucunuzda kurulu değillerse ilk iş onları kurmak olmalı.

Framework seçimini henüz yapmadıysanız veya değiştirmeyi düşünüyorsanız, bu kararın neredeyse geri dönüşsüz olduğunu unutmayın: tüm script'leriniz seçtiğiniz framework'e göre yazılır.

Sık Karşılaşılan Hatalar ve Çözümleri

• "Could not find resource script-adi": Klasör adı ile server.cfg'deki isim uyuşmuyor. Linux'ta büyük/küçük harf farkını kontrol edin. Klasörün gerçekten resources altında olduğundan emin olun.
• "attempt to index a nil value (global 'ESX')": Framework, script'ten sonra yükleniyor. ensure es_extended satırını script'inizin üstüne alın.
• "No such export ... in resource oxmysql": oxmysql başlatılmamış ya da script'ten sonra başlatılmış. En üste alın.
• SQL hataları (Unknown column / Table doesn't exist): .sql dosyası içe aktarılmamış veya yanlış veritabanına aktarılmış.
• Script başlıyor ama komutlar çalışmıyor: config.lua içindeki framework ayarı yanlış, ya da yetki (permission) tanımı eksik.
• Sunucu açılışta çöküyor: İlgili ensure satırını geçici olarak yorum satırı yapın (# ile), sunucuyu temiz başlatın ve konsol loglarını okuyun.
• Sunucu takılıyor, TPS düşüyor: Konsolda resmon komutuyla hangi resource'un kaynak yediğini bulun. Genellikle tek bir kötü yazılmış script tüm sunucuyu yavaşlatır.

Script Eklerken Güvenlik: Kaynağına Dikkat Edin

Ücretsiz script sitelerinden indirdiğiniz dosyalar her zaman masum değildir. FiveM ekosisteminde backdoor içeren script'ler yaygın bir sorundur — bu script'ler sunucunuza uzaktan komut çalıştırma, oyunculara para basma veya veritabanınızı dışarı sızdırma yeteneği verebilir.

Kurulumdan önce şunlara bakın: PerformHttpRequest ile bilinmeyen adreslere yapılan istekler, load() veya assert(load(...)) ile çalıştırılan şifrelenmiş kod blokları, anlamsız uzunlukta base64 dizileri. Bunlardan birini görüyorsanız o script'i kurmayın.

Sunucu tarafındaki genel sertleştirme adımları için sunucu güvenliği için ilk 10 adım rehberimize göz atabilirsiniz. Aynı mantığın MTA tarafındaki karşılığını ise MTA sunucusuna script ekleme yazımızda ele almıştık.

Nubitro ile FiveM Sunucusu

Script eklemek kolaydır; onlarca script'i aynı anda akıcı çalıştırmak donanım işidir. FiveM ana döngüsü büyük ölçüde tek çekirdek üzerinde çalıştığı için yüksek saat hızlı işlemci, SQL sorgularının gecikmesiz dönmesi için de NVMe disk gerekir. Nubitro'nun FiveM sunucu paketleri anında kurulum, 200 Tbps+ DDoS koruması ve 7/24 destekle geliyor. Tam kontrol isteyenler AMD Ryzen 9 tabanlı Türkiye lokasyonlu VDS seçeneklerimizi inceleyebilir. Sunucunuzu henüz kurmadıysanız FiveM sunucusu nasıl kurulur rehberimizle başlayın.

Sıkça Sorulan Sorular

Script'i ekledim ama sunucuda görünmüyor, neden?

Üç şeyi sırayla kontrol edin: klasör gerçekten resources altında mı, klasörün içinde doğrudan fxmanifest.lua var mı, ve server.cfg'de ensure satırı doğru yazılmış mı. Bu üçü tamamsa konsolda kırmızı hata satırlarını okuyun.

ESX script'i QBCore sunucusunda çalışır mı?

Hayır. Framework'ler oyuncu verisini, meslek sistemini ve para birimini farklı yapıda tutar. Bazı script'ler her iki framework'ü de destekleyecek şekilde yazılır; bunu config.lua içindeki framework seçeneğinden anlarsınız. Desteklemiyorsa ya köprü (bridge) resource kullanmanız ya da script'i uyarlamanız gerekir.

ensure ile start arasındaki fark ne?

start resource'u başlatır; zaten çalışıyorsa hiçbir şey yapmaz. ensure ise çalışmıyorsa başlatır, çalışıyorsa yeniden başlatır. server.cfg içinde her zaman ensure tercih edin.

Script'i güncellerken ne yapmalıyım?

Önce mevcut klasörün ve veritabanının yedeğini alın. Yeni sürümü açın, kendi config.lua ayarlarınızı yeni dosyaya taşıyın (eski config'i olduğu gibi kopyalamayın, yeni sürümde yeni ayarlar olabilir). Sürüm notlarında SQL değişikliği belirtiliyorsa o dosyayı da içe aktarın.

Kaç script kurabilirim?

Teknik bir üst sınır yok; sınır donanımınız ve script kalitesidir. 100 hafif script, kötü yazılmış 10 script'ten daha az yük yaratabilir. Ölçüt sayı değil, resmon çıktısındaki milisaniye değerleridir.

Script'in güvenli olduğunu nasıl anlarım?

Dosyaları açıp PerformHttpRequest, load(, uzun base64 blokları gibi şüpheli kalıpları arayın. Şifrelenmiş (escrow dışı) kod içeren ücretsiz script'lere güvenmeyin. Mümkünse script'i önce test sunucusunda deneyin.

Özet

• FiveM'de her script bir resource'tur ve geçerli bir fxmanifest.lua dosyası olmadan tanınmaz.
• Klasör adını değiştirmeyin; Linux'ta büyük/küçük harf farkı gerçek bir hata kaynağıdır.
• SQL dosyası varsa içe aktarın — öncesinde mutlaka veritabanı yedeği alın.
• server.cfg sırası kritik: oxmysql → ox_lib → framework → script'leriniz.
• Tek seferde bir script ekleyin; hata ayıklaması kat kat kolaylaşır.
• Hata mesajını tahmin etmeyin, konsoldan ve F8'den okuyun.
• Bilinmeyen kaynaklardan gelen script'leri kurmadan önce backdoor kontrolü yapın.