Agency-ProgressBar: o detalhe da interface que melhora cada script sem alarde

Um Script Pequeno, Um Efeito Enorme

Barras de progresso aparecem em toda parte no FiveM: arrombando fechaduras, consertando, lavando dinheiro, minerando, prestando socorro médico. As implementações padrão são funcionais, mas sem personalidade. Agency-ProgressBar é a nossa visão de como esse utilitário deve funcionar quando alguém se importa com os detalhes.

A Anatomia de uma Boa Barra de Progresso

Uma boa barra de progresso comunica quatro coisas ao mesmo tempo: qual ação está acontecendo, quanto já avançou, quanto tempo resta e se você pode cancelar. A maioria das implementações só cuida das duas primeiras. Agency-ProgressBar mostra as quatro, com animações sutis que deixam o progresso fluido, sem trancos.

Cancelamento que Funciona

Quando o jogador cancela a ação, uma breve animação de desaparecimento reduz a opacidade da barra a zero em 300ms. Nada de sumir de repente. Desenvolvedores podem registrar um callback de cancelamento para que os scripts façam a limpeza necessária quando os jogadores interrompem uma ação em andamento.

Posicionamento Contextual

A barra aparece perto do elemento relevante na tela: acima da sua cabeça para ações direcionadas a você, acima do NPC-alvo para ações interativas. Chega de ler o status da ação na parte inferior da tela enquanto algo acontece na parte superior. Esse posicionamento contextual é uma melhoria sutil de UX que os jogadores percebem, mesmo sem saber explicar.

O Padrão de Exports

Como todos os nossos scripts utilitários, Agency-ProgressBar oferece uma API simples de exports: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}) . Adicione-o a qualquer script em minutos. Ele funciona com Agency-Notify, Agency-Hud e o restante do nosso ecossistema sem exigir nenhuma configuração especial.

Instalação e configuração

Agency-ProgressBar é um utilitário pronto para usar, sem dependência de banco de dados. Baixe pelo Tebex, coloque a pasta no diretório de resources e adicione ensure agency-progressbar a server.cfg . Pronto. O resource começa a funcionar imediatamente, e qualquer script pode chamar a API de exports na próxima reinicialização.

Se você estiver substituindo uma barra de progresso existente (progressBar do ox_lib, qb-progressbar etc.), localizar e substituir o nome da chamada de export resolve a maioria das migrações em minutos. A estrutura dos parâmetros segue intencionalmente os padrões comuns da comunidade.

Opções de configuração

Abra config.lua para ajustar os padrões:

• Posição padrão, acima da cabeça do jogador (padrão) ou fixa na parte inferior central.
• Esquema de cores , o gradiente de cores do preenchimento. Aceita uma única cor, um gradiente de duas cores ou cores definidas por nível de gravidade (verde para normal, laranja para lento, vermelho para crítico).
• Tecla de cancelamento, qual tecla cancela uma barra de progresso cancelável. Padrão: backspace.
• Animação de cancelamento, desaparecimento gradual (padrão), deslizar para fora ou desaparecimento instantâneo.
• Exibição do tempo, mostrar os segundos restantes (padrão), a porcentagem ou nada.
• Duração mínima, ações mais curtas que esse limite ignoram a barra completamente. Padrão: 500ms.

Compatibilidade com frameworks

Agency-ProgressBar é totalmente standalone, sem dependências de framework. Funciona da mesma forma em QBCore, ESX e configurações de servidor personalizadas. A API de exports é a única forma de integração, sem globais compartilhadas, eventos de framework ou verificações de permissão. Instale e chame a partir de qualquer script, independentemente da origem.

Por que isso importa para o roleplay

Barras de progresso são um elemento básico de UX que aparece em dezenas de situações de jogo, como abrir fechaduras, algemar, fabricar, curar, coletar evidências e hackear. Quando essas barras têm aparência incompatível ou se comportam de forma inconsistente entre diferentes scripts, isso cria ruído visual sutil que prejudica a coerência do servidor.

Quando todas as barras de progresso do seu servidor usam Agency-ProgressBar, a linguagem visual fica unificada. Os jogadores desenvolvem uma intuição sobre o significado da barra e seu comportamento. O cancelamento é consistente. A tipografia combina com o restante da sua interface. São detalhes pequenos, mas que juntos proporcionam uma experiência visivelmente mais refinada para os jogadores.

O posicionamento contextual é mais importante do que parece. Uma barra de progresso ancorada à cabeça do seu personagem durante uma tentativa de abrir uma fechadura mantém seu foco na ação, e não em um canto da tela. Em momentos tensos, como quando você está sendo perseguido enquanto tenta abrir uma fechadura, isso mantém os jogadores atentos ao espaço ao redor enquanto a barra está visível.

Perguntas frequentes

Posso executar várias barras de progresso simultaneamente?

Sim. Cada Play() chamada retorna um ID e gerencia seu próprio estado. Várias barras ficam empilhadas verticalmente acima do jogador, com espaçamento adequado. Isso é útil para ações com várias etapas, em que o progresso de tarefas paralelas precisa ficar visível ao mesmo tempo, embora a maioria das situações de RP use uma barra por vez.

Como faço para anexar uma barra de progresso a um objeto ou NPC em vez de ao jogador?

Passe um target = {type = 'entity', id = entityNetId} campo na tabela de opções. A barra aparece acima da entidade especificada, em vez de acima do jogador. Use isso para ações de reparo, ações médicas em jogadores caídos ou qualquer situação em que o foco da ação esteja em outro lugar.

A barra pode ser configurada para não permitir cancelamento pelo servidor?

Sim. Defina canCancel = false ao chamar Play(). A tecla de cancelamento não tem efeito e nenhuma animação de cancelamento é reproduzida. Isso é adequado para ações impostas pelo servidor, como animações de prisão e cenas roteirizadas, em que a interrupção pelo jogador quebraria o fluxo.

Isso funciona com animações do ox_lib?

Sim. Agency-ProgressBar não depende de animações, você gerencia as animações no seu próprio script junto com a chamada da barra de progresso. A barra é apenas um elemento de interface. Combine-a com qualquer biblioteca de animação ou chamadas de animação nativas do FiveM, de forma independente.

Requisitos

• Servidor FiveM (qualquer framework ou standalone)
• conta cfx.re com uma licença válida do Agency-ProgressBar
• Sem dependência de banco de dados
• Sem dependências de recursos externos

Exemplos práticos de integração

Veja alguns padrões comuns para integrar Agency-ProgressBar a scripts existentes:

Arrombamento: Chame Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) no início de uma tentativa de arrombamento. Combine com o minijogo de arrombamento em execução paralela. Se o minijogo falhar, chame Dismiss() com o ID retornado. Se for bem-sucedido, deixe a barra concluir normalmente.

Tratamento médico: Use target = {type = 'entity', id = patientNetId} para ancorar a barra acima do paciente, em vez de acima do médico. Os jogadores que observam a cena veem o progresso acontecendo no local do tratamento, e não flutuando acima da cabeça do médico.

Coleta de evidências: Defina canCancel = false para uma coleta de evidências roteirizada que não deve poder ser interrompida, para impedir que os jogadores cancelem a ação e evitem deixar impressões digitais na cena. A barra que não pode ser cancelada comunica ao jogador que essa ação é obrigatória, não opcional.

Ações do servidor: Exiba uma barra de progresso no cliente enquanto uma ação do servidor é executada de forma assíncrona. Quando o callback do servidor retornar, deixe a barra concluir ou dispense-a antes, dependendo do resultado do servidor. A duração visual deve corresponder aproximadamente ao tempo de processamento esperado no servidor.