API

O ySkills oferece uma API completa para desenvolvedores que desejam integrar o sistema de skills em seus próprios plugins.

Requisito

Para usar a API, adicione o ySkills como dependência no seu plugin.yml:

depend: [ySkills]

softdepend: [ySkills]

Obtendo a API

Método 1: Através do Main

import com.ystoreplugins.yskills.Main;
import com.ystoreplugins.yskills.api.SkillAPI;

public class SeuPlugin extends JavaPlugin {
    
    private SkillAPI skillAPI;
    
    @Override
    public void onEnable() {
        if (getServer().getPluginManager().getPlugin("ySkills") != null) {
            skillAPI = Main.get().getSkillAPI();
            getLogger().info("ySkills API carregada com sucesso!");
        }
    }
}

Método 2: Através do SkillAPIHolder

import br.com.ystoreplugins.product.yskills.SkillAPIHolder;

SkillAPIHolder api = Main.get().getSkillAPI();

Métodos da API

Informações de Skills

Obter uma Skill

/**
 * Obtém uma skill pelo identificador
 * @param skillKey Identificador da skill (ex: "mining", "swords")
 * @return A skill ou null se não encontrada
 */
SkillHolder getSkill(String skillKey);

// Exemplo
SkillHolder mining = api.getSkill("mining");
if (mining != null) {
    String displayName = mining.getDisplayName(); // &eMineração
}

Obter Todas as Skills

/**
 * Obtém todas as skills registradas
 * @return HashMap com todas as skills (key -> Skill)
 */
HashMap<String, SkillHolder> getAllSkills();

// Exemplo
for (SkillHolder skill : api.getAllSkills().values()) {
    player.sendMessage(skill.getDisplayName());
}

Verificar se Skill Existe

/**
 * Verifica se uma skill existe
 * @param skillKey Identificador da skill
 * @return true se a skill existe
 */
boolean skillExists(String skillKey);

// Exemplo
if (api.skillExists("mining")) {
    // Fazer algo
}

Dados do Jogador

Obter Dados de um Jogador

/**
 * Obtém os dados de skill de um jogador
 * @param player Jogador
 * @return PlayerSkill ou null se não encontrado
 */
PlayerSkillHolder getPlayerSkill(Player player);

// Exemplo
PlayerSkillHolder playerSkill = api.getPlayerSkill(player);
if (playerSkill != null) {
    double totalXP = playerSkill.getTotalXp();
    double totalLevel = playerSkill.getTotalLevel();
}

Obter Nível em uma Skill

/**
 * Obtém o nível de uma skill específica
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @return Nível do jogador na skill, ou 0 se não encontrado
 */
int getPlayerLevel(Player player, String skillKey);

// Exemplo
int miningLevel = api.getPlayerLevel(player, "mining");
player.sendMessage("Seu nível de mineração: " + miningLevel);

Obter XP em uma Skill

/**
 * Obtém o XP de uma skill específica
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @return XP do jogador na skill, ou 0 se não encontrado
 */
double getPlayerXP(Player player, String skillKey);

// Exemplo
double miningXP = api.getPlayerXP(player, "mining");

Obter XP Necessário para Próximo Nível

/**
 * Obtém o XP necessário para o próximo nível
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @return XP necessário
 */
double getXPToNextLevel(Player player, String skillKey);

// Exemplo
double needed = api.getXPToNextLevel(player, "mining");
player.sendMessage("Faltam " + needed + " XP para o próximo nível");

Manipulação de XP

Adicionar XP

/**
 * Adiciona XP a uma skill
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @param xp Quantidade de XP a adicionar
 * @return true se a operação foi bem-sucedida
 */
boolean addXP(Player player, String skillKey, double xp);

// Exemplo
boolean success = api.addXP(player, "mining", 100.0);
if (success) {
    player.sendMessage("§a+100 XP em Mineração!");
}

Remover XP

/**
 * Remove XP de uma skill
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @param xp Quantidade de XP a remover
 * @return true se a operação foi bem-sucedida
 */
boolean removeXP(Player player, String skillKey, double xp);

// Exemplo
api.removeXP(player, "mining", 50.0);

Definir XP

/**
 * Define o XP de uma skill
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @param xp Quantidade de XP a definir
 * @return true se a operação foi bem-sucedida
 */
boolean setXP(Player player, String skillKey, double xp);

// Exemplo
api.setXP(player, "mining", 10000.0);

Totais do Jogador

Nível Total

/**
 * Obtém o nível total (soma de todas as skills)
 * @param player Jogador
 * @return Nível total
 */
double getTotalLevel(Player player);

// Exemplo
double total = api.getTotalLevel(player);
player.sendMessage("Nível total: " + total);

XP Total

/**
 * Obtém o XP total (soma de todas as skills)
 * @param player Jogador
 * @return XP total
 */
double getTotalXP(Player player);

Sistema de Boosters

Obter Multiplicador Total

/**
 * Obtém o multiplicador total (global * individual)
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @return Multiplicador total
 */
double getBoosterMultiplier(Player player, String skillKey);

// Exemplo
double mult = api.getBoosterMultiplier(player, "mining");
// Se global = 2x e individual = 1.5x, retorna 3.0

Verificar Boosters Ativos

/**
 * Verifica se há booster global ativo
 * @return true se houver
 */
boolean hasActiveGlobalBooster();

/**
 * Verifica se o jogador tem booster individual
 * @param player Jogador
 * @return true se tiver
 */
boolean hasActiveIndividualBooster(Player player);

// Exemplo
if (api.hasActiveGlobalBooster()) {
    player.sendMessage("§6Booster global ativo!");
}

Obter Boosters Ativos

/**
 * Obtém todos os boosters globais ativos
 * @return Lista de boosters
 */
List<BoosterHolder> getActiveGlobalBoosters();

/**
 * Obtém todos os boosters individuais do jogador
 * @param player Jogador
 * @return Lista de boosters
 */
List<BoosterHolder> getActiveIndividualBoosters(Player player);

// Exemplo
for (BoosterHolder booster : api.getActiveGlobalBoosters()) {
    player.sendMessage("Booster: " + booster.getMultiplier() + "x");
}

Sistema de Requisitos

Verificar Requisito

/**
 * Verifica se o jogador atende ao requisito
 * @param player Jogador
 * @param target Tipo do bloco/mob (ex: "DIAMOND_ORE", "WITHER")
 * @param isBlock true se for bloco, false se for mob
 * @return true se atende ao requisito
 */
boolean meetsRequirement(Player player, String target, boolean isBlock);

// Exemplo - Verificar se pode quebrar diamante
if (!api.meetsRequirement(player, "DIAMOND_ORE", true)) {
    player.sendMessage("§cVocê não tem nível suficiente!");
    event.setCancelled(true);
}

// Exemplo - Verificar se pode atacar Wither
if (!api.meetsRequirement(player, "WITHER", false)) {
    player.sendMessage("§cVocê não pode atacar este mob!");
    event.setCancelled(true);
}

Obter Requisitos

/**
 * Obtém o requisito de um bloco
 * @param blockType Tipo do bloco
 * @return SkillRequirement ou null
 */
SkillRequirement getBlockRequirement(String blockType);

/**
 * Obtém o requisito de um mob
 * @param mobType Tipo do mob
 * @return SkillRequirement ou null
 */
SkillRequirement getMobRequirement(String mobType);

// Exemplo
SkillRequirement req = api.getBlockRequirement("DIAMOND_ORE");
if (req != null) {
    Map<String, Integer> requirements = req.getRequirements();
    // mining -> 20
}

Sistema de Habilidades

Verificar se tem Habilidade

/**
 * Verifica se o jogador tem uma habilidade desbloqueada
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @param abilityKey Identificador da habilidade
 * @return true se está desbloqueada
 */
boolean hasAbility(Player player, String skillKey, String abilityKey);

// Exemplo
if (api.hasAbility(player, "mining", "super_breaker")) {
    // Jogador tem Super Breaker
}

Obter Nível da Habilidade

/**
 * Obtém o nível de uma habilidade
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @param abilityKey Identificador da habilidade
 * @return Nível da habilidade, ou 0 se não desbloqueada
 */
int getAbilityLevel(Player player, String skillKey, String abilityKey);

// Exemplo
int level = api.getAbilityLevel(player, "mining", "double_drop");
double dropChance = 5.0 + (level * 2.0); // 5% base + 2% por nível

Sistema de Ranking

Obter Posição no Ranking

/**
 * Obtém a posição do jogador no ranking
 * @param player Jogador
 * @param skillKey Identificador da skill
 * @return Posição (1-based), ou -1 se não encontrado
 */
int getPlayerRankPosition(Player player, String skillKey);

// Exemplo
int pos = api.getPlayerRankPosition(player, "mining");
if (pos == 1) {
    player.sendMessage("§6Você é o TOP 1 em Mineração!");
}

Obter Top Jogadores

/**
 * Obtém o top X jogadores de uma skill
 * @param skillKey Identificador da skill
 * @param limit Número máximo de jogadores
 * @return Lista ordenada de PlayerSkill
 */
List<PlayerSkillHolder> getTopPlayers(String skillKey, int limit);

// Exemplo - Top 10 Mining
List<PlayerSkillHolder> top10 = api.getTopPlayers("mining", 10);
int position = 1;
for (PlayerSkillHolder ps : top10) {
    player.sendMessage(position + "º - " + ps.getPlayerName());
    position++;
}

Eventos da API

O ySkills dispara vários eventos que você pode escutar:

SkillXPGainEvent

Disparado quando um jogador ganha XP em uma skill.

import br.com.ystoreplugins.product.yskills.event.SkillXPGainEvent;

@EventHandler
public void onSkillXPGain(SkillXPGainEvent event) {
    Player player = event.getPlayer();
    SkillHolder skill = event.getSkill();
    double xpGained = event.getXp();
    double xpBefore = event.getXpBefore();
    double xpAfter = event.getXpAfter();
    
    // Modificar XP ganho
    event.setXp(xpGained * 2); // Dobra o XP
    
    // Ou cancelar completamente
    // event.setXp(0);
}

SkillLevelUpEvent

Disparado quando um jogador sobe de nível em uma skill.

import br.com.ystoreplugins.product.yskills.event.SkillLevelUpEvent;

@EventHandler
public void onSkillLevelUp(SkillLevelUpEvent event) {
    Player player = event.getPlayer();
    SkillHolder skill = event.getSkill();
    int oldLevel = event.getOldLevel();
    int newLevel = event.getNewLevel();
    int levelsGained = event.getLevelsGained();
    
    player.sendMessage("§aParabéns! Você subiu para o nível " + newLevel + " em " + skill.getDisplayName());
    
    // Dar recompensa personalizada
    if (newLevel == 50) {
        player.getInventory().addItem(new ItemStack(Material.DIAMOND, 10));
    }
}

AbilityUnlockEvent

Disparado quando um jogador desbloqueia uma habilidade.

import br.com.ystoreplugins.product.yskills.event.AbilityUnlockEvent;

@EventHandler
public void onAbilityUnlock(AbilityUnlockEvent event) {
    Player player = event.getPlayer();
    SkillHolder skill = event.getSkill();
    AbilityHolder ability = event.getAbility();
    int playerLevel = event.getPlayerLevel();
    
    player.sendMessage("§6Nova habilidade desbloqueada: §f" + ability.getDisplayName());
}

BoosterActivateEvent

Disparado quando um booster é ativado (pode ser cancelado).

import br.com.ystoreplugins.product.yskills.event.BoosterActivateEvent;

@EventHandler
public void onBoosterActivate(BoosterActivateEvent event) {
    Player player = event.getPlayer(); // null se for global
    BoosterHolder booster = event.getBooster();
    boolean isGlobal = event.isGlobal();
    double multiplier = event.getMultiplier();
    
    // Cancelar ativação em determinadas condições
    if (isGlobal && multiplier > 5.0) {
        event.setCancelled(true);
        return;
    }
    
    if (isGlobal) {
        Bukkit.broadcastMessage("§6Booster global de " + multiplier + "x ativado!");
    }
}

RequirementCheckEvent

Disparado quando o sistema verifica um requisito (pode ser cancelado para permitir a ação).

import br.com.ystoreplugins.product.yskills.event.RequirementCheckEvent;

@EventHandler
public void onRequirementCheck(RequirementCheckEvent event) {
    Player player = event.getPlayer();
    String target = event.getTarget(); // DIAMOND_ORE, WITHER, etc
    SkillRequirementHolder requirement = event.getRequirement();
    boolean isBlock = event.isBlock();
    boolean meetsRequirement = event.meetsRequirement();
    
    // Permitir bypass para jogadores VIP
    if (!meetsRequirement && player.hasPermission("vip.bypass.requirements")) {
        event.setCancelled(true); // Cancela a restrição
        player.sendMessage("§aVocê usou seu bypass VIP!");
    }
}

Exemplo Completo de Integração

package com.exemplo.meuplugin;

import com.ystoreplugins.yskills.Main;
import com.ystoreplugins.yskills.api.SkillAPI;
import br.com.ystoreplugins.product.yskills.event.SkillLevelUpEvent;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class MeuPlugin extends JavaPlugin implements Listener {
    
    private SkillAPI skillAPI;
    
    @Override
    public void onEnable() {
        // Verificar se ySkills está instalado
        if (getServer().getPluginManager().getPlugin("ySkills") == null) {
            getLogger().severe("ySkills não encontrado! Desabilitando plugin.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
        
        // Obter API
        skillAPI = Main.get().getSkillAPI();
        
        // Registrar eventos
        getServer().getPluginManager().registerEvents(this, this);
        
        getLogger().info("Integração com ySkills ativada!");
    }
    
    // Método customizado usando a API
    public void darBonusVIP(Player player) {
        // Dar bônus de XP para VIPs
        if (player.hasPermission("vip.bonus")) {
            skillAPI.addXP(player, "mining", 1000.0);
            skillAPI.addXP(player, "swords", 1000.0);
            player.sendMessage("§aVocê recebeu bônus VIP de XP!");
        }
    }
    
    // Escutar evento de level up
    @EventHandler
    public void onLevelUp(SkillLevelUpEvent event) {
        Player player = event.getPlayer();
        int newLevel = event.getNewLevel();
        
        // Dar recompensa a cada 10 níveis
        if (newLevel % 10 == 0) {
            // Executar comando customizado
            getServer().dispatchCommand(getServer().getConsoleSender(), 
                "give " + player.getName() + " diamond 5");
            player.sendMessage("§6Recompensa por atingir nível " + newLevel + "!");
        }
    }
    
    // Verificar se pode fazer algo baseado no nível
    public boolean podeUsarComando(Player player) {
        int miningLevel = skillAPI.getPlayerLevel(player, "mining");
        return miningLevel >= 50;
    }
}

Documentação Completa

Para ver todos os métodos disponíveis, consulte o JavaDoc da API ou examine o código fonte em: com.ystoreplugins.yskills.api.SkillAPI

Maven/Gradle

Maven

<repositories>
    <repository>
        <id>ystoreplugins-repo</id>
        <url>https://repo.ystoreplugins.com.br/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.ystoreplugins</groupId>
        <artifactId>ySkills</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle

repositories {
    maven {
        url 'https://repo.ystoreplugins.com.br/'
    }
}

dependencies {
    compileOnly 'com.ystoreplugins:ySkills:1.0.0'
}

Versão

Substitua 1.0.0 pela versão atual do ySkills que você está usando.

API

Nesta página