GlobalHotkeys

全局快捷键注册能力。模组经 ctx.hotkeys() 获取，注册「任意场景下按下即触发」的快捷键（如开关 HUD、显示光标）。注册的快捷键进入原生设置「全局快捷键」集合面板（与内置快捷键同列），玩家统一改键；绑定持久化于游戏设置，模组无需自行保存。

方法速览

完整签名

public interface GlobalHotkeys {

    SettingsExtension.SettingHandle add(GlobalHotkey hotkey);
}

add(GlobalHotkey hotkey)

签名：

SettingsExtension.SettingHandle add(GlobalHotkey hotkey);

行为：登记一个全局快捷键，返回用于移除的句柄。

• 这是模组全局快捷键的唯一合法注册入口。 禁止模组自行监听全局按键事件来实现玩家无法改键的「隐性快捷键」——GlobalKeyEvent 是只读事件流，可用于分析输入，不可充当无法改键的快捷键通道。
• hotkey 为 null，或 hotkey.id() 为 null / 空串时抛 IllegalArgumentException。
• 幂等：同全键（模组id:id）重复注册替换旧定义，保持首次注册的展示顺序。
• 返回的 SettingHandle.remove() 按全键移除，幂等；宿主在模组停用时也会自动清理。
• 与 com.seecmd.mod.api.event.input.KeyEvent 的区别：KeyEvent 是原始按键事件流（只读，适合输入分析）；本能力是「可改键的快捷键」语义层。面向用户的快捷键功能必须走本能力注册，保证玩家始终可以改键。
• 绑定解析优先级：玩家改键（存于游戏设置）> 注册时的默认键码。

示例：

ctx.hotkeys().add(new GlobalHotkey() {

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

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

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

    @Override
    public void onHotkey() {
        hudVisible = !hudVisible;
    }
});

线程：注册任意线程可调用；GlobalHotkey.onHotkey() 在游戏线程触发。

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