قیمت‌های جلفا همیشه به‌روز می‌شوند تا با اطمینان خاطر خرید کنید.
فناوری · FiveM

اسکریپت FiveM (فایوم) چیست؟

اسکریپت FiveM (فایوم) چیست و چگونه ساخته می‌شود؟ از Lua و fxmanifest.lua تا NUI، OneSync، FXServer، IPL و Frameworkهای ESX و QBCore با مثال عملی یاد بگیرید.

ویرایش کد Lua در Visual Studio Code در کنار لوگوی FiveM
راهنمای جامع جلفا برای دنیای FiveM
Lua و fxmanifest.luaNUI و Developer ModeOneSync و Game BuildStandalone و Customized
فهرست مطالب ۱۷ بخش

اسکریپت FiveM چیست و از کجا شروع کنیم؟

در FiveM هر قابلیت تازه—از شغل و گاراژ گرفته تا HUD و بانک—با Resource ساخته می‌شود. Lua منطق بازی را می‌نویسد، NUI رابط آن را نشان می‌دهد و FXServer با OneSync دنیای چندنفره را مدیریت می‌کند.

اسکریپت فقط یک فایل Lua نیست؛ می‌تواند مجموعه‌ای از فایل‌های Lua، JavaScript، C#، رابط وب و دیتابیس باشد. معمولاً برای کارهای حساس مانند پول و مالکیت خودرو، منطق در سرور اجرا می‌شود؛ برای تعامل، تصویر و دوربین از Client استفاده می‌شود.

نمودار معماری Lua، NUI، FXServer و OneSync
در بسیاری از Resourceها، UI در NUI، تعامل در Client و اعتبارسنجی و داده در Server قرار دارد.
Lua

منطق اسکریپت، رویدادها و Nativeها

NUI

رابط کاربری با HTML، CSS و JavaScript

OneSync

هماهنگ‌سازی بازیکن و Entityها

برنامه‌نویسی Lua در FiveM

Lua زبانی سبک و قابل یادگیری است. برای اسکریپت‌نویسی FiveM از تابع‌ها، tableها، eventها و Nativeها استفاده می‌کنید. در نسخه‌های جدید، Lua 5.4 مبنای اجراست؛ گزینه قدیمی lua54 'yes' از ژوئن ۲۰۲۵ دیگر لازم نیست. FiveM از JavaScript و C# هم پشتیبانی می‌کند. مستندات Lua ↗ Lua 5.4 ↗

مثال اول: فرمان ساده روی کلاینت

client.lua
RegisterCommand('hello', function()
    print('Hello from FiveM Client!')
end, false)

اگر این فایل را به‌عنوان client_script معرفی کنید، فرمان روی کلاینت اجرا می‌شود و پیام را در F8 می‌بینید.

مثال دوم: پیام به بازیکن از سمت سرور

server.lua
RegisterCommand('welcome', function(source)
    if source == 0 then
        print('This command is for players.')
        return
    end
    TriggerClientEvent('chat:addMessage', source, {
        args = {'SERVER', 'Welcome to our FiveM server!'}
    })
end, false)

در این مثال منطق فرمان روی سرور است. برای نمایش پیام از Resource رایج chat استفاده شده؛ در سروری که chat ندارد باید پیام با NUI یا سیستم اعلان همان سرور نمایش داده شود.

قاعده امنیتی: اطلاعاتی مانند مقدار پول، سطح دسترسی یا قیمت خرید را از Client بدون بررسی نپذیرید. Client می‌تواند درخواست بدهد، اما تصمیم نهایی با Server است.

ساختار Resource و فایل fxmanifest.lua

هر Resource معمولاً یک پوشه زیر resources است. فایل fxmanifest.lua به FXServer اعلام می‌کند فایل‌های این قابلیت کجا هستند، در کدام سمت اجرا شوند و چه وابستگی‌هایی دارند. نام قدیمی این فایل __resource.lua بود که برای توسعه جدید توصیه نمی‌شود.

پوشه‌بندی نمونه
resources/
└── [local]/
    └── my_resource/
        ├── fxmanifest.lua
        ├── config.lua
        ├── client/
        │   └── main.lua
        ├── server/
        │   └── main.lua
        └── html/
            └── index.html
fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

author 'Example Developer'
description 'My FiveM resource'
version '1.0.0'

shared_script 'config.lua'
client_script 'client/main.lua'
server_script 'server/main.lua'

انواع fx_version؛ آیا باید همیشه جدیدترین را بگذاریم؟

fx_version نسخه استاندارد و رفتار Manifest است، نه شماره GTA V، Server Artifact یا زبان Lua. در مستندات فعلی سه نام FXv2 ثبت شده است:

نامزمان معرفیتفاوتکاربرد امروز
adamantدسامبر ۲۰۱۹پایه قدیمی‌تر FXv2؛ تعریف game الزامی شد.عمدتاً نگهداری کد قدیمی
bodaciousفوریه ۲۰۲۰تغییراتی در سازگاری scheduler مربوط به C# و محیط JSسازگاری Legacy
ceruleanمه ۲۰۲۰اجرای NUI در Secure Context و استفاده از HTTPS برای callbackهاتوصیه برای Resource جدید
انتخاب استاندارد برای FiveM
fx_version 'cerulean'
game 'gta5'

نام‌هایی مانند adamant و bodacious به تاریخ سازگاری مربوط می‌شوند؛ نصب Artifact جدید به‌تنهایی دلیل تغییر عجولانه Manifest یک اسکریپت قدیمی نیست. مستندات نسخه‌ها: Resource Manifest ↗

یک فایل یا چند فایل؟ server_script و server_scripts

برای یک فایل از دستور مفرد و برای چند فایل از شکل جمع استفاده کنید. از نظر عملکرد هر دو معتبرند و مفرد را نیز می‌توان چند بار نوشت.

نمونه‌ها را به‌عنوان الگو ببینید؛ در یک manifest فایل‌ها را تکراری معرفی نکنید
-- One file
server_script 'server/main.lua'

-- Multiple files (recommended style)
server_scripts {
    'server/database.lua',
    'server/main.lua',
    'server/commands.lua'
}

-- You can also repeat singular directives
client_script 'client/main.lua'
client_script 'client/hud.lua'

-- Shared by server and client
shared_scripts {
    'shared/config.lua',
    'shared/constants.lua'
}
ترتیب مهم است: اگر main.lua به متغیری که در database.lua مقداردهی شده نیاز دارد، فایل وابسته را بعد از فایل مقدماتی قرار دهید. برای پروژه بزرگ می‌توانید از ماژول‌ها و exportهای روشن‌تر استفاده کنید.

الگوهای Wildcard

فایل‌های ماژولار
client_scripts {
    'client/main.lua',
    'client/modules/*.lua'
}

server_scripts {
    'server/main.lua',
    'server/modules/**/*.lua'
}

*.lua فایل‌های یک سطح را انتخاب می‌کند؛ **/*.lua برای پوشه‌های تو در تو کاربرد دارد. مراقب باشید فایل main.lua با یک الگوی همپوشان دوبار وارد نشود و ترتیب اجرای فایل‌هایی که به هم وابسته‌اند قابل پیش‌بینی بماند.

دستورهای مهم دیگر در fxmanifest

Directiveکاربردنمونه
client_script(s)اجرای فایل در کلاینتclient_script 'client.lua'
server_script(s)اجرای فایل روی FXServerserver_script 'server.lua'
shared_script(s)کد مشترک دو سمتshared_script 'config.lua'
ui_pageورودی رابط NUIui_page 'html/index.html'
file / filesارسال فایل به کلاینتfiles {'html/*'}
dependency / dependenciesوابستگی و ترتیب استارت Resourcedependency 'ox_lib'
data_fileمعرفی متادیتای خودرو و فایل داده بازیdata_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
this_is_a_mapعلامت‌گذاری Resource نقشهthis_is_a_map 'yes'
escrow_ignoreاستثنای فایل‌ها از Asset Escrow در سناریوی مربوطescrow_ignore {'config.lua'}
node_versionانتخاب runtime جاوااسکریپت سرورnode_version '22'
نمونه جامع: فقط برای Resourceهایی که واقعاً این فایل‌ها و وابستگی‌ها را دارند
fx_version 'cerulean'
game 'gta5'

shared_scripts { 'config.lua' }
client_scripts { 'client/main.lua' }
server_scripts { 'server/main.lua' }

-- Resource dependencies
dependencies {
    'ox_lib',
    '/onesync'
}

-- Needed when using a local NUI page
ui_page 'html/index.html'
files {
    'html/index.html',
    'html/style.css',
    'html/app.js'
}

قیدهای خاص دیگری مانند /gameBuild:h4 یا /server:4500 هم وجود دارند که حداقل شرایط اجرا را تعیین می‌کنند. گزینه lua54 'yes' امروز منسوخ و غیرضروری است. برای فهرست کامل و تغییرات احتمالی، همیشه صفحه رسمی Manifest را ببینید. همه Directiveها ↗

Server Artifacts چیست و FXServer چطور نصب می‌شود؟

Artifact بسته اجرایی سرور است؛ چیزی که FXServer را راه می‌اندازد. Resourceها روی این محیط اجرا می‌شوند. تفاوت اصلی با Game Build این است که شماره Artifact به نسخه باینری سرور مربوط می‌شود، اما sv_enforceGameBuild محتوای بازی مورد استفاده کلاینت را مشخص می‌کند.

  1. از صفحه رسمی Server Download، نسخه مناسب سیستم‌عامل را دریافت کنید؛ برای نصب جدید معمولاً Recommended را انتخاب کنید.
  2. فایل‌ها را در پوشه مستقل استخراج کنید و FXServer را اجرا کنید.
  3. راه‌اندازی اولیه را در txAdmin انجام دهید، حساب Cfx را متصل و قالب سرور را انتخاب کنید.
  4. کلید لازم را از Cfx Portal دریافت و در پیکربندی وارد کنید.
  5. Resourceهای خود را زیر resources قرار دهید و به فایل server.cfg اضافه کنید.
  6. در کنسول با refresh منابع تازه را شناسایی و با ensure my_resource اجرا کنید.
نمونه تنظیمات؛ وجود و نیاز Resourceها به قالب سرور بستگی دارد
# Typical lines in server.cfg
set onesync on

ensure chat
ensure spawnmanager
ensure my_resource

پنل txAdmin با FXServer ارائه می‌شود و برای مدیریت لاگ‌ها، بازیکنان، زمان‌بندی Restart و Resourceها کاربرد دارد. نسخه Artifact را باید به‌صورت جداگانه از fx_version و Game Build کنترل کنید. Artifact رسمی ↗ نصب با txAdmin ↗

NUI چیست؟ ساخت رابط FiveM با HTML و CSS

اگر بخواهید یک گوشی، بانک، صفحه ورود، Inventory یا منوی شیک داخل بازی بسازید، NUI ابزار اصلی شماست. NUI رابط مبتنی بر Chromium است که HTML، CSS و JavaScript را در بازی نمایش می‌دهد و با Client Script ارتباط برقرار می‌کند.

HTML / JavaScript⇄Client Lua⇄Server Lua
SetNuiFocus

گرفتن/آزاد کردن تمرکز موس و کیبورد

SendNUIMessage

ارسال پیام از Lua به صفحه وب

RegisterNUICallback

گرفتن درخواست صفحه وب در Lua

fetch()

ارسال درخواست از JavaScript به Callback

یک نمونه NUI قابل اجرا؛ پنل با فرمان /panel

یک Resource به نام demo_nui با ساختار زیر بسازید:

ساختار پروژه NUI
demo_nui/
├── fxmanifest.lua
├── client.lua
└── html/
    └── index.html

۱. fxmanifest.lua

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

ui_page 'html/index.html'
files { 'html/index.html' }
client_script 'client.lua'

۲. client.lua

client.lua
local opened = false

local function setOpen(state)
    opened = state
    SetNuiFocus(state, state)
    SendNUIMessage({
        action = state and 'open' or 'close',
        text = 'Welcome to my FiveM NUI!'
    })
end

RegisterCommand('panel', function()
    setOpen(not opened)
end, false)

RegisterNUICallback('close', function(_, cb)
    setOpen(false)
    cb({ ok = true })
end)

RegisterNUICallback('ping', function(_, cb)
    cb({ ok = true, message = 'Pong from Lua!' })
end)

AddEventHandler('onClientResourceStop', function(name)
    if name == GetCurrentResourceName() then
        SetNuiFocus(false, false)
    end
end)

۳. html/index.html

html/index.html
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="UTF-8">
<title>FiveM NUI</title>
<style>
  body { margin: 0; background: transparent;
    font-family: Tahoma, sans-serif; }
  #panel { display: none; width: 360px;
    margin: 12vh auto; padding: 25px;
    background: #15263d; color: white;
    border-radius: 16px; }
  button { padding: 10px; cursor: pointer; }
</style>
</head>
<body>
  <div id="panel">
    <h2>پنل FiveM</h2>
    <p id="text"></p>
    <button id="ping">تست ارتباط</button>
    <button id="close">بستن</button>
  </div>
<script>
  const panel = document.getElementById('panel');
  const text = document.getElementById('text');

  window.addEventListener('message', event => {
    const data = event.data;
    if (data.action === 'open') {
      panel.style.display = 'block';
      text.textContent = data.text;
    }
    if (data.action === 'close') {
      panel.style.display = 'none';
    }
  });

  async function send(eventName) {
    const resource = GetParentResourceName();
    const result = await fetch(
      `https://${resource}/${eventName}`,
      { method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({}) }
    );
    return result.json();
  }

  document.getElementById('ping').onclick = async () => {
    const result = await send('ping');
    text.textContent = result.message;
  };
  document.getElementById('close').onclick = () => send('close');
</script>
</body>
</html>

بعد از قرار دادن سه فایل، در کنسول سرور refresh و ensure demo_nui را اجرا کنید. سپس در چت بازی /panel را بزنید. دکمه «تست ارتباط» پیام Lua را از طریق Callback می‌گیرد و «بستن» تمرکز موس را آزاد می‌کند.

دقت کنید: با fx_version 'cerulean' آدرس callback باید https:// باشد، نه http://. هر callback باید cb(...) را فراخوانی کند؛ حتی اگر فقط وضعیت موفقیت را برگرداند.

برای انتقال درخواست حساس از NUI به سرور، جریان معمول fetch → Client callback → TriggerServerEvent → اعتبارسنجی Server است. برای دریافت جواب از سرور نیز TriggerClientEvent و سپس SendNUIMessage به کار می‌روند. NUI رسمی ↗ Callbackها ↗

Developer Mode و ابزارهای دیباگ FiveM

باز کردن کنسول F8 با «فعال کردن Developer Mode» یک چیز نیست. کنسول برای اجرای دستور و دیدن لاگ به کار می‌رود؛ Dev Mode به امکانات توسعه اضافه اجازه دسترسی می‌دهد و روش فعال‌سازی‌اش بین Legacy و Enhanced تفاوت دارد.

محیطروشتوضیح
FiveM Legacy+set moo 31337آرگومان اجرای کلاینت برای فعال شدن دستورهای توسعه در نسخه Legacy؛ در شورتکات/خط فرمان.
FiveM Enhancedset sv_devMode trueدر server.cfg سرور توسعه؛ به کلاینت‌های متصل نیز Dev Mode می‌دهد.
کنسول معمولیF8مشاهده لاگ و اجرای دستورهای مجاز؛ الزاماً Dev Mode نیست.
گزارش بیشترdeveloper trueلاگ توسعه را بیشتر می‌کند؛ به تنهایی جایگزین Dev Mode نیست.
حالت توسعه در سرور
# Put this in a DEVELOPMENT server.cfg only
set sv_devMode true

# Do not use in a production server

طبق مستندات جدید، sv_devMode تعداد کلاینت‌های سرور را به ۸ محدود می‌کند و نباید روی سرور عمومی Production روشن شود. در Enhanced روش قدیمی +set moo 31337 حذف شده است.

ابزارهای کاربردی F8

دستورات دیباگ؛ برخی نیازمند دسترسی Developer هستند
cmdlist
resmon true
nui_devTools
profiler record 500
profiler status
profiler view

resmon مصرف Resourceها را نشان می‌دهد؛ nui_devTools ابزار توسعه Chromium رابط NUI را باز می‌کند. برای بررسی NUI می‌توانید در حالت پشتیبانی‌شده به http://localhost:13172/ نیز مراجعه کنید. txAdmin برای بررسی لاگ سرور و مدیریت Resource مفید است.

رفرنس‌ها: Console Commands ↗ Legacy در برابر Enhanced ↗ sv_devMode ↗

OneSync چیست؟ توضیح تنظیمات مهم server.cfg

OneSync سامانه همگام‌سازی موجودیت‌ها و بازیکنان FiveM است. به جای اینکه هر کلاینت همه چیز را همیشه شبیه‌سازی کند، سرور می‌تواند تشخیص دهد کدام Entity برای کدام بازیکن مرتبط است؛ این موضوع برای سرورهای شلوغ و خودروهای Server-side اهمیت دارد.

مقایسه حالت‌های OneSync

حالتمعنیانتخاب معمول
offبدون State Awareness کامل سرورفقط سناریوهای خاص
legacyحالت قدیمی سازگاری؛ ممکن است هزینه عملکردی و مشکلات بصری داشته باشدتوصیه نمی‌شود
onState Awareness کامل و مسیر‌دهی Entity توسط سرورانتخاب پیشنهادی
نمونه server.cfg برای جمعیت پیش‌فرض
# Current OneSync mode
set onesync on

# Keep ambient NPC and traffic spawning
set onesync_population true

set onesync_population false چه کاری می‌کند؟

این گزینه، سیستم ایجاد و مدیریت جمعیت پیش‌فرض OneSync را غیرفعال می‌کند. اگر قرار است ترافیک و NPCهای عادی GTA را داشته باشید، آن را بی‌دلیل روی false نگذارید؛ اگر یک سیستم اختصاصی برای جمعیت دارید، false می‌تواند انتخاب مناسبی باشد.

سناریوی کنترل جمعیت توسط Resource اختصاصی
set onesync on
set onesync_population false

set svgui_disable 1 چیست؟

این خط در فایل‌های قدیمی برای کنترل باز شدن GUI قدیمی سرور دیده می‌شود. اما در مستندات فعلی Cfx، svgui به‌عنوان دستور باز/بسته کردن پنجره دیباگ ثبت شده و svgui_disable به عنوان ConVar استانداردِ تأییدشده فهرست نشده است؛ بنابراین آن را یک تنظیم ضروری و تضمینیِ نسخه‌های امروز معرفی نمی‌کنیم.

دستور Legacy و دستور رسمی مستند
# Legacy configurations may contain:
set svgui_disable 1

# Official documented GUI command:
svgui

در سرورهای جدید txAdmin معمولاً پنل مدیریتی اصلی است. گزینه‌های دیگری مانند onesync_forceMigration (مدیریت جابه‌جایی مالکیت)، onesync_distanceCulling (خارج کردن Entity دور از محدوده Sync) و sv_entityLockdown نیز وجود دارند، اما تغییر کورکورانه پیش‌فرض‌ها توصیه نمی‌شود.

set / setr / sets چیست؟ به شکل ساده، set مقدار ConVar را تنظیم می‌کند؛ setr آن را برای Clientها replicate می‌کند و sets برای متادیتای قابل نمایش سرور کاربرد دارد. تنظیمات را فقط با Syntax رسمی همان ConVar منتشر کنید.

منبع هر سه خط و امکانات OneSync: Server Commands ↗ OneSync ↗

sv_enforceGameBuild چیست؟ نسخه‌ها و DLCهای GTA V

این تنظیم تعیین می‌کند بازیکنان سرور از چه Game Build و محتوای مرتبط با آن استفاده کنند. Game Build با Server Artifact و fx_version کاملاً متفاوت است. معمولاً Buildهای جدیدتر محتوای Buildهای قبلی را نیز در بر دارند.

فقط یکی از Buildها را انتخاب کنید
# Select game content for connecting clients
set sv_enforceGameBuild 3751

# Or, for a tested newer build:
# set sv_enforceGameBuild 3889
نکته: انتخاب Game Build باید با Artifact، اسکریپت‌ها، IPLها و مدل‌های مورد استفاده تست شود. تغییر مقدار sv_enforceGameBuild از طریق سرور روشن، به‌صورت Runtime قابل اعمال نیست و به راه‌اندازی دوباره نیاز دارد.

جدول نسخه‌های مستند FiveM

Game Buildنام / Aliasبه‌روزرسانی
1—بازی پایه بدون DLC
1604xm18Arena War
2060mpsumLos Santos Summer Special
2189h4Cayo Perico Heist
2372tunerLos Santos Tuners
2545securityThe Contract
2612mpg9ecبدون عنوان بازاریابی در جدول رسمی
2699mpsum2The Criminal Enterprises
2802mpchristmas3Los Santos Drug Wars
2944mp2023_01San Andreas Mercenaries
3095mp2023_02The Chop Shop
3258mp2024_01Bottom Dollar Bounties
3407mp2024_02Agents of Sabotage
3570mp2025_01Money Fronts
3751mp2025_02A Safehouse in the Hills
3889mp2026_01The Kortz Center Heist

این فهرست طبق صفحه رسمی Server Commands در بررسی ۱۵ اکتبر ۲۰۲۶ تنظیم شده است؛ ممکن است در آینده گزینه‌های جدیدتری اضافه شوند. برای دیدن آخرین نسخه‌ها، وارد لینک زیر شوید و عنوان sv_enforceGameBuild → FiveM builds را پیدا کنید. Buildهای Diamond Casino در این جدول رسمی شماره جداگانه مشخصی ندارند و نباید شماره‌ای برایشان حدس زد. آخرین Buildها در سایت رسمی ↗

Native Reference چیست و چگونه استفاده می‌شود؟

Nativeها توابع آماده تعامل با GTA V و Cfx هستند؛ مثلاً گرفتن مختصات، ساخت خودرو، کنترل دوربین یا درخواست بارگذاری یک IPL. در سایت Native Reference نام تابع را جست‌وجو کنید، سپس بخش API Set را ببینید: همه Nativeها از سمت Server قابل استفاده نیستند.

Nativeکاربرد رایجمحل استفاده موردنظر در این مقاله
GetEntityCoordsدریافت مختصات EntityServer یا Client مطابق API Set
CreateVehicleServerSetterایجاد Vehicle با منطق Server SetterServer
SetEntityOrphanModeسیاست نگهداری Entity بدون مالک شبکه‌ایServer
RequestIplدرخواست Streaming یک IPLClient
SendNUIMessageارسال داده به صفحه NUIClient

همیشه نوع پارامتر، خروجی و نکات صفحه Native را بررسی کنید. بعضی Nativeهای سرور به شکل RPC روی کلاینت اجرا می‌شوند و موفقیتشان تضمین یکسانی ندارد. Native Reference ↗ آموزش Nativeها ↗

ساخت خودرو از سمت Server و ماندگاری پس از Disconnect

بله؛ در FiveM می‌توان خودرو را با CreateVehicleServerSetter در سمت سرور ساخت. این روش برای خودروهای سازمانی، ماشین‌های ثابت شهر و موجودیت‌هایی که نباید صرفاً با خروج بازیکن از بین بروند بسیار کاربردی است.

مثال: دستور ادمین برای ساخت یک خودرو

این فایل را در server.lua قرار دهید و با server_script 'server.lua' در Manifest معرفی کنید:

server.lua
RegisterCommand('svcar', function(source)
    if source <= 0 then
        print('Use /svcar in game as an authorized admin.')
        return
    end

    local ped = GetPlayerPed(source)
    if ped == 0 then return end

    local coords = GetEntityCoords(ped)
    local heading = GetEntityHeading(ped)

    local vehicle = CreateVehicleServerSetter(
        GetHashKey('sultan'),
        'automobile',
        coords.x + 3.0, coords.y, coords.z,
        heading
    )

    if vehicle == 0 then
        print('Failed to create server vehicle')
        return
    end

    SetEntityOrphanMode(vehicle, 2) -- KeepEntity
    print(('Created vehicle entity %s'):format(vehicle))
end, true) -- restrict by ACE permission

چون آرگومان آخر true است، دستور با ACE محدود می‌شود. برای نمونه می‌توانید به گروه ادمین مجوز زیر بدهید؛ ساختار واقعی مدیریت کاربران به تنظیمات سرور بستگی دارد:

server.cfg / permissions.cfg
add_ace group.admin command.svcar allow

مقدار 2 در SetEntityOrphanMode حالت KeepEntity است: سرور صرفاً به دلیل orphan شدن خودرو آن را حذف نکند. با این حال سایر اسکریپت‌ها یا درخواست‌های حذف همچنان می‌توانند بر آن اثر بگذارند؛ بنابراین این خط «ضد حذف مطلق» نیست.

پس از Disconnect و Restart چه می‌شود؟

رخدادانتظار منطقی
بازیکن از سرور خارج می‌شودخودروی Server-side با مدیریت مناسب می‌تواند باقی بماند.
هیچ بازیکنی نزدیک ماشین نیستممکن است Client خودرو را در محدوده Sync نداشته باشد، اما سرور Entity را نگه دارد.
اسکریپتی DeleteEntity می‌زندخودرو می‌تواند حذف شود.
Resource ری‌استارت می‌شودوابسته به منطق Resource و اینکه خودرو را حذف/بازسازی می‌کند یا نه.
FXServer خاموش می‌شودEntity حافظه‌ای به‌تنهایی بعد از روشن‌شدن بازیابی نمی‌شود.
اطلاعات در Database ذخیره شدهمی‌توان خودرو را در Startup مجدداً با مدل، مکان و Properties بازسازی کرد.
حواستان باشد: ماندن یک Entity در زمان خروج Player با Persist شدن آن پس از Restart سرور دو مسئله جداست. برای حفظ دائمی باید وضعیت در Database یا ذخیره‌سازی پایدار ثبت و سپس دوباره Spawn شود. State Bag به‌تنهایی جای دیتابیس دائمی نیست.

مراجع: OneSync ↗ Server Setter ↗ Orphan Mode ↗

IPL چیست؟ چرا برخی ساختمان‌ها و Interiorها بارگذاری نمی‌شوند؟

IPL بخشی از سیستم Streaming و نقشه GTA V است. بعضی فضای داخلی‌ها، ساختمان‌ها و وضعیت‌های نقشه در اجرای معمول به‌صورت پیش‌فرض فعال نیستند یا فقط هنگام مأموریت خاصی Load می‌شوند. برای فعال‌کردنشان از Nativeهایی مانند RequestIpl استفاده می‌شود.

اصطلاحتوضیح کوتاه
IPLدرخواست بارگذاری بخش/حالت مشخصی از نقشه یا Interiorهای بازی.
YMAPفایل داده جای‌گذاری اجسام و نقشه؛ در Resourceهای Map رایج است.
MLOنوعی ساختار Interior سفارشی/قابل ورود با فضاها، roomها و portalها؛ با یک IPL یکسان نیست.

مثال بارگذاری IPL در Client

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
client_script 'client.lua'
client.lua
local requiredIpls = {
    'CS3_07_MPGates'
}

CreateThread(function()
    for _, name in ipairs(requiredIpls) do
        RequestIpl(name)
    end
end)

این نام صرفاً یک نمونه از IPLهای شناخته‌شده است؛ قبل از استفاده واقعی، نتیجه را با Build موردنظر تست کنید. درخواست IPL روی Client انجام می‌شود. وقتی سرور Resource را شروع کند، فایل Client برای بازیکنان متصل اجرا می‌شود؛ خود FXServer لزوماً Rendering داخل GTA را انجام نمی‌دهد.

bob74_ipl چیست و چطور استفاده می‌شود؟

پروژه bob74_ipl یک Resource شناخته‌شده برای فعال کردن بخش‌هایی از نقشه GTA V و بسیاری از Interiorهاست؛ مخصوصاً فضاهایی که در برخی حالت‌ها بارگذاری نمی‌شوند. برای استفاده، مخزن اصلی را دانلود کنید، پوشه Resource را با نام درست قرار دهید و از روی README همان نسخه تنظیمات و فایل‌های لازم را بررسی کنید.

اجرای bob74_ipl
# In server.cfg
ensure bob74_ipl

در صورت تداخل با MLOهای شخص ثالث، ممکن است دیوار نامرئی، در بسته، فضای داخلی ناقص یا بخش‌های همپوشان ببینید. در این صورت باید همان IPL یا تنظیمات مرتبط را در loader غیرفعال کنید؛ حذف یا تغییر کورکورانه تمام فایل‌های Bob74 راه مناسبی نیست. رفتار آن همچنین به Game Build و GTA Legacy/Enhanced وابسته است.

مخزن اصلی: Bob74 IPL ↗ RequestIpl Native ↗ نمونه گزارش تداخل ↗

Frameworkهای FiveM: ESX، QBCore، Qbox و گزینه‌های دیگر

Framework مجموعه‌ای از سیستم‌ها و APIهای پایه برای مدیریت بازیکن، داده کاراکتر، شغل، اقتصاد و ارتباط بین Resourceهاست. انتخاب Framework می‌تواند سرعت ساخت سرور RP را زیاد کند؛ ولی هیچ Frameworkای به‌تنهایی تضمین امنیت، عملکرد بهتر یا طراحی خوب نیست.

گزینهشناخت سریعچه زمانی مناسب است؟منبع
ESX Legacyاکوسیستم قدیمی و شناخته‌شده Roleplay؛ es_extendedتیم آشنا با ESX یا سروری با Resourceهای ESXGitHub
QBCoreچارچوب Lua برای RP، با Resourceهای متنوعپروژه‌هایی که API و ساختار QBCore را ترجیح می‌دهندGitHub
Qboxچارچوبی با معماری و ابزارهای جدیدتر در اکوسیستم FiveMپروژه‌های ماژولار؛ سازگاری Scriptها باید بررسی شودGitHub
ND_Coreهسته مستقل RP با APIها و ساختار خودشتیم‌هایی که عمداً ND را مبنا می‌گذارندGitHub
vRPفریم‌ورک شناخته‌شده با الگو و APIهای مخصوصسرورهای ساخته‌شده روی vRP یا توسعه‌دهندگان آشنا با آنGitHub
ox_coreپروژه Core در خانواده ox؛ اکوسیستم و وضعیت نگهداری شاخه انتخابی را بررسی کنیدتوسعه‌دهندگانی که مشخصاً معماری آن را نیاز دارندGitHub

ابزارهایی مانند ox_lib، ox_inventory یا oxmysql الزاماً به معنی استفاده از «Framework ox_core» نیستند؛ ممکن است به‌عنوان کتابخانه یا Resource مستقل کنار ESX، QBCore یا سیستم اختصاصی نصب شده باشند.

به‌جای مقایسه‌ ساختگی «کدام Framework چند درصد بهتر است»، این چهار عامل را بسنجید: تجربه تیم، کیفیت نگهداری، سازگاری اسکریپت‌های موردنیاز و هزینه مهاجرت از بیس فعلی. فهرست رسمی ↗

Standalone و Customized؛ بیس‌های اختصاصی چه جایگاهی دارند؟

عبارت «بیس Standalone» معمولاً برای سروری به کار می‌رود که تیم توسعه، هسته و بسیاری از سیستم‌های اصلی‌اش را خودش ساخته و از ESX یا QBCore به‌عنوان Framework مرکزی استفاده نمی‌کند. اما یک اسکریپت Standalone لزوماً هسته کامل سرور نیست؛ ممکن است فقط HUD، صندلی خودرو یا سیستم نمایش متن باشد که روی چند نوع سرور بدون وابستگی به Framework اجرا می‌شود.

۱. ESX آماده

هسته ESX و Resourceهای مرسوم با تغییرات کم. توسعه سریع‌تر است، اما ظاهر و رفتار می‌تواند شبیه سرورهای دیگر باشد.

۲. Customized ESX

هسته هنوز ESX است ولی Inventory، گاراژ، شغل‌ها و UI تا حد زیادی بازنویسی شده‌اند. اصطلاح دقیق: «ESX کاستوم».

۳. Standalone Core

هویت Player، اقتصاد، مجوزها و APIها با کد اختصاصی مدیریت می‌شوند؛ دیگر Resourceها با API همین هسته حرف می‌زنند.

۴. Hybrid

Framework آماده کنار اسکریپت‌های مستقل و سیستم‌های اختصاصی. در عمل سرورهای زیادی می‌توانند ترکیبی باشند.

چگونه بیس واقعی را تشخیص دهیم؟

بررسی resources←پیدا کردن Core و Exportها←بررسی وابستگی و Database
علامت داخل پروژهبرداشت منطقی
es_extended یا ESX.GetPlayerFromIdاحتمال استفاده از ESX زیاد است.
qb-core یا QBCore.Functions.GetPlayerاحتمال استفاده از QBCore زیاد است.
qbx_coreمی‌تواند نشانه Qbox باشد؛ وابستگی‌ها را بررسی کنید.
هسته‌ای با APIهای کاملاً اختصاصیمی‌تواند Standalone Core باشد؛ باید مشخص شود کدهای کدام پروژه مبنا قرار گرفته‌اند.
تغییر کامل HUD و Inventory فقطبه‌تنهایی نشان‌دهنده تغییر نوع Framework نیست.

در میان برخی سرورهای ایرانی، اصطلاح «بیس اختصاصی» ممکن است به ESX بسیار تغییر‌یافته اشاره کند. صرف تغییر نام Resource، حذف لوگو یا بازطراحی رابط کاربری به معنای خلق Framework تازه نیست. برای ادعای Standalone بودن، معماری Core باید واقعاً مستقل باشد.

هزینه پنهان Standalone: کنترل کامل، آزادی طراحی بیشتری دارد؛ اما احراز هویت، ذخیره امن داده، مدیریت Entity، سازگاری نسخه‌ها، مستندات و نگهداری تمام سیستم‌ها نیز به مسئولیت تیم توسعه تبدیل می‌شود.

FiveM، Frameworkها و Scriptهای Open Source

مخزن citizenfx/fivem عمومی است، ولی مجوز بخش عمده کد تابع توافق‌نامه Rockstar Games Creator Platform است و قسمت‌های معینی از آن LGPL v2 دارند. «Public repository» به‌تنهایی به معنای اجازه فروش مجدد یا توزیع بدون شرط نیست.

Frameworkهایی مثل ESX، QBCore و Qbox مخزن عمومی دارند و ممکن است مجوزهای متفاوتی در بخش‌های گوناگون داشته باشند. Resourceهای تجاری نیز گاه به کمک Asset Escrow توزیع می‌شوند. برای استفاده، کپی، Fork و انتشار مجدد باید فایل LICENSE همان پروژه را بخوانید.

عبارتمنظور
Open Sourceکد با مجوز واجد شرایط متن‌باز منتشر شده است.
Source Availableمی‌توان کد را دید، اما آزادی‌های مجوز ممکن است محدود باشد.
Free Scriptرایگان است؛ لزوماً متن‌باز یا قابل فروش مجدد نیست.
Escrow / Closedتمام یا بخشی از سورس به شکل مستقیم در اختیار مصرف‌کننده نیست.
مجوز FiveM ↗ مخزن FiveM ↗

چک‌لیست ساخت یک Resource حرفه‌ای

  1. برای پروژه جدید fx_version 'cerulean' و game 'gta5' بگذارید.
  2. منطق حساس را روی Server نگه دارید و ورودی Client را اعتبارسنجی کنید.
  3. پوشه‌ها و فایل‌های Client، Server و Shared را مشخص و جدا کنید.
  4. برای NUI از HTTPS Callback و پاسخ cb(...) استفاده کنید.
  5. تنظیم onesync و Game Build را بر اساس ویژگی‌ها و تست واقعی انتخاب کنید.
  6. Resourceهای IPL و MLO را از نظر همپوشانی بررسی کنید.
  7. Resourceها و Frameworkها را با مجوز و وابستگی روشن نصب کنید.
  8. از Database نسخه پشتیبان بگیرید و زمان Restart، حفظ وضعیت خودروها را آزمایش کنید.
جمع‌بندی: در یک سرور سالم، UI از منطق جداست، سرور به داده‌های Client اعتماد کورکورانه نمی‌کند، Entityهای مهم زیر مدیریت OneSync قرار دارند و ذخیره پایدار به دیتابیس سپرده می‌شود. برای یک سرور ESX کاستوم یا یک Standalone Core نیز اصول مهندسی همین‌ها هستند.

ارتباط ESX با سرورهای قدیمی ایرانی و تفاوت VMP

در نسل اولیه سرورهای نقش‌آفرینی فارسی، نام‌هایی مانند ایران رول پلی، IRPixel و Sunrise RP در خاطره جامعه مطرح‌اند و استفاده از ESX سفارشی‌شده از الگوهای مهم توسعه بود. در کار با پروژه‌های قدیمی، پیش از مهاجرت کد باید وابستگی‌های es_extended، نسخه‌های Resource، رویدادها، پایگاه داده و قراردادهای سمت سرور بررسی شوند؛ برچسب «Custom» به‌تنهایی به معنای مستقل بودن از ESX نیست.

با مشکلات دسترسی کاربران ایران به بخش‌هایی از FiveM و Cfx.re، پلتفرم ایرانی VMP و فهرست سرورهای آن مطرح شدند. اجرای مستقیم اسکریپت FiveM روی VMP را بدون بررسی نسخه و API فرض نکنید. برای زمینه تاریخی و سرورهای معروف، مقاله FiveM چیست؟ را بخوانید.

منابع رسمی و لینک‌های فنی

بازنگری فنی: ۱۵ اکتبر ۲۰۲۶. قبل از تغییر Production، رفتار ConVarها و شماره Game Build را دوباره از مستندات رسمی بررسی کنید؛ مخصوصاً اگر Legacy و Enhanced متفاوت‌اند.

نوشته شده توسط

امیررضا جابری

مقالات فنی جلفا با هدف آموزش کاربردی و ارجاع به منابع معتبر تهیه می‌شوند.

مقالات مرتبط

FiveM (فایوم) چیست؟ FiveM ۱۴۰۵/۰۷/۲۳ ۱۱ دقیقه مطالعه FiveM (فایوم) چیست؟ FiveM (فایوم) بستری برای ساخت سرورهای اختصاصی GTA V و تجربه Roleplay است. با تاریخچه فایوم، تفاوت آن با GTA Online، ارتباطش با Rockstar و انواع بیس سرور آشنا شوید.