API 参考 / 只读视图、场景、音频与文本

ActiveHitEffect

活动打击特效实例的句柄（世界实例层「特效实例」对象）。宿主在打击特效产生时创建内部实例（以音乐时间 τ 计活），模组经 GameplayContext 的 activeHitEffects() 取得当前存活特效的句柄列表，可读产生上下文、修改属性、提前销毁。

方法速览

方法	用途
`lane()`	特效所在轨道（写穿）
`noteType()`	触发特效的音符类型
`grade()`	触发判定等级定义（可能为 `null`）
`startMs()`	起始音乐时间 τ
`durationMs()`	当前时长（写穿）
`noteView()`	被判定音符（可能为 `null`）
`setDurationMs(long)`	改寿命，写入即时生效
`setLane(int)`	移轨（纯视觉），写入即时生效
`cancel()`	提前销毁（幂等）

lane()

java

int lane();

行为：特效当前所在轨道（物理轨道号）；setLane 之后返回新值（写穿）。示例：

java

int lane = fx.lane();

noteType()

java

HitEffectNoteType noteType();

行为：触发特效的音符类型（TAP / HOLD_HEAD / BARRIER 等），构造后不变。示例：

java

if (fx.noteType() == HitEffectNoteType.TAP) { /* 轻量特效 */ }

grade()

java

JudgmentKindDefinition grade();

行为：触发特效的判定等级定义；部分内部特效无判定等级，返回 null，调用方需判空。示例：

java

JudgmentKindDefinition g = fx.grade();
String kind = g != null ? g.id() : "";

startMs()

java

long startMs();

行为：特效起始的音乐时间 τ（毫秒）；有效期 = [startMs, startMs + durationMs)（按 τ 判定）。示例：

java

long age = ctx.musicTimeMs() - fx.startMs();

durationMs()

java

long durationMs();

行为：特效当前时长（毫秒）；setDurationMs 之后返回新值（写穿）。示例：

java

long life = fx.durationMs();

noteView()

java

NoteView noteView();

行为：被判定音符的只读视图；部分特效不由具体音符触发，返回 null。示例：

java

NoteView n = fx.noteView();
int lane = n != null ? n.lane() : fx.lane();

setDurationMs(long)

java

void setDurationMs(long durationMs);

行为：修改特效时长，写入即时生效——存活判定与强度消解按新值重算：延长让特效停留更久；缩短后已流逝超过新时长的特效下一帧自然消亡（柔和版 cancel）。非正值抛 IllegalArgumentException 且特效保持原值（绝不静默忽略）。纯视觉，不影响判定。示例：

java

fx.setDurationMs(fx.durationMs() * 2);

setLane(int)

java

void setLane(int lane);

行为：把特效移到另一条轨道，写入即时生效——下一帧起渲染位置（轨道 x、y 偏移与随轨旋转）按新轨道解析，可用于演出编排。轨道号越界（< 0 或 ≥ 谱面轨道数）抛 IllegalArgumentException 且保持原轨道。纯视觉，不影响判定与音符。示例：

java

fx.setLane(Math.min(ctx.chartView().laneCount() - 1, fx.lane() + 1));

cancel()

java

void cancel();

行为：提前销毁本特效（幂等）。销毁后立即从渲染与 activeHitEffects() 消失，倒带重演也不再出现；本局结束 / 退场景后调用是安全空操作。首次受理时宿主投递 HitEffectLifecycleEvent 的 CANCELLED 阶段。示例：

java

fx.cancel();

完整签名

java

public interface ActiveHitEffect {
    int lane();
    HitEffectNoteType noteType();
    JudgmentKindDefinition grade();
    long startMs();
    long durationMs();
    NoteView noteView();
    void setDurationMs(long durationMs);
    void setLane(int lane);
    void cancel();
}

线程：游玩回调均在游戏线程内同步调用（单线程语义，无并发写冲突）。

所有权与生命周期：句柄指向本局游玩场景的内部实例，只在本次游玩局内有效；同一特效在多次快照中得到不同句柄对象但指向同一内部实例（写入互相可见）。

稳定性：新增。读方法与 cancel() 自阶段 2 起；setDurationMs / setLane 自阶段 3 起。

上一页GameplayContext 下一页BeatGrid