API 参考 / 事件系统

TrackRenderEvent

宿主在轨道渲染器的渲染入口 / 出口各投递一次。Pre 在轨道与音符绘制之前（模组内容画在轨道之下），Post 在之后（画在轨道之上）。它比 RenderEvent 的 RenderLayer.NOTES 更细：可以精确画在「轨道与音符之下 / 之上」，不必与 NOTES 层的其它内容争顺序。

方法速览

方法	用途
`context()`	渲染上下文（层固定为 `NOTES`）
`musicTimeMs()`	当前谱面时间（毫秒）
`scrollSpeed()`	当前下落速度倍率
`visibleNoteCount()`	本帧可见音符数

context()

java

public final RenderContext context();

行为：返回渲染上下文，其层固定绑定为 RenderLayer.NOTES（轨道渲染发生在该层内部）。只在回调期间有效，不得缓存。

musicTimeMs()

java

public final long musicTimeMs();

行为：返回当前谱面时间（毫秒）。

scrollSpeed()

java

public final double scrollSpeed();

行为：返回当前下落速度倍率，可用于让自绘内容与音符滚动速度一致。

visibleNoteCount()

java

public final int visibleNoteCount();

行为：返回本帧可见音符数量（只读观察值），可用于性能自适应。

示例

java

ctx.eventBus().subscribe(TrackRenderEvent.Post.class, event -> {
    RenderCanvas canvas = event.context().canvas();
    canvas.setAlpha(0.35);
    canvas.drawRect(0, 0, event.context().width(), 2);
});

完整签名

java

public abstract class TrackRenderEvent extends Event {
    protected TrackRenderEvent(RenderContext context, long musicTimeMs,
                               double scrollSpeed, int visibleNoteCount);
    public final RenderContext context();
    public final long musicTimeMs();
    public final double scrollSpeed();
    public final int visibleNoteCount();

    public static final class Pre extends TrackRenderEvent {
        public Pre(RenderContext context, long musicTimeMs, double scrollSpeed, int visibleNoteCount);
    }

    public static final class Post extends TrackRenderEvent {
        public Post(RenderContext context, long musicTimeMs, double scrollSpeed, int visibleNoteCount);
    }
}

行为核验：只在游玩场景投递——轨道渲染器也被资源预览等场景复用，那些场景不投递本事件，监听器不得假设「每帧必到」。

性能：每帧 2 次，与 RenderEvent 同级的轻量约束。

稳定性：2.0 起冻结，2.x 内只增不破。

上一页RenderEvent 下一页ResourceReloadEvent