Keybindery

模组

· 作者 trevlar

任意按键的按键组合、可搜索的按键绑定菜单,以及每个模组各自的设置中的按键绑定。

0 本站下载 0 关注 更新于 3 周前

需要前置:Fabric API、MenuKit

最新 1.5.0+26.3 · 26.3 · Fabric

一键开服(送7天)

Keybindery

Keybindery 允许游戏中的任何按键绑定使用组合键,并使你的按键绑定更容易查找和修改。你可以将 Ctrl + Shift + K 或 X + Z 绑定到任何动作(原版或模组),搜索并筛选“按键绑定”菜单,还可以在该模组自身的设置界面中编辑其按键绑定。

我还将其构建为一个库,以便我的其他模组可以在自己的设置屏幕中添加按键绑定按钮,其他模组开发者也可以这样做。

它在客户端运行。你也可以在服务器上安装它,此时它本身不会执行任何操作,但这样像 Inventory Plus 这样依赖它的模组也能在服务器上加载。

功能

组合键绑定

  • 将类似 Ctrl + Shift + K 或 X + Z 的组合键绑定到任意按键绑定(原版或模组)。鼠标按键也可以作为组合键的一部分。
  • 单键按键绑定保持原有工作方式不变。
  • “同时模式”默认关闭,开启后会在你设定的短时间窗口内使组合键的各个按键同时按下。

更佳的“按键绑定”菜单

  • 顶部设有搜索框、“按组合键搜索”按钮以及排序和筛选下拉菜单。
  • 每一行都有一个冲突图标,显示与该按键绑定共享按键的所有其他按键绑定,以及一个重置图标。
  • 类别可通过点击折叠,原本归入“杂项”的按键绑定现按其所属模组进行分组。

暂停菜单中的按键绑定按钮

  • 暂停菜单右侧图标按钮行的末尾有一个小按钮,点击即可打开“按键绑定”菜单。

各模组设置中的按键绑定

  • 拥有 YACL 配置界面的模组会获得一个“按键绑定”标签页,列出其所有按键绑定。
  • 通过 Mod Menu 打开的其他配置界面会获得一个“按键绑定”按钮,点击后可打开仅筛选该模组按键绑定的“按键绑定”菜单。

其他模组内部的按键绑定

  • 基于 Keybindery 开发的模组可以直接在其自身设置中提供组合键绑定按钮。Inventory Plus 将其按键绑定显示在对应的设置旁边,而 Sandboxes 则为每个沙盒分配独立的按键。

依赖项

  • Fabric API,用于注册按键绑定并挂钩至游戏的客户端事件。
  • MenuKit 7.4.0 或更高版本,且低于 8.0.0。它负责绘制“按键绑定”菜单顶部的工具栏以及其他模组配置界面上的“按键绑定”按钮。

YACL 3.9.7 已打包在 JAR 文件内,因此无需额外安装。

搭配推荐

  • Mod Menu。Keybindery 自身的设置可通过 Mod Menu 打开,且其他模组配置界面上的“按键绑定”按钮也依赖此模组。

兼容性

  • Minecraft 26.3 及 Fabric Loader 0.15.0 或更高版本。
  • 客户端必需,服务器可选。
  • Keybindery 通过窄化的 Mixin 注入来修改 KeyMapping,且从不覆盖原版方法,因此其他涉及相同代码的模组仍可正常运行。这也是它能与 Controlify 等输入类模组共存的原因。
  • 如果你更倾向于使用其他模组的控制界面(如 Controlling)或原版界面,你可以在 Keybindery 的设置中禁用其替换功能。
  • 组合键保存在原版的 options.txt 文件中。如果后续移除 Keybindery,所有按键绑定将恢复为单键状态。

使用方法

打开“按键绑定”菜单

  • 在游戏中按下 Escape 键。在一排小型方形按钮的最右侧,有一个带有字母 K 图标的按钮。悬停时显示“按键绑定”。
  • 点击该按钮以打开“按键绑定”菜单。“完成”按钮可返回暂停菜单。
  • 也可通过常规路径打开:选项 > 控制 > 按键绑定。

将组合键绑定到按键绑定

  • 每一行都是一个宽按钮,左侧显示按键绑定名称,右侧显示当前按键。
  • 点击该行,然后按住组合键中的所有按键并松开。组合键是你同时按住的一组按键(最多六个),当最后一个按键松开时保存。
  • 在等待按键输入期间按下的鼠标按键将成为组合键的一部分。用于打开该行的点击不计入组合键。点击可以发生在按键之前或之后,只要所有按键在同一时刻被按住即可。
  • 在等待按键输入期间,按下 Escape、Delete 或 Backspace 可清除该按键绑定,使其处于未绑定状态。
  • 当组合键的所有按键都被按住时触发。所有匹配的按键绑定都会触发,因此如果 Y 绑定到一个动作,而 Shift + Y 绑定到另一个动作,按下 Shift + Y 将同时触发两者。
  • 过长的按键绑定名称会在行内滚动显示。

冲突与重置

  • 当两个按键绑定共享任何按键时即发生冲突。绑定到 S 的按键绑定会与原版绑定在 S 上的“向后行走”冲突,而 X + Z 会与 X 冲突。唯一不被标记的例外是两个原版按键绑定均处于默认按键的情况。
  • 存在冲突的按键绑定会以黄色方括号显示其按键。
  • 每行旁边的警告图标会将列表筛选为与该行共享按键的所有按键绑定。悬停时显示“显示冲突”。如果该行无冲突,则图标呈灰色不可用状态。
  • 重置图标可将按键绑定恢复为其默认按键。如果按键绑定已处于默认状态,则图标呈灰色不可用状态。

搜索、排序与筛选

“按键绑定”菜单顶部的工具栏包含两行。

  • 按名称搜索。 输入按键绑定名称或其类别的部分内容以缩小列表范围。不区分大小写。使用 | 分隔多个条件以显示匹配其中任一条件的按键绑定,例如 Inventory Plus | Hotbar Pockets。
  • 按组合键搜索。 点击该按钮,按住一个组合键并松开。列表将显示所有与该组合键共享按键的已绑定按键绑定。在等待按键输入期间按下 Escape、Delete 或 Backspace 可清除该搜索。
  • 排序。 类别(默认)、字母顺序或组合键。字母顺序和组合键排序将显示不带类别标题的单一列表。
  • 筛选。 无(默认)、有冲突或未绑定。
  • 更改搜索、排序或筛选条件会使列表滚动回顶部。
  • 每次打开菜单时,默认设置为按类别排序且无筛选。

折叠类别

  • 使用分类排序时,每个分类标题旁都有一个箭头。点击标题可折叠该分类下的按键绑定,再次点击则展开。
  • “全部折叠”按钮会折叠视图中所有分类。当所有分类均处于折叠状态时,该按钮文字变为“全部展开”。
  • 被折叠的分类在关闭游戏前将保持折叠状态。
  • 原版会将其归入“杂项”的按键绑定,现在改为按来源模组进行分组,归类于以模组 ID 为名称的标题下。

改用原版的控制设置界面

Keybindery 的设置中包含一个“控制设置界面”选项卡,其中仅有一个设置项。

设置项 默认值 功能说明
禁用控制设置界面替换 关 开启后,游戏将使用原版的“按键绑定”界面,而非 Keybindery 的界面。需关闭并重新打开界面以使更改生效。

同时按下模式

通常情况下,只要组合键中的所有按键都处于按住状态,无论它们最初是按下的时间间隔多久,组合键都会触发。启用“同时按下模式”后,要求组合键中所有按键的首次按下也必须落在设定的时间窗口内,因此长时间按住 Ctrl 后再敲击 K 不再被视为 Ctrl + K。

从 Mod Menu(模组菜单)打开 Keybindery 的设置。“同时按下模式”位于“组合键检测”选项卡中。

设置项 默认值 范围 功能说明
同时按下模式 关 开或关 要求组合键的所有按键必须同时按下。
同时按下窗口时间 (毫秒) 100 50 至 500,步长为 10 允许组合键中第一个与最后一个按键之间的最大时间间隔。数值越大宽容度越高,越小越严格。仅在启用“同时按下模式”时可修改此值。

要在游戏过程中切换模式,可为“同时按下模式”按键分配快捷键。

按键 分类 默认值 功能说明
同时按下模式 Keybindery 未绑定 开启或关闭“同时按下模式”,并在快捷栏上方显示当前状态。

从模组设置中查找其按键绑定

Keybindery 通过按键绑定名称中的模组 ID 来匹配所属模组,这是 Fabric 模组的常见惯例。没有按键绑定的模组既不会显示对应选项卡,也不会显示相关按钮。

  • YACL 配置界面 在其选项卡末尾增加一个“按键绑定”选项卡,每行对应一个按键绑定。点击某一行,然后按住并释放一个组合键即可完成绑定。按 Escape 取消操作并保留旧按键,按 Delete 或 Backspace 清空绑定。警告图标会打开已过滤出该按键绑定冲突项的“按键绑定”菜单,重置图标则将其恢复为默认值。对配置的更改会在保存配置界面时应用,与其他 YACL 设置的行为一致。
  • 选项卡的最后一行是“按键绑定菜单”,包含一个“打开”按钮,用于打开无过滤条件的完整“按键绑定”菜单。
  • 其他通过 Mod Menu 打开的配置界面 右上角会增加一个“按键绑定”按钮。点击它会打开“按键绑定”菜单,并将搜索框自动填入该模组的分类名称,以便玩家查看过滤器并可清除它。

面向模组开发者

其他模组可以使用 Keybindery 在自己的设置界面中添加组合键绑定按钮,并在游戏运行时创建按键绑定。

API 提供的功能

  • 读取和设置任意 KeyMapping 的组合键。
  • 通过一次调用即可向 YACL 配置中添加一行按键绑定。该行包含标签、带有组合键按钮的行、冲突警告图标以及重置图标。
  • 打开针对一个或多个模组过滤的“按键绑定”菜单,并检查某个模组是否拥有任何按键绑定。
  • 通过 setDefaultChord 为映射设置默认组合键,这样全新安装和重置时都会回到该组合键。
  • 使用 isHeld 检查映射组合键中的每个按键当前是否均处于按住状态。它在界面打开期间也能正常工作,这与 KeyMapping.isDown() 不同。
  • 在游戏运行时注册按键绑定,例如为玩家在游戏中创建的事物(如沙盒)各注册一个。这些绑定不会出现在“按键绑定”菜单中,而是由模组自行显示和保存。
  • 获取可用于任何界面或列表的原版组合键捕获按钮。
  • 对于 MenuKit 界面,ChordButton 是一个 MenuKit 元素,在一行内包含组合键按钮、冲突警告图标和重置图标。它位于 Keybindery 的 jar 包中而非 API jar 包中,因此使用它的模组依赖于 Keybindery。
  • 在未安装 Keybindery 的情况下,所有 API 调用都会安全地不执行任何操作,因此模组可以在无需依赖 Keybindery 的前提下支持其功能。

示例

ConfigCategory keybindsCategory = ConfigCategory.createBuilder()
        .name(Component.literal("Controls"))
        .options(KeybinderyAPI.getInstance().createYACLChordOption(
                myKey, Component.literal("My action"), OptionDescription.EMPTY))
        .build();

入门指南

公共接口和 Chord 类位于独立的 jar 包 keybindery-api 中。请针对该 jar 包进行编译。Keybindery 会将 keybindery-api 打包在其自身的 jar 包内,因此玩家只需安装 Keybindery,无需额外安装其他内容。使用了 ChordButton 的模组则直接依赖于 Keybindery 本身。

读取或设置组合键

KeybinderyAPI api = KeybinderyAPI.getInstance();

Chord chord = api.getChord(myKey);     // 当前组合键,若未绑定则为 Chord.UNBOUND
api.setChord(myKey, newChord);          // 覆盖写入

setChord 会立即保存游戏的选项数据,因此重启后组合键设置依然保留。

为模组打开“按键绑定”菜单

KeybinderyAPI api = KeybinderyAPI.getInstance();
if (api.hasKeybinds("mymod")) {
    api.openModKeybinds("mymod", currentScreen);                 // 单个模组
    api.openModKeybinds(List.of("mymod", "myaddon"), currentScreen); // 多个模组同时打开
}

菜单将在 currentScreen 之上打开,且搜索框已预先填入内容,以便玩家查看过滤器并可清除它。

在运行时注册按键绑定

对于属于玩家在游戏过程中创建的事物(如沙盒或锁组)的按键绑定,请使用 bindings() 进行注册,而不是创建 KeyMapping。

RuntimeBindings bindings = KeybinderyAPI.getInstance().bindings();
Identifier id = Identifier.fromNamespaceAndPath("mymod", "sandbox/nether_test");
bindings.register(id, Component.literal("Sandbox: Nether test"), chord, () -> openSandbox());
List<BindingConflict> clashes = bindings.conflicts(chord, id); // 所有共享同一按键的其他绑定
bindings.unregister(id);

使用相同的 ID 重新注册会替换原有的绑定。一个绑定会在原版按键映射所响应的按下事件中触发,遵循玩家的连按模式(包括同时模式),并在客户端线程上运行。标签文本是在该绑定作为冲突显示时呈现的内容。conflicts 方法依据与“按键设置”菜单相同的规则检查玩家的按键映射,以及所有其他运行时绑定。运行时绑定不会被保存,因此请使用 Chord.serialize() 序列化连按组合,并在游戏启动时重新注册它。

用于自定义界面的连按按钮

captureWidget 返回一个能够捕获连按组合的原版按钮。

AbstractWidget button = KeybinderyAPI.getInstance().captureWidget(x, y, 150, 20, chord, newChord -> {
    saveChord(newChord.serialize());
    bindings.register(id, label, newChord, onPress);
});
if (button != null) addRenderableWidget(button);

玩家点击按钮,按下连按组合,然后松开按键,此时 onChange 回调将获取到新的连按组合。在捕获过程中按下 Escape 或 Delete 键会清空已捕获的组合。该按钮会持续显示最新的连按组合,并由模组进行存储。

未安装 Keybindery 时

keybindery-api 对 Keybindery 没有运行时依赖。如果玩家没有安装 Keybindery,所有的调用都会指向一个存根实现。读取连按时会返回 UNBOUND,写入操作则不会执行任何动作。createYACLChordOption 会返回一个禁用的标签,显示内容为 "<label>: (Keybindery not installed)"。hasKeybinds 和 isHeld 返回 false,而 openModKeybinds 不会执行任何操作。运行时绑定不会注册任何内容,conflicts 返回空列表,且 captureWidget 返回 null;当其为 null 时,请省略该按钮的添加。模组自身的界面仍然可以正常渲染。

许可证

MIT。详见 LICENSE。

致谢

灵感来源于 Amecs 的多按键绑定功能,以及 Controlling 的控制台搜索功能。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源