Como criar um comando /car no FiveM com IA (passo a passo)

Um comando /car que cria um veículo é das primeiras coisas que muitos donos de FiveM querem, e é um bom teste para qualquer IA para FiveM. Ele envolve um script de client, um de server, um manifest, o server.cfg e permissões, e tem uma falha de segurança clássica se for escrito sem cuidado. Este post mostra como pedir isso a um agente que roda junto do seu servidor, o que o agente faz e como conferir o resultado no jogo.

Se você ainda está escolhendo a ferramenta, leia antes o comparativo de IA para FiveM. Os passos abaixo usam o FiveAI, em que um agente trabalha dentro da sua pasta server-data.

Passo 1: descreva em palavras simples

Você não precisa citar arquivos. Diga o que quer, quem pode usar e os limites:

Crie um comando /car. /car sultan cria um Sultan ao meu lado e me coloca no banco do motorista. Só admins podem usar. Se eu digitar um modelo que não existe, me avise.

Os três detalhes desse pedido fazem trabalho de verdade. "Só admins" impede que qualquer jogador crie carros. "Me avise" dá ao comando um caminho de erro. O modelo como argumento faz um único comando servir para qualquer veículo.

Aqui você pode omitir o framework, porque criar um veículo não depende de ESX, QBCore nem Qbox. Mencione quando o pedido envolver dinheiro, empregos ou itens, por exemplo "cobre R$ 500 do jogador quando usar /car".

Passo 2: o que o agente faz

O agente segue a mesma rotina na maioria dos pedidos, e você acompanha no chat e no console ao vivo:

1. Procura primeiro. Olha resources/ e o server.cfg para ver se já existe um comando car. Se existir, avisa e pergunta antes de mexer. O que já existe é seu, então ele não reescreve em silêncio.
2. Cria um resource novo. Funções novas ficam numa pasta própria dentro de resources/[fiveai]/ (aqui car-command), e seus outros scripts não são tocados.
3. Adiciona a linha ensure ao server.cfg para o resource iniciar com o servidor.
4. Configura a permissão. O comando é restrito, então o jogador precisa da permissão command.car. O agente concede a um grupo ou a jogadores específicos, não a todo mundo.
5. Inicia o resource e lê o console. Ele pode pedir seu OK antes de iniciar, porque isso muda o servidor em execução. Depois confere o console em busca de erros.
6. Responde em palavras simples: o que fez, quais arquivos e o que testar.

Um detalhe esperado: uma linha de permissão no server.cfg só vale depois de reiniciar o servidor por completo. O agente não reinicia o servidor por conta própria. Ele avisa que a mudança vale depois que você reiniciar, por exemplo pelo txAdmin.

Passo 3: como fica o resultado

O código exato varia, mas um resultado correto tem este formato. O manifest, fxmanifest.lua:

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

server_script 'server.lua'
client_script 'client.lua'

O script de server registra um comando restrito e valida o argumento:

RegisterCommand('car', function(source, args)
    if source == 0 then return end

    local model = args[1]
    if not model or not model:match('^[%w_]+$') then
        TriggerClientEvent('chat:addMessage', source, { args = { 'car', 'Uso: /car <modelo>' } })
        return
    end

    TriggerClientEvent('fiveai_car:spawn', source, model)
end, true)

O último argumento, true, é o que torna o comando restrito. O script de client confere se o modelo existe, carrega e cria o veículo:

RegisterNetEvent('fiveai_car:spawn', function(modelName)
    local hash = joaat(modelName)
    if not IsModelInCdimage(hash) or not IsModelAVehicle(hash) then
        TriggerEvent('chat:addMessage', { args = { 'car', modelName .. ' não é um veículo.' } })
        return
    end

    RequestModel(hash)
    while not HasModelLoaded(hash) do Wait(0) end

    local ped = PlayerPedId()
    local coords = GetEntityCoords(ped)
    local vehicle = CreateVehicle(hash, coords.x, coords.y, coords.z, GetEntityHeading(ped), true, false)
    SetPedIntoVehicle(ped, vehicle, -1)
    SetModelAsNoLongerNeeded(hash)
end)

E no server.cfg, junto das outras linhas de permissão, o nome do resource e a permissão:

ensure car-command
add_ace group.admin command.car allow

Duas coisas para conferir ao ler o que um agente produziu. O comando é restrito, então um jogador comum não consegue usá-lo, e o nome do modelo é validado antes do uso. Para entender por que isso importa, leia por que o ChatGPT escreve scripts de FiveM quebrados e o guia da skill de segurança do FiveM.

Passo 4: confira no jogo

Não confie num "pronto", nem no do agente. Teste:

1. Reinicie o servidor se o agente disse que a permissão precisa disso, e entre.
2. Rode /car sultan como admin. Um Sultan deve aparecer onde você está e você deve ficar no banco do motorista.
3. Rode /car notacar. Você deve ver um erro no chat e nenhuma falha.
4. Rode /car sultan como jogador comum. Deve ser recusado. É o teste que quase todo mundo pula, e o que importa num servidor ao vivo.
5. Olhe o console. Pergunte ao agente "tem erros no console?" ou abra o console F8 no jogo. Uma inicialização limpa não tem linhas vermelhas do resource novo.

Se algo estiver errado, diga o que viu: "o carro aparece mas não me coloca como motorista" ou "o console diz que o resource não foi encontrado". O agente lê o console e os arquivos e corrige o mínimo. Ele não reescreve o resource.

Adapte ao seu servidor

Quando o comando básico funcionar, amplie uma mudança por vez e peça cada uma:

• "Apague meu veículo anterior do /car quando eu criar outro."
• "Permita só estes modelos: sultan, buffalo, kuruma."
• "Registre cada uso do /car com o nome do jogador."
• "Faça disso um benefício de emprego: só a polícia pode usar." Nesse caso, diga o seu framework ao agente. O guia do ESX e o guia do QBCore mostram as APIs de jogador e emprego que ele deve usar.

Pedidos pequenos e específicos geram mudanças pequenas e fáceis de revisar. Mantenha resources/ no git para poder desfazer qualquer uma.