Saltar para o conteúdo principal

Integração com Vault

O EliteMobs pode usar um fornecedor de economia Vault em vez do saldo interno. O plugin compila com a VaultAPI 1.7; instale plugins Vault e de economia compatíveis no servidor.

Efeitos na progressão​

A progressão do EliteMobs combina competências de armas e armadura, loot e treino opcional de classes. Os jogadores normalmente ganham equipamento e moeda através do combate do EliteMobs. Introduzir dinheiro de outra economia altera a rapidez com que podem comprar equipamento e serviços.

Reveja os preços das lojas, valores de revenda do loot e serviços pagos antes de ligar uma economia externa.

Os requisitos separados de competências continuam a aplicar-se quando ativados. O Vault não dá XP de competências, não desbloqueia classes nem ignora provas dos treinadores. Se ativar a integração, ajuste a economia aos preços das lojas e serviços do EliteMobs para que os rendimentos externos não tornem irrelevantes as recompensas do combate.

Requisitos​

Para usar a integração com o Vault, tem de ter:

  • Um plugin Vault ativado e compatível com as chamadas VaultAPI do EliteMobs
  • Um plugin de economia que registe um serviço Vault Economy
  • Ambos os plugins corretamente configurados e em funcionamento

O EliteMobs deteta o Vault ativado durante a inicialização e seleciona o respetivo caminho de economia quando useVault é true. A deteção, por si só, não prova que tenha encontrado um fornecedor de economia.

Configuração​

Para ativar a integração com o Vault:

  1. Garanta que o plugin Vault está instalado no seu servidor
  2. Garanta que o plugin de economia regista o fornecedor Vault antes de o EliteMobs inicializar
  3. Abra o EconomySettings.yml na pasta do plugin EliteMobs
  4. Defina useVault: true
  5. Reinicie o servidor

Exemplo de configuração:

# Whether to use Vault for the economy instead of the built-in system.
# NOT RECOMMENDED! See: https://wiki.nightbreak.io/EliteMobs/vault
useVault: false

Como Funciona​

Quando a integração com o Vault está ativa com um fornecedor funcional:

  • As operações futuras usam o fornecedor de economia do Vault. Os Elite Coins existentes na base de dados do EliteMobs não são convertidos nem transferidos automaticamente.
  • Os jogadores ganham a moeda da sua economia em vez de Elite Coins ao matar Elite Mobs
  • As transações das lojas e outros serviços que cobram moeda usam a economia do servidor. As reparações continuam a consumir sucata.
  • O Vault gere o saldo monetário; o EliteMobs continua a registar a dívida de jogo e a descontá-la dos rendimentos recebidos no EliteMobs antes de depositar o restante.

Operações de moeda:

  • Depósitos: O dinheiro é adicionado ao saldo Vault do jogador
  • Levantamentos: O dinheiro é removido do saldo Vault do jogador
  • Verificações de saldo: Consulta o saldo Vault do jogador
  • Definição direta de saldo: DESATIVADA por segurança (use o seu plugin de economia)

Na inicialização, o Vault ativado com useVault: true define VAULT_ENABLED antes de procurar o fornecedor. Um fornecedor em falta pode, por isso, deixar o modo Vault ativo sem uma economia utilizável. As consultas de saldo dão então um aviso e devolvem zero; os depósitos ou levantamentos normais podem falhar, enquanto as funções de compra com verificação devolvem uma falha. Se o Vault estiver ausente ou desativado num arranque novo, mantém-se a economia interna. Uma exceção capturada durante a configuração do Vault também desativa esse modo.

Depois de o modo Vault estar ativo, não há mudança automática para a economia interna nem nova ligação ao fornecedor durante a execução. Corrija o registo do fornecedor e reinicie antes de aceitar transações. currencyName continua a ser uma definição visual separada do EliteMobs; ativar o Vault não a renomeia automaticamente.

Funcionalidades de Segurança​

Por razões de segurança, o EliteMobs NÃO suporta definir diretamente o saldo de moeda de um jogador através do Vault. Qualquer tentativa de o fazer será bloqueada e registada. Use os comandos do seu plugin de economia para definir saldos diretamente, se necessário.

Exemplo de Cenário​

Suponha que uma recompensa paga 100 moedas e que o jogador não tem dívida de jogo. É um valor ilustrativo, não um pagamento fixo por cada mob de nível 50.

Sem o Vault:

  • O jogador mata um Elite Mob de nível 50
  • Recebe 100 Elite Coins (guardados na base de dados do EliteMobs)
  • Pode gastar Elite Coins nas lojas e serviços do EliteMobs

Com o Vault:

  • O jogador mata um Elite Mob de nível 50
  • Recebe 100 [moeda da sua economia] (guardados no Vault/plugin de economia)
  • Pode gastar dinheiro no EliteMobs e noutros sistemas que usem esse fornecedor
  • As transferências de outros jogadores dependem das funcionalidades do plugin de economia
  • A economia é unificada entre todos os plugins

Os rendimentos externos podem acelerar o acesso a equipamento e serviços. Os requisitos de competências e os desbloqueios de classes continuam a aplicar-se de forma independente.

Resolução de Problemas​

Se a integração com o Vault estiver ativada mas não funcionar:

  1. Verifique os registos do servidor à procura de: "Vault detected." (numa linha de registo do EliteMobs)

    • Se faltar: o plugin Vault não está instalado ou não está a carregar

  2. Procure pelo aviso: "Vault preference detected. This is not the recommended setting."

    • Isto é esperado quando a integração com o Vault está ativada — é um lembrete, não um erro
    • Se o Vault continuar a não funcionar, garanta que o seu plugin de economia está corretamente registado junto do Vault

  3. Procure por: "Player tried to check currency when they had no economy entry"

    • É um aviso genérico de referência nula, não uma prova de falta de conta do jogador. O próprio fornecedor de economia guardado pode ser nulo.
    • Verifique se o fornecedor estava registado antes da inicialização do EliteMobs e depois consulte a gestão de contas e os registos do plugin de economia.

  4. Se estiver ativado mas o EliteMobs continuar a usar Elite Coins:

    • Verifique que a chave de configuração é exatamente: useVault: true
    • Reinicie o servidor após alterar a configuração
    • Verifique que existe um plugin de economia registado junto do Vault

  5. Se os saldos mostrarem zero ou as transações falharem apesar da mensagem de deteção:

    • Confirme que existia um fornecedor disponível na inicialização; a mensagem só confirma o próprio Vault.
    • Restabeleça o fornecedor e reinicie. O EliteMobs não se liga automaticamente a um fornecedor recém-registado.

Para Programadores​

Se estiver a desenvolver um addon ou uma integração:

  • Seleção do Vault: VaultCompatibility.VAULT_ENABLED não prova a disponibilidade do fornecedor; getEconomy() pode ser nulo
  • API de economia: Use os métodos de EconomyHandler (não diretamente o VaultCompatibility)
  • Operações suportadas: adicionar, subtrair, consultar, crédito com verificação, levantamento com verificação para compras e reembolso de compras (definir saldo está desativado)
  • Todas as alterações de saldo têm de correr na thread do servidor e para um jogador cujos dados do EliteMobs estejam carregados (EconomyHandler.isReady); caso contrário, lançam IllegalStateException.
  • tryCredit, tryWithdraw e refundPayment lançam IllegalArgumentException para um montante negativo ou não finito, e devolvem false quando o Vault rejeita a transação ou já está em curso outra alteração para esse jogador. tryCredit cobra primeiro a dívida de jogo e só guarda a nova dívida depois de o Vault aceitar o depósito; refundPayment não cobra a dívida.
  • addCurrency e subtractCurrency lançam IllegalStateException quando o fornecedor rejeita a alteração, em vez de falharem silenciosamente.
  • Precisão da moeda: o sistema interno usa 2 casas decimais
  • Sem recurso em tempo de execução: quando VAULT_ENABLED é verdadeiro, o EconomyHandler delega sempre no Vault; não existe qualquer reversão automática para a economia interna

Localização do código-fonte:

  • src/main/java/com/magmaguy/elitemobs/economy/VaultCompatibility.java
  • src/main/java/com/magmaguy/elitemobs/economy/EconomyHandler.java

O EliteMobs usa a VaultAPI 1.7 como dependência apenas de compilação. O JAR do plugin Vault tem de estar presente no servidor em tempo de execução.