API 参考 / capability 包：服务、状态与游玩访问

GameplayHud

想先跑起来？

这一页是签名与行为参考。隐藏原版 HUD 并自绘一层。直接做一遍：教程 · 自定义 HUD。

游玩 HUD 控制能力。遵循「能力原语优先」：只提供「读 HUD 数值」+「隐藏原版组件开关」+「覆盖渲染」+「单元素微调」，不提供「把进度条替换成指定样式」这类功能封装。

取值路径有两种：GameplayMod.createGameplayHud() 返回实例（按启用顺序收集，可有多个），或经 ctx.capabilities().register(GameplayHud.class, ...) 注册（只保留一个，追加在列表末尾）。

方法速览

方法	用途
`values()`	读本帧 HUD 数值快照
`updateValues(HudValues)`	宿主注入本帧数值（模组保存）
`setProgressVisible(boolean)`	声明隐藏原版 HP 进度条
`setComboVisible(boolean)`	声明隐藏原版连击数
`setScoreVisible(boolean)`	声明隐藏原版分数
`setAccuracyVisible(boolean)`	声明隐藏原版准度
`isProgressVisible()` / `isComboVisible()` / `isScoreVisible()` / `isAccuracyVisible()`	宿主反查隐藏声明
`renderOverlay(RenderCanvas, HudContext)`	覆盖渲染
`wantsOverlayWithoutHiding()`	不隐藏也要覆盖渲染
`override(HudElement)`	单元素属性微调

完整签名

java

public interface GameplayHud {

    HudValues values();

    default void updateValues(HudValues values);

    void setProgressVisible(boolean visible);

    void setComboVisible(boolean visible);

    void setScoreVisible(boolean visible);

    void setAccuracyVisible(boolean visible);

    boolean isProgressVisible();

    boolean isComboVisible();

    boolean isScoreVisible();

    boolean isAccuracyVisible();

    void renderOverlay(RenderCanvas canvas, HudContext hudCtx);

    default boolean wantsOverlayWithoutHiding();

    default HudElementOverride override(HudElement element);
}

values()

签名：

java

HudValues values();

行为：返回宿主最近一次经 updateValues 注入的 HUD 数值快照（见 HudValues）。宿主保证每次 renderOverlay 之前注入；不要在别处缓存「来自其它渠道」的数值。注入前可返回 null，调用方应判空。

示例：

java

HudValues v = values();
int combo = v != null ? v.combo() : 0;

updateValues(HudValues values)

签名：

java

default void updateValues(HudValues values);

行为：宿主每帧在覆盖渲染调用前注入本帧 HUD 数值快照（永不为 null）。默认实现忽略注入；模组应覆写以保存快照供 values() 返回。

示例：

java

private HudValues snapshot;

@Override
public void updateValues(HudValues values) {
    this.snapshot = values;
}

setProgressVisible(boolean visible)

签名：

java

void setProgressVisible(boolean visible);

行为：模组主动声明原版 HP 进度条是否要画（宿主不会调用，只在渲染时反查 isProgressVisible()）。false = 声明隐藏，宿主跳过该组件并进入覆盖渲染。

示例：

java

setProgressVisible(false);

setComboVisible(boolean visible)

签名：

java

void setComboVisible(boolean visible);

行为：声明原版连击数是否要画；语义同 setProgressVisible。

示例：

java

setComboVisible(false);

setScoreVisible(boolean visible)

签名：

java

void setScoreVisible(boolean visible);

行为：声明原版分数是否要画；语义同 setProgressVisible。

示例：

java

setScoreVisible(false);

setAccuracyVisible(boolean visible)

签名：

java

void setAccuracyVisible(boolean visible);

行为：声明原版准度是否要画；语义同 setProgressVisible。

示例：

java

setAccuracyVisible(false);

isProgressVisible()

签名：

java

boolean isProgressVisible();

行为：返回模组声明的可见性（声明值，不是真实渲染状态）。多实例叠加时宿主取「任一隐藏即隐藏」。

示例：

java

@Override
public boolean isProgressVisible() {
    return !progressHidden;
}

isComboVisible()

签名：

java

boolean isComboVisible();

行为：返回连击数的可见性声明；语义同 isProgressVisible。

示例：

java

@Override
public boolean isComboVisible() {
    return !comboHidden;
}

isScoreVisible()

签名：

java

boolean isScoreVisible();

行为：返回分数的可见性声明；语义同 isProgressVisible。

示例：

java

@Override
public boolean isScoreVisible() {
    return !scoreHidden;
}

isAccuracyVisible()

签名：

java

boolean isAccuracyVisible();

行为：返回准度的可见性声明；语义同 isProgressVisible。

示例：

java

@Override
public boolean isAccuracyVisible() {
    return !accuracyHidden;
}

renderOverlay(RenderCanvas canvas, HudContext hudCtx)

签名：

java

void renderOverlay(RenderCanvas canvas, HudContext hudCtx);

行为：覆盖渲染。宿主仅在「至少一个原版 HUD 组件被声明隐藏」或「某实例 wantsOverlayWithoutHiding() 返回 true」时调用；多实例按启用顺序依次调用（可互相叠加绘制）。

调用前宿主已对每个实例调用 updateValues 注入本帧数值。
canvas 为本帧绘制画布，hudCtx 为覆盖渲染上下文。
在游戏渲染线程执行，回调内不应阻塞；异常由宿主隔离，不影响其它实例与游戏循环。

示例：

java

@Override
public void renderOverlay(RenderCanvas canvas, HudContext hudCtx) {
    HudValues v = values();
    int combo = v != null ? v.combo() : 0;
    canvas.drawText("COMBO " + combo, 40, 120,
            TextStyle.of(20, java.awt.Color.WHITE));
}

wantsOverlayWithoutHiding()

签名：

java

default boolean wantsOverlayWithoutHiding();

行为：声明「不隐藏任何原版组件也要覆盖渲染」。默认 false：仅当模组隐藏了至少一个原版 HUD 组件时宿主才调用 renderOverlay。返回 true 表示希望在原版 HUD 之上附加绘制内容（如提示层、装饰层），同时保留全部原版组件。

示例：

java

@Override
public boolean wantsOverlayWithoutHiding() {
    return true;
}

override(HudElement element)

签名：

java

default HudElementOverride override(HudElement element);

行为：对单个原版 HUD 元素声明可改属性（见 HudElement / HudElementOverride）；返回 null（默认）= 不微调该元素。

宿主按帧反查：HUD 可见（整体 alpha > 0.01 且未被层替换压制）时每帧逐元素调用一次；实现应返回缓存的声明对象或轻量构造。
合并语义（多模组）：偏移 offsetX / offsetY 求和，透明度 alphaScale 连乘，颜色 colorArgb 启用顺序最后者生效并输出 [ModConflict] 限频告警。
全部为默认值（偏移 0 / 透明度 1 / 颜色 null）的声明等同无声明，宿主返回 null。
抛异常由宿主隔离（视为该实例不声明）。
实现边界：只有经 createGameplayHud() 提供的实例参与元素微调；经 capabilities().register(GameplayHud.class, ...) 注册的实例不参与（但仍参与可见性声明与覆盖渲染）。

示例：

java

private final HudElementOverride comboShift = new HudElementOverride() {
    @Override
    public double offsetX() {
        return 6.0;
    }
};

@Override
public HudElementOverride override(HudElement element) {
    return element == HudElement.COMBO ? comboShift : null;
}

线程：values() / isXxxVisible() 在渲染线程被宿主读取，应轻量返回缓存结果；updateValues / renderOverlay / override 在渲染线程执行；setXxxVisible 由模组自行调用（任意线程，实现应自行保证字段可见性，建议 volatile）。

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

上一页GameStateAccess 下一页HudElement