Основные ошибки ресурсов FiveM

Правильная структура папки resources

Ресурсы располагаются внутри каталога данных FXServer:

server-data\
├── resources\
│ ├── [cfx-default]\
│ ├── [standalone]\
│ ├── [framework]\
│ ├── [maps]\
│ ├── [vehicles]\
│ └── my_resource\
└── server.cfg

Папки в квадратных скобках являются категориями. Они помогают группировать ресурсы, но сами не считаются отдельным ресурсом без собственного манифеста.

Пример категории:

resources\
└── [jobs]\
 ├── police_job\
 │ ├── fxmanifest.lua
 │ ├── client.lua
 │ └── server.lua
 └── taxi_job\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

В server.cfg можно запустить каждый ресурс отдельно:

ensure police_job
ensure taxi_job

или всю категорию:

ensure [jobs]

Ресурс лежит не в активном server-data

На компьютере может находиться несколько профилей txAdmin и несколько папок resources. Проверьте путь активного профиля и значение каталога данных, из которого запускается текущий server.cfg.

Лишняя вложенная папка после распаковки

Одна из самых частых ошибок:

resources\
└── my_resource-main\
 └── my_resource\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

FXServer проверяет внешний каталог my_resource-main, но манифест находится уровнем ниже.

Правильно:

resources\
└── my_resource\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

Архив содержит README и отдельную папку

Не всегда нужно переносить весь распакованный каталог. Найдите папку, внутри которой непосредственно находятся fxmanifest.lua, скрипты и остальные файлы ресурса.

Проверьте название ресурса

Команда ensure должна использовать точное имя папки:

resources\[standalone]\my-police-script\

Запуск:

ensure my-police-script

Не используйте:

ensure resources/my-police-script
ensure [standalone]/my-police-script
ensure my-police-script-main

если фактическое имя отличается.

Рекомендации по названию

• используйте латинские буквы;
• избегайте пробелов;
• не добавляйте лишние точки;
• не переименовывайте зависимость без изменения обращений к ней;
• сохраняйте имя, ожидаемое exports и другими скриптами;
• на Linux учитывайте регистр символов.

Если скрипт обращается к:

exports['qb-core']:GetCoreObject()

переименование папки qb-core в qbcore нарушит этот вызов.

Команды refresh, ensure, restart и stop

После добавления новой папки выполните в серверной консоли:

refresh

Команда заново сканирует каталог ресурсов и считывает манифесты.

Затем запустите ресурс:

ensure my_resource

Другие команды:

start my_resource
stop my_resource
restart my_resource

После изменения fxmanifest.lua

Выполните:

refresh
ensure my_resource

Обычный restart может не перечитать изменения манифеста так, как ожидается после добавления новых файлов или изменения структуры.

Запуск ресурса через server.cfg

Чтобы ресурс запускался вместе с сервером, добавьте:

ensure my_resource

Не дублируйте одну строку в нескольких конфигурационных файлах. Проверьте, не выполняется ли дополнительный файл:

exec resources.cfg
exec framework.cfg

Resource started дважды

Повторный ensure обычно не создаёт второй независимый экземпляр, но дублирование конфигурации усложняет порядок запуска и поиск ошибок.

Храните ресурсы по разделам:

# Основные ресурсы
ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager

# База данных
ensure oxmysql

# Framework
ensure es_extended

# Дополнения
ensure esx_job
ensure esx_inventory

Правильный порядок запуска ресурсов

Ресурс, предоставляющий функции, exports или базу данных, должен запуститься раньше скрипта, который их использует.

Пример общего порядка:

ensure oxmysql
ensure framework_core
ensure framework_inventory
ensure framework_target
ensure custom_jobs
ensure custom_scripts
ensure maps
ensure vehicles

Почему порядок важен

Если job-скрипт запускается раньше ESX или QBCore, он может получить nil вместо объекта framework. Если скрипт выполняет SQL-запрос до запуска oxmysql, появится ошибка export или отсутствующего объекта MySQL.

Зависимость уже указана в манифесте

Директива dependency требует загрузить другой ресурс раньше текущего. Тем не менее порядок в server.cfg должен оставаться понятным и последовательным, особенно для больших framework-сборок.

Что такое fxmanifest.lua

fxmanifest.lua находится в корне каждого ресурса и сообщает FXServer:

• для какой игры предназначен ресурс;
• какие скрипты выполняются на клиенте;
• какие скрипты выполняются на сервере;
• какие файлы выполняются на обеих сторонах;
• какие файлы нужно передать игроку;
• какая HTML-страница является NUI;
• какие ресурсы должны запускаться раньше;
• какие игровые метафайлы необходимо подключить;
• является ли ресурс картой.

Старые ресурсы могут использовать __resource.lua. Такой формат считается устаревшим. Простое переименование файла без переноса корректных директив не всегда достаточно.

Базовый пример fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

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

shared_scripts {
 'config.lua'
}

client_scripts {
 'client/main.lua'
}

server_scripts {
 'server/main.lua'
}

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

ui_page 'html/index.html'

dependencies {
 'framework_core'
}

Добавляйте только те директивы, которые действительно нужны ресурсу. Копирование огромного манифеста из другого скрипта может подключить несуществующие файлы и зависимости.

Ошибки синтаксиса fxmanifest.lua

Пропущена запятая

Неправильно:

client_scripts {
 'client/main.lua'
 'client/events.lua'
}

Правильно:

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

Не закрыта фигурная скобка

files {
 'html/index.html',
 'html/app.js'

После последнего элемента должна находиться закрывающая скобка:

files {
 'html/index.html',
 'html/app.js'
}

Использованы неправильные кавычки

Текстовый редактор может заменить обычные кавычки типографскими:

fx_version ‘cerulean’

Используйте:

fx_version 'cerulean'

Файл сохранён как fxmanifest.lua.txt

Включите отображение расширений Windows и убедитесь, что полное имя файла:

fxmanifest.lua

client_scripts и server_scripts

Клиентские файлы выполняются на компьютере игрока:

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

Серверные файлы выполняются внутри FXServer:

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

Серверный файл указан как клиентский

Это может привести к отсутствию серверных функций, попытке вызвать недоступные API или утечке конфигурации клиенту.

Клиентский файл указан как server_script

Сервер не имеет игровых функций, доступных только клиенту, например работы с локальным Ped, камерой или NUI-фокусом.

Пути с шаблонами

client_scripts {
 'client/*.lua',
 'modules/**/client.lua'
}

После добавления нового файла через шаблон выполните refresh и перезапустите ресурс.

Осторожно используйте shared_scripts

shared_scripts выполняются на клиенте и сервере:

shared_scripts {
 'config.lua',
 'shared/*.lua'
}

В них нельзя хранить:

• пароли базы данных;
• секретные API-ключи;
• Discord webhook для закрытых журналов;
• административные токены;
• серверные проверки безопасности;
• данные, которые не должен получать игрок.

Клиент может получить содержимое передаваемых файлов. Закрытые параметры храните в серверном скрипте, переменных окружения или защищённой конфигурации.

Директива files

files добавляет файлы в клиентский пакет ресурса:

files {
 'html/index.html',
 'html/app.js',
 'html/style.css',
 'html/images/*.png'
}

Она нужна для:

• NUI-страниц;
• изображений и шрифтов;
• JSON-конфигураций клиента;
• игровых метафайлов;
• некоторых аудиофайлов;
• файлов, используемых через data_file.

Файл существует, но не загружается игроку

Проверьте:

• указан ли он в files;
• совпадает ли регистр букв;
• правильный ли относительный путь;
• не находится ли он вне папки ресурса;
• перезапущен ли ресурс после изменения манифеста;
• очищен ли клиентский кэш при необходимости.

Как указать зависимости ресурса

dependencies {
 'oxmysql',
 'framework_core',
 'inventory_resource'
}

Или одна зависимость:

dependency 'framework_core'

Ресурс не запустится нормально, если обязательная зависимость:

• отсутствует;
• называется иначе;
• не имеет рабочего манифеста;
• завершается с ошибкой;
• запущена несовместимая версия;
• не предоставляет ожидаемый export.

Директива также может задавать минимальные требования к серверной сборке, OneSync или game build, но такие ограничения следует брать из документации конкретного ресурса.

Ошибка Could not find dependency

Пример:

Could not find dependency es_extended for resource esx_example

Проверьте:

1. Существует ли папка es_extended.
2. Есть ли в ней fxmanifest.lua.
3. Не появилась ли лишняя вложенная папка.
4. Не переименован ли core.
5. Выполнена ли команда refresh.
6. Запускается ли зависимость самостоятельно.
7. Нет ли ошибки в её собственной консоли.

Если зависимость запускается, но текущий ресурс продолжает её не видеть, сравните точное имя папки с записью в dependencies.

Нужно ли добавлять lua54 'yes'

В актуальных серверных сборках FiveM все Lua-скрипты уже используют Lua 5.4. Директива:

lua54 'yes'

считается устаревшей и больше не требуется.

Наличие этой строки обычно не является причиной сбоя старого ресурса, но добавлять её как универсальное решение каждой ошибки не нужно.

Старый скрипт перестал работать

Проверяйте совместимость его кода с Lua 5.4:

• устаревшие функции;
• работу с целыми числами;
• форматирование строк;
• обращение к старым библиотекам;
• неподдерживаемые глобальные переменные;
• версию framework.

Основные ошибки ресурсов FiveM

Правильная структура папки resources

Ресурсы располагаются внутри каталога данных FXServer:

server-data\
├── resources\
│ ├── [cfx-default]\
│ ├── [standalone]\
│ ├── [framework]\
│ ├── [maps]\
│ ├── [vehicles]\
│ └── my_resource\
└── server.cfg

Папки в квадратных скобках являются категориями. Они помогают группировать ресурсы, но сами не считаются отдельным ресурсом без собственного манифеста.

Пример категории:

resources\
└── [jobs]\
 ├── police_job\
 │ ├── fxmanifest.lua
 │ ├── client.lua
 │ └── server.lua
 └── taxi_job\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

В server.cfg можно запустить каждый ресурс отдельно:

ensure police_job
ensure taxi_job

или всю категорию:

ensure [jobs]

Ресурс лежит не в активном server-data

На компьютере может находиться несколько профилей txAdmin и несколько папок resources. Проверьте путь активного профиля и значение каталога данных, из которого запускается текущий server.cfg.

Лишняя вложенная папка после распаковки

Одна из самых частых ошибок:

resources\
└── my_resource-main\
 └── my_resource\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

FXServer проверяет внешний каталог my_resource-main, но манифест находится уровнем ниже.

Правильно:

resources\
└── my_resource\
 ├── fxmanifest.lua
 ├── client.lua
 └── server.lua

Архив содержит README и отдельную папку

Не всегда нужно переносить весь распакованный каталог. Найдите папку, внутри которой непосредственно находятся fxmanifest.lua, скрипты и остальные файлы ресурса.

Проверьте название ресурса

Команда ensure должна использовать точное имя папки:

resources\[standalone]\my-police-script\

Запуск:

ensure my-police-script

Не используйте:

ensure resources/my-police-script
ensure [standalone]/my-police-script
ensure my-police-script-main

если фактическое имя отличается.

Рекомендации по названию

• используйте латинские буквы;
• избегайте пробелов;
• не добавляйте лишние точки;
• не переименовывайте зависимость без изменения обращений к ней;
• сохраняйте имя, ожидаемое exports и другими скриптами;
• на Linux учитывайте регистр символов.

Если скрипт обращается к:

exports['qb-core']:GetCoreObject()

переименование папки qb-core в qbcore нарушит этот вызов.

Команды refresh, ensure, restart и stop

После добавления новой папки выполните в серверной консоли:

refresh

Команда заново сканирует каталог ресурсов и считывает манифесты.

Затем запустите ресурс:

ensure my_resource

Другие команды:

start my_resource
stop my_resource
restart my_resource

После изменения fxmanifest.lua

Выполните:

refresh
ensure my_resource

Обычный restart может не перечитать изменения манифеста так, как ожидается после добавления новых файлов или изменения структуры.

Запуск ресурса через server.cfg

Чтобы ресурс запускался вместе с сервером, добавьте:

ensure my_resource

Не дублируйте одну строку в нескольких конфигурационных файлах. Проверьте, не выполняется ли дополнительный файл:

exec resources.cfg
exec framework.cfg

Resource started дважды

Повторный ensure обычно не создаёт второй независимый экземпляр, но дублирование конфигурации усложняет порядок запуска и поиск ошибок.

Храните ресурсы по разделам:

# Основные ресурсы
ensure mapmanager
ensure chat
ensure spawnmanager
ensure sessionmanager

# База данных
ensure oxmysql

# Framework
ensure es_extended

# Дополнения
ensure esx_job
ensure esx_inventory

Правильный порядок запуска ресурсов

Ресурс, предоставляющий функции, exports или базу данных, должен запуститься раньше скрипта, который их использует.

Пример общего порядка:

ensure oxmysql
ensure framework_core
ensure framework_inventory
ensure framework_target
ensure custom_jobs
ensure custom_scripts
ensure maps
ensure vehicles

Почему порядок важен

Если job-скрипт запускается раньше ESX или QBCore, он может получить nil вместо объекта framework. Если скрипт выполняет SQL-запрос до запуска oxmysql, появится ошибка export или отсутствующего объекта MySQL.

Зависимость уже указана в манифесте

Директива dependency требует загрузить другой ресурс раньше текущего. Тем не менее порядок в server.cfg должен оставаться понятным и последовательным, особенно для больших framework-сборок.

Что такое fxmanifest.lua

fxmanifest.lua находится в корне каждого ресурса и сообщает FXServer:

• для какой игры предназначен ресурс;
• какие скрипты выполняются на клиенте;
• какие скрипты выполняются на сервере;
• какие файлы выполняются на обеих сторонах;
• какие файлы нужно передать игроку;
• какая HTML-страница является NUI;
• какие ресурсы должны запускаться раньше;
• какие игровые метафайлы необходимо подключить;
• является ли ресурс картой.

Старые ресурсы могут использовать __resource.lua. Такой формат считается устаревшим. Простое переименование файла без переноса корректных директив не всегда достаточно.

Базовый пример fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

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

shared_scripts {
 'config.lua'
}

client_scripts {
 'client/main.lua'
}

server_scripts {
 'server/main.lua'
}

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

ui_page 'html/index.html'

dependencies {
 'framework_core'
}

Добавляйте только те директивы, которые действительно нужны ресурсу. Копирование огромного манифеста из другого скрипта может подключить несуществующие файлы и зависимости.

Ошибки синтаксиса fxmanifest.lua

Пропущена запятая

Неправильно:

client_scripts {
 'client/main.lua'
 'client/events.lua'
}

Правильно:

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

Не закрыта фигурная скобка

files {
 'html/index.html',
 'html/app.js'

После последнего элемента должна находиться закрывающая скобка:

files {
 'html/index.html',
 'html/app.js'
}

Использованы неправильные кавычки

Текстовый редактор может заменить обычные кавычки типографскими:

fx_version ‘cerulean’

Используйте:

fx_version 'cerulean'

Файл сохранён как fxmanifest.lua.txt

Включите отображение расширений Windows и убедитесь, что полное имя файла:

fxmanifest.lua

client_scripts и server_scripts

Клиентские файлы выполняются на компьютере игрока:

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

Серверные файлы выполняются внутри FXServer:

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

Серверный файл указан как клиентский

Это может привести к отсутствию серверных функций, попытке вызвать недоступные API или утечке конфигурации клиенту.

Клиентский файл указан как server_script

Сервер не имеет игровых функций, доступных только клиенту, например работы с локальным Ped, камерой или NUI-фокусом.

Пути с шаблонами

client_scripts {
 'client/*.lua',
 'modules/**/client.lua'
}

После добавления нового файла через шаблон выполните refresh и перезапустите ресурс.

Осторожно используйте shared_scripts

shared_scripts выполняются на клиенте и сервере:

shared_scripts {
 'config.lua',
 'shared/*.lua'
}

В них нельзя хранить:

• пароли базы данных;
• секретные API-ключи;
• Discord webhook для закрытых журналов;
• административные токены;
• серверные проверки безопасности;
• данные, которые не должен получать игрок.

Клиент может получить содержимое передаваемых файлов. Закрытые параметры храните в серверном скрипте, переменных окружения или защищённой конфигурации.

Директива files

files добавляет файлы в клиентский пакет ресурса:

files {
 'html/index.html',
 'html/app.js',
 'html/style.css',
 'html/images/*.png'
}

Она нужна для:

• NUI-страниц;
• изображений и шрифтов;
• JSON-конфигураций клиента;
• игровых метафайлов;
• некоторых аудиофайлов;
• файлов, используемых через data_file.

Файл существует, но не загружается игроку

Проверьте:

• указан ли он в files;
• совпадает ли регистр букв;
• правильный ли относительный путь;
• не находится ли он вне папки ресурса;
• перезапущен ли ресурс после изменения манифеста;
• очищен ли клиентский кэш при необходимости.

Как указать зависимости ресурса

dependencies {
 'oxmysql',
 'framework_core',
 'inventory_resource'
}

Или одна зависимость:

dependency 'framework_core'

Ресурс не запустится нормально, если обязательная зависимость:

• отсутствует;
• называется иначе;
• не имеет рабочего манифеста;
• завершается с ошибкой;
• запущена несовместимая версия;
• не предоставляет ожидаемый export.

Директива также может задавать минимальные требования к серверной сборке, OneSync или game build, но такие ограничения следует брать из документации конкретного ресурса.

Ошибка Could not find dependency

Пример:

Could not find dependency es_extended for resource esx_example

Проверьте:

1. Существует ли папка es_extended.
2. Есть ли в ней fxmanifest.lua.
3. Не появилась ли лишняя вложенная папка.
4. Не переименован ли core.
5. Выполнена ли команда refresh.
6. Запускается ли зависимость самостоятельно.
7. Нет ли ошибки в её собственной консоли.

Если зависимость запускается, но текущий ресурс продолжает её не видеть, сравните точное имя папки с записью в dependencies.

Нужно ли добавлять lua54 'yes'

В актуальных серверных сборках FiveM все Lua-скрипты уже используют Lua 5.4. Директива:

lua54 'yes'

считается устаревшей и больше не требуется.

Наличие этой строки обычно не является причиной сбоя старого ресурса, но добавлять её как универсальное решение каждой ошибки не нужно.

Старый скрипт перестал работать

Проверяйте совместимость его кода с Lua 5.4:

• устаревшие функции;
• работу с целыми числами;
• форматирование строк;
• обращение к старым библиотекам;
• неподдерживаемые глобальные переменные;
• версию framework.