Настройка FiveM VS Code: Lua language server, нативы, без ложных предупреждений

Вы открываете совершенно хороший скрипт в VS Code, и это выглядит так:

Undefined global `PlayerPedId`.

Каждый нативный, exports, ESX и QBCore получает жёлтое подчёркивание, и реальные ошибки тонут в шуме. Это руководство настраивает VS Code так, чтобы он понимал FiveM Lua и предупреждал вас только о вещах, которые действительно неправильны.

#Установите Lua language server

В панели расширений установите расширение Lua language server. Широко используемый — это расширение "Lua" от sumneko, которое построено на Lua Language Server (LuaLS). Это даёт вам завершение, переход к определению, переименование и диагностику.

Откройте папку ресурсов как рабочую область (не один файл), чтобы сервер мог видеть каждый скрипт и настройки, которые вы собираетесь добавить.

#Добавьте определения нативов FiveM

LuaLS обычный не имеет представления, что GetEntityCoords принимает. Сообщество поддерживает типизацию для FiveM / CfxLua: набор файлов аннотаций, которые описывают нативы, глобальные Cfx.re и дополнительный синтаксис Lua, который позволяет FiveM. Найдите в панели расширений "CfxLua" или "FiveM natives" или посмотрите дополнение "FiveM" в менеджере дополнений LuaLS и выберите активно поддерживаемый.

С ними установленными вы получаете подписи при вводе:

local ped = PlayerPedId()
local coords = GetEntityCoords(ped)

Наведите курсор на нативный, и параметры и типы возвращаемых значений показываются. Большинство типизаций также включают аннотации exports, lib, если вы добавляете определения ox_lib, и таблицу cache.

Совет: имена расширений и настройки меняются со временем. Если параметр ниже не существует в вашей версии, проверьте собственный README расширения, который всегда более актуален, чем руководство.

#Настройки рабочей области

Создайте .vscode/settings.json в корне папки ресурсов. Это сохраняет настройки с проектом, поэтому все, кто его открывает, получают одно и то же поведение:

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.runtime.nonstandardSymbol": [
    "/**/", "`", "+=", "-=", "*=", "/=", "<<=", ">>=", "&=", "|=", "^="
  ],
  "Lua.diagnostics.globals": [
    "ESX", "QBCore", "Config", "Locales", "PlayerData",
    "lib", "cache", "exports"
  ],
  "Lua.workspace.checkThirdParty": false,
  "Lua.workspace.ignoreDir": [".vscode", "node_modules", "dist"]
}

Что делает каждая часть:

• Lua.runtime.version соответствует lua54 'yes' в вашем fxmanifest.lua.
• nonstandardSymbol сообщает парсеру, что составное присваивание FiveM (x += 1) и хэши обратного апострофа действительны. Без него совершенно хороший код помечается как синтаксическая ошибка.
• Lua.diagnostics.globals перечисляет имена, которые скрипт определяет где-то, где сервер не может отследить. Добавьте свои: ESX, QBCore, таблицу Config из config.lua. Если расширение типизации уже объявляет lib и exports, вы можете удалить их из списка.

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

#Исправьте предупреждения, которые реальны

Некоторые предупреждения редактора делают свою работу:

local players = ESX.GetPlayers()
for i = 1, #player do   -- 'player' is not defined: should be 'players'
end

Превратите Lua.diagnostics.globals в короткий, намеренный список и каждое оставшееся Undefined global — это опечатка или отсутствующая local. Это также самый быстрый способ найти случайные глобальные переменные, которые руководство resmon перечисляет как источник производительности и ошибок.

Для одноразовых случаев встроенный комментарий лучше, чем глобальная настройка:

---@diagnostic disable-next-line: undefined-global
local x = SomeOtherResourceGlobal

#Аннотируйте свой собственный код

LuaLS читает комментарии ---@. Несколько строк делают ваши собственные функции самодокументирующимися и дают вызывающим код автодополнение:

---@param plate string
---@param coords vector3
---@return boolean
local function isPlateNear(plate, coords)
    -- ...
end

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

#Форматировать при сохранении

Установите StyLua (расширение для форматера StyLua) или используйте собственный форматер языкового сервера. Для StyLua добавьте stylua.toml рядом с вашими ресурсами:

column_width = 120
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferSingle"

Затем в настройках VS Code:

{
  "[lua]": {
    "editor.defaultFormatter": "JohnnyMorganz.stylua",
    "editor.formatOnSave": true
  }
}

Проверьте ID форматера в панели расширений, если он не срабатывает. StyLua может не нравиться синтаксис только FiveM, такой как хэши обратного апострофа, поэтому запустите его на копии в первый раз, если ваши скрипты интенсивно их используют.

#Поиск нативов

Редактор сообщает вам сигнатуру; официальный справочник нативов говорит вам, что на самом деле делает нативный, с примечаниями других разработчиков. Страницы нативов находятся на docs.fivem.net/natives, и строка поиска находит нативный по имени или описанию. Две привычки помогают:

• Ищите по тому, что вы хотите, а не по точному имени: "получить ближайший автомобиль", "кость пешехода".
• Сначала прочитайте Cfx.re нативный, затем текст справки GTA V, так как некоторые нативы ведут себя иначе на сборке FiveM.

Для деталей клиента/сервера см. события клиента и сервера и Wait и потоки.

#Чеклист