SlotKit
SlotKit 是一个面向 Fabric 模组的槽位库,基于 MenuKit 构建。模组可以使用它来查找并对任何菜单(原版或模组添加的)中的槽位进行操作,也可以创建真实的槽位和自定义菜单,并实现持久化与同步。我最初是为自己的模组开发它,随后将其开源以便其他模组开发者也能使用。
如果你是玩家且另一个模组提示需要 SlotKit,只需与该模组一起安装即可。
SlotKit 曾名为 MenuKit: Containers。为 Containers 构建的模组需要进行更新,升级指南 中提供了具体步骤。MenuKit: Containers 6.2.0 仍保留在此项目的版本列表中。
功能特性
SlotKit 分为两个层级。仅在使用第二层级时,另一侧才需要安装 SlotKit。
| 层级 |
需安装 SlotKit 的一侧 |
新增功能 |
| 客户端 |
仅需客户端。适用于任何服务器,包括原版服务器。 |
每个菜单中的槽位组与分类、槽位操作、否决权与门控机制,以及放置在槽位或槽位组上的面板 |
| 客户端与服务器 |
两侧均需安装 |
创建的槽位、自定义容器菜单、存储附件、逐槽位状态,以及潜影盒和包裹内的物品 |
- 无论是原版的还是创建的槽位组,都会发布在一个分类下,供任意模组读取,无论是否打开菜单。
- 每个针对槽位的操作都被命名为一种“操作”。原版包含十一种,每种手势对应一个,模组可以添加自己的操作。检查顺序为:槽位自身设置 → 其所属组设置 → 其所属分类设置,锁定类模组可否决任何操作。
- MenuKit 面板可以围绕一个槽位组放置,或相对于单个槽位进行偏移,从而在该组或该槽位出现的每个屏幕上显示。这包括生存模式背包、所有箱子以及其他所有容器。
- 关于槽位的每条规则(否决权、分类规则、门控、槽位状态通道)都声明适用于生存模式、创造模式或两者,且在创造模式下同样生效。面板在不同模式下可以占据不同位置。
- 玩家背包槽位具有唯一地址,在所有屏幕和所有玩家间保持一致,因此可以在启动时为规则指定其名称。
- 菜单中的每个容器保持独立。Shift-click 操作绝不会意外落入其他模组的槽位中;模组可以通过组的 ID 在其自有面板中显示任意容器的槽位。
- 服务器可以向玩家当前打开的菜单添加槽位组,并在不需要时移除,例如在打开箱子屏幕时从中取出潜影盒。
- 面板可以放置在分类下的每个已显示组上,因此箱子和旁边打开的每个潜影盒或末影箱都会获得专属面板。
- 玩家在箱子前切换到背包、潜影盒或末影箱再返回时,箱子在世界中始终保持打开状态。
- MenuKit 滚动区域中的槽位会被裁剪,从而支持长网格槽位的滚动效果。
- 创建的槽位是 UI 组件。口袋、额外装备槽或挎包都是真正的
Slot,通过原版协议同步。模组只需注册一次槽位组,并将其放置在自有 MenuKit 面板中,紧邻按钮和标签,出现在所选的任何屏幕上。
- 服务器可以为每位玩家打开、关闭和调整槽位组大小,模组可决定 shift-click 的目标位置。
- 槽位内容可向其他玩家展示,用于在玩家模型上绘制装备。
- 模组可在玩家携带物品的任何位置查找并使用它们:背包、末影箱、以及嵌套至任意深度的潜影盒和包裹。玩家当前打开的箱子也可被搜索。更改会通过所有容器回写,菜单可保持在嵌套物品上(如包裹位于潜影盒内)。模组自身的携带槽位(如口袋或携带式末影箱)也可被搜索。
- 物品可携带模组自定义的状态,可选择保存或不保存;当该状态或客户端检查条件满足时,槽位会以不同方式渲染物品:动画、替换堆叠或在其上方/下方添加标记。
- 模组可对槽位执行普通双击以触发自定义动作,该手势在所有使用该功能的模组中保持一致。
- 自定义容器菜单由 MenuKit 面板构建而成。
- 创建的槽位在创造模式和生存模式下行为与原版一致,包括死亡掉落以及绑定诅咒和修复之 enchant 的处理。
- 逐槽位状态可附加到任意槽位,可以是私有(仅对特定玩家可见)或共享(对所有查看者可见)。服务器会校验客户端发送的每次写入。状态存储在槽位所有者(玩家、方块、实体或物品)上,可通过
/data get 命令读取。
- 世界加载前,两侧会检查对方安装了哪些模组。服务器仅拒绝缺少构建槽位所需模组的玩家,并提供需安装的模组名称及链接。其余玩家正常加入。
- 使用 MenuKit: Containers 保存的世界和玩家文件可直接加载,无需转换,潜影盒的内容和槽位状态均得以保留。
示例
位于玩家背包上方的面板,从客户端入口点注册一次。它使用客户端层级,因此适用于任何服务器。
Panel panel = Panel.builder("mymod:toolbar")
.style(PanelStyle.NONE)
.elements(toolbarButtons)
.in(ModeScope.BOTH, SlotPlacement.group(SlotGroupCategory.PLAYER_INVENTORY,
PanelPosition.region(OutsideRegion.TOP_ALIGN_RIGHT)))
.visibleWhen(() -> config.toolbar)
.build();
new AnchorPanelAdapter(panel);
在每个容器屏幕上显示的九个同步口袋槽位,从通用入口点注册一次。这些需要在两侧安装 SlotKit。
public static final PlayerStorageAttachment<NonNullList<ItemStack>> POCKETS =
StorageAttachment.playerAttached("mymod", "pockets", 9);
POCKET_SLOTS = ParityGroup.register("mymod:pockets",
SlotSpec.at("pockets", SlotGroupCategory.PLAYER_INVENTORY).count(9)
.storage(player -> POCKETS.bind(player)));
槽位位于模组自有的面板中,从客户端入口点构建。
// 客户端初始化程序:你的面板,以及按钮下方的插槽。
Panel pockets = Panel.builder("mymod:pockets")
.add(Button.builder().label(Component.literal("Sort")).size(60, 14).build())
.add(SlotFlowElement.builder().addGroup(POCKET_SLOTS).at(0, 18).build())
.style(PanelStyle.RAISED)
.in(ModeScope.BOTH, Placement.screen(PanelPosition.region(OutsideRegion.LEFT_ALIGN_TOP).priority(20)))
.build()
.visibleWhen(() -> ClientSlots.isShown(POCKET_SLOTS.id()));
new ScreenPanelAdapter(pockets).onMatching(ScreenMatcher.all());
入门指南
Minecraft 26.3 未混淆,因此 SlotKit 与 MenuKit 一样,使用普通的 implementation 配置。
repositories {
maven { url 'https://api.modrinth.com/maven' }
}
dependencies {
implementation 'maven.modrinth:menukit:7.5.0+26.3'
implementation 'maven.modrinth:xQUBXV8I:2.3.0+26.3' // SlotKit
}
xQUBXV8I 是 SlotKit 的 Modrinth 项目 ID。无论 slug 是什么,它都指向该项目。
在 fabric.mod.json 中声明两者,各自针对其版本,并包含上下限(原因)。用空格分隔界限,因为 Fabric 不识别逗号。
"depends": { "menukit": ">=7.5.0 <8.0.0", "slotkit": ">=2.3.0 <3.0.0" }
玩家将 SlotKit 作为独立模组安装,与使用它的模组并列。在其 Modrinth 页面上将其列为必需依赖项,以便随其他模组一起安装。
要求
兼容性
适用于带有 Fabric 的 Minecraft 26.3。请在客户端安装 SlotKit。仅当服务器上安装了添加插槽的模组(如 Hotbar Pockets 或 Simple Elytra Slot)时,服务器才需要它。该模组会将 SlotKit 列为必需依赖项,因此 SlotKit 会随之安装。这就是为什么 Modrinth 将 SlotKit 列为客户端模组,尽管它最终也会出现在许多服务器上。SlotKit 替换了 MenuKit: Containers,因此两者不能同时安装,也不能与 Inventory Max 一起安装。
被以下模组使用
使用方法
本指南按照模组通常接触 SlotKit 的顺序进行介绍,从在客户端查找插槽到构建需要两端的插槽。每个部分都链接到完整的开发者文档。概念 定义了所有术语,配方 为每个常见任务提供了工作示例。
公共 API
API 是名为 api 的软件包中的所有类型,即 com.trevlar.slotkit.api.*。版本契约涵盖这些内容。任何其他软件包都是内部的,可以在任何发布(包括补丁)中更改。如果某个任务看似需要内部类型,则是 API 中的缺失,请为此提交 issue。版本控制 说明了版本号各部分的承诺。
声明哪些端需要 SlotKit
模组在其 fabric.mod.json 中声明它是否需要在两端都需要 SlotKit。
"custom": { "slotkit": { "bothSides": "required" } }
required 用于构建插槽或自定义菜单的模组。拥有该模组的服务器只允许拥有 SlotKit 和该模组的客户端加入。
preferred 用于在一端工作并在两端通过共享插槽状态等方式发挥更大作用的模组。不会因它而拒绝任何人。
- 没有
slotkit 块的模组仅查找并对插槽进行操作。它在任何服务器上都能工作,永远不会导致拒绝。
任何其他值都会在模组加载时抛出异常。声明端 涵盖了握手过程以及被拒绝玩家看到的每条消息。
选择模式范围
关于插槽的每个声明都指定了其适用的游戏模式:ModeScope.SURVIVAL、CREATIVE 或 BOTH,这是 MenuKit 的 ModeScope。SlotKit 在每个检查中读取操作玩家的模式,因此为 BOTH 声明的锁定在创造模式的两个标签页上都有效。没有范围的表单仍然有效,意味着 BOTH,但已弃用。参见模式范围。
查找插槽组
插槽组类别是插槽组的名称,例如 PLAYER_INVENTORY、PLAYER_HOTBAR、CHEST_STORAGE 或 FURNACE_INPUT。SlotGroupCategories.all() 列出打开菜单前的所有类别,SlotGroupCategories.of(menu) 列出菜单上的类别及其插槽,SlotGroupCategories.categoriesBySlot(menu) 给出每个插槽的类别。SlotGroups 列出单个组,可以在两者都声明 PLAYER_INVENTORY 时将一个模组的口袋与主背包区分开。这是客户端层级。插槽组类别 有命名和创建类别的完整规则。
将面板放置在插槽或插槽组上
槽锚点(Slot anchor)是一种 MenuKit 锚点,其框体对应于打开的屏幕上单个槽位的框架或单个槽位组的框体。SlotPlacement.group(group, position) 会在槽位组周围放置一个面板,如上面的第一个示例所示;而 SlotPlacement.slot(address, dx, dy) 则会在距离单个槽位有偏移的位置放置它。每个模式通过 Panel.Builder.in(scope, placement) 接受一个放置配置,并通过 MenuKit 的 AnchorPanelAdapter 进行注册。面板仅在菜单打开时显示其所在的槽位或组,因此“创造模式”和“生存模式”的放置配置会将同一个槽位放置在两个不同的位置,无需模组自行检查模式。这属于客户端层级。参见 槽锚点 和 在创造模式下将槽位放置在别处。
允许、限制与否决操作
操作是对槽位执行的动作。原版 Minecraft 共有十一项操作:CLICK_TAKE、CLICK_PUT、SHIFT_CLICK_OUT、SHIFT_CLICK_IN、COLLECT、DRAG_FILL、HOTBAR_SWAP、OFFHAND_SWAP、DROP、DROP_STACK 和 INVENTORY_INSERT,且默认全部开启。
- 槽位允许的操作由级联决定。单个槽位的声明优先于槽位组,槽位组优先于其所属类别,类别优先于键的默认值。
SlotOperations.inherent(scope, category, operation, value) 用于设置类别级别。
SlotOperations.veto(scope, rule) 注册一条规则,该规则只能表示“拒绝”,适用于非槽位作者模组的场景,例如锁定机制。
SlotOperations.allows(menu, slot, player, operation) 是唯一的检查方法,当级联允许该操作且无否决拒绝时,检查通过。
- 门控(Gate)设定了槽位接受和释放的内容,以及其持有的物品数量。可通过
SlotSpec.gate(...) 或 Window.slot(scope, address).gate(...) 进行设置。Address.playerInventory(n) 在启动时为玩家背包中的槽位命名,在任何屏幕上地址均相同。
- 模组通过声明
BehaviorKey、使用 SlotOperations.define 发布,并在语言文件中提供名称和描述,从而添加自定义操作。
操作 和 门控 涵盖了角色、AppliesTo 以及使用 SlotOperations.as 进行的点击标记。另见 在锁定的槽位上阻止操作 和 添加自定义操作。
构建创建的槽位
创建的槽位(Created slot)是模组添加到菜单中的真实 Slot。ParityGroup.register(owner, spec) 在公共代码中仅注册一次这些槽位组成的组,适用于玩家背包菜单和所有容器菜单,如上面的第二个示例所示。SlotKit 不会为其构建面板。模组使用 SlotFlowElement(按行排列槽位)或 SlotElement(放置单个槽位)在其自己的 MenuKit 面板中展示该组。内容通过槽位所有者上的 StorageAttachment 持久化,为玩家创建时使用 StorageAttachment.playerAttached(namespace, key, size),为单次菜单会话创建时使用 EphemeralStorage.of(size)。
- 所有者的 ID 命名空间应为模组 ID。如果不符合此条件,或模组未声明
required,register 将在启动时抛出异常。错误消息会指明组名及需要添加的行。
SlotSpec.shiftClickIn(true) 使该组成为鼠标右键快速移动的目标,SlotSpec.emptyIcon(...) 则在其空槽位中绘制轮廓。
SlotSpec.activeCount(start) 允许服务器为每位玩家设置该组中处于活动状态的槽位数量,QuickMoveRoutes 决定鼠标右键快速移动的目的地。
StorageAttachment.playerAttachedVisible(...) 还会将内容发送给其他玩家的客户端,用于在玩家身上绘制的装备。
SlotPlacement 可将面板放置在槽位组或单个槽位上,例如副手槽上方。
这需要双方都安装 SlotKit。参见 parity 组、存储 和 在副手槽上方放置槽位。
在潜影盒和 bundles 内部查找物品
ItemSources 遍历玩家携带的物品,包括背包、末影箱,以及任意深度的潜影盒和 bundles,优先匹配最近的物品。ItemScope 指定应搜索其中哪些部分。在服务器端,take 和 walk 会移除或更改物品,并通过所有容器写回更改。find 在任一侧列出匹配项,并为每项提供一个 ItemPath,以便客户端选择物品,服务器随后通过 at 对其执行操作。相同的调用还可接受调用方提供的 Container,例如玩家当前打开的箱子。解析仅针对模组传入的容器进行,因此在服务器端应传递位于玩家菜单背后的那个容器,切勿使用客户端命名的容器。为了在嵌套物品(如箱子里的潜影盒中的 bundle)保持菜单打开状态,请使用 ItemSources.live(container, path) 绑定它。LiveItem 可接受任意数量的写入,并将每次写入沿链路上传;当物品移动或被其他内容更改时,它将变为过时状态,因此菜单的 stillValid 应返回 !live.isStale()。参见 物品源 和 在潜影盒和 bundles 内部查找并使用物品。
自 2.2.0 版本起,ItemSources.pathOf(player, slot) 为主物品栏、末影箱或携带附件的槽位中的物品命名,客户端与服务端返回结果一致。在客户端,末影箱自身的菜单会显示一个占位容器,因此其槽位在此处不具名称。通过 playerAttached(...).carried() 声明的玩家附件用于存放玩家自身的物品,使用 carried(true) 的作用域可遍历这些物品,而 containerOf(player, path) 则返回其内容。玩家、方块或实体附件的所有绑定共享同一份堆栈列表,因此无论在哪里读取,堆栈都是同一个对象。详见 Item sources。
为物品赋予状态,并改变其绘制方式
ItemState 是一个依附于物品的值,它会随潜影盒等物品一同传递,并与堆栈同步至所有客户端。ItemState.Saved.YES 会将该状态与物品一起保存,而 Saved.NO 则在重新连接或重启时丢弃它。服务端通过 set 和 clear 来设置该状态。只有声明了 bothSides: required 的模组才能声明状态。SlotLooks 会在持有 ItemState 或 SlotLooks.When 检查在客户端返回 true 时,改变槽位绘制物品的方式:animate 播放动画,swapWhen 在其位置绘制另一堆物品,而 under 和 over 则通过 MenuKit 的槽位装饰绘制标记。请在客户端初始化器中声明外观效果。详见 Item state and slot looks 以及 Show an item as open。
处理对槽位的双击操作
SlotDoubleClick 将槽位的普通左键双击操作交由模组的动作处理。两次点击需在 1 秒内完成,且光标位于同一像素位置,并且仅计算真实鼠标操作,因此排序模组的模拟点击永远不会配对。第一次点击保持原版行为并提起堆栈,在配对等待期间,该堆栈会绘制回其原槽位中。第二次点击(原版会将其视为收集全部)会交给第一个接受该槽位的注册项。详见 Double-click 以及 Open an item on a double-click。
按组 ID 显示容器
SlotGroupElement.of(id) 会以行形式显示一个槽位组,通过其在当前打开菜单上的 SlotGroupId 进行查找。SlotGroupElement.of(SlotGroupId.category(SlotGroupCategory.CHEST_STORAGE)) 会显示单个箱子、双联箱或桶,且不包含任何菜单类型索引;其他模组创建的组会通过其保存形式命名,无需对该模组存在编译依赖。该元素仅在所属组的槽位存在时显示。在其他面板中显示某个组,仅会在屏幕上移动其槽位。每个容器保持独立,且菜单自身的 Shift 点击会在 SlotKit 添加的每个槽位前停止。详见 Slot group element 以及 Separate containers。
向已打开的菜单添加槽位组
OnDemandGroup 在公共代码中只注册一次,类似于 ParityGroup,但在服务端添加之前,它不会出现在任何菜单上。BOX.add(player, storage) 会将实例的槽位添加到玩家当前打开的菜单中(包括客户端),而 instance.remove() 则会移除它们。每个实例都是独立的槽位组,ID 类似 mymod:box:slots#0,针对该类型的声明会应用于所有实例。被移除的实例的槽位仍保留在菜单上,处于非活动状态,直到同类型的下一个实例接管它们,因此在菜单打开期间,其他槽位的索引不会发生移动。对于没有安装 SlotKit 及该类型模组的客户端,add 会返回 null。这需要双方都安装 SlotKit。类的 Javadoc 涵盖了门控、快速移动路径以及每个实例的活动计数。
为类别中的每个组放置面板
SlotPlacement.group(category, position) 仅能访问该类别的原版组。CategoryPanels.declare(category, on -> panel) 会在当前打开菜单上显示的该类别的每个组上放置一个面板,包括创建的组和按需实例,因此箱子和模组在旁边打开的潜影箱与末影箱各自都会获得自己的排序按钮。on.group() 命名了面板所在的组。在处理点击时应读取此值,因为标签页切换可能会更改它。请在初始化时声明,每类别最多 CategoryPanels.MAX_SHOWN 个面板。SlotGroupCategory.BUNDLE_STORAGE 是已打开的束口袋的类别,因此其他模组会以相同方式对待任何模组的束口袋。此为客户端层级。
在菜单之间切换
MenuSwitch 允许玩家在菜单之间切换,同时其在世界中打开的那个菜单会排在其他菜单之后等待。在服务端的标签页点击操作中,MenuSwitch.open(player, provider) 会打开一个菜单并将箱子暂时搁置(其盖子保持开启,无关闭音效),openInventory(player) 会打开物品栏,而 back(player) 则会返回到箱子。通过 open 打开的菜单在玩家离开时会正常关闭,因此工作台网格会归还其物品。游标上的堆栈会随着每次切换而移动。当搁置的菜单的 stillValid 失败、玩家死亡、切换维度或离开,或前方的菜单关闭时,该搁置的菜单会正确关闭,onSetAsideClosed 会监听所有这些情况。open 和 back 仅发送原版数据包。openInventory 需要客户端安装 SlotKit,若无则返回 false。仅限服务端线程。
在滚动区域内滚动槽位
位于 MenuKit ScrollContainer 内的 SlotElement 像任何其他元素一样进行滚动和裁剪。跨越滚动区域边缘的槽位仅在其可见区域内绘制、悬停并接受点击。使用 SlotElement 的模组无需为此编写额外代码。
打开自定义菜单
CustomMenu.define(id, ...) 构建一个具有自身槽位的容器菜单,并使用 MenuKit 面板进行布局。服务器决定显示哪些面板,玩家只能切换声明为 toggleable() 的面板,而客户端仅在其 validWhen 条件满足时才能打开该菜单。适用与 ParityGroup 相同的定义检查。请参阅 使用其自身槽位打开自定义菜单。
将状态附加到槽位
SlotState.register(scope, id, codec, streamCodec, defaultValue, visibility, canWrite) 创建一个通道,为每个槽位存储一个类型的值,独立于槽位中的物品。PRIVATE 为每位查看者存储一个值,而 SHARED 为所有人存储一个值。槽位通过 Address 命名,在菜单重新打开时在两端解析。服务器会检查客户端发送的每次写入操作,且除非 canWrite 规则允许,否则 SHARED 通道会拒绝所有客户端。请参阅 槽位状态通道 和 将标志附加到槽位。
询问另一端运行了什么
Presence 报告玩家加入时另一端的状态。在客户端,Presence.serverHasSlotKit()、serverHas(modId) 和 serverHasChannel(channelId) 用于查询服务器的情况。在服务器端,Presence.clientHasSlotKit(player) 和 clientHas(player, modId) 用于查询玩家的情况。请参阅 Presence。
了解限制
Limits 列出了 SlotKit 未实现的功能以及本版本中的开放缺陷,例如叠加面板中的已创建槽位。
升级
Upgrading 指导模组从 SlotKit 2.1 升级到 2.2、从 2.0 升级到 2.1,以及从 1.x 升级到 2.0,为每项变更提供前后对比;并涵盖从 MenuKit: Containers 或 MenuKit 6 的槽位代码迁移的方法,包括导入映射和两个重命名操作。
许可证
MIT。
SlotKit
SlotKit is a slot library for Fabric mods, built on MenuKit. A mod uses it to find and act on the slots in any menu, vanilla or modded, or to build real slots and custom menus that persist and sync. I built it for my own mods and opened it up so other modders can use it too.
If you're a player and another mod asked for SlotKit, install it alongside that mod and you're done.
SlotKit was called MenuKit: Containers. Mods built for Containers need an update, and the upgrading guide has the steps. MenuKit: Containers 6.2.0 is still in this project's version list.
Features
SlotKit has two tiers. A mod needs SlotKit on the other side only for the second.
| Tier |
Needs SlotKit on |
Adds |
| Client |
The client only. It works on any server, vanilla included. |
Slot groups and categories in every menu, slot operations, vetoes and gates, and panels placed on a slot or a slot group |
| Client and server |
Both sides |
Created slots, custom container menus, storage attachments, per-slot state, and items found inside shulker boxes and bundles |
- Every slot group, vanilla or created, is published under a category any mod can read, with or without a menu open.
- Each thing that can be done to a slot is named as an operation. Vanilla has eleven, one per gesture, and a mod can add its own. A slot's own setting is checked first, then its group's, then its category's, and a locking mod can veto any operation.
- A MenuKit panel can be placed around a slot group, or at an offset from one slot, so it shows on every screen with that group or slot. That includes the survival inventory, every chest, and every other container.
- Every rule about a slot (a veto, a category rule, a gate, a slot-state channel) is declared for survival, creative, or both, and holds in creative too. A panel can take a different place in each mode.
- A player inventory slot has one address, the same on every screen and for every player, so a rule can name it at startup.
- Each container on a menu stays its own container. A menu's shift-click never lands in another mod's slots by accident, and a mod can show any container's slots in its own panel by the group's id.
- The server can add slot groups to the menu a player has open and remove them again, for something the player opens while a screen is up, like a shulker box opened from a chest's screen.
- A panel can sit on every shown group of a category, so a chest and each shulker box or ender chest opened beside it get a panel of their own.
- A player at a chest can switch to their inventory, a shulker box, or their ender chest and back, and the chest stays open in the world the whole time.
- Slots in a MenuKit scroll area clip to it, so a long grid of slots can scroll.
- Created slots are UI components. A pocket, an extra equipment slot, or a satchel is each a real
Slot, synced by vanilla's protocol. A mod registers its slot groups once and places them in its own MenuKit panels, next to its buttons and labels, on every screen it chooses.
- The server can open, close, and resize a slot group for each player, and a mod can decide where a shift-click goes.
- A slot's contents can be shown to other players, for gear drawn on the player model.
- A mod can find and use items anywhere a player carries them: the inventory, the ender chest, and shulker boxes and bundles nested to any depth. The chest a player has open can be searched too. A change writes back through every container, and a menu can stay open on a nested item, like a bundle inside a shulker box. A mod's own carried slots, such as a pocket or a carried ender chest, can be searched as well.
- An item can carry a state of the mod's own, saved with it or not, and a slot can draw the item differently while that state or a client-side check holds: an animation, another stack in its place, or a mark under or over it.
- A mod can take a plain double-click on a slot for its own action, the same gesture in every mod that uses it.
- Custom container menus are built from MenuKit panels.
- Created slots behave like vanilla ones in creative and survival, on death, and with Curse of Binding and Mending.
- Per-slot state can be attached to any slot, either private to each player or shared by everyone viewing it. The server checks every write a client sends. The state is stored on the slot's owner (a player, block, entity, or item), where
/data get can read it.
- Each side checks which mods the other has before the world loads. A server refuses only players missing a mod that builds slots, and names the mods to install, with links. Everyone else joins.
- Worlds and player files saved with MenuKit: Containers load with no conversion, and shulker boxes keep their contents and slot state.
Example
A panel above the player inventory, registered once from the client entry point. It uses the client tier, so it works on any server.
Panel panel = Panel.builder("mymod:toolbar")
.style(PanelStyle.NONE)
.elements(toolbarButtons)
.in(ModeScope.BOTH, SlotPlacement.group(SlotGroupCategory.PLAYER_INVENTORY,
PanelPosition.region(OutsideRegion.TOP_ALIGN_RIGHT)))
.visibleWhen(() -> config.toolbar)
.build();
new AnchorPanelAdapter(panel);
Nine synced pocket slots on every container screen, registered once from the common entry point. These need SlotKit on both sides.
public static final PlayerStorageAttachment<NonNullList<ItemStack>> POCKETS =
StorageAttachment.playerAttached("mymod", "pockets", 9);
POCKET_SLOTS = ParityGroup.register("mymod:pockets",
SlotSpec.at("pockets", SlotGroupCategory.PLAYER_INVENTORY).count(9)
.storage(player -> POCKETS.bind(player)));
The slots go in a panel of the mod's own, built from the client entry point.
// Client initializer: your panel, the slots under a button.
Panel pockets = Panel.builder("mymod:pockets")
.add(Button.builder().label(Component.literal("Sort")).size(60, 14).build())
.add(SlotFlowElement.builder().addGroup(POCKET_SLOTS).at(0, 18).build())
.style(PanelStyle.RAISED)
.in(ModeScope.BOTH, Placement.screen(PanelPosition.region(OutsideRegion.LEFT_ALIGN_TOP).priority(20)))
.build()
.visibleWhen(() -> ClientSlots.isShown(POCKET_SLOTS.id()));
new ScreenPanelAdapter(pockets).onMatching(ScreenMatcher.all());
Getting started
Minecraft 26.3 is unobfuscated, so SlotKit goes on the plain implementation configuration, beside MenuKit.
repositories {
maven { url 'https://api.modrinth.com/maven' }
}
dependencies {
implementation 'maven.modrinth:menukit:7.5.0+26.3'
implementation 'maven.modrinth:xQUBXV8I:2.3.0+26.3' // SlotKit
}
xQUBXV8I is SlotKit's Modrinth project id. It points to the project no matter what the slug is.
Declare both in fabric.mod.json, each against its own version, with both bounds (why). Separate the bounds with a space, since Fabric doesn't read a comma there.
"depends": { "menukit": ">=7.5.0 <8.0.0", "slotkit": ">=2.3.0 <3.0.0" }
Players install SlotKit as its own mod, next to the mods that use it. List it as a required dependency on the mod's Modrinth page so it's installed with them.
Requirements
- MenuKit 7.5.0 or newer, below 8.0.0. SlotKit builds its panels and slot drawing on MenuKit.
- Fabric API
Compatibility
Minecraft 26.3 with Fabric. Install SlotKit on the client. A server needs it only when a mod that adds slots, such as Hotbar Pockets or Simple Elytra Slot, is installed there too. That mod lists SlotKit as a required dependency, so SlotKit comes along with it. That's why Modrinth lists SlotKit as client-side, even though it ends up on plenty of servers. SlotKit replaces MenuKit: Containers, so the two can't be installed together, and it can't be installed with Inventory Max either.
Used by
How to use
This guide follows the order a mod usually meets SlotKit, from finding slots on the client to building slots that need both sides. Each part links to the full developer docs. Concepts defines every term, and Recipes has a worked example for each common task.
The public API
The API is every type in a package named api, which is com.trevlar.slotkit.api.*. The version contract covers those. Every other package is internal and can change in any release, a patch included. A task that seems to need an internal type is a gap in the API, so open an issue for it. Versioning has what each part of a version number promises.
Declare which sides need SlotKit
A mod states in its fabric.mod.json whether it needs SlotKit on both sides.
"custom": { "slotkit": { "bothSides": "required" } }
required is for a mod that builds slots or custom menus. A server with the mod admits only clients that have SlotKit and the mod.
preferred is for a mod that works on one side and does more with both, such as shared slot state. Nobody is refused for it.
- A mod with no
slotkit block only finds and acts on slots. It works on any server and never causes a refusal.
Any other value throws when the mod loads. Declaring sides covers the handshake and every message a refused player sees.
Choose a mode scope
Every declaration about a slot names the game mode it's for: ModeScope.SURVIVAL, CREATIVE, or BOTH, MenuKit's ModeScope. SlotKit reads the acting player's mode on each check, so a lock declared for BOTH holds on both of creative's tabs. The forms without a scope still work, mean BOTH, and are deprecated. See Mode scope.
Find slot groups
A slot group category is a name for a group of slots, such as PLAYER_INVENTORY, PLAYER_HOTBAR, CHEST_STORAGE, or FURNACE_INPUT. SlotGroupCategories.all() lists every category with no menu open, SlotGroupCategories.of(menu) lists the categories on a menu with their slots, and SlotGroupCategories.categoriesBySlot(menu) gives the category of each slot. SlotGroups lists individual groups, which can tell one mod's pockets apart from the main inventory when both declare PLAYER_INVENTORY. This is client tier. Slot group category has the full rules for naming and minting categories.
Place a panel on a slot or a slot group
A slot anchor is a MenuKit anchor whose box is one slot's frame or one slot group's box on the open screen. SlotPlacement.group(group, position) places a panel around a slot group, as in the first example above, and SlotPlacement.slot(address, dx, dy) places it at an offset from one slot. The panel takes one placement per mode with Panel.Builder.in(scope, placement) and is registered with MenuKit's AnchorPanelAdapter. A panel shows only where its slot or group is on the open menu, so a placement for creative and another for survival put the same slot in two places with no mode check of the mod's own. This is client tier. See Slot anchors and Put a slot in another place in creative.
Allow, gate, and veto operations
An operation is something done to a slot. Vanilla's eleven are CLICK_TAKE, CLICK_PUT, SHIFT_CLICK_OUT, SHIFT_CLICK_IN, COLLECT, DRAG_FILL, HOTBAR_SWAP, OFFHAND_SWAP, DROP, DROP_STACK, and INVENTORY_INSERT, and every one is on by default.
- What a slot allows is decided by a cascade. A per-slot declaration wins over the slot's group, the group wins over its category, and the category wins over the key's default.
SlotOperations.inherent(scope, category, operation, value) sets the category level.
SlotOperations.veto(scope, rule) registers a rule that can only say no, for a mod that is not the slot's author, such as a lock.
SlotOperations.allows(menu, slot, player, operation) is the one check, and it passes when the cascade allows the operation and no veto refuses it.
- A gate sets what a slot accepts and releases, and how many of an item it holds. It is set with
SlotSpec.gate(...) or Window.slot(scope, address).gate(...). Address.playerInventory(n) names a player inventory slot at startup, the same address on every screen.
- A mod adds its own operation by declaring a
BehaviorKey, publishing it with SlotOperations.define, and shipping a name and description in its lang file.
Operation and Gate cover roles, AppliesTo, and click tagging with SlotOperations.as. See also Block operations on a locked slot and Add an operation of your own.
Build created slots
A created slot is a real Slot a mod adds to a menu. ParityGroup.register(owner, spec) registers a group of them once, in common code, on the player's inventory menu and every container menu, as in the second example above. SlotKit builds no panel for it. The mod shows the group in its own MenuKit panel with SlotFlowElement, which lays the slots out in rows, or SlotElement, which places one slot. The contents persist through a StorageAttachment on the slot's owner, built with StorageAttachment.playerAttached(namespace, key, size) for a player or EphemeralStorage.of(size) for one menu session.
- The owner id's namespace is the mod's id.
register throws at startup when it isn't, or when the mod doesn't declare required. The message names the group and the line to add.
SlotSpec.shiftClickIn(true) makes a group a shift-click target, and SlotSpec.emptyIcon(...) draws an outline in its empty slots.
SlotSpec.activeCount(start) lets the server set how many of the group's slots are live for each player, and QuickMoveRoutes decides where a shift-click goes.
StorageAttachment.playerAttachedVisible(...) also sends the contents to other players' clients, for gear drawn on the player.
- A
SlotPlacement places the panel on a slot group or a slot, such as above the offhand.
This needs SlotKit on both sides. See Parity group, Storage, and Put a slot above the offhand.
Find items inside shulker boxes and bundles
ItemSources walks the items a player carries, in the inventory, the ender chest, and shulker boxes and bundles to any depth, nearest first. An ItemScope says which of those to search. On the server, take and walk remove or change an item and write the change back through every container. find lists matches on either side with an ItemPath for each, so a client can choose an item and the server can act on it with at. The same calls also take a Container the caller supplies, such as the chest a player has open. It resolves only against the container the mod passes in, so on the server pass the one behind the player's menu, never one the client names. To keep a menu open on a nested item, such as a bundle inside a shulker box in a chest, bind it with ItemSources.live(container, path). The LiveItem takes any number of writes, sends each one back up the chain, and goes stale when the item moves or something else changes it, so the menu's stillValid returns !live.isStale(). See Item sources and Find and use items inside shulker boxes and bundles.
Since 2.2.0, ItemSources.pathOf(player, slot) names the item in a main inventory slot, an ender chest slot, or a carried attachment's slot, with the same answer on the client and the server. On the client an ender chest's own menu shows a stand-in container, so its slots name nothing there. A player attachment declared playerAttached(...).carried() holds the player's own things, a scope with carried(true) walks it, and containerOf(player, path) returns its contents. Every binding of a player, block, or entity attachment shares one list of stacks, so a stack is the same object wherever it's read. See Item sources.
Give an item a state, and change how it draws
An ItemState is a value that rides on an item, through shulker boxes and back, synced to every client with the stack. ItemState.Saved.YES saves it with the item, and Saved.NO drops it at a relog or restart. The server sets it with set and clear. Only a mod that declares bothSides: required can declare a state. SlotLooks changes how a slot draws an item while an ItemState holds or a SlotLooks.When check answers yes on the client: animate plays an animation, swapWhen draws another stack in its place, and under and over draw a mark through MenuKit's slot decorations. Declare looks from the client initializer. See Item state and slot looks and Show an item as open.
Take a double-click on a slot
SlotDoubleClick gives a plain left double-click on a slot to a mod's action. Both clicks land within one second with the cursor on the same pixel, and only the real mouse counts, so a sort mod's simulated clicks never pair. The first click stays vanilla's and lifts the stack, which is drawn back in its slot while the pair is pending. The second, which vanilla would take as gather all, goes to the first registration that accepted the slot. See Double-click and Open an item on a double-click.
Show a container by its group's id
SlotGroupElement.of(id) shows one slot group in rows, found by its SlotGroupId on whatever menu is open. SlotGroupElement.of(SlotGroupId.category(SlotGroupCategory.CHEST_STORAGE)) shows a single chest, a double chest, or a barrel with no menu-type indices, and another mod's created group is named by its saved form with no compile dependency on that mod. The element shows only while the group's slots do. Showing a group in another panel moves its slots on the screen only. Each container stays its own, and a menu's own shift-click stops before every slot SlotKit added. See Slot group element and Separate containers.
Add slot groups to an open menu
An OnDemandGroup is registered once in common code, like a ParityGroup, but it's on no menu until the server adds it. BOX.add(player, storage) puts an instance's slots on the menu the player has open, the client's included, and instance.remove() takes them away. Each instance is its own slot group, with an id like mymod:box:slots#0, and declarations on the kind reach every instance. A removed instance's slots stay on the menu, inert, until the next instance of its kind takes them, so no other slot's index moves while the menu is open. add returns null for a client without SlotKit and the kind's mod. This needs SlotKit on both sides. The class Javadoc covers gates, quick-move routes, and active counts per instance.
Put a panel on every group of a category
SlotPlacement.group(category, position) reaches only a category's vanilla group. CategoryPanels.declare(category, on -> panel) puts one panel on each group of the category shown on the open menu, created groups and on-demand instances included, so a chest and the shulker box and ender chest a mod opens beside it each get their own Sort button. on.group() names the group a panel sits on. Read it when acting on a click, since a tab switch can change it. Declare at init, up to CategoryPanels.MAX_SHOWN panels per category. SlotGroupCategory.BUNDLE_STORAGE is the category for an opened bundle, so other mods treat any mod's bundle the same way. This is client tier.
Switch between menus
MenuSwitch moves a player between menus while the one they opened in the world waits behind the others. From a tab click on the server, MenuSwitch.open(player, provider) opens a menu with the chest set aside (its lid stays up, with no close sound), openInventory(player) opens the inventory, and back(player) returns to the chest. Menus opened through open close normally when the player leaves them, so the crafting grid hands its items back. The stack on the cursor moves with every switch. The set-aside menu closes properly when its stillValid fails, the player dies, changes dimension, or leaves, or the menu in front closes, and onSetAsideClosed hears each of these. open and back send only vanilla packets. openInventory needs SlotKit on the client and returns false without it. Server thread only.
Scroll slots in a scroll area
A SlotElement inside a MenuKit ScrollContainer scrolls and clips like any other element. A slot across the edge of the scroll area draws, hovers, and takes clicks only where it shows. A mod that uses SlotElement needs no extra code for this.
Open a custom menu
CustomMenu.define(id, ...) builds a container menu with its own slots, laid out with MenuKit panels. The server decides which panels are shown, a player can toggle only a panel declared toggleable(), and a client can open the menu only while its validWhen holds. The same definition check as ParityGroup applies. See Open a custom menu with its own slots.
Attach state to a slot
SlotState.register(scope, id, codec, streamCodec, defaultValue, visibility, canWrite) creates a channel that stores one typed value per slot, separate from the slot's item. PRIVATE stores one value per viewer, and SHARED stores one value for everyone. A slot is named by an Address, which resolves after a menu reopens and on both sides. The server checks every write a client sends, and a SHARED channel refuses every client unless its canWrite rule allows them. See Slot state channel and Attach a flag to a slot.
Ask what the other side runs
Presence reports what the other side had when the player joined. On the client, Presence.serverHasSlotKit(), serverHas(modId), and serverHasChannel(channelId) answer about the server. On the server, Presence.clientHasSlotKit(player) and clientHas(player, modId) answer about a player. See Presence.
Know the limits
Limits lists what SlotKit doesn't do and the open gaps in this release, such as created slots in overlay panels.
Upgrade
Upgrading moves a mod from SlotKit 2.1 to 2.2, from 2.0 to 2.1, and from 1.x to 2.0, with a before and after for each change, and from MenuKit: Containers or MenuKit 6's slot code, with an import map and the two renames.
License
MIT.
评论 0
登录后参与评分
还没有评论,来抢沙发吧