Configuração VS Code FiveM: servidor de linguagem Lua, natives, sem avisos falsos

Você abre um script perfeitamente bom no VS Code e se parece com isto:

Undefined global `PlayerPedId`.

Todo native, exports, ESX e QBCore recebe um sublinhado amarelo, e erros reais se afogam no ruído. Este guia configura VS Code para que entenda Lua FiveM, e apenas avisa você sobre coisas que estão realmente erradas.

#Instale um servidor de linguagem Lua

No painel Extensões, instale uma extensão de servidor de linguagem Lua. A amplamente utilizada é a extensão "Lua" por sumneko, que é construída em Lua Language Server (LuaLS). Fornece conclusão, ir para definição, renomear e diagnósticos.

Abra sua pasta de recursos como o workspace (não um único arquivo), para que o servidor possa ver cada script e as configurações que você está prestes a adicionar.

#Adicione definições de natives FiveM

Plain LuaLS não tem ideia do que GetEntityCoords recebe. A comunidade mantém typings para FiveM / CfxLua: um conjunto de arquivos de anotação que descrevem os natives, os globals Cfx.re e a sintaxe Lua extra que FiveM permite. Procure no painel Extensões por "CfxLua" ou "FiveM natives", ou procure por um addon "FiveM" no gerenciador de addon LuaLS, e escolha um que seja mantido ativamente.

Com eles instalados, você obtém assinaturas quando digita:

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

Passe o mouse sobre um native e os tipos de parâmetros e retorno aparecem. A maioria das typings também inclui exports, anotações lib se você adicionar as definições ox_lib, e a tabela cache.

Dica: Os nomes das extensões e configurações mudam ao longo do tempo. Se uma configuração abaixo não existir em sua versão, verifique o próprio README da extensão, que é sempre mais atual que um tutorial.

#Configurações do workspace

Crie .vscode/settings.json na raiz de sua pasta de recursos. Isso mantém as configurações com o projeto, portanto todos que o abrem obtêm o mesmo comportamento:

{
  "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"]
}

O que cada parte faz:

• Lua.runtime.version corresponde a lua54 'yes' em seu fxmanifest.lua.
• nonstandardSymbol diz ao analisador que o operador de atribuição composta FiveM (x += 1) e hashes de backtick são válidos. Sem isso, código perfeitamente bom é sinalizado como erro de sintaxe.
• Lua.diagnostics.globals lista nomes que o script define em algum lugar que o servidor não consegue rastrear. Adicione o seu próprio: ESX, QBCore, uma tabela Config de config.lua. Se uma extensão typings já declara lib e exports, você pode removê-los da lista.

Adicione apenas globals reais. Se você silenciar tudo, você perde o aviso que pega uma variável digitada incorretamente, que é uma das melhores coisas que o editor faz por você.

#Corrija os avisos que são reais

Alguns avisos são o editor fazendo seu trabalho:

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

Transforme Lua.diagnostics.globals em uma lista curta e deliberada e cada Undefined global restante é um erro de digitação ou um local ausente. Essa também é a maneira mais rápida de encontrar globals acidentais, que o guia resmon lista como uma fonte de performance e bug.

Para casos únicos, um comentário inline é melhor que uma configuração global:

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

#Anote seu próprio código

LuaLS lê comentários ---@. Algumas linhas tornam suas próprias funções autodocumentadas e fornecem conclusão aos chamadores:

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

Se você construir uma biblioteca que outros scripts chamam através de exports, colocar essas anotações nas funções exportadas compensa mais.

#Formate ao salvar

Instale StyLua (a extensão para o formatter StyLua) ou use o próprio formatter do servidor de linguagem. Para StyLua, adicione um stylua.toml próximo aos seus recursos:

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

Então nas configurações do VS Code:

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

Verifique a ID do formatter no painel Extensões se não disparar. StyLua pode não gostar de sintaxe apenas de FiveM, como hashes de backtick, portanto execute em uma cópia primeiro se seus scripts os usarem muito.

#Procure os natives

O editor lhe diz a assinatura; a referência de natives oficial lhe diz o que o native realmente faz, com notas de outros desenvolvedores. As páginas de natives estão em docs.fivem.net/natives, e a caixa de busca encontra um native por nome ou descrição. Dois hábitos ajudam:

• Procure pelo que você quer, não o nome exato: "get closest vehicle", "ped bone".
• Leia o native Cfx.re primeiro, depois o texto de referência GTA V, pois alguns natives se comportam diferentemente na compilação FiveM.

Para detalhes de cliente/servidor, veja eventos de cliente e servidor e Wait e threads.

#Checklist