yHunterBountyAddon

Visão geral

O yHunterBountyAddon adiciona ao yHunter um sistema de alvo prioritário com bounty dinâmica.

O addon busca, via PlaceholderAPI, um jogador alvo definido por placeholders externos, calcula uma recompensa com base na fortuna desse alvo e distribui o valor entre os jogadores que participaram do abate.

Este addon não é um plugin standalone. Ele roda dentro do yHunter e depende da ativação do produto yHunterBountyAddon no container/licenciamento do yPlugins.

Dependências

• yHunter
• yPlugins
• Vault
• Plugin de economia compatível com Vault
• PlaceholderAPI
• Placeholder ou expansion capaz de retornar o alvo e a fortuna do alvo
• Produto/container yHunterBountyAddon ativado

O sistema só fica ativo quando todas as condições abaixo forem verdadeiras:

• O container yHunterBountyAddon estiver ativado no yPlugins.
• enabled: true estiver configurado em addons/bounty.yml.
• O PlaceholderAPI estiver carregado no servidor.

Arquivo de configuração

O arquivo principal do addon fica em:

plugins/yHunter/addons/bounty.yml

No projeto, o arquivo padrão fica em:

src/main/resources/addons/bounty.yml

Configuração padrão

# Ativar o sistema de bounty dinamica
enabled: true

placeholders:
  # Placeholder que retorna o nome do jogador mais rico.
  # Ajuste para o placeholder do seu ranking/economia.
  target-name: '%yeconomy_top_player_1%'
  # Placeholder que retorna a fortuna do alvo.
  # Use {target} para injetar o nome retornado em target-name.
  target-money: '%yeconomy_top_value_1%'

reward:
  # Recompensa dinamica = fortuna do alvo * (percent-of-fortune / 100)
  percent-of-fortune: 1.5
  # Limites de seguranca
  min: 1000.0
  max: 500000.0

update:
  # Intervalo de atualizacao do alvo/recompensa em ticks (20 = 1s)
  refresh-ticks: 200

combat:
  # Tempo maximo sem bater no alvo para continuar elegivel ao rateio
  damage-timeout-seconds: 30
  # Limpa historico de dano quando o alvo prioritario muda
  clear-contributors-on-target-change: true

messages:
  status-active: '&aATIVO'
  status-inactive: '&cINATIVO'
  status-no-target: '&cSem alvo'
  payout: '&aVoce recebeu &eR${money} &ada bounty de &e{target}&a.'
  new-target-broadcast: |
    &r
    &c&lALVO PRIORITARIO ATUALIZADO
    &7Novo alvo: &f{target}
    &7Fortuna: &aR${fortune}
    &7Bounty dinamica: &6R${reward}
    &r
  target-killed-broadcast: |
    &r
    &a&lALVO PRIORITARIO ELIMINADO
    &7Alvo: &f{target}
    &7Abatido por: &f{killer}
    &7Participantes: &f{participants}
    &7Bounty distribuida: &6R${reward}
    &r

menu-item:
  # Icone exclusivo no menu principal do hunter
  enabled: true
  slot: 22
  material: '{player}'
  Name: '&c&lAlvo Prioritario'
  lore-active:
    - ''
    - '&7Status: {status}'
    - '&7Alvo: &f{target}'
    - '&7Fortuna: &aR${fortune}'
    - '&7Bounty atual: &6R${reward}'
    - ''
    - '&eAo matar o alvo, o valor e rateado'
    - '&eentre quem participou do abate.'
  lore-inactive:
    - ''
    - '&7Status: {status}'
    - '&7Alvo: &f-'
    - '&7Fortuna: &aR$0'
    - '&7Bounty atual: &6R$0'
    - ''
    - '&cAguardando dados do PlaceholderAPI.'

Seções da configuração

enabled

Ativa ou desativa o sistema no arquivo de configuração.

enabled: true

Mesmo com essa opção ativada, o addon ainda depende do container yHunterBountyAddon e do PlaceholderAPI.

placeholders

Define quais placeholders serão usados para descobrir o alvo e a fortuna dele.

placeholders:
  target-name: '%yeconomy_top_player_1%'
  target-money: '%yeconomy_top_value_1%'

target-name deve retornar o nome do jogador alvo.

target-money deve retornar a fortuna do jogador alvo. O valor pode ser numérico ou formatado no padrão reconhecido pelo formatter do yHunter.

Também é possível usar {target} dentro do placeholder de dinheiro:

placeholders:
  target-name: '%yeconomy_top_player_1%'
  target-money: '%vault_eco_balance_{target}%'

Antes de ser usado, o nome retornado pelo placeholder passa por uma limpeza simples:

• Remove cores do Minecraft.
• Remove espaços extras.
• Se houver espaço no texto, usa apenas a primeira palavra.
• Remove % restantes.

reward

Controla o cálculo da bounty dinâmica.

reward:
  percent-of-fortune: 1.5
  min: 1000.0
  max: 500000.0

A fórmula usada é:

recompensa = fortuna_do_alvo * (percent-of-fortune / 100)

Depois do cálculo, o valor passa pelos limites configurados:

• min: valor mínimo da bounty.
• max: valor máximo da bounty.

Se max for 0 ou menor, o limite máximo não é aplicado.

update

Controla a frequência de atualização do alvo e da recompensa.

update:
  refresh-ticks: 200

O valor é em ticks. No Minecraft, 20 ticks = 1 segundo.

Exemplos:

Se o valor configurado for menor ou igual a 0, o plugin usa 200 ticks.

O comando de reload recarrega a configuração, mas não recria o scheduler do addon. Se você alterar refresh-ticks, reinicie o servidor para garantir que o novo intervalo seja aplicado.

combat

Controla quem participa do rateio da recompensa.

combat:
  damage-timeout-seconds: 30
  clear-contributors-on-target-change: true

damage-timeout-seconds define por quanto tempo o dano de um jogador continua válido para o rateio. Se o jogador ficou mais tempo que isso sem bater no alvo, ele deixa de ser elegível.

clear-contributors-on-target-change define se a lista de contribuidores deve ser limpa quando o alvo prioritário muda.

messages

Controla mensagens enviadas pelo addon.

messages:
  status-active: '&aATIVO'
  status-inactive: '&cINATIVO'
  status-no-target: '&cSem alvo'
  payout: '&aVoce recebeu &eR${money} &ada bounty de &e{target}&a.'

status-active aparece no menu quando o sistema está ativo e existe alvo.

status-inactive aparece quando o sistema está desativado.

status-no-target aparece quando o sistema está ativo, mas não conseguiu encontrar um alvo válido.

payout é enviada ao jogador que recebeu parte da bounty.

new-target-broadcast é enviada para todos os jogadores online quando o alvo prioritário muda.

target-killed-broadcast é enviada para todos os jogadores online quando o alvo prioritário é eliminado.

menu-item

Adiciona um item exclusivo no menu principal do /hunter.

menu-item:
  enabled: true
  slot: 22
  material: '{player}'
  Name: '&c&lAlvo Prioritario'

enabled ativa ou desativa o item no menu.

slot define o slot no inventário do menu principal.

material, Name, lore-active e lore-inactive seguem o mesmo padrão de item usado nos menus do yHunter.

Quando o item for uma skull reconhecida pelo sistema de itens da yStore e existir alvo ativo, a skin do item será atualizada para a skin do alvo.

Placeholders internos

Os textos do addon aceitam os placeholders abaixo.

Fluxo de funcionamento

1. O yHunter carrega o arquivo addons/bounty.yml.
2. O addon verifica se o container yHunterBountyAddon está ativo.
3. O addon verifica se o PlaceholderAPI está carregado.
4. O sistema consulta o placeholder placeholders.target-name usando um jogador online como contexto.
5. O nome retornado é limpo e definido como alvo prioritário.
6. O sistema consulta placeholders.target-money para obter a fortuna do alvo.
7. A recompensa é calculada usando reward.percent-of-fortune.
8. Os limites reward.min e reward.max são aplicados.
9. Se o alvo mudou, o broadcast new-target-broadcast é enviado.
10. Quando jogadores causam dano ao alvo, o dano é registrado.
11. Quando o alvo morre, a recompensa é distribuída entre os participantes elegíveis.
12. O broadcast target-killed-broadcast é enviado.

Rateio da bounty

Quando o alvo prioritário morre, o addon procura os jogadores que causaram dano recente nele.

Para ser elegível, o jogador precisa:

• Ter causado dano no alvo prioritário.
• Estar online no momento da morte.
• Ter causado dano dentro do tempo de combat.damage-timeout-seconds.

O valor é dividido proporcionalmente ao dano causado.

Exemplo:

Bounty: R$100.000
Jogador A causou 70 de dano
Jogador B causou 30 de dano

Jogador A recebe R$70.000
Jogador B recebe R$30.000

Se nenhum participante elegível for encontrado, toda a bounty vai para o killer.

Regras herdadas do yHunter

A bounty dinâmica é distribuída dentro do fluxo de morte do yHunter. Por isso, ela respeita as validações gerais desse fluxo.

O pagamento pode não acontecer se:

• O killer não tiver a permissão configurada em Opcoes.KillPerm, quando essa permissão estiver definida.
• A morte acontecer em um mundo listado em Opcoes.Mundos blacklist.
• O alvo ou o killer forem NPCs.
• O killer for o próprio alvo.
• O yHunter não tiver os dados do jogador carregados.
• O killer e o alvo forem do mesmo clan/faction em hooks suportados.

Comandos relacionados

O addon não adiciona comandos próprios. Ele usa os comandos do yHunter.

Se o addon estava desativado quando o servidor iniciou, use restart para ativá-lo corretamente depois de mudar enabled para true ou depois de instalar/ativar dependências. O reload não recria o BountyManager quando ele não iniciou ativo.

Integração com menu

O item do alvo prioritário é aplicado diretamente no menu principal do yHunter.

Arquivo do menu principal:

plugins/yHunter/menus/principal.yml

Configuração do item do addon:

menu-item:
  enabled: true
  slot: 22

O slot padrão 22 fica no centro inferior de um menu com tamanho 27.

Se esse slot já estiver ocupado por outro item decorativo ou customizado, o item do addon pode sobrescrevê-lo no momento em que o menu é aberto.

Exemplos de configuração

Alvo baseado no top 1 da economia

placeholders:
  target-name: '%yeconomy_top_player_1%'
  target-money: '%yeconomy_top_value_1%'

Fortuna consultada pelo nome do alvo

placeholders:
  target-name: '%yeconomy_top_player_1%'
  target-money: '%vault_eco_balance_{target}%'

Bounty mais agressiva

reward:
  percent-of-fortune: 5.0
  min: 10000.0
  max: 2000000.0

Atualização a cada minuto

update:
  refresh-ticks: 1200

Troubleshooting

O item aparece como inativo

Verifique:

• Se o container yHunterBountyAddon está ativado.
• Se enabled: true está configurado em addons/bounty.yml.
• Se o PlaceholderAPI está instalado e carregado.
• Se o servidor foi reiniciado após ativar o addon pela primeira vez.

O alvo não aparece

Verifique:

• Se existe pelo menos um jogador online.
• Se placeholders.target-name retorna um nome válido.
• Se a expansion usada pelo PlaceholderAPI está instalada.
• Se o placeholder não está retornando texto vazio, mensagem de erro ou valor com formato inesperado.

A fortuna aparece como zero ou errada

Verifique:

• Se placeholders.target-money retorna apenas número ou formato aceito pelo yHunter.
• Se o placeholder aceita {target} quando esse formato estiver sendo usado.
• Se a economia usada pelo placeholder é a mesma economia ligada ao Vault.

A bounty não foi paga

Verifique:

• Se a morte passou pelas regras gerais do yHunter.
• Se o killer e o alvo não estão no mesmo clan/faction.
• Se o mundo não está na blacklist.
• Se o killer tem a permissão de kill configurada, quando Opcoes.KillPerm não estiver vazio.
• Se o alvo morto era realmente o alvo prioritário atual.

O valor não atualizou depois do reload

Alguns valores são recarregados pelo /hunter reload, mas o intervalo do scheduler (update.refresh-ticks) não é reprogramado em runtime.

Para aplicar alterações no intervalo ou ativar o addon depois de ele ter iniciado desativado, reinicie o servidor.

Arquivos e classes relacionadas