Como adicionar scripts e recursos FiveM sem erro

Adicionar resources no FiveM parece trivial até o servidor não subir, o console mostrar Couldn't load resource ou um script novo derrubar o framework inteiro. A maior parte dos erros não vem do resource em si — vem de estrutura de pastas errada, fxmanifest inválido, ordem incorreta no server.cfg ou conflito com outro script.

Este guia é pra quem opera um servidor FiveM próprio (Windows ou Linux), já tem framework instalado (ESX ou QBCore) e quer adicionar scripts da comunidade ou pagos sem quebrar nada. Tempo estimado: 10 a 15 minutos por resource bem testado.

Pré-requisitos

Se o seu servidor está em uma VPS Linux, conecte via SSH antes. Em Windows, conecte via RDP e abra um terminal PowerShell na pasta do servidor.

Entendendo a estrutura de um resource

Antes de adicionar qualquer coisa, vale conhecer o que o FXServer espera. Um resource FiveM válido é uma pasta dentro de resources/ (ou em subpastas com prefixo [categoria]) que contém pelo menos um fxmanifest.lua no diretório raiz. Sem esse arquivo, o FXServer ignora o resource — não importa quantos .lua ou .js estejam dentro.

A estrutura típica:

resources/
└── [scripts]/
    └── meu-resource/
        ├── fxmanifest.lua
        ├── client.lua
        ├── server.lua
        ├── config.lua
        └── html/
            ├── index.html
            ├── style.css
            └── script.js

Pastas com colchetes ([scripts], [esx], [qb]) são apenas organização visual — o FXServer faz varredura recursiva. Você pode aninhar até 2-3 níveis sem problema. Evite mais que isso pra não dificultar manutenção.

O fxmanifest.lua mínimo

Todo resource precisa declarar versão da API e jogo alvo. O arquivo mínimo viável:

fx_version 'cerulean'
game 'gta5'

author 'Nome do autor'
description 'Descrição curta'
version '1.0.0'

client_scripts {
  'client.lua'
}

server_scripts {
  'server.lua'
}

shared_scripts {
  'config.lua'
}

fx_version 'cerulean' é o valor atual recomendado (suporta features modernas do FiveM). Versões antigas como adamant ou bodacious ainda funcionam mas perdem capacidades.

Adicionando um resource passo a passo

scp -r meu-resource/ usuario@ip-do-servidor:/path/to/server-data/resources/[scripts]/

ls /path/to/server-data/resources/[scripts]/meu-resource/

ensure meu-resource

# Frameworks primeiro
ensure qb-core

# Bibliotecas e dependências
ensure ox_lib
ensure oxmysql

# Scripts de gameplay
ensure qb-multicharacter
ensure qb-spawn
ensure meu-resource

refresh
ensure meu-resource

Started resource meu-resource

Verificando que tudo está funcionando

No console do servidor, rode resources pra ver a lista completa de resources ativos. O nome do seu resource deve aparecer com status started. Se aparecer como stopped, ele foi reconhecido mas não está rodando — verifique o ensure no server.cfg.

Pra testar funcionalmente, entre no servidor com seu client FiveM. Scripts client-side reagem geralmente a comandos (/comando), itens no inventário ou eventos automáticos. Abra o console F8 do client (~ ou F8) — erros Lua ou JavaScript do lado client aparecem ali com stack trace.

Resolução de problemas comuns

”Couldn’t load resource X”

Quase sempre é um fxmanifest.lua ausente ou inválido. Verifique:

• O arquivo se chama exatamente fxmanifest.lua (minúsculas, com .lua)
• Tem fx_version 'cerulean' e game 'gta5' declarados
• Sintaxe Lua válida (vírgulas e aspas equilibradas)

Se o arquivo está correto, confirme que o nome da pasta bate exatamente com o ensure no server.cfg. Em Linux, MeuResource e meuresource são pastas diferentes — case-sensitive.

”Error loading script” com erro Lua

O console mostra a linha exata do erro. Causas frequentes:

• Variável de framework usada antes do framework carregar (ordem errada no server.cfg)
• Dependência ausente (exports['ox_lib'] chamado sem ox_lib rodando)
• Sintaxe Lua quebrada por edição manual

Pra isolar: comente o resource no server.cfg, reinicie, e adicione um por vez até reproduzir o erro.

Servidor crasha ao iniciar

Comente todos os ensure exceto os core (mapmanager, chat, spawnmanager, sessionmanager, framework). Reinicie. Se subir sem crash, adicione resources um a um até identificar o culpado. Esse processo demora mas é o único confiável quando o erro acontece muito cedo no boot.

Conflito entre dois scripts no mesmo evento

Dois resources que registram handler para o mesmo evento (AddEventHandler('playerSpawned', ...)) podem competir pela ordem de execução. O FiveM não garante ordem entre handlers do mesmo evento em resources diferentes. Solução: defina explicitamente dependência no fxmanifest.lua do resource que precisa rodar depois:

dependencies {
  'outro-resource'
}

Isso garante que outro-resource carregue primeiro.

Próximos passos

Com a estrutura limpa e resources rodando estável, vale aprofundar em:

• Otimização de scripts: identificar resources que consomem muito CPU usando resmon no client (Shift+~). Resources acima de 1.0ms client-side merecem revisão.
• Backup automatizado de resources: versionar a pasta resources/ em Git privado evita perda quando você quebra algo testando.
• Whitelist de scripts: em servidores roleplay, manter uma lista curada de resources aprovados reduz superfície de bug e exploit.
• Banco de dados separado por categoria: scripts pesados (jobs, inventário) podem usar databases isoladas pra reduzir contenção.

Se você está rodando FiveM em produção com 32+ slots e quer infraestrutura que aguenta latência baixa para o Brasil, os servidores de jogos da Hostini entregam latência abaixo de 30ms pra todo o Sudeste com proteção DDoS já incluída no preço.