ModuleLifecycleEvent、TaczGunDamageEvent、TaczGunKillEvent、AttributeDamageEvent 等事件类的 API 参考。

事件系统

Suite 提供标准 Bukkit 事件，供第三方插件监听模块状态变化和战斗事件。

ModuleLifecycleEvent

模块生命周期事件——模块加载/卸载/重载时触发。标记为 @ApiStability.Stable。

第三方插件（不仅限于 AXS 模块）可通过标准 Bukkit 事件机制监听此事件。

使用示例

public class MyListener implements Listener {
 
    @EventHandler
    public void onModuleLifecycle(ModuleLifecycleEvent event) {
        if (event.phase() == ModuleLifecycleEvent.Phase.ENABLED
                && "warehouse".equals(event.moduleId())) {
            // warehouse 模块已加载完成，可安全查找其 Capability
        }
 
        if (event.phase() == ModuleLifecycleEvent.Phase.DISABLING
                && "title".equals(event.moduleId())) {
            // title 模块即将禁用，清理引用
        }
    }
}

生命周期阶段

Phase	说明	时机
`ENABLING`	模块即将启用	`onEnable()` 之前
`ENABLED`	模块已成功启用	`onEnable()` 返回 `true` 之后
`ENABLE_FAILED`	模块启用失败	`onEnable()` 抛出异常
`DISABLING`	模块即将禁用	`onDisable()` 之前
`DISABLED`	模块已禁用	`onDisable()` 完成之后
`RELOADING`	模块开始重载	`onReload()` 之前
`RELOADED`	模块重载完成	`onReload()` 完成之后

事件属性

方法	返回类型	说明
`moduleId()`	`String`	模块 id（如 `"warehouse"`）
`moduleName()`	`String`	模块显示名称
`phase()`	`Phase`	当前生命周期阶段
`module()`	`AXSModule`	模块实例（`ENABLE_FAILED` 时可能不完整）

典型场景

场景	推荐监听的 Phase
等待目标模块加载后查找 Capability	`ENABLED`
清理对某模块的引用	`DISABLING`
重载后刷新缓存	`RELOADED`
记录模块失败日志	`ENABLE_FAILED`

AttributeDamageEvent

统一属性伤害事件，由宿主从各属性插件（AttributePlus / CraneAttribute / MythicLib / Symphony）归一化后分发。标记为 @ApiStability.Stable。

注册方式： context.attributeBridge().registerDamageListener(listener)

事件字段

字段	类型	说明
`attacker`	`@Nullable Player`	攻击者（非玩家攻击时为 null）
`target`	`@NotNull Entity`	受击实体
`damage`	`double`	伤害数值
`source`	`Source`	伤害来源
`critical`	`boolean`	是否暴击
`dodged`	`boolean`	是否被闪避（dodged=true 时 damage=0）
`relation`	`@Nullable DamageRelation`	元素克制关系

Source 枚举

值	说明
`ATTRIBUTE_PLUS`	AttributePlus 属性伤害
`CRANE_ATTRIBUTE`	CraneAttribute 属性伤害
`MYTHIC_LIB`	MythicLib / MMOItems 属性伤害
`SYMPHONY`	Symphony 属性伤害
`BUKKIN`	Bukkit 原版伤害
`OTHER`	其他来源

DamageRelation 枚举

值	说明
`ADVANTAGED`	优势（克制对方）
`NEUTRAL`	中性
`DISADVANTAGED`	劣势（被克制）

使用示例

context.attributeBridge().registerDamageListener(event -> {
    if (event.dodged()) {
        showDodgeText(event.attacker(), event.target());
        return;
    }
    if (event.critical()) {
        showCriticalText(event.attacker(), event.target(), event.damage());
        return;
    }
    if (event.relation() == AttributeDamageEvent.DamageRelation.ADVANTAGED) {
        showAdvantagedText(event.attacker(), event.target(), event.damage());
    }
});

AttributeHealEvent

统一属性治疗事件，由宿主从各属性插件归一化后分发。标记为 @ApiStability.Stable。

注册方式： context.attributeBridge().registerHealListener(listener)

字段	类型	说明
`healer`	`@Nullable Player`	治疗者
`target`	`@NotNull LivingEntity`	治疗目标
`amount`	`double`	治疗量
`source`	`Source`	治疗来源

TaczGunDamageEvent

TACZ（创世战术武器）枪械伤害事件。当 TACZ Mod 的 EntityHurtByGunEvent.Pre 触发时，由 TaczCombatBridge 转换为标准 Bukkit 事件并广播。标记为 @ApiStability.Stable。

此事件与 EntityDamageByEntityEvent 完全解耦：TACZ 伤害不再被伪装为 Bukkit 原版事件，模块可明确区分枪械伤害与近战/弓箭等原版伤害。

注册方式： 标准 Bukkit @EventHandler 监听

事件字段

方法	返回类型	说明
`getAttacker()`	`@NotNull Player`	攻击者（开枪的玩家）
`getTarget()`	`@NotNull LivingEntity`	被击中的实体
`getDamage()`	`double`	伤害值（尚未经过护甲/抗性减免）
`isHeadShot()`	`boolean`	是否为爆头
`getGunId()`	`@NotNull String`	枪械 ID（如 `tacz:modern_kinetic_gun`）

使用示例

@EventHandler
public void onTaczDamage(TaczGunDamageEvent event) {
    Player attacker = event.getAttacker();
    LivingEntity target = event.getTarget();
    double damage = event.getDamage();
    boolean headshot = event.isHeadShot();
    String gunId = event.getGunId();
    // CombatEffect 可据此显示枪械伤害飘字
    // EntityTracker 可据此统计 Boss 枪械伤害排行
}

TaczGunKillEvent

TACZ 枪械击杀事件。当 TACZ Mod 的 EntityKillByGunEvent 触发时转换并广播。标记为 @ApiStability.Stable。

TACZ 击杀不保证 LivingEntity.getKiller() 返回枪手，模块应监听本事件以准确获取枪械击杀的攻击者信息。

注册方式： 标准 Bukkit @EventHandler 监听

事件字段

方法	返回类型	说明
`getAttacker()`	`@NotNull Player`	攻击者（开枪的玩家）
`getKilledEntity()`	`@NotNull LivingEntity`	被击杀的实体
`getDamage()`	`double`	基础伤害值
`isHeadShot()`	`boolean`	是否为爆头击杀
`getGunId()`	`@NotNull String`	枪械 ID

使用示例

@EventHandler
public void onTaczKill(TaczGunKillEvent event) {
    Player attacker = event.getAttacker();
    LivingEntity victim = event.getKilledEntity();
    boolean headshot = event.isHeadShot();
    // 统计击杀信息、发放奖励等
}

注意事项

所有事件在主线程上触发，避免在 handler 中执行耗时操作。
ENABLE_FAILED 阶段获取的模块实例可能处于不完整状态，不应调用其业务方法。
事件实现了标准 Bukkit HandlerList 协议，可通过 getHandlerList() 获取。

事件系统

本页目录