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

NoteView

想先跑起来？

这一页是签名与行为参考。判定与事件里看到的音符只读视图。直接做一遍：教程 · 添加新音符类型。

音符只读视图（不可变快照）。供 JudgeResult 与事件使用，暴露音符的判定相关属性；模组也可经 GameplayContext#pendingNotes() / nextNote() / noteById(long)、JudgeContext#notes() 或 ActiveHitEffect#noteView() 拿到它。

方法速览

方法	用途
`noteId()`	稳定实例 id（未知为 `-1`）
`time()`	音符时间（毫秒）
`lane()`	音符所在轨道
`endTime()`	长音符结束时间（非长音符为 `null`）
`isHold()` / `isBarrier()` / `isExploit()` / `isPayload()`	音符种类判定
`noteTypeId()`	音符类型命名空间 id
`extensionData()`	运行时扩展数据

noteId()

java

default long noteId();

行为：音符稳定实例 id——宿主在谱面解析期按谱面音符列表顺序从 0 起连续分配，同一局内恒定、可跨帧引用（取代按 (time, lane, type) 拼组合键的猜测式寻址）。只存在于运行期、不参与谱面序列化；重开同一谱面按同一规则重新分配。默认返回 -1（旧版只读事件载荷可能不提供身份）。示例：

java

long id = note.noteId();
NoteView again = id >= 0 ? ctx.noteById(id) : null;

time()

java

long time();

行为：音符时间（毫秒，音乐时间轴）。示例：

java

long t = note.time();

lane()

java

int lane();

行为：音符所在轨道索引（0 起）。示例：

java

int lane = note.lane();

endTime()

java

Long endTime();

行为：长音符结束时间（毫秒）；非长音符返回 null（注意是包装类型 Long）。示例：

java

Long end = note.endTime();
long holdMs = end != null ? end - note.time() : 0L;

isHold()

java

boolean isHold();

行为：是否为长音符。示例：

java

if (note.isHold()) { /* 长条 */ }

isBarrier()

java

boolean isBarrier();

行为：是否为屏障音符。示例：

java

if (note.isBarrier()) { /* 屏障 */ }

isExploit()

java

boolean isExploit();

行为：是否为 exploit 音符。示例：

java

if (note.isExploit()) { /* exploit */ }

isPayload()

java

boolean isPayload();

行为：是否为 payload 音符。示例：

java

if (note.isPayload()) { /* payload */ }

noteTypeId()

java

default String noteTypeId();

行为：音符类型唯一标识（命名空间格式，如 "seecmd:hold"、"mymod:slide"）：模组自定义类型返回其注册 id，宿主内置类型返回 "seecmd:*"；宿主尚未接入类型定义（或该音符无类型）时返回 null。默认返回 null。示例：

java

String type = note.noteTypeId();
boolean custom = type != null && type.startsWith("mymod:");

extensionData()

java

default Object extensionData();

行为：运行时扩展数据（宿主/模组经 NoteData.setExtensionData 写入的只读透传）。自定义音符类型可在判定回调（如 onJudgeTick 的 JudgeContext.notes()）中取回创建时挂载的数据；宿主内置类型返回 null。默认返回 null。示例：

java

Object data = note.extensionData();
if (data instanceof MySlideData slide) {
    slide.phase = note.time();
}

完整签名

java

public interface NoteView {
    default long noteId();
    long time();
    int lane();
    Long endTime();
    boolean isHold();
    boolean isBarrier();
    boolean isExploit();
    boolean isPayload();
    default String noteTypeId();
    default Object extensionData();
}

线程：源码未声明额外线程约束。

性能：源码未标注额外性能约束（实例为不可变值快照，字段在构造期固定）。

稳定性：2.0 起冻结：2.x 内只增不破。noteId() 为新增且为 default，既有实现者零改动。

上一页ChartView 下一页LaneView