灵活按键提示

智能按键提示

从 1.1.2 版本起需要 OneEngoughLib！

本模组提供了一个灵活且动态的按键提示系统，并具备可自定义按键修改的扩展功能。 它改善了整体玩家体验，并帮助简化按键管理。

---

如何使用

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

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

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

---

主要特性

本模组会在适当的时候有选择地显示相关按键提示。 它为模组或整合包开发者提供了灵活的 API，用于显示基于上下文的按键提示。

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

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

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

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

也支持基于数据包的提示，但条件逻辑和语法有限——最适合简单的用例。 更多信息参见数据包扩展指南。

示例输出：

每个方法的 group 参数代表一个按键提示组 ID。 例如，本模组在与 JEI 集成时使用 "jei_skp" 作为组 ID，该组默认是禁用的。 您可以在配置文件中使用组 ID 自由启用或禁用任何组。

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

示例：

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

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

ConfigAction.modifyKey(List<String> 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 重新定位影响）。

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 版本。

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