Um script pequeno, um efeito desproporcional
As barras de progresso aparecem por todo o lado no FiveM — arrombar fechaduras, reparar, lavar dinheiro, minerar, prestar primeiros socorros. As implementações por defeito são funcionais, mas sem graça. O Agency-ProgressBar é a nossa visão de como este utilitário se deve sentir quando alguém se preocupa com os detalhes.
A anatomia de uma boa barra de progresso
Uma boa barra de progresso comunica quatro coisas ao mesmo tempo: que ação está a acontecer, o quanto já avançaste, quanto tempo falta e se podes cancelar. A maioria das implementações só cobre as duas primeiras. O Agency-ProgressBar mostra as quatro, com animações subtis que tornam o progresso fluido em vez de aos solavancos.
Cancelamento que funciona
O cancelamento iniciado pelo jogador dispara uma breve animação de fade-out que devolve a opacidade da barra a zero em 300ms. Sem desaparecimento abrupto. Os programadores podem registar um callback de cancelamento para que os scripts limpem corretamente quando os jogadores se afastam de uma ação a meio.
Posicionamento contextual
A barra aparece perto do elemento relevante no ecrã — por cima da tua cabeça para ações dirigidas a ti próprio, por cima do NPC alvo para ações interativas. Acabou-se ler o estado da ação no fundo do ecrã enquanto algo acontece no topo. Este posicionamento contextual é uma melhoria de UX subtil que os jogadores sentem sem conseguirem nomear.
O padrão de exports
Como todos os nossos scripts utilitários, o Agency-ProgressBar expõe uma API de exports simples: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Integra-o em qualquer script em minutos. Combina-se com o Agency-Notify, Agency-Hud e com o resto do nosso ecossistema sem qualquer configuração especial.
Instalação e Configuração
Agency-Progressbar se instala como um recurso utilitário do FiveM. Não requer configuração de banco de dados pois opera puramente no lado do cliente. Após adicionar ao server.cfg, está imediatamente disponível através de exports para qualquer outro recurso.
Opções de Configuração
- Posição padrão — parte inferior da tela, centro ou acima da cabeça do personagem
- Esquema de cores — paleta padrão ou cores personalizadas por código HTML
- Velocidade de animação — quão rápido a barra aparece e desaparece
- Tecla de cancelamento — quais teclas permitem cancelar a barra de progresso em andamento
Compatibilidade com Frameworks
Agency-Progressbar é completamente independente do framework. Funciona igualmente no ESX, QBCore e servidores standalone pois só manipula animações do jogador com callbacks opcionais do servidor.
Por Que Isso Importa para o Roleplay
As barras de progresso fazem com que as ações pareçam deliberadas. Sem elas, o roleplay se torna uma série de teclas instantâneas sem peso ou consequência. Com Agency-Progressbar, cada ação tem duração e pode ser interrompida, criando tensão e drama nos cenários de RP.
Uso em Scripts Personalizados
Agency-Progressbar realmente brilha quando você o integra em seus próprios recursos. A chamada de API do lado do cliente é simples e direta. Você pode encadear múltiplas barras de progresso para ações complexas de várias etapas.
Casos de Uso Concretos
- Reanimar um jogador caído — 10 segundos, cancelável se o jogador se mover
- Revistar um veículo — 5 segundos, requer estar próximo ao veículo
- Plantar um explosivo — 30 segundos, longo para criar tensão dramática
- Coletar recursos — 3 segundos por recurso coletado
- Abrir uma fechadura — 8 segundos com kit de arrombamento
Perguntas Frequentes
- Agency-Progressbar pode se integrar com animações de personagens? Sim, você pode especificar um dicionário e clipe de animação que toca enquanto a barra avança.
- Os jogadores podem cancelar a barra de progresso? Configurável por ação — algumas ações podem ser canceláveis, outras não.
- Qual é o impacto no desempenho com muitos jogadores usando barras de progresso simultaneamente? Cada barra de progresso é processada localmente no cliente, sem carga no servidor.
Sobre o Agency Scripts
Agency Scripts é uma coleção de recursos premium do FiveM projetados para servidores de roleplay que levam a imersão a sério. Cada recurso é construído com os mesmos princípios: compatibilidade multi-framework, desempenho otimizado e configuração flexível para se adaptar a qualquer conceito de servidor.
Todos os recursos do Agency estão disponíveis através do sistema de licenças da cfx.re Keymaster. Uma vez comprado, você pode implantar o recurso em qualquer servidor que possua, com suporte ativo disponível através do Discord do Agency Scripts.
Suporte e Comunidade
A comunidade do Agency Scripts inclui milhares de servidores FiveM que usam esses recursos. O Discord oficial é onde os desenvolvedores compartilham suas configurações, fazem perguntas e sugerem novos recursos. As atualizações são regulares e incluem tanto correções de bugs quanto novos recursos baseados no feedback da comunidade.
Para dúvidas de instalação, problemas de compatibilidade ou solicitações de recursos, o Discord é o melhor canal. A documentação é mantida atualizada e cobre todas as configurações com exemplos práticos.
Requisitos do Sistema
Para usar os recursos do Agency Scripts, seu servidor FiveM precisa atender aos seguintes requisitos mínimos:
- Versão do servidor FiveM — artifact 4752 ou superior recomendado
- Framework — ESX 1.2+, QBCore (qualquer versão principal) ou configuração standalone
- Banco de dados — MariaDB ou MySQL 5.7+ com oxmysql como camada de banco de dados
- ox_lib — recomendado para elementos de UI aprimorados, nem sempre obrigatório
Os recursos do Agency Scripts são testados nos artifacts de servidor mais recentes e atualizados regularmente para acompanhar as mudanças do FiveM. As licenças são por servidor mas não têm data de expiração uma vez compradas através do Keymaster.
Por Que os Servidores Escolhem Agency Scripts
A principal razão pela qual os servidores FiveM escolhem Agency Scripts é a consistência. Quando todas as suas ferramentas vêm do mesmo fornecedor, elas têm o mesmo estilo de configuração, o mesmo suporte e o mesmo padrão de qualidade. Não há surpresas ao atualizar um recurso porque você sabe o que esperar.
Para administradores de servidor que querem passar mais tempo no roleplay e menos tempo solucionando problemas de scripts, essa consistência tem valor real. Em vez de ter dez recursos diferentes de dez desenvolvedores diferentes, todos com filosofias de design diferentes e documentação inconsistente, você tem um ecossistema coeso.
Integração Entre Recursos
Os recursos Agency são projetados para funcionar juntos. Agency-Notify é usado por Agency-Reports para alertar admins. Agency-HUD complementa Agency-Phone para uma experiência de interface unificada. Agency-Admin pode suspender jogadores que abusaram do sistema Agency-Blackmarket. Essas integrações não são acidentais — são recursos planejados que fazem o ecossistema funcionar melhor como um todo do que como partes separadas.
Quando você adiciona um novo recurso Agency a um servidor que já usa outros recursos Agency, a compatibilidade está garantida. Não é preciso testar se os eventos colidem, se as configurações do banco de dados conflitam ou se os estilos de UI são inconsistentes. Tudo se encaixa.