QBCore, ESX ou standalone: como Agency Scripts funciona com seu framework

O problema da compatibilidade com frameworks

A maioria dos scripts de FiveM vem com um framework definido diretamente no código. Se você usa QBCore, precisa usar scripts QBCore. Quem usa ESX fica limitado a scripts ESX. Já quem usa standalone geralmente precisa improvisar. Os scripts da Agency Scripts foram criados com a filosofia oposta: o framework é um adaptador, não uma premissa.

O padrão Adapter

Cada script da Agency expõe um pequeno conjunto de funções de consulta: getPlayerData, getInventory, addMoney, removeItem, getJob. Disponibilizamos adaptadores que conectam essas funções às implementações de QBCore e ESX. Para standalone, você implementa as quatro ou cinco funções por conta própria, o que geralmente leva uma manhã de trabalho, e todos os scripts da Agency passam a ser compatíveis.

O que isso significa na prática

Quando você muda seu servidor de QBCore para ESX, algo que acontece a cada poucos anos conforme os frameworks evoluem, os scripts da Agency não precisam ser reinstalados nem reconfigurados. Você troca o adaptador e todo o resto continua funcionando. Isso é extremamente raro no ecossistema FiveM e é o principal motivo pelo qual os proprietários de servidores padronizam nossas ferramentas para o longo prazo.

O que significam os rótulos de framework nas páginas dos nossos produtos

Quando uma página de produto lista "QBCore, ESX", significa que fornecemos adaptadores prontos para ambos. Quando diz "Standalone", significa que o script é independente de framework, não precisa de adaptador e funciona em qualquer servidor. Na prática, quase todos os scripts da Agency podem ser usados em configurações standalone com uma pequena camada de compatibilidade.

Quando perguntar antes de comprar

Se você usa uma configuração incomum, um framework personalizado, um QBCore muito modificado ou algo sob medida, abra um chamado no nosso Discord antes de comprar. Vamos dizer com honestidade o que vai funcionar, o que precisa de uma pequena adaptação e o que não vale a pena. Sem pressão para comprar, preferimos que você compre um script adequado às suas necessidades em vez de três que não sejam.

Como o padrão de adaptadores funciona na prática

Quando você instala um script da Agency, a pasta do recurso contém um framework subdiretório com pelo menos três arquivos: qb.lua, esx.luae standalone.lua. O script principal detecta automaticamente qual framework está presente, verificando o export do QBCore ou do ESX. O arquivo do adaptador correspondente é carregado, os outros não. Essa detecção automática acontece antes de qualquer lógica de jogo ser executada, sem sobrecarga em tempo de execução pela detecção do framework.

Cada adaptador implementa a mesma interface interna. Se um script precisa dar dinheiro a um jogador, ele chama Framework.AddMoney(src, amount) internamente. Essa função em qb.lua chama o export de dinheiro do QBCore; em esx.lua ela chama o sistema de contas do ESX; em standalone.lua ela chama a função que você definiu em config.lua. Uma chamada, três implementações, nenhuma alteração no script ao mudar de framework.

Instalação no QBCore

Para servidores QBCore, a instalação geralmente tem três etapas: baixar o recurso, colocá-lo na pasta resources e adicioná-lo ao server.cfg. A detecção do framework é automática. Se você usa um QBCore significativamente modificado, com sistema de dinheiro, inventário ou empregos personalizados, talvez precise substituir funções específicas do adaptador em config.lua em vez de editar qb.lua diretamente. A abordagem de substituição pela configuração significa que você não perderá suas alterações nas atualizações do recurso.

Instalação no ESX

A instalação no ESX segue o mesmo padrão. Às vezes, é necessário realizar uma etapa adicional: se sua versão do ESX for significativamente antiga, anterior à 1.7, algumas funções do adaptador fazem referência a nomes de exports mais recentes do ESX. O recurso inclui uma opção de compatibilidade com versões antigas Config.ESXLegacy = true que alterna para chamadas da API antiga do ESX em todos os scripts da Agency que precisam dela.

Instalação em Standalone

Historicamente, é no modo standalone que a maioria dos proprietários de servidores encontra dificuldades com outros scripts. O suporte standalone da Agency Scripts é explícito e bem documentado. Para cada script, o arquivo do adaptador standalone lista exatamente quais funções você precisa implementar. A maioria dos scripts precisa de quatro a oito funções. Cada função tem um comentário explicando o que deve retornar. Uma implementação standalone típica leva de uma a três horas, dependendo da complexidade do seu sistema personalizado de dados dos jogadores.

Depois de implementar o adaptador para um script da Agency, os seguintes levam bem menos tempo, pois as mesmas funções personalizadas costumam ser aplicáveis a vários recursos.

Por que isso importa para a operação do servidor a longo prazo

Os frameworks FiveM não são permanentes. Servidores que estão em operação há três anos ou mais provavelmente já passaram por pelo menos uma mudança importante de framework, talvez migrando de uma versão derivada do ESX mantida pela comunidade para o ESX principal, ou de uma versão antiga do QBCore para a atual. Servidores que dependem de scripts vinculados ao framework pagam um alto custo de migração: cada script precisa ser atualizado ou substituído quando o framework muda significativamente.

A arquitetura de adaptadores da Agency Scripts significa que uma migração de framework afeta apenas a camada do adaptador. Os dados do Agency-Phone, os registros do Agency-Admin, o histórico de transações do Agency-Blackmarket e o progresso dos jogadores no Agency-Minerjob permanecem intactos. Você troca os arquivos do adaptador, atualiza o config.lua e os scripts continuam funcionando. Esse é o verdadeiro valor a longo prazo da abordagem de compatibilidade, não apenas oferecer suporte a vários frameworks, mas também proteger seu servidor da evolução dos frameworks.

Perguntas frequentes

Todos os scripts da Agency usam o mesmo padrão de adaptadores?

Sim. Todos os scripts pagos da Agency e a maioria dos gratuitos usam esse padrão. As únicas exceções são recursos puramente de interface, como Agency-Loadingscreen e Agency-Notify, que não interagem com nenhum framework e funcionam da mesma forma em todos os lugares.

Posso combinar adaptadores de framework? Por exemplo, usar o dinheiro do QBCore, mas o inventário standalone?

Sim, por meio de substituições de configuração. Defina a detecção do framework como QBCore e, em seguida, substitua funções específicas do adaptador em config.lua para chamar seu sistema de inventário personalizado em vez do QBCore. O sistema de substituições existe justamente para servidores com configurações híbridas.

E se um novo framework se tornar popular e ainda não for compatível?

Abra um chamado de suporte no Discord. Avaliamos solicitações de suporte a novos frameworks com base na adesão da comunidade. Historicamente, adicionamos suporte para frameworks com comunidades significativas em 2-4 semanas. Enquanto isso, o caminho do adaptador standalone funciona com qualquer framework como solução temporária.

Os adaptadores de framework são atualizados quando o próprio framework é atualizado?

Sim. Quando QBCore ou ESX lança uma alteração incompatível, publicamos atualizações do adaptador poucos dias após o lançamento do framework. Assinantes ativos recebem notificações de atualização pelo Tebex. Esse é um dos motivos pelos quais o modelo de assinatura existe, a manutenção dos adaptadores é um trabalho contínuo, não um custo único.

Resumo dos requisitos por framework

• QBCore, qualquer versão recente do QBCore. Detecção automática, sem configuração para instalações padrão.
• ESX, ESX Legacy 1.7+ ou ESX principal. Defina a opção legacy para versões mais antigas.
• Standalone, implemente 4-8 funções por script em config.lua. Configuração única, reutilizável nos scripts da Agency.
• Todas as instalações, conta cfx.re com licença válida, servidor FiveM com Artifacts 5181 ou superior recomendado.