Instalas scripts FiveM colocando o recurso na pasta resources/, iniciando-o na server.cfg com ensure e carregando antes dependências como ESX, QBCore ou drivers de base de dados. O essencial é uma estrutura de pastas limpa, a ordem de arranque correta, uma importação SQL verificada e uma olhada à consola do servidor depois do reinício.
Pré-requisitos
Precisas de acesso aos ficheiros do servidor, à server.cfg, à consola do servidor e, se o script usar tabelas de base de dados, à tua base de dados MySQL ou MariaDB. Num servidor FiveM alugado, isso normalmente inclui um gestor de ficheiros, FTP/SFTP e uma ferramenta de base de dados como phpMyAdmin ou Adminer. Se ainda estás a planear o servidor completo, o guia interno Alugar e configurar um servidor FiveM ajuda com a estrutura básica.
Tecnicamente, o FiveM chama recursos aos scripts. Segundo a documentação oficial da Cfx.re, o fxmanifest.lua descreve que ficheiros, scripts e metadados pertencem a um recurso. Por isso, verifica sempre primeiro se a pasta extraída contém um ficheiro de manifesto válido. Sem manifesto, o servidor não consegue carregar o recurso corretamente.
Verificar a estrutura do script
Um recurso FiveM típico tem este aspeto:
meu_script/
├── fxmanifest.lua # Ficheiro de manifesto
├── client.lua # Código do cliente
├── server.lua # Código do servidor
├── config.lua # Configuração
└── html/ # NUI (interface web)
É importante não carregares acidentalmente uma pasta extra de empacotamento. Por exemplo, resources/meu_script-main/meu_script/fxmanifest.lua estaria errado se o recurso devesse ficar diretamente em resources/meu_script/fxmanifest.lua. Depois de extrair, abre a pasta e confirma o nível onde está o fxmanifest.lua.
Instalar o script
- Transferir o script
- Extrair para a pasta
resources/ - Adicionar à
server.cfg:
ensure meu_script
- Reiniciar o servidor
Usa como nome do recurso exatamente o nome da pasta ou o nome indicado no README. Muitos erros surgem por grafias diferentes, espaços no nome da pasta ou caracteres especiais. O recomendado são nomes curtos com letras minúsculas, hífenes ou underscores.
Configurar scripts ESX
Os scripts ESX dependem de a base ESX e os recursos adicionais necessários serem iniciados antes. A ordem concreta pode variar conforme a versão do ESX e o script, por isso a regra é: verifica o README do script e respeita a documentação existente do framework.
# Base ESX
ensure es_extended
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_list
# Trabalhos
ensure esx_policejob
ensure esx_ambulancejob
ensure esx_mechanicjob
ensure esx_taxijob
# Funcionalidades
ensure esx_banking
ensure esx_vehicleshop
ensure esx_property
Se um script de trabalho esperar tabelas de base de dados ou itens próprios, importa o ficheiro SQL incluído antes do primeiro arranque em produção. Faz antes uma cópia de segurança da base de dados. Em servidores de roleplay existentes, ficheiros SQL podem sobrescrever colunas, itens ou trabalhos se não estiverem ajustados à tua instalação.
Configurar scripts QBCore
Os recursos QBCore seguem um princípio semelhante: primeiro o framework, depois bibliotecas partilhadas e, em seguida, inventário, trabalhos, garagens, Phone ou HUD. Um exemplo simples:
ensure qb-core
ensure qb-policejob
ensure qb-ambulancejob
ensure qb-garages
ensure qb-inventory
ensure qb-phone
Verifica sobretudo ficheiros de configuração como config.lua, shared/config.lua ou ficheiros de itens específicos do framework. Alguns scripts QBCore esperam entradas em Items, Jobs, Gangs ou Permissions. Introduz apenas valores documentados pelo script. Se quiseres planear recursos, txAdmin e operação do servidor num contexto mais amplo, lê também Alugar servidor FiveM: configurar GTA RP, recursos e txAdmin 2025.
Respeitar a ordem de arranque
A ordem de arranque é importante:
- Framework primeiro (ESX/QBCore)
- Dependencies (oxmysql, etc.)
- Scripts base (inventário, HUD)
- Scripts de trabalho
- Scripts cosméticos (emotes, roupa)
Coloca as Dependencies usadas em conjunto o mais centralmente possível e antes de todos os recursos dependentes. Se vários scripts exigirem a mesma biblioteca, ela deve ser iniciada apenas uma vez. Com ligação à base de dados, o driver da base de dados tem de estar em execução antes de os recursos enviarem consultas SQL.
Fontes gratuitas de scripts
| Fonte | Descrição |
|---|---|
| GitHub | Scripts open-source |
| Fórum cfx.re | Scripts da comunidade |
| Overextended | Open-source de alta qualidade |
Transfere scripts apenas de fontes onde seja possível verificar código, changelog ou feedback da comunidade. Em downloads desconhecidos, presta especial atenção a código Lua ofuscado, pedidos HTTP inexplicáveis, webhooks externos e tokens codificados diretamente. Instala novos recursos primeiro numa instância de teste ou fora dos horários principais de jogo.
Verificar o resultado
Reinicia o servidor e observa a consola. Um recurso carregado corretamente aparece sem erros de manifesto, dependência ou SQL. No jogo, testa depois exatamente a função que o script disponibiliza: menu de trabalho, interação com inventário, marcador, comando, janela NUI ou alteração na base de dados. Testa com os cargos e permissões que os jogadores reais usarão mais tarde.
Usa adicionalmente refresh e ensure meu_script na consola do servidor apenas para testes controlados. Para alterações em produção, um reinício limpo costuma ser mais expressivo, porque reproduz a ordem de arranque completa.
Resolução de problemas
SCRIPT ERROR
Verifica primeiro a linha na consola. Muitas vezes falta uma Dependency, uma variável de configuração está mal definida ou uma função exportada é chamada antes do arranque do recurso de destino. Compara a mensagem de erro com o README do script.
Erro SQL
Importa as tabelas ou colunas incluídas, caso o script as exija. Se as tabelas já existirem, não executes SQL novamente às cegas. Cria uma cópia de segurança e ajusta as instruções à estrutura existente da tua base de dados.
O script não carrega
Confirma o nome da pasta, a entrada ensure e o fxmanifest.lua. Um erro de digitação no ficheiro de manifesto ou uma pasta mal aninhada basta para impedir o recurso de arrancar.
A função não aparece no jogo
Verifica permissões, trabalhos, itens, coordenadas e versão do framework. Muitos scripts de roleplay funcionam apenas para determinados trabalhos ou grupos. Por isso, não testes apenas como admin, mas também com um perfil normal de jogador.
Verificação, limites e caminho seguro de retorno
O guia “Instalar scripts no servidor FiveM – ESX e QBCore” aplica-se ao tipo de servidor descrito no artigo e ao estado de versões visível no momento da verificação. Nomes de menus, versões disponíveis, compatibilidade de mods ou plugins e recursos necessários podem mudar depois de atualizações. Por isso, não transfiras valores para outra versão de jogo, loader ou servidor sem os verificar.
Antes de alterares o mundo, o estado de jogo, a configuração ou extensões, cria uma cópia de segurança dos ficheiros afetados. Depois altera apenas um passo relacionado de cada vez e verifica-o com a mesma versão de cliente e servidor com que queres jogar mais tarde.
| Ponto de verificação | Resultado esperado | Cancelamento e retorno |
|---|---|---|
| Arranque do servidor | O servidor chega ao estado operacional sem nova mensagem de erro. | Em caso de erros de arranque, desfazer a alteração e repor a última cópia de segurança. |
| Teste de ligação | Uma conta de teste consegue ligar através do endereço mostrado no painel. | Em caso de erros de versão ou ligação, voltar a comparar versão, porta e permissões. |
| Teste funcional | A função alterada em concreto funciona sem danificar dados existentes do mundo ou do jogo. | Em caso de efeitos secundários, parar o servidor e restaurar os ficheiros guardados. |
Um teste individual bem-sucedido não garante desempenho nem disponibilidade. Tamanho do mundo, mods, plugins, número de jogadores, rota de rede e carga simultânea podem alterar o resultado. Documenta versão, alteração e resultado do teste para conseguires compreender desvios posteriores.
FAQ
Tenho de reiniciar o servidor após cada script?
Para um teste fiável, sim. Recursos individuais podem ser recarregados pela consola, mas um reinício completo mostra se a ordem de arranque e todas as Dependencies estão mesmo corretas.
Posso usar ESX e QBCore ao mesmo tempo?
Na prática, deves escolher um framework. Muitos scripts são claramente feitos para ESX ou QBCore e esperam eventos, tabelas e estruturas de configuração diferentes.
O que faço se um script não tiver fxmanifest.lua?
Então pode estar desatualizado, mal extraído ou não preparado para estruturas atuais de recursos FiveM. Verifica a fonte e a documentação antes de o instalares em produção.
Devo testar scripts gratuitos diretamente no servidor live?
Melhor não. Testa novos recursos primeiro separadamente, faz cópia de segurança dos ficheiros e da base de dados e verifica a consola. Especialmente em servidores de roleplay, scripts com erros podem afetar inventário, trabalhos ou progresso dos jogadores.
Quantos scripts pode usar um servidor FiveM?
Não existe um número geral que faça sentido. O que conta é a qualidade dos scripts, dependências, carga da base de dados, comportamento por tick e número de jogadores. Planeia recursos conscientemente e remove scripts não utilizados de forma consistente.