API 与桥接开发

EMC 玩家属性提供开放 API，允许其他插件注册属性提供者和伤害处理器，将自己的属性系统接入统一框架。

API 入口

通过 EMCPlayerAttrAPI 静态类获取各管理器实例：

import org.emc.playerattr.api.EMCPlayerAttrAPI;

// 获取属性管理器
IAttributeManager attrManager = EMCPlayerAttrAPI.getAttributeManager();

// 获取伤害管理器
IDamageManager dmgManager = EMCPlayerAttrAPI.getDamageManager();

注意：调用前确保 EMC 玩家属性已加载，建议在 plugin.yml 中声明 softdepend: [EMC玩家属性]。

属性提供者接口

IAttributeProvider

任何能为玩家提供属性修改的系统都应实现此接口。

public interface IAttributeProvider {
    // 唯一标识
    String getProviderId();

    // 显示名称
    String getProviderName();

    // 获取该提供者为指定玩家提供的所有属性修改器
    Collection<AttributeModifier> getModifiers(Player player);

    // 优先级，数值越小越先计算（默认 0）
    default int getPriority() { return 0; }
}

注册属性提供者

IAttributeManager attrManager = EMCPlayerAttrAPI.getAttributeManager();
attrManager.registerProvider(new MySkillAttributeProvider());

AttributeModifier

属性修改器定义了对某个属性的具体修改：

// 示例：创建一个修改器
AttributeModifier modifier = new AttributeModifier(
    "my_skill_buff",           // 修改器 ID
    Attribute.PHYSICAL_ATTACK, // 目标属性
    10.0,                      // 修改值
    ModifierOperation.ADD      // 操作类型
);

伤害处理器接口

IDamageHandler

用于在伤害计算流程中插入自定义逻辑。

public interface IDamageHandler {
    // 唯一标识
    String getHandlerId();

    // 优先级，数值越小越先执行
    int getPriority();

    // 处理伤害计算
    void handleDamage(DamageContext context);
}

注册伤害处理器

IDamageManager dmgManager = EMCPlayerAttrAPI.getDamageManager();
dmgManager.registerHandler(new MyDamageHandler());

伤害处理器示例

public class MyDamageHandler implements IDamageHandler {
    @Override
    public String getHandlerId() {
        return "my_plugin_damage";
    }

    @Override
    public int getPriority() {
        return 20; // 在武器(0)和饰品(10)之后执行
    }

    @Override
    public void handleDamage(DamageContext context) {
        // 例：如果攻击者有特殊 Buff，伤害 +50%
        if (hasSpecialBuff(context.getAttacker())) {
            double dmg = context.getFinalDamage();
            context.setFinalDamage(dmg * 1.5);
        }
    }
}

内置桥接实现

武器桥接

EMC 自定义武器在启动时自动注册：

组件	类名	功能
属性提供者	WeaponAttributeProvider	读取手持武器的攻击力、暴击、攻速等属性
伤害处理器	WeaponDamageHandler	应用武器攻击源特效、元素伤害计算

饰品桥接

EMC 自定义饰品在启动时自动注册：

组件	类名	功能
属性提供者	AccessoryAttributeProvider	汇总所有已装备饰品的属性加成
伤害处理器	AccessoryDamageHandler	处理饰品触发效果（攻击/受伤/击杀触发）

属性映射

桥接层通过 AttributeMapping 将武器/饰品的属性键名映射到 Attribute 枚举：

武器/饰品属性	玩家属性
base-damage / attack-damage	PHYSICAL_ATTACK
attack-speed	ATTACK_SPEED
crit-chance	CRITICAL_CHANCE
crit-multiplier / crit-damage	CRITICAL_DAMAGE
attack-range	ATTACK_RANGE
armor-penetration	ARMOR_PENETRATION
knockback	WEAPON_KNOCKBACK
lifesteal	LIFE_STEAL
health	MAX_HEALTH
defense	PHYSICAL_DEFENSE
magic-defense	MAGIC_DEFENSE
dodge	DODGE_CHANCE
block	BLOCK_CHANCE
thorns	THORNS

Bukkit 属性同步

AttributeSyncListener 会在属性重算后自动将以下属性同步到 Bukkit 原生属性系统：

玩家属性	Bukkit 属性
MAX_HEALTH	generic.maxHealth
MOVE_SPEED	generic.movementSpeed
ATTACK_SPEED	generic.attackSpeed（1.9+）
KNOCKBACK_RESISTANCE	generic.knockbackResistance

这意味着修改这些属性后，效果会立即反映在游戏中。

开发建议

• 使用 softdepend 声明依赖，通过 try-catch 包裹注册代码
• 属性提供者的 getModifiers() 应高效运行（可能被频繁调用）
• 伤害处理器中避免耗时操作，保持处理链的低延迟
• 优先级建议：核心系统 010，扩展系统 2050，修饰系统 50+