İlk Siparişe Özel %20 İndirim Kodu:
Oyun Sunucuları

FiveM Script Kurulumu: fxmanifest.lua, oxmysql ve server.cfg Yönetimi

FiveM script kurma adımları, fxmanifest.lua anatomisi, oxmysql veritabanı entegrasyonu, server.cfg ensure sıralaması ve kaynak yönetimi rehberi.

5 dk okuma

İçindekiler

FiveM sunucunuza yeni bir mekanik, araç paketi, meslek veya arayüz eklemek, arşivden çıkan dosyaları sunucu klasörüne kopyalamaktan ibaret değildir. FXServer mimarisinde her bağımsız modül bir kaynak (resource) olarak çalışır. Bir kaynağın sunucu tarafından tanınması, istemcilere doğru aktarılması ve çökme üretmeden yürütülmesi; kaynak bildirim dosyasının (fxmanifest.lua) bütünlüğüne, veritabanı şemasının hazırlanmasına ve server.cfg başlatma sırasına doğrudan bağlıdır.

Bu rehberde modern script anatomisini, fxmanifest.lua parametrelerini, resources dizin organizasyonunu, MariaDB SQL şemalarının aktarılmasını, server.cfg hiyerarşisini ve canlı kaynak yönetimini bulabilirsiniz.

Modern script anatomisi ve fxmanifest.lua yapılandırması

Bir klasörün FiveM tarafından kaynak olarak algılanabilmesi için kök dizininde mutlaka geçerli bir bildirim dosyası bulunmalıdır. Eski sunucu paketlerinden kalan __resource.lua dosyaları güncelliğini yitirmiştir ve modern FXServer sürümlerinde uyarı üretir. Güncel tüm scriptlerde standart bildirim dosyası fxmanifest.lua adını taşır.

Bir fxmanifest.lua dosyasının taşıdığı temel alanlar şunlardır:

  • fx_version: Kaynak API sürümünü belirler. Güncel FXServer altyapılarında standart sürüm 'cerulean' veya 'bodacious' değeridir.
  • game: Hedef oyun motorunu tanımlar. GTA V sunucuları için bu değer daima 'gta5' olmalıdır.
  • lua54: Kaynağın modern Lua 5.4 motoru ile çalıştırılmasını sağlar (lua54 'yes'). Bu satır bulunmadığında FiveM geriye dönük uyumluluk modunda eski Lua motoruna döner; bu da bellek yönetimini ve bazı modern kütüphanelerin çalışmasını olumsuz etkiler.
  • client_scripts, server_scripts, shared_scripts: Hangi kod dosyalarının oyuncunun bilgisayarında (istemci), hangi dosyaların doğrudan sunucuda yürütüleceğini ve hangi yapılandırma dosyalarının iki tarafta ortak paylaşılacağını belirler.

Örnek bir modern fxmanifest.lua dosya yapısı:

fx_version 'cerulean'
game 'gta5'

author 'TREAS Rehber'
description 'Örnek FiveM Araç Teslim Kaynağı'
version '1.0.0'

lua54 'yes'

shared_scripts {
    'config.lua',
    '@oxmysql/lib/MySQL.lua'
}

client_scripts {
    'client/main.lua',
    'client/utils.lua'
}

server_scripts {
    'server/main.lua',
    'server/database.lua'
}

files {
    'html/index.html',
    'html/style.css',
    'html/script.js'
}

ui_page 'html/index.html'

dependency 'oxmysql'

Yukarıdaki yapılandırmada yer alan @oxmysql/lib/MySQL.lua ifadesindeki @ sembolü, başka bir bağımsız kaynağın (oxmysql) dosyasını doğrudan bu kaynağın çalışma alanına dahil etmek için kullanılır. dependency 'oxmysql' satırı ise sunucuya bu script çalışmadan önce oxmysql kaynağının hazır bulunması gerektiğini bildirir.

Sunucu dosya hiyerarşisi ve resources klasörü düzeni

Sunucu dosyalarınızı düzenli tutmak, yüzlerce script arasında aradığınızı bulabilmek ve güncelleme yaparken hata yapmamak adına klasör hiyerarşisi oluşturmanız gerekir. FXServer, köşe parantez ([...]) ile adlandırılmış klasörleri kategori grubu olarak kabul eder.

Önerilen kaynak dizin yapısı:

server-data/
├── server.cfg
└── resources/
    ├── [cfx-default]/
    │   ├── chat/
    │   ├── hardcap/
    │   └── sessionmanager/
    ├── [kutuphaneler]/
    │   ├── oxmysql/
    │   └── ox_lib/
    ├── [framework]/
    │   └── es_extended/
    └── [yerel-scriptler]/
        ├── ozel-garaj/
        │   ├── fxmanifest.lua
        │   ├── config.lua
        │   ├── client/
        │   └── server/
        └── market-sistemi/

Köşeli parantez kullanımının en büyük avantajı, server.cfg dosyasında klasör içindeki her scripti tek tek yazmak yerine, ensure [yerel-scriptler] komutuyla tüm alt klasörleri tek satırda sırayla başlatabilmenizdir. Kategori klasörünün adı köşeli parantez içinde kalmalı, script klasörünün adı ise küçük harf ve tire karakterleriyle düzenlenmelidir.

MariaDB ve SQL veritabanı şemasının aktarılması

Kullanıcı envanteri, araç sahipliği, meslek kayıtları veya para durumunu saklayan scriptler bir veritabanı tablosuna ihtiyaç duyar. İndirdiğiniz script paketinin içinde .sql uzantılı bir kurulum dosyası (install.sql, schema.sql veya script_adi.sql) bulunuyorsa, bu şemanın sunucunun MariaDB veritabanına aktarılması gerekir:

  1. HeidiSQL veya phpMyAdmin gibi bir veritabanı yönetim aracıyla sunucunuzun veritabanına bağlanın.
  2. FiveM sunucunuz için oluşturduğunuz veritabanını seçin.
  3. SQL sorgu sekmesini açarak scriptle gelen .sql dosyasının içeriğini yapıştırın ve sorguyu çalıştırın.

Örnek bir tablo oluşturma sorgusu:

CREATE TABLE IF NOT EXISTS `oyuncu_araclari` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `citizenid` varchar(50) NOT NULL,
  `plaka` varchar(12) NOT NULL,
  `garaj_id` varchar(50) DEFAULT 'merkez',
  `durum` tinyint(1) DEFAULT 1,
  PRIMARY KEY (`id`),
  UNIQUE KEY `plaka` (`plaka`),
  KEY `citizenid` (`citizenid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Veritabanı tablolarında sık sorgulanan sütunlara (örneğin citizenid veya plaka) indeks (KEY) tanımlanması önemlidir. İndekssiz tablolarda oyuncu sayısı arttıkça her veri sorgusu tüm tabloyu baştan sona tarar; bu da disk okuma yükünü artırarak sunucu ana döngüsünde gecikmelere sebep olur.

server.cfg başlatma hiyerarşisi ve oxmysql bağımlılıkları

FiveM sunucusu açılırken server.cfg dosyasını yukarıdan aşağıya doğru satır satır okur. Bu nedenle kaynakların başlatılma sırası çalışabilirlik açısından belirleyicidir. Bir script henüz yüklenmemiş bir framework'e veya veritabanı kütüphanesine erişmeye çalışırsa başlatma anında hata vererek durur.

Doğru başlatma sıralaması şu şekildedir:

  1. Temel Cfx.re bileşenleri (chat, sessionmanager, spawnmanager, hardcap)
  2. Veritabanı arayüzü (oxmysql)
  3. Çekirdek yardımcı kütüphaneler (ox_lib vb.)
  4. Oyun framework'ü (es_extended veya qb-core)
  5. Bağımsız eklentiler, meslekler, araçlar ve yerel scriptler

Örnek bir server.cfg yapılandırma bloğu:

# Temel Cfx.re bilesenleri
ensure chat
ensure spawnmanager
ensure sessionmanager
ensure hardcap

# Veritabani surucusu ve kütüphaneler
ensure oxmysql
ensure ox_lib

# Framework
ensure es_extended

# Diger kaynak gruplari
ensure [kutuphaneler]
ensure [yerel-scriptler]

Kaynak yönetiminde kullanılan başlatma komutları arasındaki farklar:

  • start script_adi: Kaynağı başlatır. Kaynak zaten çalışıyorsa işlem yapmaz veya konsola uyarı bırakır.
  • ensure script_adi: Kaynak çalışmıyorsa başlatır; halihazırda çalışıyorsa yeniden başlatır. Yapılandırma dosyalarında standart olarak ensure tercih edilir.
  • stop script_adi: Çalışan kaynağı tamamen durdurur.

Canlı sunucuda kaynak yönetimi: refresh, ensure ve restart sınırları

Sunucuyu tamamen yeniden başlatmadan yeni bir script eklemek veya kod düzenlemelerini test etmek mümkündür:

  1. Yeni script klasörünü resources dizinine yükledikten sonra sunucu konsoluna veya yetkili oyun içi F8 konsoluna refresh komutunu yazın. Bu işlem resources dizinini baştan tarayarak yeni dosyaları FXServer belleğine kaydeder.
  2. Ardından ensure script_adi komutunu girerek yeni kaynağı başlatın.

Canlı yeniden başlatmanın sınırları bulunmaktadır:

  • Kullanıcı arayüzü (NUI/HTML), harita dosyaları veya basit istemci hesaplamaları içeren scriptler canlı ortamda sorunsuz yeniden başlatılabilir.
  • Ağ olaylarını (RegisterNetEvent) kaydeden, veritabanı bağlantı havuzu oluşturan veya oyuncuların aktif verilerini bellekte tutan temel sistem scriptleri canlıda yeniden başlatıldığında çift olay tetiklenmesi, veri kaybı veya istemci çökmeleri meydana gelebilir. Bu tür çekirdek kaynaklarda yapılan değişikliklerin ardından sunucunun tamamen kapatılıp açılması önerilir.

Sık karşılaşılan script hataları ve teşhis tablosu

FiveM konsolunda karşılaşılan yaygın script hataları ve çözüm yolları aşağıdaki tabloda özetlenmiştir:

Hata MesajıOlası NedenÇözüm Adımı
Failed to load fxmanifest.luaSöz dizimi hatası, eksik parantez/tırnak veya UTF-8 BOM karakter kodlaması.Dosyayı UTF-8 (BOM'suz) formatında kaydedin; Lua söz dizimi kurallarını denetleyin.
Could not find dependency oxmysqloxmysql klasörü resources altında bulunamıyor veya adı değiştirilmiş.Klasör adının doğruluğunu teyit edin ve server.cfg dosyasında ilgili scriptten önce başlatıldığından emin olun.
attempt to index a nil value ('oxmysql')Veritabanı sürücüsü yüklenmeden önce script veritabanı sorgusu yürütmeye çalıştı.Scriptin fxmanifest.lua dosyasına @oxmysql/lib/MySQL.lua satırını ekleyin ve server.cfg sırasını düzeltin.
Table 'veritabani.tablo' doesn't existScriptin ihtiyaç duyduğu .sql şeması veritabanına aktarılmamış.Script klasöründeki SQL dosyasını veritabanı yönetim aracı ile içeri aktarın.
Server thread hitch warning: timer took X msOptimize edilmemiş döngü veya ağır SQL sorguları sunucu ana döngüsünü kilitledi.Döngülere dinamik bekleme süreleri ekleyin ve tablolara indeks verin; gecikme tespiti için /rehber/fivem-sunucu-optimizasyonu-resmon-lag rehberine bakın.

Donanım performansı ve ağ güvenliği

Çok sayıda eklenti barındıran FiveM sunucularında toplam kaynak tüketimi doğrudan altyapı gücüne dayanır. FXServer ana oyun döngüsünü tek bir işlem parçacığında yürüttüğü için, karmaşık script döngülerinin sunucuyu kilitlemesini engellemede yüksek tek çekirdek frekansı belirleyicidir. TREAS, FiveM projeleri için ayrılmış vCore kaynaklı sanal sunucular sağlar. Özellikle /sunucular/ekstrem VDS paketlerinde yer alan AMD Ryzen 9 9950X işlemcilerin 5.9 GHz saat hızı, yoğun script yüklerinde işlemci darboğazı oluşmasını önlemeye yardımcı olur.

Scriptlerin veritabanı okuma ve yazma işlemlerinde diske binen yükü hafifletmek adına sistemlerde Samsung 990 Pro Gen4 NVMe depolama birimleri kullanılır. Olası yapılandırma hatalarına veya dosya bozulmalarına karşı her VPS ve VDS'te 1 adet ücretsiz snapshot hakkı sunulur; böylece kapsamlı script yüklemelerinden önce anlık durum kaydı alabilirsiniz.

Ağ tarafında ise Mars İstanbul Veri Merkezi altyapısında sunucu bağlantılarında 10 Gbps port hızı sağlanırken, /ddos-koruma katmanında 12 Tbps DDoS koruma kapasiteli TRSHIELD altyapısı aktiftir. TRSHIELD bünyesinde FiveM için udp/30120 bağlantı doğrulaması ve tcp/30120 SYN koruması profili bulunur. Bu profil sahte paket taşkınlarını süzerken, TRSHIELD'ın FiveM profili sunucunun FiveM sunucu listesinde görünmesine engel olmaz ve ek izin listesi ayarı gerektirmez. FiveM altyapınıza uygun sanal sunucu seçeneklerini /oyun-sunucusu sayfasından inceleyebilirsiniz.

Sık sorulan sorular

Bir scriptin fxmanifest.lua dosyasında lua54 'yes' tanımı neden önemlidir?

FiveM varsayılan olarak geriye dönük uyumluluk için eski Lua çalışma ortamını kullanabilir. lua54 'yes' direktifi, scriptin modern Lua 5.4 motoruyla derlenmesini sağlayarak bellek yönetimini iyileştirir ve yeni kütüphanelerle uyumsuzluk yaşanmasını önler.

resources klasöründeki köşeli parantezli dizinlerin işlevi nedir?

[arabalar] veya [meslekler] gibi köşeli parantez içeren klasörler FXServer tarafından kategori olarak algılanır. Bu klasörler tek bir ensure komutuyla topluca başlatılabilir ve dosya hiyerarşisinin düzenli kalmasını sağlar.

oxmysql bağımlılığı olan bir script neden veritabanı hatası verir?

Script, server.cfg dosyasında oxmysql kaynağından önce başlatılmışsa veya scriptin ihtiyaç duyduğu .sql tablosu MariaDB veritabanına aktarılmamışsa sunucu konsolunda nil index veya tablo bulunamadı hatası oluşur.

Canlı FiveM sunucusunda çalışan her script refresh ve ensure ile güncellenebilir mi?

Hayır. Yalnızca istemci arayüzü veya basit mantık içeren scriptler canlıda yeniden başlatılabilir. Ağ olayları kaydeden, temel veritabanı bağlantı havuzunu yöneten veya global durum tutan ağır kaynaklar sunucunun tamamen yeniden başlatılmasını gerektirir.

Yeni sistem yönetimi ve ağ rehberlerimizi arama sonuçlarında öncelikli görmek için:Google'da tercih edilen kaynaklara ekle (dış bağlantı)