API

A API fornece uma interface pública para desenvolvedores integrarem seus plugins ao sistema de integração com Discord do yDiscordHook, permitindo enviar mensagens e embeds para jogadores Discord.

Obtendo a instância da API

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

Exemplo:

DiscordAPIHolder discordAPI;

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

Métodos disponíveis

getPlayer(String playerName)

Recupera os dados Discord de um jogador pelo nome.

PlayerDcHolder playerDc = discordAPI.getPlayer("Steve");

Parâmetros:

playerName - Nome do jogador

Retorno:

PlayerDcHolder contendo dados Discord do jogador ou null se não encontrado/não vinculado

Observações:

Retorna null se o jogador não tiver Discord vinculado
Acesso seguro aos dados Discord do jogador

getPlayer(Player player)

Recupera os dados Discord de um jogador Bukkit.

PlayerDcHolder playerDc = discordAPI.getPlayer(player);

Parâmetros:

player - Objeto Player do Bukkit

Retorno:

PlayerDcHolder contendo dados Discord do jogador ou null se não encontrado/não vinculado

Observações:

Converte automaticamente o objeto Player para nome
Método sobrecarregado para conveniência

sendMessage(PlayerDcHolder playerDc, String message)

Envia uma mensagem de texto simples para o jogador no Discord.

boolean success = discordAPI.sendMessage(playerDc, "Olá, bem-vindo!");

Parâmetros:

playerDc - Dados Discord do jogador
message - Mensagem de texto a enviar

Retorno:

true se a mensagem foi enviada com sucesso, false caso contrário

Observações:

Envia via DM (Direct Message) privado no Discord
A mensagem é enviada de forma assíncrona
Retorna false se o jogador não tiver Discord vinculado ou se houver erro

sendEmbed`(PlayerDcHolder playerDc, String embed, HashMap<String, String> toReplace)`

Envia um embed formatado para o jogador no Discord com substituição de placeholders.

HashMap<String, String> replace = new HashMap<>();
replace.put("{player_name}", "Steve");
replace.put("{level}", "50");

boolean success = discordAPI.sendEmbed(playerDc, "embed_name", replace);

Parâmetros:

playerDc - Dados Discord do jogador
embed - Nome do embed configurado
toReplace - HashMap com chave-valor para substituição de placeholders

Retorno:

true se o embed foi enviado com sucesso, false caso contrário

Observações:

Permite personalização dinâmica via placeholders
Os placeholders no embed são substituídos pelos valores do HashMap
Retorna false se o embed não existir ou houver erro no envio

sendEmbed`(PlayerDcHolder playerDc, String embed, HashMap<String, String> toReplace, String imageBase64)`

Envia um embed formatado com imagem personalizada.

HashMap<String, String> replace = new HashMap<>();
replace.put("{player}", "Steve");

boolean success = discordAPI.sendEmbed(playerDc, "rank_embed", replace, base64Image);

Parâmetros:

playerDc - Dados Discord do jogador
embed - Nome do embed configurado
toReplace - HashMap com chave-valor para substituição de placeholders
imageBase64 - String contendo imagem em base64

Retorno:

true se o embed foi enviado com sucesso, false caso contrário

Observações:

Permite adicionar imagem customizada ao embed
A imagem deve estar em formato base64
Útil para enviar prints, troféus, skins, etc.
Retorna false se houver erro no envio ou conversão de imagem

getJda()

Obtém a instância JDA (Java Discord API) do bot.

JDA jda = discordAPI.getJda();

Retorno:

Instância JDA do bot Discord

Observações:

Fornece acesso direto à API do JDA
Permite operações avançadas e customizadas
Útil para desenvolvedores com conhecimento de JDA
Pode retornar null se o bot não estiver inicializado

Estrutura de dados

PlayerDcHolder

Representa os dados Discord de um jogador Minecraft.

Propriedades principais:

ID Discord do usuário
Nome do usuário Discord
Status de vinculação
Timestamp de vinculação
Permissões Discord

Boas práticas

Sempre verifique se PlayerDcHolder não é null antes de usar
Use sendMessage() para notificações simples
Use sendEmbed() para informações estruturadas e visuais
Valide o HashMap de substituição antes de enviar embeds
Evite enviar muitas mensagens em curto período (rate limiting)
Converta imagens para base64 antes de enviar

Exemplos de uso

Enviar notificação simples

PlayerDcHolder playerDc = discordAPI.getPlayer("Steve");
if (playerDc != null) {
    discordAPI.sendMessage(playerDc, "Você ganhou 1000 moedas!");
}

Enviar embed com placeholders

PlayerDcHolder playerDc = discordAPI.getPlayer(player);
if (playerDc != null) {
    HashMap<String, String> replace = new HashMap<>();
    replace.put("{player}", player.getName());
    replace.put("{level}", String.valueOf(getPlayerLevel(player)));
    replace.put("{rank}", getPlayerRank(player));
    
    discordAPI.sendEmbed(playerDc, "level_up", replace);
}

Enviar embed com imagem customizada

@EventHandler
public void onPlayerRankUp(PlayerRankUpEvent event) {
    Player player = event.getPlayer();
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    if (playerDc != null) {
        HashMap<String, String> replace = new HashMap<>();
        replace.put("{new_rank}", event.getNewRank());
        replace.put("{date}", new SimpleDateFormat("dd/MM/yyyy").format(new Date()));
        
        String skinBase64 = getPlayerSkinBase64(player);
        discordAPI.sendEmbed(playerDc, "rank_promotion", replace, skinBase64);
    }
}

Notificar sobre eventos importantes

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    if (playerDc != null) {
        HashMap<String, String> replace = new HashMap<>();
        replace.put("{player}", player.getName());
        replace.put("{time}", new SimpleDateFormat("HH:mm").format(new Date()));
        
        discordAPI.sendEmbed(playerDc, "welcome", replace);
    }
}

Sistema de recompensas com notificação

public void giveReward(Player player, String rewardName, double amount) {
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    if (playerDc != null) {
        HashMap<String, String> replace = new HashMap<>();
        replace.put("{reward}", rewardName);
        replace.put("{amount}", String.valueOf(amount));
        replace.put("{total}", String.valueOf(getPlayerBalance(player)));
        
        discordAPI.sendEmbed(playerDc, "reward_received", replace);
    }
    
    addBalance(player.getName(), amount);
}

Alertar sobre atividades suspeitas

@EventHandler
public void onMultipleFailedLogins(MultipleFailedLoginsEvent event) {
    Player player = event.getPlayer();
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    if (playerDc != null) {
        HashMap<String, String> replace = new HashMap<>();
        replace.put("{attempts}", String.valueOf(event.getAttempts()));
        replace.put("{ip}", event.getIP());
        
        discordAPI.sendEmbed(playerDc, "security_alert", replace);
    }
}

Integração com sistemas de tickets

public void notifyTicketResponse(Player player, String ticketId, String response) {
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    if (playerDc != null) {
        HashMap<String, String> replace = new HashMap<>();
        replace.put("{ticket_id}", ticketId);
        replace.put("{response}", response);
        replace.put("{date}", new SimpleDateFormat("dd/MM/yyyy HH:mm").format(new Date()));
        
        discordAPI.sendEmbed(playerDc, "ticket_response", replace);
    }
}

Dashboard de sincronização

public void showSyncStatus(Player player) {
    PlayerDcHolder playerDc = discordAPI.getPlayer(player);
    
    player.sendMessage("═══════════════════════════");
    player.sendMessage("STATUS DISCORD");
    player.sendMessage("═══════════════════════════");
    
    if (playerDc != null) {
        player.sendMessage("Status: ✓ VINCULADO");
        player.sendMessage("Mensagens habilitadas");
        
        // Testar envio
        boolean testSuccess = discordAPI.sendMessage(playerDc, "Teste de conexão");
        player.sendMessage("Teste de conexão: " + (testSuccess ? "✓" : "✗"));
    } else {
        player.sendMessage("Status: ✗ NÃO VINCULADO");
        player.sendMessage("Digite /discord para vincular sua conta");
    }
    
    player.sendMessage("═══════════════════════════");
}

Usar JDA diretamente para operações avançadas

JDA jda = discordAPI.getJda();
if (jda != null) {
    jda.getTextChannelById("CHANNEL_ID")
        .sendMessage("Mensagem customizada do servidor!")
        .queue();
}

Nesta página