SlotKit

模组

· 作者 trevlar

一个用于查找和操作任意菜单中槽位、以及构建持久化并同步的真实槽位的 Fabric 库。

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

需要前置:Fabric API、MenuKit

最新 2.3.0+26.3 · 26.3 · Fabric

一键开服(送7天)

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 页面上将其列为必需依赖项,以便随其他模组一起安装。

要求

  • MenuKit 7.5.0 或更高版本,低于 8.0.0。SlotKit 基于 MenuKit 构建其面板和插槽绘制功能。
  • Fabric API

兼容性

适用于带有 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。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源