API

API do yTempoOnline para rastreamento e gerenciamento de tempo de jogo do jogador

Visão Geral

A API do yTempoOnline fornece métodos para recuperar e rastrear dados de tempo de jogo dos jogadores. Este plugin rastreia o tempo total que os jogadores passaram no servidor e fornece acesso a essas informações através de uma API simples.

Obtendo a Instância da API

import br.com.ystoreplugins.product.ytempoonline.TempoAPIHolder;
import com.ystoreplugins.ytempoonline.api.TempoAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

// Método 1: Instanciação direta
TempoAPI api = new TempoAPI();

// Método 2: Através do provedor de serviços (recomendado)
RegisteredServiceProvider<TempoAPIHolder> provider = 
    Bukkit.getServicesManager().getRegistration(TempoAPIHolder.class);
    
if (provider != null) {
    TempoAPIHolder api = provider.getProvider();
    // Usar API
}

Métodos Disponíveis

retrievePlayer(String player)

Recupera dados de tempo de jogo em cache para um jogador específico.

Parâmetros:

player (String) - O nome ou UUID do jogador

Retorna:

PlayerTempoHolder - O objeto de dados de tempo de jogo do jogador, ou null se não encontrado em cache

Observações Importantes:

Retorna dados em cache; pode não refletir mudanças em tempo real até que o cache seja atualizado
Retorna null se o jogador não for encontrado no cache
O jogador deve ter feito login pelo menos uma vez para que os dados sejam armazenados em cache
Os dados são recuperados do cache de usuários do gerenciador de dados principal
Sempre verifique se há null antes de acessar dados do jogador

Exemplo de Uso:

TempoAPI api = new TempoAPI();

PlayerTempoHolder playerData = api.retrievePlayer("Steve");
if (playerData != null) {
    System.out.println("Jogador encontrado em cache");
    // Acessar dados de tempo de jogo do jogador
} else {
    System.out.println("Jogador não encontrado em cache");
}

Estruturas de Dados

PlayerTempoHolder

Contém informações de tempo de jogo para um jogador.

Propriedades Principais:

Armazena tempo de jogo acumulado em ticks ou milissegundos
Rastreia dados de sessão e tempo total no servidor
Inclui informações de identificação do jogador

Operações Comuns:

PlayerTempoHolder playerData = api.retrievePlayer("Steve");

if (playerData != null) {
    // Acessar informações de tempo de jogo
    // Métodos disponíveis dependem da implementação de PlayerTempoHolder
    // Tipicamente inclui getters para tempo total de jogo, contagem de sessão, etc.
}

Padrão de Acesso: O PlayerTempoHolder é acessado através do cache de usuários do gerenciador de dados principal e fornece acesso direto às métricas de tempo de jogo do jogador.

Melhores Práticas

Verificar Nulo - Sempre verifique que retrievePlayer() não retorna null antes de usar os dados.
Consciência do Cache - Entenda que a API retorna dados em cache; o tempo de jogo atualizado recentemente pode levar tempo para refletir.
Identificação do Jogador - Use o identificador correto do jogador (nome ou UUID) ao consultar a API.
Persistência de Dados - Os dados de tempo de jogo são persistidos e carregados do armazenamento quando o servidor inicia.
Operações Assíncronas - Considere recuperar dados de tempo de jogo de forma assíncrona se estiver verificando muitos jogadores.
Atualizações de Cache - O cache é atualizado quando os jogadores entram, saem ou em intervalos regulares.
Tratamento de Erros - Implemente verificações nulas apropriadas e lidar com dados de jogador ausentes graciosamente.

Exemplos de Código

Exemplo 1: Obter Tempo de Jogo do Jogador

public void displayPlayerPlaytime(String playerName) {
    TempoAPI api = new TempoAPI();
    PlayerTempoHolder playerData = api.retrievePlayer(playerName);
    
    if (playerData != null) {
        System.out.println("Jogador " + playerName + " está em cache");
        // Processar dados de tempo de jogo
    } else {
        System.out.println("Jogador " + playerName + " não encontrado em cache");
    }
}

Exemplo 2: Verificar Múltiplos Jogadores

public void checkMultiplePlayersPlaytime(List<String> playerNames) {
    TempoAPI api = new TempoAPI();
    
    for (String playerName : playerNames) {
        PlayerTempoHolder playerData = api.retrievePlayer(playerName);
        
        if (playerData != null) {
            System.out.println(playerName + " - Dados de tempo de jogo disponíveis");
        } else {
            System.out.println(playerName + " - Não em cache");
        }
    }
}

Exemplo 3: Ranking de Tempo de Jogo

public void displayPlaytimeLeaderboard() {
    TempoAPI api = new TempoAPI();
    List<String> players = getServerPlayers(); // Seu método para obter todos os jogadores
    
    System.out.println("=== Ranking de Tempo de Jogo ===");
    
    players.stream()
        .map(api::retrievePlayer)
        .filter(playerData -> playerData != null)
        .sorted((a, b) -> {
            // Ordenar por tempo de jogo (implementação depende de PlayerTempoHolder)
            return 0; // Substituir pela comparação real
        })
        .forEach(playerData -> {
            System.out.println("Jogador: " + playerData);
        });
}

Exemplo 4: Manipulador de Entrada de Jogador com Tempo de Jogo

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;

public class PlaytimeTracker implements Listener {
    private final TempoAPI api = new TempoAPI();
    
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        String playerName = event.getPlayer().getName();
        PlayerTempoHolder playerData = api.retrievePlayer(playerName);
        
        if (playerData != null) {
            System.out.println(playerName + " entrou no servidor");
            // Acessar tempo de jogo acumulado
        } else {
            // Jogador pela primeira vez ou dados não em cache
            System.out.println(playerName + " entrou pela primeira vez ou dados não em cache");
        }
    }
}

Exemplo 5: Recompensas Baseadas em Tempo de Jogo

public class PlaytimeRewardManager {
    private final TempoAPI api = new TempoAPI();
    private final long REWARD_THRESHOLD = 86400000; // 24 horas em milissegundos
    
    public void checkAndRewardPlaytime(Player player) {
        PlayerTempoHolder playerData = api.retrievePlayer(player.getName());
        
        if (playerData != null) {
            // Verificar se o jogador acumulou tempo de jogo suficiente
            // Implementação depende de como PlayerTempoHolder armazena tempo
            
            System.out.println("Verificando recompensas de tempo de jogo para " + player.getName());
            
            // Se o tempo de jogo exceder o limite
            // Dar recompensas ao jogador (itens, dinheiro, etc.)
        }
    }
}

Exemplo 6: Verificação de Tempo de Jogo

public boolean verifyPlayerPlaytime(String playerName) {
    TempoAPI api = new TempoAPI();
    PlayerTempoHolder playerData = api.retrievePlayer(playerName);
    
    if (playerData == null) {
        System.out.println("Jogador não possui dados de tempo de jogo");
        return false;
    }
    
    // Verificar se o jogador existe e possui dados
    System.out.println("Jogador " + playerName + " possui dados de tempo de jogo");
    return true;
}

Exemplo 7: Verificação em Lote de Tempo de Jogo

public Map<String, Boolean> batchPlaytimeCheck(List<String> playerNames) {
    TempoAPI api = new TempoAPI();
    Map<String, Boolean> results = new HashMap<>();
    
    for (String playerName : playerNames) {
        PlayerTempoHolder playerData = api.retrievePlayer(playerName);
        results.put(playerName, playerData != null);
    }
    
    return results;
}

Exemplo 8: Recuperação Assíncrona de Tempo de Jogo

import org.bukkit.Bukkit;
import org.bukkit.plugin.Plugin;

public class AsyncPlaytimeRetriever {
    private final Plugin plugin;
    private final TempoAPI api = new TempoAPI();
    
    public AsyncPlaytimeRetriever(Plugin plugin) {
        this.plugin = plugin;
    }
    
    public void retrievePlaytimeAsync(String playerName, Consumer<PlayerTempoHolder> callback) {
        Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
            PlayerTempoHolder playerData = api.retrievePlayer(playerName);
            
            Bukkit.getScheduler().runTask(plugin, () -> {
                callback.accept(playerData);
            });
        });
    }
}

Exemplo 9: Resumo de Status do Jogador

public void displayPlayerStatus(String playerName) {
    TempoAPI api = new TempoAPI();
    PlayerTempoHolder playerData = api.retrievePlayer(playerName);
    
    System.out.println("=== Status do Jogador: " + playerName + " ===");
    
    if (playerData != null) {
        System.out.println("Status: Dados Disponíveis");
        System.out.println("Em Cache: Sim");
        // Exibir informações adicionais de tempo de jogo
    } else {
        System.out.println("Status: Não Encontrado");
        System.out.println("Em Cache: Não");
        System.out.println("Nota: O jogador pode precisar entrar no servidor primeiro");
    }
}

Exemplo 10: Integração com Outros Sistemas

public class PlaytimeIntegration {
    private final TempoAPI tempoAPI = new TempoAPI();
    
    public void integrateWithRewardSystem(Player player) {
        PlayerTempoHolder playerData = tempoAPI.retrievePlayer(player.getName());
        
        if (playerData != null) {
            // Usar dados de tempo de jogo para determinar recompensas
            System.out.println("Jogador " + player.getName() + " possui dados de tempo de jogo");
            
            // Calcular com base no tempo de jogo acumulado
            // Conceder pontos, itens ou status especial
            
            // Isto pode ser integrado com:
            // - yEconomy para recompensas monetárias
            // - yRankup para progressão
            // - yRecompensas para recompensas
            // - Qualquer sistema de recompensa personalizado
            
        } else {
            System.out.println("Jogador " + player.getName() + " não possui dados de tempo de jogo");
            System.out.println("Não é possível conceder recompensas neste momento");
        }
    }
}

Exemplo 11: Comparação de Tempo de Jogo

public void comparePlayerPlaytime(String player1, String player2) {
    TempoAPI api = new TempoAPI();
    
    PlayerTempoHolder data1 = api.retrievePlayer(player1);
    PlayerTempoHolder data2 = api.retrievePlayer(player2);
    
    if (data1 != null && data2 != null) {
        System.out.println("=== Comparação de Tempo de Jogo ===");
        System.out.println("Jogador 1: " + player1);
        System.out.println("Jogador 2: " + player2);
        
        // Comparar tempo de jogo entre jogadores
        // Lógica depende da implementação de PlayerTempoHolder
        
    } else {
        System.out.println("Não é possível comparar: Um ou ambos os jogadores não encontrados em cache");
    }
}

Exemplo 12: Exemplo de Integração Completa

public class PlaytimeSystemIntegration {
    private final Plugin plugin;
    private final TempoAPI api;
    
    public PlaytimeSystemIntegration(Plugin plugin) {
        this.plugin = plugin;
        this.api = new TempoAPI();
    }
    
    public void onPlayerLogin(Player player) {
        String playerName = player.getName();
        PlayerTempoHolder playerData = api.retrievePlayer(playerName);
        
        if (playerData != null) {
            // O jogador tem histórico de tempo de jogo
            System.out.println("[TEMPO DE JOGO] " + playerName + " fez login");
            
            // Verificar marcos
            checkPlaytimeMilestones(player, playerData);
            
            // Aplicar benefícios baseados em tempo de jogo
            applyPlaytimePerks(player, playerData);
        } else {
            // Novo jogador ou primeiro login
            System.out.println("[TEMPO DE JOGO] Novo jogador ou dados não em cache: " + playerName);
            
            // Boas-vindas ao novo jogador
            player.sendMessage("§6Bem-vindo! Seu tempo de jogo está sendo rastreado.");
        }
    }
    
    private void checkPlaytimeMilestones(Player player, PlayerTempoHolder playerData) {
        // Verificar se o jogador atingiu marcos de tempo de jogo
        System.out.println("[MARCO] Verificando marcos para " + player.getName());
    }
    
    private void applyPlaytimePerks(Player player, PlayerTempoHolder playerData) {
        // Aplicar benefícios com base no tempo de jogo acumulado
        System.out.println("[BENEFÍCIOS] Aplicando benefícios de tempo de jogo a " + player.getName());
    }
}

Nesta página