Como instalar script FiveM: ESX, QBCore, Qbox e standalone

Se você quer saber como instalar script FiveM, a resposta curta é: baixar, copiar a pasta e dar ensure. Na prática, quando o recurso não sobe, o console enche de erros vermelhos ou o script funciona pela metade, o problema quase sempre está em um de quatro lugares: a estrutura de pastas, o ensure do server.cfg, o fxmanifest.lua ou uma dependência que falta. Neste tutorial você vê o processo completo, as diferenças entre frameworks e os erros típicos com solução, para instalar qualquer recurso em dois minutos e não em duas horas.

A pasta resources e como organizá-la

Todo recurso do FiveM fica dentro da pasta resources do servidor, e cada script é uma pasta com um fxmanifest.lua na raiz. Se o manifest estiver um nível abaixo, por causa de uma pasta dupla ao extrair o zip, o recurso nem aparece na lista. Use nomes simples, sem espaços nem caracteres especiais.

Em instalações com txAdmin, a pasta fica dentro dos seus dados do servidor, por exemplo server-data/resources. A estrutura costuma ser assim:

resources/
├── [standalone]/
│   ├── ox_lib/
│   └── oxmysql/
├── [qb]/
│   ├── qb-core/
│   └── qb-inventory/
└── meu_script/
    ├── fxmanifest.lua
    ├── client/
    ├── server/
    └── config.lua

Duas regras de ouro ao copiar um script novo:

• Cuidado com a pasta dupla. Ao extrair um zip é comum terminar com meu_script/meu_script/fxmanifest.lua. O FiveM procura o manifest na raiz da pasta do recurso: se ele estiver um nível mais fundo, o recurso não é reconhecido.
• Nada de espaços ou caracteres estranhos no nome. meu script v2 (final) é receita para erro. Use nomes simples: meu_script.

As pastas entre colchetes, como [standalone] ou [qb], são só categorias de organização: o FiveM varre o conteúdo delas atrás de recursos, mas elas mesmas não são recursos.

Como adicionar o script no server.cfg com ensure?

Para o servidor iniciar um script, você precisa declarar ensure nome_da_pasta no server.cfg. O nome é o da pasta do recurso, não o do zip nem o nome comercial, e as dependências devem vir antes de quem as usa. Copiar a pasta sozinho não basta.

ensure oxmysql
ensure ox_lib
ensure qb-core
ensure meu_script

Se o meu_script precisa do ox_lib, a linha do ox_lib tem que vir antes. Você também pode subir uma categoria inteira com ensure [qb], útil quando há muitos recursos agrupados.

Um truque para não reiniciar o servidor a cada teste: pelo console (ou pelo txAdmin) você roda ensure meu_script com o servidor ligado para iniciar ou reiniciar só aquele recurso. Se o servidor ainda nem existe, comece pelo guia de como criar servidor FiveM passo a passo.

Como entender o fxmanifest.lua?

O fxmanifest.lua é a ficha técnica do recurso: diz ao FXServer quais arquivos carregar e onde executar cada um (client, server ou ambos). Saber ler o manifest mostra de relance o que o script precisa para funcionar, mesmo que você raramente precise editá-lo. Um manifest moderno é assim:

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

author 'Cube Resources'
description 'Exemplo de manifest moderno'
version '1.0.0'

shared_scripts {
    '@ox_lib/init.lua',
    'config.lua',
}

client_scripts {
    'client/*.lua',
}

server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/*.lua',
}

dependencies {
    'ox_lib',
    'oxmysql',
}

O essencial de cada bloco:

• fx_version 'cerulean' é a versão atual do manifest. Se você vê __resource.lua no lugar de fxmanifest.lua, o recurso é antiquíssimo: pode até rodar, mas é sinal de alerta sobre a qualidade dele.
• shared_scripts rodam no client e no server (típico para configs), client_scripts só no client e server_scripts só no server. Uma native de client em script de server gera o clássico “attempt to call a nil value”.
• O prefixo @ importa um arquivo de outro recurso: @ox_lib/init.lua carrega a biblioteca do ox_lib dentro deste script. Por isso o ox_lib precisa estar instalado e iniciado antes.
• dependencies declara quais recursos precisam existir e estar iniciados; se faltar algum, o servidor se recusa a subir o recurso e avisa no console.

Dependências e ordem de inicialização

A maioria dos scripts modernos depende de dois ou três recursos base: oxmysql para banco de dados, ox_lib para interface e utilidades e, às vezes, um inventário específico como o ox_inventory. A documentação do script sempre lista essas dependências. Instale-as primeiro e coloque-as antes no server.cfg.

Uma ordem de inicialização saudável fica assim: primeiro o banco de dados (oxmysql), depois as bibliotecas (ox_lib), depois o core do framework (qb-core, es_extended ou qbx_core), depois inventário e módulos do framework e, no fim, os scripts de terceiros. Se o inventário ainda é uma decisão em aberto, o guia do melhor inventário para FiveM compara as opções mais usadas.

O que muda ao instalar em ESX, QBCore, Qbox e standalone?

O processo mecânico é o mesmo em qualquer framework: pasta em resources, dependências e ensure. O que muda é a integração, como o config.lua, arquivos SQL e os nomes de recursos que o script espera encontrar. Scripts standalone são os mais simples, pois não dependem de framework.

• ESX Legacy: os scripts costumam trazer um config.lua para ajustar empregos, preços e permissões e, às vezes, um arquivo .sql que você precisa importar no banco antes da primeira inicialização. Confirme que o script pede ESX Legacy e não versões antigas (1.2 ou anteriores), cujos eventos não existem mais.
• QBCore: parecido, com a particularidade de que muitos recursos esperam nomes específicos de outros recursos qb (por exemplo qb-target ou qb-menu). Se você renomeou pastas do core, vai ter que ajustar as configs.
• Qbox: compatível com boa parte do ecossistema QBCore por meio de bridges, mas confira sempre se o script declara suporte a qbx_core.
• Standalone: a instalação mais limpa, sem framework no meio. No máximo, dependência do ox_lib. Ideal para HUDs, loading screens e utilidades.

Muitos scripts de qualidade são multiframework: detectam o framework ao iniciar ou deixam você escolher no config. Se ainda tem dúvida sobre qual base é melhor a longo prazo, a comparação QBCore vs ESX vs Qbox ajuda a decidir, e você pode explorar os scripts para QBCore, ESX e Qbox.

Como instalar script FiveM com escrow?

Instalar um script com escrow é igual a instalar um script aberto: mesma pasta, mesmo ensure. A diferença é que parte dos arquivos vai cifrada e só roda em servidores cuja chave de licença pertence à conta do Keymaster que comprou o asset. Os únicos arquivos editáveis são os que o autor deixou de fora do cifrado.

Na prática, duas observações:

• Você precisa ter comprado com a mesma conta Cfx.re que gera a licença do seu servidor.
• Só dá para editar os arquivos que o autor deixou fora da cifragem (normalmente o config.lua e pastas marcadas como editáveis).

Se o console mostrar erros de autorização ao iniciar um recurso cifrado, o problema quase sempre é a conta ou a chave, e não o script. Para entender conta, licença e asset grants, veja o guia do Keymaster FiveM.

Quais são os erros mais comuns e como ler o console?

O console do servidor (ou a aba Live Console do txAdmin) diz exatamente o que falhou, basta ler com calma. Os três erros mais comuns são recurso que não aparece, erro de fx_version e dependência faltando, e cada um tem uma causa direta e uma correção simples.

• O recurso não sobe e nem aparece: quase sempre é pasta dupla após extrair, nome com espaços ou fxmanifest.lua ausente. A mensagem típica é Couldn't find resource meu_script.
• Erro de fx_version: mensagens como resource is not compatible ou reclamações sobre o manifest indicam recurso velho ou manifest corrompido. Confira se existe fx_version 'cerulean' (ou ao menos uma versão válida) e game 'gta5'.
• Dependência faltando: Could not start dependency ox_lib for resource meu_script significa exatamente isso: instale a dependência ou corrija a ordem dos ensure.

Diante de qualquer erro de script em vermelho, a primeira linha da mensagem aponta arquivo e linha exatos (@meu_script/server/main.lua:42). Com isso você já sabe se a falha está na sua config (o mais comum) ou no código do recurso.

Instalar direito é só metade do trabalho: a outra metade é escolher scripts que valham a pena. Se está montando a base do servidor, vale ver também a lista dos melhores scripts para FiveM.