Guia do Framework Qbox: Instalação, Ponte QBCore e Migração

Qbox é um framework de roleplay FiveM que começou como um fork QBCore e agora fornece suas próprias APIs e recursos principais. Ele mantém uma ponte de compatibilidade para muitos recursos QBCore bem escritos, mas o acesso direto ao banco de dados, o acesso a arquivos internos e comportamentos não suportados são exceções documentadas. Use a receita oficial Qbox txAdmin para uma nova instalação e audite cada recurso antes de uma migração.

Principais conclusões

• Qbox é um framework, não apenas um pacote de utilitários Ox ou uma pasta QBCore renomeada.
• O procedimento oficial atual de instalação usa a receita QBox da categoria de receitas populares no txAdmin.
• A ponte QB pode ajudar com recursos compatíveis, mas não é uma garantia para cada script QBCore.
• A migração inclui configuração, níveis de cargos, conversão do inventário e do banco de dados, além de testes de cada recurso.
• Não há uma classificação universal de desempenho entre Qbox, QBCore e ESX sustentada por fontes.

O que é Qbox

A introdução oficial do Qbox registra a criação do projeto em 27 de setembro de 2022 e descreve sua origem no QBCore. Desde então, o projeto desenvolveu seu próprio núcleo e recursos relacionados. Sua camada de compatibilidade existe para facilitar o uso de muitos recursos QB enquanto as equipes adotam as APIs atuais do Qbox, mas o Qbox deve ser avaliado como seu próprio framework e receita.

O atual qbx_core manifest declara diretamente ox_lib e oxmysql dependências. A receita oficial reúne Qbox e recursos de terceiros selecionados em um stack de partida completo. Como o conteúdo da receita pode mudar, link para a receita atual em vez de congelar uma longa lista de dependências em um tutorial de instalação evergreen.

Instale Qbox através da receita oficial

1. Prepare um ambiente FXServer suportado e abra sua configuração txAdmin embutida.
2. Atenda aos requisitos de banco de dados listados na documentação de instalação atual Qbox.
3. Selecione a receita oficial QBox popular em vez de montar um núcleo parcial manualmente.
4. Complete as variáveis da receita, a configuração do banco de dados e a configuração do servidor usando a documentação atual.
5. Revise a lista de recursos gerada e a ordem de início antes do primeiro início público.
6. Verifique o carregamento de jogadores, a criação de personagens, permissões, persistência e logs em um servidor de teste.

Não substitua os manifests do fornecedor por exemplos encurtados copiados de um guia. Instale as versões oficiais ou da receita e trate seus manifests como parte do contrato de dependência. Quando uma atualização altera um requisito de núcleo ou biblioteca, compare a documentação de lançamento contra cada recurso dependente antes da implantação.

Qbox e a ponte QBCore

O guia de conversão oficial do Qbox explica como a ponte QB suporta a compatibilidade enquanto as APIs são substituídas incrementalmente. O FAQ do Qbox afirma que a maioria dos scripts QBCore bem escritos pode funcionar através dessa ponte, e então identifica exceções importantes: recursos que acessam diretamente tabelas de banco de dados, leem ou modificam arquivos internos do núcleo, ou dependem de comportamentos não suportados podem precisar de alterações.

Comportamento do recurso	Expectativa de migração
Usa APIs QB documentadas cobertas pela ponte	Candidato para teste de ponte; a compatibilidade ainda precisa ser verificada.
Lê tabelas de framework diretamente	Audite consultas e suposições de esquema antes de tocar nos dados ao vivo.
Carrega arquivos internos do núcleo	Refatore para exportações ou módulos suportados onde documentado.
Pressupõe níveis de empregos ou gangues armazenados como texto	Revise os requisitos do Qbox para converter os níveis dos cargos em valores numéricos.
Possui dados de inventário ou de personagem	Use o caminho de conversão documentado e valide cada relação.

Um produto marcado como compatível com QBCore deve, portanto, ser testado contra Qbox como um alvo separado. Pergunte se ele usa apenas APIs cobertas pela ponte documentada, quais sistemas de inventário e alvo ele espera, e se seu SQL supõe um esquema QB que o Qbox não expõe da mesma forma.

Checklist de migração para um servidor QBCore existente

1. Congelar e inventariar: registrar núcleo, banco de dados, inventário, trabalhos, gangues, veículos, moradias, telefones, permissões e recursos personalizados.
2. Fazer backup: criar snapshots restauráveis do banco de dados e recursos antes do trabalho de conversão.
3. Revisar configuração: Qbox documenta alterações nos arquivos de configuração e acesso à API; não copie internos antigos do núcleo sem pensar.
4. Converta os níveis dos cargos e os dados: siga as etapas oficiais atuais para converter os níveis de empregos e gangues em valores numéricos e converter o inventário e o banco de dados.
5. Auditar recursos: classifique cada integração como coberta pelo bridge, adaptável ou incompatível.
6. Teste em etapas: valide personagens, dinheiro, empregos, gangues, inventário, veículos, permissões e comportamento de reconexão.
7. Inspecione as evidências: revise os logs do servidor, do cliente e do banco de dados e compare as contagens dos registros principais antes do cutover.
8. Mantenha o rollback disponível: não altere o único banco de dados de produção com um snippet de conversão genérico.

Escolha o Qbox por razões explícitas

O Qbox se encaixa em um novo servidor que deliberadamente deseja a receita e as APIs atuais do Qbox. Também pode servir a uma equipe QBCore preparada para auditar a compatibilidade do bridge e concluir o trabalho de conversão documentado. É um alvo de migração ruim quando recursos críticos dependem de internos não documentados do core e a equipe não consegue substituí-los ou adaptá-los com segurança.

Não escolha o Qbox porque uma página promete que um inventário, uma biblioteca de banco de dados ou um framework é automaticamente mais rápido. O desempenho depende do conjunto completo de recursos, da carga de trabalho do banco de dados, do comportamento dos jogadores, do artefato e da configuração do servidor. Se o desempenho for um fator de decisão, faça benchmark de ações representativas em ambientes equivalentes e guarde os logs.

Validação em produção

Teste ações bem-sucedidas e negadas, não apenas o caminho ideal. Confirme que as alterações de dinheiro acontecem uma única vez, que as permissões de emprego e gangue rejeitam jogadores não autorizados, que o inventário permanece consistente entre reconexões, que os veículos de propriedade dos jogadores persistem e que as ações administrativas são registradas. As solicitações do cliente devem ser validadas no servidor; um evento acionado pelo cliente não é seguro apenas porque a UI o esconde dos jogadores comuns.

Use a comparação de frameworks para a decisão mais ampla entre ESX/QBCore/Qbox. Ao selecionar no catálogo de scripts pagos de FiveM, comece com QBOX Scripts e verifique os requisitos atuais de framework, bridge, inventário e dependências na página do produto antes da compra.

Posicione o Qbox na decisão de framework

Compare a receita atual do Qbox com o dedicado Guia de arquitetura QBCore e o completo Guia de decisão ESX, QBCore e Qbox antes de converter dados de produção.

Documentação de referência

Fonte: docs.qbox.re · Fonte: docs.qbox.re · Fonte: docs.qbox.re