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

فهرست مطالب ۱۷ بخش
اسکریپت FiveM چیست و از کجا شروع کنیم؟
در FiveM هر قابلیت تازه—از شغل و گاراژ گرفته تا HUD و بانک—با Resource ساخته میشود. Lua منطق بازی را مینویسد، NUI رابط آن را نشان میدهد و FXServer با OneSync دنیای چندنفره را مدیریت میکند.
اسکریپت فقط یک فایل Lua نیست؛ میتواند مجموعهای از فایلهای Lua، JavaScript، C#، رابط وب و دیتابیس باشد. معمولاً برای کارهای حساس مانند پول و مالکیت خودرو، منطق در سرور اجرا میشود؛ برای تعامل، تصویر و دوربین از Client استفاده میشود.
منطق اسکریپت، رویدادها و Nativeها
رابط کاربری با HTML، CSS و JavaScript
هماهنگسازی بازیکن و Entityها
برنامهنویسی Lua در FiveM
Lua زبانی سبک و قابل یادگیری است. برای اسکریپتنویسی FiveM از تابعها، tableها، eventها و Nativeها استفاده میکنید. در نسخههای جدید، Lua 5.4 مبنای اجراست؛ گزینه قدیمی lua54 'yes' از ژوئن ۲۰۲۵ دیگر لازم نیست. FiveM از JavaScript و C# هم پشتیبانی میکند. مستندات Lua ↗ Lua 5.4 ↗
مثال اول: فرمان ساده روی کلاینت
RegisterCommand('hello', function()
print('Hello from FiveM Client!')
end, false)اگر این فایل را بهعنوان client_script معرفی کنید، فرمان روی کلاینت اجرا میشود و پیام را در F8 میبینید.
مثال دوم: پیام به بازیکن از سمت سرور
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 یا سیستم اعلان همان سرور نمایش داده شود.
ساختار 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.htmlfx_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 جدید |
fx_version 'cerulean'
game 'gta5'نامهایی مانند adamant و bodacious به تاریخ سازگاری مربوط میشوند؛ نصب Artifact جدید بهتنهایی دلیل تغییر عجولانه Manifest یک اسکریپت قدیمی نیست. مستندات نسخهها: Resource Manifest ↗
یک فایل یا چند فایل؟ server_script و server_scripts
برای یک فایل از دستور مفرد و برای چند فایل از شکل جمع استفاده کنید. از نظر عملکرد هر دو معتبرند و مفرد را نیز میتوان چند بار نوشت.
-- 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) | اجرای فایل روی FXServer | server_script 'server.lua' |
shared_script(s) | کد مشترک دو سمت | shared_script 'config.lua' |
ui_page | ورودی رابط NUI | ui_page 'html/index.html' |
file / files | ارسال فایل به کلاینت | files {'html/*'} |
dependency / dependencies | وابستگی و ترتیب استارت Resource | dependency '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' |
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 محتوای بازی مورد استفاده کلاینت را مشخص میکند.
- از صفحه رسمی Server Download، نسخه مناسب سیستمعامل را دریافت کنید؛ برای نصب جدید معمولاً Recommended را انتخاب کنید.
- فایلها را در پوشه مستقل استخراج کنید و FXServer را اجرا کنید.
- راهاندازی اولیه را در txAdmin انجام دهید، حساب Cfx را متصل و قالب سرور را انتخاب کنید.
- کلید لازم را از Cfx Portal دریافت و در پیکربندی وارد کنید.
- Resourceهای خود را زیر
resourcesقرار دهید و به فایلserver.cfgاضافه کنید. - در کنسول با
refreshمنابع تازه را شناسایی و باensure my_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 ارتباط برقرار میکند.
SetNuiFocusگرفتن/آزاد کردن تمرکز موس و کیبورد
SendNUIMessageارسال پیام از Lua به صفحه وب
RegisterNUICallbackگرفتن درخواست صفحه وب در Lua
fetch()ارسال درخواست از JavaScript به Callback
یک نمونه NUI قابل اجرا؛ پنل با فرمان /panel
یک Resource به نام demo_nui با ساختار زیر بسازید:
demo_nui/
├── fxmanifest.lua
├── client.lua
└── html/
└── index.html۱. fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
ui_page 'html/index.html'
files { 'html/index.html' }
client_script '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
<!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 Enhanced | set 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
cmdlist
resmon true
nui_devTools
profiler record 500
profiler status
profiler viewresmon مصرف 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 | حالت قدیمی سازگاری؛ ممکن است هزینه عملکردی و مشکلات بصری داشته باشد | توصیه نمیشود |
on | State Awareness کامل و مسیردهی Entity توسط سرور | انتخاب پیشنهادی |
# Current OneSync mode
set onesync on
# Keep ambient NPC and traffic spawning
set onesync_population trueset onesync_population false چه کاری میکند؟
این گزینه، سیستم ایجاد و مدیریت جمعیت پیشفرض OneSync را غیرفعال میکند. اگر قرار است ترافیک و NPCهای عادی GTA را داشته باشید، آن را بیدلیل روی false نگذارید؛ اگر یک سیستم اختصاصی برای جمعیت دارید، false میتواند انتخاب مناسبی باشد.
set onesync on
set onesync_population falseset svgui_disable 1 چیست؟
این خط در فایلهای قدیمی برای کنترل باز شدن GUI قدیمی سرور دیده میشود. اما در مستندات فعلی Cfx، svgui بهعنوان دستور باز/بسته کردن پنجره دیباگ ثبت شده و svgui_disable به عنوان ConVar استانداردِ تأییدشده فهرست نشده است؛ بنابراین آن را یک تنظیم ضروری و تضمینیِ نسخههای امروز معرفی نمیکنیم.
# Legacy configurations may contain:
set svgui_disable 1
# Official documented GUI command:
svguiدر سرورهای جدید txAdmin معمولاً پنل مدیریتی اصلی است. گزینههای دیگری مانند onesync_forceMigration (مدیریت جابهجایی مالکیت)، onesync_distanceCulling (خارج کردن Entity دور از محدوده Sync) و sv_entityLockdown نیز وجود دارند، اما تغییر کورکورانه پیشفرضها توصیه نمیشود.
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های قبلی را نیز در بر دارند.
# Select game content for connecting clients
set sv_enforceGameBuild 3751
# Or, for a tested newer build:
# set sv_enforceGameBuild 3889sv_enforceGameBuild از طریق سرور روشن، بهصورت Runtime قابل اعمال نیست و به راهاندازی دوباره نیاز دارد.جدول نسخههای مستند FiveM
| Game Build | نام / Alias | بهروزرسانی |
|---|---|---|
1 | — | بازی پایه بدون DLC |
1604 | xm18 | Arena War |
2060 | mpsum | Los Santos Summer Special |
2189 | h4 | Cayo Perico Heist |
2372 | tuner | Los Santos Tuners |
2545 | security | The Contract |
2612 | mpg9ec | بدون عنوان بازاریابی در جدول رسمی |
2699 | mpsum2 | The Criminal Enterprises |
2802 | mpchristmas3 | Los Santos Drug Wars |
2944 | mp2023_01 | San Andreas Mercenaries |
3095 | mp2023_02 | The Chop Shop |
3258 | mp2024_01 | Bottom Dollar Bounties |
3407 | mp2024_02 | Agents of Sabotage |
3570 | mp2025_01 | Money Fronts |
3751 | mp2025_02 | A Safehouse in the Hills |
3889 | mp2026_01 | The 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 | دریافت مختصات Entity | Server یا Client مطابق API Set |
CreateVehicleServerSetter | ایجاد Vehicle با منطق Server Setter | Server |
SetEntityOrphanMode | سیاست نگهداری Entity بدون مالک شبکهای | Server |
RequestIpl | درخواست Streaming یک IPL | Client |
SendNUIMessage | ارسال داده به صفحه NUI | Client |
همیشه نوع پارامتر، خروجی و نکات صفحه Native را بررسی کنید. بعضی Nativeهای سرور به شکل RPC روی کلاینت اجرا میشوند و موفقیتشان تضمین یکسانی ندارد. Native Reference ↗ آموزش Nativeها ↗
ساخت خودرو از سمت Server و ماندگاری پس از Disconnect
بله؛ در FiveM میتوان خودرو را با CreateVehicleServerSetter در سمت سرور ساخت. این روش برای خودروهای سازمانی، ماشینهای ثابت شهر و موجودیتهایی که نباید صرفاً با خروج بازیکن از بین بروند بسیار کاربردی است.
مثال: دستور ادمین برای ساخت یک خودرو
این فایل را در server.lua قرار دهید و با server_script 'server.lua' در Manifest معرفی کنید:
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 محدود میشود. برای نمونه میتوانید به گروه ادمین مجوز زیر بدهید؛ ساختار واقعی مدیریت کاربران به تنظیمات سرور بستگی دارد:
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 بازسازی کرد. |
IPL چیست؟ چرا برخی ساختمانها و Interiorها بارگذاری نمیشوند؟
IPL بخشی از سیستم Streaming و نقشه GTA V است. بعضی فضای داخلیها، ساختمانها و وضعیتهای نقشه در اجرای معمول بهصورت پیشفرض فعال نیستند یا فقط هنگام مأموریت خاصی Load میشوند. برای فعالکردنشان از Nativeهایی مانند RequestIpl استفاده میشود.
| اصطلاح | توضیح کوتاه |
|---|---|
| IPL | درخواست بارگذاری بخش/حالت مشخصی از نقشه یا Interiorهای بازی. |
| YMAP | فایل داده جایگذاری اجسام و نقشه؛ در Resourceهای Map رایج است. |
| MLO | نوعی ساختار Interior سفارشی/قابل ورود با فضاها، roomها و portalها؛ با یک IPL یکسان نیست. |
مثال بارگذاری IPL در Client
fx_version 'cerulean'
game 'gta5'
client_script '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 همان نسخه تنظیمات و فایلهای لازم را بررسی کنید.
# 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های ESX | GitHub |
| 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 یا سیستم اختصاصی نصب شده باشند.
Standalone و Customized؛ بیسهای اختصاصی چه جایگاهی دارند؟
عبارت «بیس Standalone» معمولاً برای سروری به کار میرود که تیم توسعه، هسته و بسیاری از سیستمهای اصلیاش را خودش ساخته و از ESX یا QBCore بهعنوان Framework مرکزی استفاده نمیکند. اما یک اسکریپت Standalone لزوماً هسته کامل سرور نیست؛ ممکن است فقط HUD، صندلی خودرو یا سیستم نمایش متن باشد که روی چند نوع سرور بدون وابستگی به Framework اجرا میشود.
هسته ESX و Resourceهای مرسوم با تغییرات کم. توسعه سریعتر است، اما ظاهر و رفتار میتواند شبیه سرورهای دیگر باشد.
هسته هنوز ESX است ولی Inventory، گاراژ، شغلها و UI تا حد زیادی بازنویسی شدهاند. اصطلاح دقیق: «ESX کاستوم».
هویت Player، اقتصاد، مجوزها و APIها با کد اختصاصی مدیریت میشوند؛ دیگر Resourceها با API همین هسته حرف میزنند.
Framework آماده کنار اسکریپتهای مستقل و سیستمهای اختصاصی. در عمل سرورهای زیادی میتوانند ترکیبی باشند.
چگونه بیس واقعی را تشخیص دهیم؟
| علامت داخل پروژه | برداشت منطقی |
|---|---|
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 باید واقعاً مستقل باشد.
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 | تمام یا بخشی از سورس به شکل مستقیم در اختیار مصرفکننده نیست. |
چکلیست ساخت یک Resource حرفهای
- برای پروژه جدید
fx_version 'cerulean'وgame 'gta5'بگذارید. - منطق حساس را روی Server نگه دارید و ورودی Client را اعتبارسنجی کنید.
- پوشهها و فایلهای Client، Server و Shared را مشخص و جدا کنید.
- برای NUI از HTTPS Callback و پاسخ
cb(...)استفاده کنید. - تنظیم
onesyncو Game Build را بر اساس ویژگیها و تست واقعی انتخاب کنید. - Resourceهای IPL و MLO را از نظر همپوشانی بررسی کنید.
- Resourceها و Frameworkها را با مجوز و وابستگی روشن نصب کنید.
- از Database نسخه پشتیبان بگیرید و زمان Restart، حفظ وضعیت خودروها را آزمایش کنید.
ارتباط 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 (فایوم) چیست؟ را بخوانید.