AuraSkills API 文档

概述

AuraSkills 是一个 Minecraft 技能系统插件，提供丰富的 API 用于与其他插件集成和自定义内容开发。

核心包名

dev.aurelium:auraskills-api-bukkit:2.2.4

API 实例获取

获取主 API 实例

AuraSkillsApi auraSkills = AuraSkillsApi.get();

获取 Bukkit API 实例

对于需要 Bukkit 类的情况（如 ItemManager 与 Regions API）：

AuraSkillsBukkit auraSkillsBukkit = AuraSkillsBukkit.get();

与玩家交互

获取玩家技能信息

SkillsUser user = auraSkills.getUser(player.getUniqueId());

注意：只有在线玩家会收到技能数据，离线玩家返回的 SkillsUser 对象所有值均为默认值。

技能操作

获取和设置技能等级

// 获取玩家的耕作技能等级
int level = user.getSkillLevel(Skills.FARMING);

// 将战斗技能等级设置为 10
user.setSkillLevel(Skills.FIGHTING, 10);

获取和添加技能经验值

// 获取经验值
double xp = user.getSkillXp(Skills.FARMING);

// 添加经验值
user.addSkillXp(Skills.FARMING, 20.0);

// 无视任意经验修饰符添加经验值
user.addSkillXpRaw(Skills.FARMING, 15.0);

// 将经验值设置为 0（仅对当前技能等级的升级进度有效）
user.setSkillXp(Skills.FARMING, 0.0);

属性操作

获取属性等级

// 获取玩家的力量属性等级
double level = user.getStatLevel(Stats.STRENGTH);

// 获取来源于永久技能奖励的属性等级（无视修饰符）
double baseLevel = user.getBaseStatLevel(Stats.HEALTH);

添加和移除属性修饰符

// 添加 10 点智慧属性修饰符
user.addStatModifier(new StatModifier("my_modifier_name", Stats.WISDOM, 10.0));

// 通过名称移除修饰符
user.removeStatModifier("my_modifier_name");

魔力值操作

获取和设置魔力值

// 获取当前魔力值
double mana = user.getMana();

// 获取最大魔力值（受智慧属性影响）
double maxMana = user.getMaxMana();

// 消耗魔力值
if (user.consumeMana(15.0)) {
    // 魔力消耗成功
}

手动设置魔力值

if (mana >= 10.0) {
    user.setMana(mana - 10.0);
} else {
    // 魔力值不足以扣除的情况
}

事件系统

可用事件列表

LootDropEvent – 在插件掉落/修改战利品时触发
SkillsLoadEvent – 在插件完成技能载入时触发
ManaAbilityActivateEvent – 在玩家激活魔法能力时触发
ManaAbilityRefreshEvent – 在玩家指定的魔法能力冷却完毕时触发
ManaRegenertaeEvent – 在玩家自然恢复魔力值时触发
SkillLevelUpEvent – 在玩家升级技能时触发
XpGainEvent – 在玩家获取技能经验时触发
CustomRegenEvent – 在玩家通过自定义恢复机制再生生命时触发

事件注册

与普通的 Bukkit 事件注册方式相同。

全局注册

获取全局注册实例

GlobalRegistry registry = auraSkills.getGlobalRegistry();

获取技能实例

Skill skill = registry.getSkill(NamespacedId.of("pluginname", "skillname"));

自定义内容

获取命名空间注册器

AuraSkillsApi auraSkills = AuraSkillsApi.get();
NamespacedRegistry registry = auraSkills.useRegistry("pluginname", getDataFolder());

内容目录

useRegistry 的第二个参数为代表内容目录的 Java 文件对象，建议使用插件的数据文件夹（Plugin#getDataFolder()）。

自定义属性

创建自定义特征

public class CustomTraits {
    public static final CustomTrait DODGE_CHANCE = CustomTrait.builder(
        NamespacedId.of("pluginname", "dodge_chance")
    ).displayName("闪避几率").build();
}

创建自定义属性

public class CustomStats {
    public static final CustomStat DEXTERITY = CustomStat.builder(
        NamespacedId.of("pluginname", "dexterity")
    ).trait(CustomTraits.DODGE_CHANCE, 0.5)  // 闪避率每等级灵巧增加 0.5
     .displayName("灵巧")
     .description("增加闪避几率.")
     .color("<green>")
     .symbol("")
     .item(ItemContext.builder()
         .material("lime_stained_glass_pane")
         .group("lower")  // 在 AuraSkills/menus/stats.yml 中设置的组
         .order(2)  // 组内位置
         .build())
     .build();
}

注册自定义特征和属性

AuraSkillsApi auraSkills = AuraSkillsApi.get();
NamespacedRegistry registry = auraSkills.useRegistry("pluginname", getDataFolder());
registry.registerTrait(CustomTraits.DODGE_CHANCE);
registry.registerStat(CustomStats.DEXTERITY);

特征处理实现

public class DodgeChanceTrait implements BukkitTraitHandler, Listener {
    private final AuraSkillsApi auraSkills;
    
    public DodgeChanceTrait(AuraSkillsApi auraSkills) {
        this.auraSkills = auraSkills;
    }
    
    @Override
    public Trait[] getTraits() {
        return new Trait[]{CustomTraits.DODGE_CHANCE};
    }
    
    @Override
    public double getBaseLevel(Player player, Trait trait) {
        return 0;
    }
    
    @Override
    public void onReload(Player player, SkillsUser user, Trait trait) {
        // 在特征的上级属性改变时调用
    }
    
    @EventHandler(ignoreCancelled = true)
    public void onAttack(EntityDamageByEntityEvent event) {
        if (!(event.getEntity() instanceof Player)) return;
        
        Player player = (Player) event.getEntity();
        SkillsUser user = auraSkills.getUser(player.getUniqueId());
        
        double dodgeChance = user.getEffectiveTraitLevel(Traits.DODGE_CHANCE);
        
        if (ThreadLocalRandom.current().nextDouble() < dodgeChance) {
            event.setCancelled(true);
            player.sendMessage("闪避了此次攻击");
        }
    }
}

注册特征处理器

AuraSkillsApi auraSkills = AuraSkillsApi.get();
auraSkills.getHandlers().registerTraitHandler(new DodgeChanceTrait(auraSkills));

自定义技能

创建自定义技能

public class CustomSkills {
    public static final CustomSkill TRADING = CustomSkill.builder(
        NamespacedId.of("pluginname", "trading")
    ).displayName("交易")
     .description("与村民交易可获得经验值")
     .item(ItemContext.builder()
         .material("emerald")
         .pos("4,4")
         .build())
     .build();
}

注册自定义技能

AuraSkillsApi auraSkills = AuraSkillsApi.get();
NamespacedRegistry registry = auraSkills.useRegistry("pluginname", getDataFolder());
registry.registerSkill(CustomSkills.TRADING);

自定义经验来源

创建自定义来源类

public class TradingSource extends CustomSource {
    private final double multiplier;
    
    public TradingSource(SourceValues values, double multiplier) {
        super(values);
        this.multiplier = multiplier;
    }
    
    public double getMultiplier() {
        return multiplier;
    }
}

注册来源类型

SourceType trading = registry.registerSourceType("trading", (XpSourceParser<TradingSource>) (source, context) -> {
    double multiplier = source.node("multiplier").getDouble(1.0);
    return new TradingSource(context.parseValues(source), multiplier);
});

自定义魔法能力

创建自定义魔法能力

public class CustomManaAbilities {
    public static final CustomManaAbility LEAP = CustomManaAbility.builder(
        NamespacedId.of("pluginname", "leap")
    ).displayName("凌波微步")
     .description("立即向前冲刺 [右键点击羽毛触发技能]")
     .build();
}

注册自定义魔法能力

AuraSkillsApi auraSkills = AuraSkillsApi.get();
NamespacedRegistry registry = auraSkills.useRegistry("pluginname", getDataFolder());
registry.registerManaAbility(CustomManaAbilities.LEAP);

获取魔法能力值

SkillsUser user = auraSkills.getUser(player.getUniqueId());
ManaAbility manaAbility = CustomManaAbilities.LEAP;
int level = user.getManaAbilityLevel(manaAbility);
double value = manaAbility.getValue(level);
double cooldown = manaAbility.getCooldown(level);
double manaCost = manaAbility.getManaCost(level);

配置示例

属性配置 (stats.yml)

stats:
  pluginname/dexterity:
    enabled: true
    traits:
      pluginname/dodge_chance:
        modifier: 0.5  # 会覆盖 CustomStatBuilder#trait 中传递的值

traits:
  pluginname/dodge_chance:
    enabled: true

经验来源配置 (sources/trading.yml)

sources:
  trade:
    type: pluginname/trading
    multiplier: 5

能力配置 (abilities.yml)

abilities:
  pluginname/magic_archer:
    enabled: true
    base_value: 15
    value_per_level: 10
    unlock: 6
    level_up: 5
    max_level: 0

重要注意事项

命名空间一致性：传递至 NamespacedId.of 的名称必须与传递至 AuraSkillsApi#useRegistry 的名称相同
插件名称小写：插件名称必须为小写
配置生成：需要通过 Plugin#saveResource 在插件文件夹中生成配置文件
事件监听：如果特征处理器类实现了监听器，调用 registerTraitHandler 会自动注册任意 Bukkit 事件
技能加载时机：若要访问技能、属性等相关数据，请监听 SkillsLoadEvent 而非在 onEnable 下写入代码

枚举类

技能枚举 (Skills)

FARMING – 耕作
FIGHTING – 战斗
其他默认技能…

属性枚举 (Stats)

STRENGTH – 力量
HEALTH – 生命
WISDOM – 智慧
其他默认属性…

特征枚举 (Traits)

包含所有默认特征

实用方法

检查玩家是否在线

SkillsUser user = auraSkills.getUser(player.getUniqueId());
// 只有在线玩家会收到技能数据

获取玩家所有技能信息

通过 Skills 枚举对象获取所有技能实例。

获取玩家所有属性信息

通过 Stats 枚举对象获取所有属性实例。

版本兼容性

API 版本：2.2.4
支持 Minecraft 版本：请参考插件文档
向后兼容性：请参考更新日志

故障排除

常见问题

技能数据未加载：确保监听 SkillsLoadEvent 而非在 onEnable 中访问技能数据
自定义内容未生效：检查命名空间是否一致，配置是否正确
事件未触发：确保正确注册了事件监听器
魔力值操作失败：使用 consumeMana 方法会自动检查魔力值是否足够

调试建议

检查插件日志输出
验证命名空间和配置路径
确保所有必要的依赖已正确添加
测试在线玩家和离线玩家的不同行为

文档来自SnowCutieOwO – wiki

Overview