Converter Scripts FiveM entre ESX, QBCore e Qbox

Converta um recurso FiveM mapeando suas dependências de framework, inventário e banco de dados, e então testando um fluxo de jogo por vez. Renomear eventos ESX para eventos QBCore não é uma conversão completa. Uma migração de personagem em todo o servidor é um projeto separado.

Antes de alterar o código

Trabalhe em um servidor de desenvolvimento isolado com uma cópia do recurso e um banco de dados descartável. Registre as versões exatas do framework de origem e destino, inventário, biblioteca de direcionamento, biblioteca de UI e licença do recurso. Arquivos protegidos exigem uma versão suportada do autor; a configuração editável sozinha pode não ser suficiente.

1. Inventarie os pontos de integração

Pesquise os arquivos de recurso por ESX, QBCore, qbx_core, exports, RegisterNetEvent, MySQL e nomes de tabelas SQL. Classifique cada correspondência como servidor, cliente ou compartilhada. Liste as entradas esperadas, valores de retorno e comportamento de falha antes de substituí-los.

Por exemplo, um fluxo de loja inclui abrir sua UI, verificar o acesso, ler preços, efetuar pagamento, adicionar inventário e salvar o resultado. Converter apenas sua notificação deixa o comportamento importante inalterado.

2. Mapeie o comportamento explicitamente

Resolva o jogador do framework de destino no servidor no momento da ação. Identificadores ESX e IDs de personagem QBCore/Qbox têm significados diferentes; não gere IDs de personagem a partir de hashes truncados ou sobrescreva identificadores de conta. Mantenha um mapeamento revisado quando os dados existentes precisarem ser movidos.

Escolha a integração de inventário de forma deliberada. Nomes de itens, unidades de peso, tratamento de slots, metadados e verificações de capacidade variam. Não alterne silenciosamente para outro sistema de inventário em caso de falha. Defina a correspondência de dinheiro em espécie, saldos bancários e eventuais moedas ilícitas sem tratar contas distintas como equivalentes.

3. Implemente um pequeno adaptador

Mantenha as chamadas de jogador, trabalho, dinheiro e inventário específicas do framework em um módulo apenas do servidor. Notificações do cliente e callbacks da UI pertencem a um módulo cliente separado. Declare as dependências reais em fxmanifest.lua e inicie-as antes do recurso.

Para Qbox, consulte os exports do servidor e suas diretrizes de compatibilidade. Uma ponte de compatibilidade pode ajudar recursos QB existentes, mas não garante compatibilidade com todos os inventários, consultas de banco de dados ou core modificado.

4. Preserve o limite de confiança

O servidor deve determinar itens permitidos, preços, saldos, permissões de trabalho e conclusão de tarefas recompensadas. Trate cada argumento de evento do cliente como não confiável. Um nome de trabalho sozinho não prova que uma entrega ocorreu; um evento repetido não deve pagar repetidamente. Verifique os resultados de débito e entrega de itens, e defina a compensação quando a segunda ação falhar.

5. Converta o armazenamento de propriedade do recurso

Compare os esquemas instalados de origem e destino antes de escrever uma migração. Use um script separado e versionado para esses esquemas exatos. Preserve os identificadores originais, placas, metadados e uma tabela persistente de correspondências. Informe linhas duplicadas ou sem correspondência em vez de ignorá-las. Não altere via SQL saldos gerenciados pelo framework enquanto estiverem carregados na memória dele.

6. Verifique e libere

1. Teste um personagem novo e um existente: login, a ação convertida, reconexão e reinício do servidor. Verifique a persistência após cada um.
2. Teste permissões negadas, fundos insuficientes, inventário cheio, entrada inválida, solicitações repetidas e desconexões durante a operação. Confirme que nenhum dinheiro ou item não intencional é criado.
3. Compare as linhas do banco de dados e os saldos antes e depois de ações de teste conhecidas. Investigue cada diferença inesperada.
4. Implante os arquivos revisados e qualquer migração necessária durante uma janela de manutenção. Mantenha backups de arquivos/banco de dados correspondentes e um procedimento de reversão que considere as gravações feitas após o lançamento.

Se a conversão falhar

Um export ausente geralmente aponta para o recurso/versão ou ordem de início errados. Um callback que nunca retorna precisa de inspeção tanto do registro quanto da invocação, incluindo argumentos e lado da execução. Itens ausentes podem refletir metadados de inventário ou regras de capacidade. Diagnostique o limite de falha em vez de adicionar shims de compatibilidade amplos.

Documentação de referência

Cfx.re — manifesto de recurso · Cfx.re — segurança do servidor

Uso simultâneo de ESX e QBCore: por que não é viável