Smart Key Prompts - 智能按键提示

智能按键提示

需要 OneEngoughLib 1.1.2 及以上版本！

本模组提供了一个灵活且动态的按键提示系统，以及用于自定义按键修改的扩展功能。

它改善了整体玩家体验，并有助于简化按键管理。

如何使用

对于普通玩家，只需安装并游玩——无需设置。

对于开发者，有四种方式在游戏中添加新的按键提示：

• 目标模组主动集成智能按键提示。
• 使用 KubeJS 调用本模组提供的 API。
• 通过数据包添加支持（有一定限制；请参阅数据包扩展指南）。
• 通过本模组内的内置适配直接添加。

主要功能

本模组会在适当时机选择性地显示相关的按键提示。

它为模组或整合包开发者提供了灵活的 API，以显示基于上下文的按键提示。

// 显示一个已注册的按键绑定。
show(String group, String desc);

// 显示一个完全自定义的按键提示。
custom(String group, String key, String desc);

// 使用别名显示一个已注册的按键绑定。
alias(String group, String desc, String alias);

只需在特定条件下（例如，在客户端刻事件期间）调用这些方法，即可显示上下文相关的按键提示。

详细的实现示例见下文。

也支持基于数据包的提示，尽管条件逻辑和语法有限——最适合较简单的用例。

更多信息请参阅数据包扩展指南。

示例输出：

每个方法的 group 参数代表一个按键提示组 ID。

例如，本模组在与 JEI 集成时使用 "jei_skp" 作为组 ID，默认是禁用的。

您可以在配置文件中使用组 ID 自由启用或禁用任何组。

当屏幕上显示按键提示时，按下控制键（默认：K）+ 左键单击将直接打开对应的按键绑定菜单——无需在完整列表中搜索。

示例：

请注意，此快捷方式仅适用于链接到已注册按键绑定的提示（show、alias），

而不适用于完全自定义的提示（custom）。

此外，您可以通过编程方式触发特定按键绑定的配置界面：

ConfigAction.modifyKey(List keyDescList);

按住控制键会锁定当前的按键提示，使其暂时持续显示。

最后，控制键 + 右键单击可切换 HUD 的可见性和位置。

按住控制键时，可以使用鼠标滚轮调整 HUD 大小。

灵活的提示系统

"key" 和 "desc" 字段指的是语言文件中的条目。

例如，在 Minecraft 的默认语言文件 \assets\minecraft\lang\en_us.json 中：

{
  "key.keyboard.f11": "F11",
  "key.keyboard.left.shift": "左 Shift",
  "key.mouse.left": "左键"
}

在 TaCZ 的语言文件 \assets\tacz\lang\zh_cn.json 中：

{
  "key.tacz.fire_select.desc": "开火模式",
  "key.tacz.inspect.desc": "检视",
  "key.tacz.interact.desc": "持械交互"
}

在模组中的使用示例：

@SubscribeEvent
public static void tick(TickEvent.ClientTickEvent event) {
    if (!ModList.get().isLoaded("immersive_aircraft")) return;
    Player player = Minecraft.getInstance().player;
    if (player == null || Minecraft.getInstance().screen != null) return;
    String vehicle = Utils.getVehicleType(player);
    if (vehicle != null && vehicle.startsWith("immersive_aircraft:")) {
        SmartKeyPrompts.custom(modid, Utils.getKeyByDesc("key.inventory"), "immersive_aircraft.slot.upgrade");
        SmartKeyPrompts.show(modid, "key.immersive_aircraft.dismount");
        String keyUse = Utils.getKeyByDesc("key.immersive_aircraft.fallback_use");
        SmartKeyPrompts.custom(modid, Objects.equals(keyUse, "key.keyboard.unknown") ? "key.mouse.right" : keyUse, "item.immersive_aircraft.item.weapon");
        if (vehicle.equals("immersive_aircraft:biplane")) {
            SmartKeyPrompts.custom(modid, Utils.getKeyByDesc("key.jump"), "item.immersive_aircraft.engine");
        }
    }
}

在 KubeJS 中的使用：

ClientEvents.tick(event => {
    let player = event.player;
    if (["key.left", "key.right", "key.forward", "key.back"].map(desc => SKP$KeyUtils.isKeyPressedOfDesc(desc)).includes(true)) {
        SKP$PromptUtils.show("parcool", "key.parcool.Dodge");
    }
    if (!player.onGround() && !player.isInWater()) {
        SKP$PromptUtils.show("parcool", "key.parcool.Breakfall");
        SKP$PromptUtils.show("parcool", "key.parcool.ClingToCliff");
    }
    if (player.isSprinting()) {
        SKP$PromptUtils.show("parcool", "key.parcool.FastRun");
    }
    if (SKP$KeyUtils.isKeyPressedOfDesc("key.parcool.FastRun")) {
        SKP$PromptUtils.show("parcool", SKP$KeyUtils.getKeyByDesc("key.parcool.Dodge"));
        SKP$PromptUtils.custom("parcool", SKP$KeyUtils.getKeyByDesc("key.sneak"), "parcool.action.CatLeap");
    }
});

对于组合键，您可以使用：

SmartKeyPrompts.custom(modid, "key.keyboard.left.shift+key.mouse.left", "批量转移物品");

基于数据包的配置示例（请参阅指南）：

{
  "modid": "tacz_skp",
  "vars": {
    "modLoaded": "isModLoaded('tacz')",
    "hasTaczGun": "mainHandItem == 'tacz:modern_kinetic_gun'",
    "isNotInVehicle": "!isInVehicle()"
  },
  "entries": [
    {
      "when": {
        "modLoaded": "true",
        "hasTaczGun": "true",
        "isNotInVehicle": "true"
      },
      "then": [
        "show('tacz_skp', 'key.tacz.shoot.desc')",
        "show('tacz_skp', 'key.tacz.zoom.desc')",
        "show('tacz_skp', 'key.tacz.reload.desc')"
      ]
    }
  ]
}

扩展示例：当瞄准一个实体时，在准星下方显示交互提示。

@SubscribeEvent
public static void tick(TickEvent.ClientTickEvent event) {
    if (!ModList.get().isLoaded(modid)) return;
    if (PlayerUtils.getTargetedEntityType() == "minecraft:pig") {
        PromptUtils.addDesc("key.pig.feed").forKey("key.mouse.right").withCustom(true).atPosition("crosshair").toGroup(modid);
    }
}

"custom" 和 "position" 都可以自定义。

"custom" 标志决定提示是否出现在过滤后的按键绑定菜单中，

而 "position" 控制提示显示的位置（固定位置，不受 HUD 重新定位影响）。

智能按键提示还提供了各种实用方法——例如按键检测和实体瞄准——以简化模组开发。

灵活的禁用功能

按住控制键（默认：K）时，提示会变为锁定状态，并显示其完整标识符（group:desc）。

在 KubeJS 中，您可以动态启用或禁用提示：

SKP$PromptUtils.disablePromptByGroup(String group)
SKP$PromptUtils.enablePromptByGroup(String group)
SKP$PromptUtils.disablePromptByDesc(String desc)
SKP$PromptUtils.enablePromptByDesc(String desc)
SKP$PromptUtils.disablePrompt(String group, String desc)
SKP$PromptUtils.enablePrompt(String group, String desc)

您还可以禁用或重新启用特定的按键绑定：

SKP$KeyUtils.isKeyDisabled(String desc)
SKP$KeyUtils.getDisabledKeyMappingList()
SKP$KeyUtils.disableKeyMapping(String desc)
SKP$KeyUtils.disableKeyMapping(List list)
SKP$KeyUtils.disableAllKeyMapping()
SKP$KeyUtils.enableKeyMapping(String desc)
SKP$KeyUtils.enableKeyMapping(List list)
SKP$KeyUtils.enableAllKeyMapping()

例如，调用 disableKeyMapping("key.jump") 会阻止玩家跳跃。

其他信息

如果您希望本模组支持另一个模组，请随时联系。

您也可以直接将新的按键提示组提交到代码仓库。

推荐搭配模组： KeyBindJS

计划中的功能：

• 更多提示位置（例如，跟随鼠标）。
• 支持双击和长按按键。
• HUD 视觉改进。
• 可能向后移植到更多 Minecraft 版本。

支持的模组完整列表请参阅官方文档。