API

Obtendo a instância da API

A API é exposta através de um BukkitService assim como feito comumente no Vault.

Exemplo:

BolsaAPIHolder bolsaAPI;

try {
  RegisteredServiceProvider<BolsaAPIHolder> rsp = Bukkit.getServer().getServicesManager().getRegistration(BolsaAPIHolder.class);
  return rsp == null ? null : (BolsaAPIHolder)rsp.getProvider();
} catch (Throwable t) {
  return null;
}

Métodos disponíveis

getDelay()

Obtém o tempo de delay entre atualizações do mercado.

int delay = bolsaAPI.getDelay();

Retorno:

• Tempo em ticks entre atualizações do mercado

Observações:

• Valor em ticks (20 ticks = 1 segundo)
• Define a frequência de mudanças no valor da bolsa

getValue()

Obtém o valor atual do mercado.

int currentValue = bolsaAPI.getValue();

Retorno:

• Valor inteiro atual do mercado

Observações:

• Representa o preço base do item negociado na bolsa
• Varia de acordo com as tendências do mercado

getSpecialEffectDuration()

Obtém a duração do efeito especial do mercado.

int duration = bolsaAPI.getSpecialEffectDuration();

Retorno:

• Duração em ticks do efeito especial ativo

Observações:

• Tempo em ticks (20 ticks = 1 segundo)
• Indica quanto tempo falta para o efeito especial expirar

getCircuitBreakerTime()

Obtém o tempo restante do circuit breaker.

int remainingTime = bolsaAPI.getCircuitBreakerTime();

Retorno:

• Tempo em ticks restante do circuit breaker

Observações:

• O circuit breaker é um mecanismo de proteção contra flutuações extremas
• Tempo em ticks (20 ticks = 1 segundo)
• Retorna 0 se não houver circuit breaker ativo

isCircuitBreakerActive()

Verifica se o circuit breaker está ativo.

boolean isActive = bolsaAPI.isCircuitBreakerActive();

Retorno:

• true se o circuit breaker está ativo, false caso contrário

Observações:

• O circuit breaker é ativado quando há flutuações extremas de preço
• Previne manipulação artificial do mercado

getTrendText()

Obtém o texto descritivo da tendência atual do mercado.

String trend = bolsaAPI.getTrendText();

Retorno:

• String contendo descrição da tendência (ex: "Tendência de Alta", "Tendência de Baixa", "Estável")

Observações:

• Texto formatado para exibição ao jogador
• Pode incluir símbolos ou cores conforme configuração
• Útil para dashboards e interfaces de informação

getMarketText()

Obtém o texto descritivo do status atual do mercado.

String marketStatus = bolsaAPI.getMarketText();

Retorno:

• String contendo descrição do status do mercado

Observações:

• Inclui informações sobre o estado geral da bolsa
• Pode indicar eventos especiais do mercado
• Útil para notificações e displays em tempo real

Boas práticas

• Verifique isCircuitBreakerActive() antes de operações sensíveis
• Armazene valores consultados para evitar múltiplas chamadas
• Use getTrendText() e getMarketText() para informar jogadores
• Evite chamadas excessivas em eventos de alta frequência
• Considere o delay antes de fazer operações críticas

Exemplos de uso

Verificando valor atual da bolsa

int currentValue = bolsaAPI.getValue();
System.out.println("Valor da bolsa: " + currentValue);

Exibindo informações de mercado ao jogador

BolsaAPIHolder bolsaAPI = getBolsaAPI();
player.sendMessage("Tendência: " + bolsaAPI.getTrendText());
player.sendMessage("Status: " + bolsaAPI.getMarketText());

Aplicando multiplicador baseado em tendência

int baseValue = 100;
int marketValue = bolsaAPI.getValue();
double multiplier = (double) marketValue / 100; // Assumindo 100 como base
double finalValue = baseValue * multiplier;

Verificando proteção do circuit breaker

if (bolsaAPI.isCircuitBreakerActive()) {
    int timeRemaining = bolsaAPI.getCircuitBreakerTime();
    System.out.println("Circuit breaker ativo por mais " + (timeRemaining / 20) + " segundos");
    // Adiar operação crítica
} else {
    // Prosseguir com operação crítica
}

Monitorando efeitos especiais

int effectDuration = bolsaAPI.getSpecialEffectDuration();
if (effectDuration > 0) {
    System.out.println("Efeito especial ativo por " + (effectDuration / 20) + " segundos");
}

Dashboard de informações de mercado

BolsaAPIHolder bolsaAPI = getBolsaAPI();

player.sendMessage("═══════════════════════════");
player.sendMessage("BOLSA DE VALORES");
player.sendMessage("═══════════════════════════");
player.sendMessage("Valor: " + bolsaAPI.getValue());
player.sendMessage("Tendência: " + bolsaAPI.getTrendText());
player.sendMessage("Status: " + bolsaAPI.getMarketText());

if (bolsaAPI.isCircuitBreakerActive()) {
    player.sendMessage("⚠ Circuit Breaker Ativo!");
}

player.sendMessage("═══════════════════════════");