API 参考 / 渲染、资源与语言

CustomRenderLayer

用途：声明一个带小数层号的新层，参与全局排序。与 RenderEvent 插槽的区别：插槽在同一位置只有「订阅顺序」，而自定义层提供声明式层号，多模组叠加时按层号全序绘制（同层号按注册顺序）。

完整签名

java

public interface CustomRenderLayer {

    String id();

    double index();

    void render(RenderContext ctx);
}

id()

签名：

java

String id();

行为：层 id，仅用于诊断与日志（同模组内应唯一，跨模组可重复）。

index()

签名：

java

double index();

行为：层号，决定插入位置：index 落在 [L, L+1) ⇒ 渲染于第 L 层内容之后、第 L+1 层内容之前；index < 0 ⇒ 一切内容之前；index >= 6 ⇒ FULLSCREEN 之后（滤镜之后、延后暂停 UI 之前）。

index < 4 的自定义层处于世界相机深度作用域内（3D/z 原语生效）；index >= 4 永久正交、3D 原语退化为 2D。

render(RenderContext ctx)

签名：

java

void render(RenderContext ctx);

行为：渲染线程内同步调用。ctx 生命周期同 RenderEvent（不得缓存）；ctx.layer() 返回该边界所属的内置层（自定义层没有自己的枚举值）。

示例：插在音符与判定特效之间的一层

java

public final class TrailLayer implements CustomRenderLayer {
    @Override public String id() { return "trail"; }
    @Override public double index() { return 2.5; }   // NOTES 之后、JUDGE_FX 之前
    @Override public void render(RenderContext ctx) {
        RenderCanvas c = ctx.canvas();
        c.save();
        c.setAlpha(0.35);
        c.setColor(java.awt.Color.CYAN);
        c.fillRect(0, ctx.height() - 60, ctx.width(), 60);
        c.restore();
    }
}

// onPreInit 内注册
ctx.registries().customRenderLayers().register(
        RegistryKey.of("mymod", "trail", CustomRenderLayer.class), new TrailLayer());

上一页LayerOverride 下一页MatrixStack