API 参考 / 能力接口（capability 包）

GlobalHotkey

想先跑起来？

这一页是签名与行为参考。一个快捷键的定义与回调。直接做一遍：教程 · 设置项与快捷键。

单个全局快捷键的定义，经 GlobalHotkeys.add 注册。它的「全局」指任意场景下按下即触发，与场景内业务按键（游玩轨道键、编辑器内操作）区分。

方法速览

方法	用途
`id()`	模组内唯一快捷键 id
`labelKey()`	设置面板行的标签译键
`defaultKeyCode()`	默认键码（`VK_*`）
`onHotkey()`	按下沿回调

完整签名

java

public interface GlobalHotkey {

    String id();

    String labelKey();

    int defaultKeyCode();

    default void onHotkey();
}

id()

签名：

java

String id();

行为：模组内唯一快捷键 id；宿主拼 模组id:id 为全键（改键持久化 / 日志用）。不得为 null 或空串（注册时校验）。

示例：

java

@Override
public String id() {
    return "toggle_hud";
}

labelKey()

签名：

java

String labelKey();

行为：标签译键（设置面板行显示名；经 Translator.get，缺失时回退原文）。建议带模组前缀避免与其它模组撞名，如 mymod.hotkey.toggle。

示例：

java

@Override
public String labelKey() {
    return "mymod.hotkey.toggle";
}

defaultKeyCode()

签名：

java

int defaultKeyCode();

行为：默认键码（java.awt.event.KeyEvent.VK_* 常量值；字面量，如 18=Alt）。玩家可在设置中改键；选择默认键时避开常见组合键的修饰键单独触发场景。解析时优先使用玩家改键结果。

示例：

java

@Override
public int defaultKeyCode() {
    return java.awt.event.KeyEvent.VK_F7;
}

onHotkey()

签名：

java

void onHotkey();

行为：快捷键触发回调，按下沿语义，在游戏线程触发，每帧至多一次。默认空实现。实现应轻量；长时间操作须自行起线程（如经 ctx.network() 线程池）。抛异常由宿主限频隔离，不影响其它快捷键与游戏循环。

示例：

java

@Override
public void onHotkey() {
    hudVisible = !hudVisible;             // 只做轻量状态切换
}

线程：onHotkey() 在游戏线程触发，每帧至多一次。

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

本分类只放「基础能力」：能力注册表、模组管理、UI 定制、设置扩展、全局快捷键。服务与游玩访问类能力（NetworkAccess / ModServiceRegistry / SceneHost / StoryAccess / AudioAccess / InputAccess / GameStateAccess / GameplayHud / HudElement / LaneInputMapper）见左侧「capability 包：服务、状态与游玩访问」分类。

上一页GlobalHotkeys 下一页capability 包：服务、状态与游玩访问