Smart Key Prompts

智能按键提示

需要 OneEngoughLib 1.1.2 或更高版本！

此模组提供灵活且动态的按键提示系统，并支持扩展的自定义按键修改功能。
它能提升玩家的整体体验，并让按键管理更加便捷。

---

使用方法

对于普通玩家，只需安装后即可游玩——无需任何设置。

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

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

---

主要功能

此模组会根据情况，在适当的时机选择性地显示相关按键提示。
它为模组或整合包开发者提供灵活的 API，用于显示基于情境的按键提示。

// Display an existing registered keybinding.
show(String group, String desc);

// Display a fully custom key prompt.
custom(String group, String key, String desc);

// Display an existing registered keybinding under an alias.
alias(String group, String desc, String alias);

只需在特定条件下（例如客户端 tick 事件期间）调用这些方法，即可显示情境相关的按键提示。
详细的实现示例请见下文。

也支持基于数据包的提示，但条件逻辑和语法较为有限，因此更适合简单的使用场景。
更多信息请参阅数据包扩展指南。

示例效果：

每个方法的 group 参数都表示按键提示组 ID。
例如，此模组与 JEI 集成时使用 "jei_skp" 作为组 ID，且该组默认处于禁用状态。
你可以在配置文件中使用组 ID，自由启用或禁用任意组。

当屏幕上显示按键提示时，按下Control 键（默认：K）+ 鼠标左键即可直接打开对应的按键绑定菜单，无需在完整列表中查找。

示例：

请注意，此快捷操作仅适用于关联到已注册按键绑定的提示（show、alias），
不适用于完全自定义的提示（custom）。

此外，你还可以通过程序调用特定按键绑定的配置界面：

ConfigAction.modifyKey(List<String> keyDescList);

按住 Control 键可锁定当前按键提示，使其暂时持续显示。

最后，按下Control 键 + 鼠标右键可切换 HUD 的显示状态和位置。
按住 Control 时，可以使用鼠标滚轮调整 HUD 大小。

---

灵活的提示系统

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

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

{
  "key.keyboard.f11": "F11",
  "key.keyboard.left.shift": "Left Shift",
  "key.mouse.left": "Left Button"
}

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

{
  "key.tacz.fire_select.desc": "Fire Mode",
  "key.tacz.inspect.desc": "Inspect",
  "key.tacz.interact.desc": "Interact while armed"
}

模组中的用法示例：

@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", "Transfer items in bulk");

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

{
  "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 重新定位影响）。

Smart Key Prompts 还提供了各种实用方法——例如按键检测和实体目标检测——以简化模组开发。

---

灵活禁用

按住控制键（默认：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<String> list)
SKP$KeyUtils.disableAllKeyMapping()
SKP$KeyUtils.enableKeyMapping(String desc)
SKP$KeyUtils.enableKeyMapping(List<String> list)
SKP$KeyUtils.enableAllKeyMapping()

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

---

其他信息

如果你希望此模组支持其他模组，欢迎联系我们。
你也可以直接向仓库提交新的按键提示组。

推荐搭配模组： KeyBindJS

计划中的功能：

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

在官方文档中查看支持的模组完整列表。