API 参考 / 事件系统
HitEffectLifecycleEvent
打击特效实例的三个生命周期节点各投递一次：CREATED（实例进入宿主活动列表的当帧）、CANCELLED（句柄 cancel() 首次受理的当帧，幂等重复取消不重发）、EXPIRED（实例自然到期，或超保留窗被清扫时补报）。每实例恰好一个消亡事件（CANCELLED 与 EXPIRED 互斥、只报其一）；倒带回退令特效「复活」时不重发消亡事件。
方法速览
| 方法 | 用途 |
|---|---|
phase() | 生命周期阶段 CREATED / CANCELLED / EXPIRED |
lane() | 特效所在轨道（事件时刻值） |
noteType() | 音符类型（打击特效口径） |
grade() | 判定等级定义，可能为 null |
startMs() | 特效起始 τ（毫秒） |
durationMs() | 事件时刻的时长（毫秒） |
note() | 触发音符的只读视图，可能为 null |
phase()
java
public Phase phase();行为：返回生命周期阶段。CREATED 覆盖正常击打、幽灵击打、autoplay 等一切创建路径。
lane()
java
public int lane();行为：返回特效所在轨道。这是事件时刻值，句柄后续 setLane 不会回填历史事件。
noteType()
java
public HitEffectNoteType noteType();行为：返回音符类型（打击特效口径）。
grade()
java
public JudgmentKindDefinition grade();行为：返回判定等级定义，可能为 null（部分内部特效没有判定等级）。
startMs()
java
public long startMs();行为：返回特效起始的音乐时间 τ（毫秒）。
durationMs()
java
public long durationMs();行为：返回事件时刻的时长（毫秒）。CANCELLED / EXPIRED 携带消亡前最后生效值（包含 setDurationMs 修改后的口径）。
note()
java
public NoteView note();行为：返回触发音符的只读视图，可能为 null。
示例
java
ctx.eventBus().subscribe(HitEffectLifecycleEvent.class, event -> {
switch (event.phase()) {
case CREATED:
liveEffects++;
break;
case CANCELLED:
case EXPIRED:
liveEffects = Math.max(0, liveEffects - 1);
releasePooledEffect(event.lane());
break;
default:
break;
}
});完整签名
java
public class HitEffectLifecycleEvent extends Event {
public enum Phase {
CREATED,
CANCELLED,
EXPIRED
}
public HitEffectLifecycleEvent(Phase phase, int lane, HitEffectNoteType noteType,
JudgmentKindDefinition grade, long startMs,
long durationMs, NoteView note);
public Phase phase();
public int lane();
public HitEffectNoteType noteType();
public JudgmentKindDefinition grade();
public long startMs();
public long durationMs();
public NoteView note();
}行为核验：宿主在创建特效的当帧发 CREATED；句柄取消只在首次受理时发 CANCELLED；自然到期（elapsed ≥ 当前时长）或超 8 秒保留窗清扫时发 EXPIRED（每实例至多一次）。本局结束的场景整体清理不投递，静默预览会话（EventPolicy.SILENT）也不投递。事件不可取消；需要干预请用句柄原语（setDurationMs / setLane / cancel()），可在 CREATED 当帧响应。
性能：打击密集时每帧可能多次投递，监听器必须极轻。
稳定性： 新增，2.x 内只增不破。