ModularPacks
ModularPacks 是一款 Paper 插件,为 Minecraft 服务器添加了可升级的物理背包。
ModularPacks 不像其他基于命令的玩家储物箱那样处理背包,而是将背包作为一个实际的物品。玩家可以携带、打开、升级、放置、分享它,并围绕它进行建造,使其成为世界中真实的一部分。本插件旨在为 Paper 服务器带来类似模组化的背包体验,同时保持对原版客户端的兼容性。
ModularPacks 深受模组化背包系统(尤其是可安装升级模块的概念)的启发,但它并非仅仅通过修改几个设置而成的快速克隆品。该插件基于 Paper 的服务器端系统、PersistentDataContainer 物品标识、SQLite 存储、可配置配方、管理员恢复工具以及用于自定义模块支持的 API 构建而成。
功能
- 具有持久身份标识的物理背包物品
- 可配置的背包等级、大小、配方、名称、描述、颜色、头颅纹理和自定义模型数据
- 可安装的升级模块
- 可放置的背包,支持可配置的世界渲染
- 可共享的背包,支持可配置的共享用户数量限制
- 基于 SQLite 的背包内容和已安装模块状态的存储
- 用于发放、打开、列出、恢复和更改背包的管理员命令
- 意外掉落虚空物品的恢复日志
- 可选的更新检查器,支持游戏内和控制台通知
- 通过
CustomModelData 实现的可选资源包支持
- 公共 API,允许其他插件注册自定义模块
可选资源包
想要自定义背包和模块的外观?请使用官方的 ModularPacks Resources 资源包以获得完整的模型支持和主题物品渲染!
资源包链接:
插件无需该资源包即可运行,但推荐安装以获得预期的视觉效果。
要求与安装
要求
- Paper
1.21.10+
- Java
21
- Maven(如果从源代码构建)
ModularPacks 基于 Paper API 构建,专为基于 Paper 的服务器设计。其他服务器平台如果在保持 Paper API 兼容性的前提下可能也能运行,但 Paper 是唯一受支持的目标平台。
安装
-
下载插件 jar 文件。
-
将其放入服务器的 plugins/ 文件夹中。
-
启动服务器一次。
-
ModularPacks 将生成其数据文件夹和默认文件:
plugins/ModularPacks/config.yml
plugins/ModularPacks/lang/en_us.yml
plugins/ModularPacks/backpacks.db,在首次使用背包数据时创建
-
根据需要编辑 config.yml 和 lang/en_us.yml。
-
重启服务器,或运行:
/backpack reload
设计目标与背包行为
ModularPacks 有何不同?
许多背包插件通过添加命令、虚拟库存或简单的打开菜单的物品来解决存储问题。ModularPacks 采取了不同的方法。
每个背包都在物品上存储了其唯一的 UUID。物品本身只是一个钥匙。内容、已安装的模块、模块状态、共享数据和恢复信息都安全地存储在 SQLite 数据库中。这意味着背包可以重命名、升级、放置、由管理员打开、恢复或检查,而不仅仅依赖于脆弱的项目描述文本。
该插件也是围绕“模块”而非单一硬编码的背包菜单设计的。背包可以拥有升级槽位,模块可以提供被动效果、自定义屏幕、过滤器、泵、储罐、制作工具或其他行为。这种结构使得插件具备可扩展性,而不仅仅是一个固定大小的存储菜单。
简而言之:灵感是熟悉的,但实现是专门为希望获得可配置且可扩展功能的 Paper 服务器、服务器所有者、管理员和开发者构建的。
背包的工作原理
每个 ModularPacks 背包都会在物品上存储持久元数据:
backpack_id - 背包的 UUID 身份标识
backpack_type - 配置的类型或等级,例如 Leather、Iron 或 Netherite
实际内容存储在插件数据库中,而不是直接存储在物品描述文本中。当玩家打开背包时,ModularPacks 会加载该 backpack_id 的内容和已安装的模块。当菜单关闭时,插件会将更新后的内容和模块状态保存回 SQLite。
这种设计有助于防止过时物品数据,并使管理员恢复成为可能。它还允许链接或共享背包行为,而无需尝试将整个库存存储在物品文本中。
默认背包等级
默认配置包含以下背包类型:
| Type |
Rows |
Upgrade Slots |
Leather |
2 |
1 |
Copper |
3 |
1 |
Iron |
4 |
2 |
Gold |
6 |
3 |
Diamond |
8 |
4 |
Netherite |
10 |
5 |
这些仅是默认值。您可以通过 config.yml 编辑现有类型或添加新类型。
默认模块
模块在 config.yml 下的 Upgrades: 部分进行配置。每个模块都可以有自己的配方、显示物品、描述、自定义模型数据、切换行为和模块特定的设置。
默认模块包括:
实用模块
Everlasting - 使背包不可破坏
Magnet - 将附近的物品拉入背包
FluidTank - 存储桶装流体
ExperienceTank - 存储并释放玩家经验值
Feeding - 自动使用背包内容物喂养玩家
Void - 过滤丢弃物品,同时记录可恢复的物品数据
Restock - 从背包内容物中为玩家补充库存
Pump - 在玩家和 Fluid Tank(流体储罐)模块之间移动桶装流体
ExpPump - 在玩家和 Experience Tank(经验储罐)模块之间移动经验值
工作台模块
Crafting - 便携式合成台
Smelting - 便携式熔炉
Blasting - 便携式高炉
Smoking - 便携式烟熏炉
Stonecutter - 便携式切石机
Anvil - 便携式铁砧
Smithing - 便携式锻造台
Jukebox - 具有播放列表功能的便携式唱片机
Autocrafting - 可配置的自动合成行为
基本用法
玩家可以通过配方或管理员命令获得背包。
要打开背包,请右键点击背包物品。
在背包菜单中,玩家可以与存储槽位和已安装的模块进行交互。模块操作显示在模块的lore(描述文本)中,因此服务器所有者可以在语言文件中自定义说明。
常见的模块交互包括:
- 左键点击以打开或配置模块
- 右键点击以执行次要操作或切换模式
- Shift + 左键点击以切换可切换的模块
- Shift + 右键点击以移除模块
具体行为取决于模块类型。
命令与权限
命令
基础命令为:
/backpack
帮助
/backpack help
/backpack help <command>
根据发送者的权限显示可用命令。
给予背包和模块
/backpack give type <typeId> [player] [amount]
/backpack give module <upgradeId> [player] [amount]
示例:
/backpack give type Leather Steve 1
/backpack give module Magnet Steve 1
预览配方
/backpack recipe backpack <typeId> [variantId]
/backpack recipe module <upgradeId>
示例:
/backpack recipe backpack Iron
/backpack recipe backpack Iron 2
/backpack recipe module Magnet
配方预览对玩家很有用,因为 ModularPacks 的配方不仅包含原版材料,还可能包含背包或模块作为合成原料。
列出背包
/backpack list [playerName [menu] | unowned]
示例:
/backpack list
/backpack list Steve
/backpack list Steve menu
/backpack list unowned
这允许管理员检查存储的背包记录,如果服务器缓存了离线玩家的 UUID,还可以查看由离线玩家拥有的背包。
如果在玩家名称后添加 menu,ModularPacks 会打开一个 GUI 界面显示该玩家存储的背包,而不是将列表打印到聊天栏。当一名玩家拥有多个背包且管理员需要快速检查或打开其中一个时,这非常有用。
以管理员身份打开背包
/backpack open <uuid>
/backpack open <player> <Type#N>
示例:
/backpack open Steve Netherite#1
这在管理、恢复和支持方面非常有用。
更改手中背包的类型
/backpack settype <typeId> [--force]
这会更改你主手当前持有的背包的层级/类型。
请谨慎使用此功能。当将背包更改为更小的类型时,ModularPacks 通常会检查新尺寸范围外是否存在任何物品,如果这些槽位被占用则会阻止更改。
--force 标志会绕过此保护,强制调整背包大小。如果新类型的存储槽位较少,超出新尺寸的任何物品可能会被截断并丢失。只有了解风险的管理员才应使用此功能,最好在检查背包内容或进行数据库备份后使用。
重新加载配置
/backpack reload [config|lang|recipes|all]
示例:
/backpack reload
/backpack reload config
/backpack reload lang
/backpack reload recipes
/backpack reload all
无需完全重启服务器即可重新加载 ModularPacks 的特定部分。
config 重新加载 config.yml、背包类型、升级项、放置背包渲染以及更新检查器设置。
lang 重新加载语言文件。
recipes 重新加载并重新注册背包和模块配方。
all 重新加载所有内容。
不带参数运行 /backpack reload 的行为等同于 all。
恢复工具
/backpack recover backpack <player> <backpackUuid>
/backpack recover void <player|uuid> list [limit] [all]
/backpack recover void <player|uuid> <id|latest> [receiver]
虚空回收命令与 voided_items 数据库表配合工作。当 Void(虚空)模块删除物品时,ModularPacks 会存储足够的物品数据,以便管理员稍后将其恢复。
权限
| 权限 |
默认值 |
描述 |
modularpacks.command |
true |
允许使用基础 /backpack 命令 |
modularpacks.recipe |
true |
允许使用配方预览命令 |
modularpacks.open |
true |
允许玩家打开背包 |
modularpacks.place |
true |
允许玩家在世界中放置背包 |
modularpacks.pickup |
true |
允许玩家拾取已放置的背包 |
modularpacks.reload |
op |
允许重新加载配置、语言和配方 |
modularpacks.admin |
op |
允许使用管理员级别的背包工具 |
modularpacks.update.notify |
op |
启用时接收更新通知 |
服务器管理员在发布服务器之前应审查这些默认设置。面向玩家的权限默认启用,而管理权限仅限操作员使用。
配置与数据
配置
主配置文件:
plugins/ModularPacks/config.yml
配置文件分为两个主要部分:
modularpacks: 用于全局插件行为
BackpackTypes: 和 Upgrades: 用于背包和模块定义
全局设置
重要的全局设置包括:
modularpacks:
Enabled: true
ResizeGUI: true
AutoCloseOnTeleport: true
AllowShulkerBoxes: false
AllowBundles: false
BackpackInsertBlacklist: []
ResizeGUI 控制背包页面是动态调整大小还是保持固定大小。
AutoCloseOnTeleport 会在玩家传送时关闭已打开的背包菜单。
AllowShulkerBoxes 和 AllowBundles 控制是否允许将嵌套存储物品放入背包中。
BackpackInsertBlacklist 阻止特定材质被插入到背包中。磁铁模块也会遵守此列表。
更新检查器
UpdateChecker:
Enabled: true
ShowChangeLog: true
CheckOnStartup: true
PeriodicCheck: true
CheckIntervalHours: 24
NotifyPermission: modularpacks.update.notify
ReleaseApiUrl: https://api.github.com/repos/tootertutor/ModularPacks/releases/latest
当有新的 GitHub 版本可用时,更新检查器可以通知控制台和拥有权限的玩家。你可以禁用启动检查、定期检查、更改日志输出或整个更新检查器。
调试点击日志
Debug:
ClickLog: false
启用后,ModularPacks 会将背包和模块库存的点击或拖拽事件写入以下文件:
plugins/ModularPacks/click-events.log
这主要用于调试库存排序模组、意外的 GUI 行为或可能的重复物品报告。除非你正在积极排查问题,否则请保持禁用状态。
GUI 材质
NavPageButtons: ARROW
NavBorderFiller: GRAY_STAINED_GLASS_PANE
UnlockedUpgradeSlotMaterial: WHITE_STAINED_GLASS_PANE
LockedUpgradeSlotMaterial: IRON_BARS
这些设置控制常见的菜单项,如页面按钮、边框填充物、已解锁的模块槽位和已锁定的模块槽位。
可放置的背包
Placeable: true
DropPlacedBackpacksOnExplosion: false
启用可放置背包后,玩家可以将背包物品放置在世界中。已放置的背包使用渲染的物品展示实体,并且可以像物理对象一样进行交互。
渲染变换可以进行自定义:
PlacedBackpackRender:
Offset:
X: 0.5
Y: 0.4
Z: 0.4
Rotation:
X: 0.0
Y: 0.0
Z: 0.0
Scale:
X: 1.0
Y: 1.0
Z: 1.0
这在需要使用自定义资源包模型且模型在方块上显示位置不同时非常有用。
共享背包
SharedBackpacks:
Enabled: true
MaxSharedUsers: 5
共享背包允许多名玩家处理同一个背包数据。最大共享用户数可以根据服务器的平衡性和管理需求进行调整。
背包类型配置
背包类型在 BackpackTypes: 下定义。
示例:
BackpackTypes:
Leather:
Rows: 2
UpgradeSlots: 1
CraftingRecipe:
Type: Crafting
Pattern:
- "SLS"
- "WCW"
- "LLL"
Ingredients:
L: LEATHER
S: STRING
C: CHEST
W: WHITE_WOOL
OutputMaterial: PLAYER_HEAD
DisplayName: "&6Leather Backpack"
Lore:
- "&7Leather Backpack that can carry 2 rows of items."
- "{backpackContents}"
- "{backpackId}"
- "{installedModules}"
CustomModelData: 1001
DefaultColor: 11100488
SkullData: <base64 skull texture>
每种背包类型可以定义:
Rows - 存储行数
UpgradeSlots - 模块槽位数
CraftingRecipe - 合成或锻造配方
OutputMaterial - 用于制作背包的物品材质
DisplayName - 物品显示名称
Lore - 支持占位符的物品描述
CustomModelData - 可选的资源包模型数据
DefaultColor - 受支持的视觉效果使用的颜色值
SkullData - 玩家头颅背包的 base64 头颅纹理数据
合成配方
标准合成配方使用 3x3 图案:
CraftingRecipe:
Type: Crafting
Pattern:
- "III"
- "IBI"
- "III"
Ingredients:
I: IRON_INGOT
B: BACKPACK:Leather
OutputMaterial: PLAYER_HEAD
多种配方变体
背包可以有多个替代配方:
CraftingRecipe:
- "1":
Type: Crafting
Pattern:
- "III"
- "IBI"
- "III"
Ingredients:
I: IRON_INGOT
B: BACKPACK:Leather
- "2":
Type: Crafting
Pattern:
- " I "
- "IBI"
- " I "
Ingredients:
I: IRON_INGOT
B: BACKPACK:Copper
玩家可以使用以下命令预览特定变体:
/backpack recipe backpack Iron 2
锻造配方
背包类型也可以使用锻造配方:
CraftingRecipe:
Type: Smithing
Template: NETHERITE_UPGRADE_SMITHING_TEMPLATE
Base: BACKPACK:Diamond
Addition: NETHERITE_INGOT
OutputMaterial: PLAYER_HEAD
这对于从钻石到下界合金等等级升级非常有用。
配方原料令牌
配方原料支持原版 Bukkit 材质名称和 ModularPacks 特定的令牌。
| Token |
Description |
Example |
BACKPACK:<TypeId> |
需要给定类型的 ModularPacks 背包 |
BACKPACK:Leather |
<TYPE>_BACKPACK |
备用背包令牌格式 |
DIAMOND_BACKPACK |
MODULE:<UpgradeId> |
需要 ModularPacks 模块物品 |
MODULE:Magnet |
UPGRADE:<UpgradeId> |
备用模块令牌格式 |
UPGRADE:Crafting |
这些令牌使得配方能够要求实际的 ModularPacks 物品,而不仅仅是原版材料。
升级配置
模块在 Upgrades: 下定义。
示例:
Upgrades:
Magnet:
Enabled: true
Toggleable: true
Range: 6.0
MaxItemsPerTick: 32
CraftingRecipe:
Type: Crafting
Pattern:
- "L R"
- "ITI"
- "III"
Ingredients:
L: LAPIS_LAZULI
R: REDSTONE
I: IRON_INGOT
T: MODULE:CraftingTemplate
OutputMaterial: LEVER
Glint: true
DisplayName: "&aMagnet Upgrade"
Lore:
- "&7Automatically picks up items in a radius of the backpack."
- "{toggleState}"
- "{moduleActions}"
- "{magnetRange}"
CustomModelData: 2002
常见的升级设置包括:
Enabled - 模块是否可用
Toggleable - 模块是否可以开启或关闭
SecondaryAction - 模块是否有右键操作
CraftingRecipe - 用于制作模块的配方
OutputMaterial - 模块物品使用的材质
Glint - 物品是否应显示附魔光泽
DisplayName - 模块物品名称
Lore - 模块物品描述
CustomModelData - 可选的资源包模型数据
一些模块还有自己的设置,例如磁铁范围、喂食阈值、唱片机播放模式、泵的方向或经验泵行为。
语言文件
语言文件:
plugins/ModularPacks/lang/en_us.yml
语言文件控制面向用户的模块操作文本、切换标签、模式标签、占位符扩展以及放置背包的消息。
这让你无需编辑源代码即可更改插件的语气。你可以使消息简洁明了、更具风格化,或与你的服务器主题相匹配。
常见占位符
背包描述占位符:
| Placeholder |
Description |
{backpackContents} |
替换为当前已用槽位和物品数量,或为空消息 |
{backpackId} |
显示背包 UUID |
{installedModules} |
显示已安装模块的信息 |
模块描述占位符:
| Placeholder |
Description |
{moduleActions} |
默认模块交互说明 |
{moduleActionsFeeding} |
喂食模块说明 |
{moduleActionsFluidTank} |
流体罐模块说明 |
{moduleActionsExperienceTank} |
经验罐说明 |
{moduleActionsJukebox} |
唱片机模块说明 |
{moduleActionsRestock} |
补货模块说明 |
{moduleActionsAutocrafting} |
自动合成模块说明 |
{moduleActionsPump} |
泵模块说明 |
{moduleActionsExpPump} |
经验泵模块说明 |
{toggleState} |
启用或禁用的切换文本 |
{magnetRange} |
磁铁范围显示 |
{feedingMode} |
喂食模式显示 |
{containedFluid} |
罐体或存储显示文本 |
{jukeboxMode} |
唱片机播放模式 |
{restockThreshold} |
补货阈值值 |
{pumpMode} |
泵或经验泵模式 |
{expPumpMending} |
经验泵修复状态 |
放置背包消息
放置背包消息也是可配置的:
backpack:
placement:
disabled: "&cPlaceable backpacks are disabled."
no_permission: "&cYou don't have permission to place backpacks."
open:
no_permission: "&cYou don't have permission to open backpacks."
locked: "&cThis backpack is currently open by {player}."
pickup:
no_permission: "&cYou don't have permission to pick up backpacks."
数据存储
ModularPacks 使用 SQLite 并将数据存储在:
plugins/ModularPacks/backpacks.db
重要表包括:
| Table |
Purpose |
backpacks |
存储背包元数据、所有者数据、内容、共享数据、排序锁定状态和自定义背包名称 |
backpack_modules |
存储已安装的模块、模块快照和模块状态 |
voided_items |
存储由虚空模块移除的可恢复物品数据 |
使用 SQLite 是为了让服务器管理员无需设置 MySQL 或其他外部数据库。该插件还启用了 SQLite 设置,如 WAL 模式和繁忙超时,以使正常使用更加流畅。
资源包支持
资源包是可选的。
默认情况下,ModularPacks 可以使用正常的 Minecraft 材质和玩家头颅。如果你想要自定义背包或模块的外观,请在 config.yml 中设置 CustomModelData 值,并在你的资源包中提供匹配的模型。
外观相关的配置字段:
OutputMaterial
CustomModelData
DisplayName
Lore
DefaultColor
SkullData
PlacedBackpackRender
这意味着插件首先可以作为服务器端的存储系统使用,之后可以在不更改核心背包数据的情况下进行视觉升级。
开发者 API
API
ModularPacks 包含一个供其他插件使用的公共 API。
外部插件可以使用该 API 来:
- 检查 ModularPacks 是否已加载
- 访问 ModularPacks 插件实例
- 注册自定义模块
- 注册自定义模块物品定义
- 按 ID 查找模块
- 按屏幕类型查找模块
- 检查玩家的活跃模块会话
- 获取活跃模块会话的背包 UUID
获取 API
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api == null) {
// ModularPacks 未加载或未就绪。
return;
}
你也可以使用:
ModularPacksAPI api = ModularPacksAPI.getInstance();
getAPI() 会先执行插件管理器检查,这对于软依赖集成通常更安全。
注册模块实现
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api != null) {
api.registerModule(new MyCustomModule());
}
这将仅注册模块行为。如果你希望模块可制作或通过 ModularPacks 的物品创建功能可用,请同时使用 UpgradeDef 进行注册。
使用物品定义注册模块
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api != null) {
MyCustomModule module = new MyCustomModule();
UpgradeDef def = new UpgradeDef(
"MyModule",
"&6My Custom Module",
Material.DIAMOND,
List.of("&7Custom functionality"),
1001,
false,
true,
true,
false,
ScreenType.GENERIC
);
api.registerModule(module, def);
}
模块 ID 与 UpgradeDef ID 必须匹配。ModularPacks 会验证这一点,以防止模块以其 ID 注册而其物品定义使用另一个 ID 的情况发生。
实现 IModule
自定义模块需实现:
public interface IModule {
String getModuleId();
ScreenType getScreenType();
boolean hasSession(Player player);
UUID getSessionBackpackId(Player player);
void open(ModularPacksPlugin plugin, Player player, UUID backpackId, String backpackType, UUID moduleId);
void handleClose(ModularPacksPlugin plugin, Player player, Inventory inventory);
boolean isValidInventoryView(InventoryView view);
String getDisplayName();
}
模块还可以重写:
default void updateResult(Inventory inventory) {}
default boolean isEnabled() { return true; }
这为自定义模块提供了一种一致的方式来打开屏幕、在关闭时保存状态、验证库存视图以及暴露显示名称。
插件依赖设置
如果你的插件需要 ModularPacks,请将其作为依赖项添加到你的 plugin.yml 中:
depend: [ModularPacks]
如果你的插件可以在没有 ModularPacks 的情况下运行,请使用软依赖:
softdepend: [ModularPacks]
然后在使用集成之前检查 ModularPacksAPI.getAPI()。
构建、发布和项目状态
从源码构建
克隆仓库并使用 Maven 进行构建:
git clone https://github.com/TooterTutor/ModularPacks.git
cd ModularPacks
mvn -DskipTests package
编译后的 jar 文件将生成在:
target/modularpacks-<version>.jar
项目状态
ModularPacks 正在积极开发中。随着插件的成熟,配置键、模块行为和 API 细节可能会发生变化。服务器管理员应在重大更新前备份 plugins/ModularPacks/backpacks.db。
致谢
由 TooterTutor 创建。
灵感来源于模组化的、可升级的背包概念,但它是作为 Paper 插件构建的,拥有自己的存储模型、管理工具、配置系统和扩展 API。
ModularPacks
ModularPacks is a Paper plugin that adds physical, upgradeable backpacks to Minecraft servers.
Instead of treating backpacks like another command-based player vault, ModularPacks makes the backpack an actual item. Players carry it, open it, upgrade it, place it, share it, and build around it like a real part of the world. The goal is to bring a modded-style backpack experience to Paper servers while keeping the server playable for vanilla clients.
ModularPacks was heavily inspired by the feel of modded backpack systems, especially the idea of installable upgrades, but it is not meant to be a quick clone with a few settings changed. This plugin was built around Paper's server-side systems, PersistentDataContainer item identity, SQLite-backed storage, configurable recipes, admin recovery tools, and an API for custom module support.
Features
- Physical backpack items with persistent identity
- Configurable backpack tiers, sizes, recipes, names, lore, colors, skull textures, and custom model data
- Installable upgrade modules
- Placeable backpacks with configurable world rendering
- Shared backpacks with configurable shared-user limits
- SQLite-backed storage for backpack contents and installed module state
- Admin commands for giving, opening, listing, recovering, and changing backpacks
- Void recovery logging for accidentally voided items
- Optional update checker with in-game and console notifications
- Optional resource pack support through
CustomModelData
- Public API for registering custom modules from other plugins
Optional Resource Pack
Want custom backpack and module visuals? Use the official ModularPacks Resources pack for full model support and themed item rendering!
Resource pack link:
The plugin works without the pack, but the pack is recommended for the intended visual experience.
Requirements and installation
Requirements
- Paper
1.21.10+
- Java
21
- Maven, if building from source
ModularPacks is built against the Paper API and is intended for Paper-based servers. Other server platforms may work if they maintain Paper API compatibility, but Paper is the supported target.
Installation
-
Download the plugin jar.
-
Place it in your server's plugins/ folder.
-
Start the server once.
-
ModularPacks will generate its data folder and default files:
plugins/ModularPacks/config.yml
plugins/ModularPacks/lang/en_us.yml
plugins/ModularPacks/backpacks.db, created when backpack data is first used
-
Edit config.yml and lang/en_us.yml as needed.
-
Restart the server, or run:
/backpack reload
Design goals and backpack behavior
What makes ModularPacks different?
A lot of backpack plugins solve storage by adding a command, a virtual inventory, or a simple item that opens a menu. ModularPacks takes a different approach.
Each backpack has its own UUID stored on the item. The item itself is only the key. The contents, installed modules, module state, share data, and recovery information are stored safely in SQLite. This means a backpack can be renamed, upgraded, placed, opened by admins, recovered, or inspected without relying on fragile item lore alone.
The plugin is also designed around modules rather than one hardcoded backpack menu. A backpack can have upgrade slots, and modules can provide passive effects, custom screens, filters, pumps, tanks, crafting utilities, or other behavior. That structure is what makes the plugin expandable instead of just being a fixed-size storage menu.
In short: the inspiration is familiar, but the implementation is built specifically for Paper servers, server owners, admins, and developers who want something configurable and expandable.
How backpacks work
Every ModularPacks backpack stores persistent metadata on the item:
backpack_id - the UUID identity of the backpack
backpack_type - the configured type or tier, such as Leather, Iron, or Netherite
The actual contents are stored in the plugin database, not directly in the item lore. When a player opens a backpack, ModularPacks loads the contents and installed modules for that backpack_id. When the menu closes, the plugin saves the updated contents and module state back to SQLite.
This design helps prevent stale item data and makes admin recovery possible. It also allows linked or shared backpack behavior without trying to store an entire inventory inside item text.
Default backpack tiers
The default configuration includes these backpack types:
| Type |
Rows |
Upgrade Slots |
Leather |
2 |
1 |
Copper |
3 |
1 |
Iron |
4 |
2 |
Gold |
6 |
3 |
Diamond |
8 |
4 |
Netherite |
10 |
5 |
These are only defaults. You can edit existing types or add new ones through config.yml.
Default modules
Modules are configured under Upgrades: in config.yml. Each module can have its own recipe, display item, lore, custom model data, toggle behavior, and module-specific settings.
Default modules include:
Utility modules
Everlasting - makes a backpack indestructible
Magnet - pulls nearby items into the backpack
FluidTank - stores bucket-based fluids
ExperienceTank - stores and dispenses player experience
Feeding - automatically feeds the player using backpack contents
Void - voids filtered items while logging recoverable item data
Restock - restocks the player's inventory from backpack contents
Pump - moves buckets between the player and a Fluid Tank module
ExpPump - moves XP between the player and an Experience Tank module
Workstation modules
Crafting - portable crafting table
Smelting - portable furnace
Blasting - portable blast furnace
Smoking - portable smoker
Stonecutter - portable stonecutter
Anvil - portable anvil
Smithing - portable smithing table
Jukebox - portable jukebox with playlist behavior
Autocrafting - configurable automatic crafting behavior
Basic usage
Players can obtain backpacks through recipes or admin commands.
To open a backpack, right-click the backpack item.
Inside the backpack menu, players can interact with storage slots and installed modules. Module actions are shown in the module lore, so server owners can customize the instructions in the language file.
Common module interactions include:
- Left-click to open or configure a module
- Right-click to run a secondary action or cycle a mode
- Shift + left-click to toggle a toggleable module
- Shift + right-click to remove a module
The exact behavior depends on the module.
Commands and permissions
Commands
The base command is:
/backpack
Help
/backpack help
/backpack help <command>
Shows available commands based on the sender's permissions.
Give backpacks and modules
/backpack give type <typeId> [player] [amount]
/backpack give module <upgradeId> [player] [amount]
Examples:
/backpack give type Leather Steve 1
/backpack give module Magnet Steve 1
Preview recipes
/backpack recipe backpack <typeId> [variantId]
/backpack recipe module <upgradeId>
Examples:
/backpack recipe backpack Iron
/backpack recipe backpack Iron 2
/backpack recipe module Magnet
Recipe previews are useful for players because ModularPacks recipes can include backpack or module ingredients, not just vanilla materials.
List backpacks
/backpack list [playerName [menu] | unowned]
Examples:
/backpack list
/backpack list Steve
/backpack list Steve menu
/backpack list unowned
This allows admins to inspect stored backpack records, including backpacks owned by offline players if the server has cached their UUID.
If menu is added after a player name, ModularPacks opens a GUI showing that player's stored backpacks instead of printing the list to chat. This is useful when a player owns multiple backpacks and an admin needs to quickly inspect or open one of them.
Open backpacks as an admin
/backpack open <uuid>
/backpack open <player> <Type#N>
Example:
/backpack open Steve Netherite#1
This is useful for moderation, recovery, and support.
Change the backpack type in your hand
/backpack settype <typeId> [--force]
This changes the tier/type of the backpack currently held in your main hand.
Use this carefully. When changing a backpack to a smaller type, ModularPacks normally checks whether any items exist outside the new size and blocks the change if those slots are occupied.
The --force flag bypasses that protection and allows the backpack to be resized anyway. If the new type has fewer storage slots, any items beyond the new size may be truncated and lost. This should only be used by admins who understand the risk, preferably after checking the backpack contents or making a database backup.
Reload configuration
/backpack reload [config|lang|recipes|all]
Examples:
/backpack reload
/backpack reload config
/backpack reload lang
/backpack reload recipes
/backpack reload all
Reloads specific parts of ModularPacks without requiring a full server restart.
config reloads config.yml, backpack types, upgrades, placed backpack renders, and update checker settings.
lang reloads language files.
recipes reloads and re-registers backpack and module recipes.
all reloads everything.
Running /backpack reload with no argument behaves like all.
Recovery tools
/backpack recover backpack <player> <backpackUuid>
/backpack recover void <player|uuid> list [limit] [all]
/backpack recover void <player|uuid> <id|latest> [receiver]
The void recovery commands work with the voided_items database table. When the Void module deletes an item, ModularPacks stores enough item data for admins to recover it later.
Permissions
| Permission |
Default |
Description |
modularpacks.command |
true |
Allows use of the base /backpack command |
modularpacks.recipe |
true |
Allows recipe preview commands |
modularpacks.open |
true |
Allows players to open backpacks |
modularpacks.place |
true |
Allows players to place backpacks in the world |
modularpacks.pickup |
true |
Allows players to pick up placed backpacks |
modularpacks.reload |
op |
Allows reloading config, language, and recipes |
modularpacks.admin |
op |
Allows admin-level backpack tools |
modularpacks.update.notify |
op |
Receives update notifications when enabled |
Server owners should review these defaults before publishing a server. The player-facing permissions are enabled by default, while administrative permissions are restricted to operators.
Configuration and data
Configuration
Main configuration file:
plugins/ModularPacks/config.yml
The config is split into two main sections:
modularpacks: for global plugin behavior
BackpackTypes: and Upgrades: for backpack and module definitions
Global settings
Important global settings include:
modularpacks:
Enabled: true
ResizeGUI: true
AutoCloseOnTeleport: true
AllowShulkerBoxes: false
AllowBundles: false
BackpackInsertBlacklist: []
ResizeGUI controls whether backpack pages dynamically resize or keep a fixed size.
AutoCloseOnTeleport closes open backpack menus when a player teleports.
AllowShulkerBoxes and AllowBundles control whether nested storage items can be placed inside backpacks.
BackpackInsertBlacklist blocks specific materials from being inserted into backpacks. The Magnet module also respects this list.
Update checker
UpdateChecker:
Enabled: true
ShowChangeLog: true
CheckOnStartup: true
PeriodicCheck: true
CheckIntervalHours: 24
NotifyPermission: modularpacks.update.notify
ReleaseApiUrl: https://api.github.com/repos/tootertutor/ModularPacks/releases/latest
The update checker can notify console and permitted players when a new GitHub release is available. You can disable startup checks, periodic checks, changelog output, or the entire update checker.
Debug click logging
Debug:
ClickLog: false
When enabled, ModularPacks writes backpack and module inventory click or drag events to:
plugins/ModularPacks/click-events.log
This is mainly intended for debugging inventory sorting mods, unexpected GUI behavior, or possible dupe reports. Leave it disabled unless you are actively troubleshooting.
GUI materials
NavPageButtons: ARROW
NavBorderFiller: GRAY_STAINED_GLASS_PANE
UnlockedUpgradeSlotMaterial: WHITE_STAINED_GLASS_PANE
LockedUpgradeSlotMaterial: IRON_BARS
These settings control common menu items such as page buttons, border fillers, unlocked module slots, and locked module slots.
Placeable backpacks
Placeable: true
DropPlacedBackpacksOnExplosion: false
When placeable backpacks are enabled, players can place backpack items into the world. Placed backpacks use a rendered item display and can be interacted with like a physical object.
The render transform can be customized:
PlacedBackpackRender:
Offset:
X: 0.5
Y: 0.4
Z: 0.4
Rotation:
X: 0.0
Y: 0.0
Z: 0.0
Scale:
X: 1.0
Y: 1.0
Z: 1.0
This is useful when using custom resource pack models that need to sit differently on the block.
Shared backpacks
SharedBackpacks:
Enabled: true
MaxSharedUsers: 5
Shared backpacks allow multiple players to work with the same backpack data. The maximum number of shared users can be adjusted to fit your server's balance and moderation needs.
Backpack type configuration
Backpack types are defined under BackpackTypes:.
Example:
BackpackTypes:
Leather:
Rows: 2
UpgradeSlots: 1
CraftingRecipe:
Type: Crafting
Pattern:
- "SLS"
- "WCW"
- "LLL"
Ingredients:
L: LEATHER
S: STRING
C: CHEST
W: WHITE_WOOL
OutputMaterial: PLAYER_HEAD
DisplayName: "&6Leather Backpack"
Lore:
- "&7Leather Backpack that can carry 2 rows of items."
- "{backpackContents}"
- "{backpackId}"
- "{installedModules}"
CustomModelData: 1001
DefaultColor: 11100488
SkullData: <base64 skull texture>
Each backpack type can define:
Rows - number of storage rows
UpgradeSlots - number of module slots
CraftingRecipe - crafting or smithing recipe
OutputMaterial - item material used for the backpack
DisplayName - item display name
Lore - item lore with placeholder support
CustomModelData - optional resource pack model data
DefaultColor - color value used by supported visuals
SkullData - base64 skull texture data for player head backpacks
Crafting recipes
A standard crafting recipe uses a 3x3 pattern:
CraftingRecipe:
Type: Crafting
Pattern:
- "III"
- "IBI"
- "III"
Ingredients:
I: IRON_INGOT
B: BACKPACK:Leather
OutputMaterial: PLAYER_HEAD
Multiple recipe variants
Backpacks can have multiple alternative recipes:
CraftingRecipe:
- "1":
Type: Crafting
Pattern:
- "III"
- "IBI"
- "III"
Ingredients:
I: IRON_INGOT
B: BACKPACK:Leather
- "2":
Type: Crafting
Pattern:
- " I "
- "IBI"
- " I "
Ingredients:
I: IRON_INGOT
B: BACKPACK:Copper
Players can preview a specific variant with:
/backpack recipe backpack Iron 2
Smithing recipes
Backpack types can also use smithing recipes:
CraftingRecipe:
Type: Smithing
Template: NETHERITE_UPGRADE_SMITHING_TEMPLATE
Base: BACKPACK:Diamond
Addition: NETHERITE_INGOT
OutputMaterial: PLAYER_HEAD
This is useful for tier upgrades like Diamond to Netherite.
Recipe ingredient tokens
Recipe ingredients support vanilla Bukkit material names and ModularPacks-specific tokens.
| Token |
Description |
Example |
BACKPACK:<TypeId> |
Requires a ModularPacks backpack of the given type |
BACKPACK:Leather |
<TYPE>_BACKPACK |
Alternate backpack token format |
DIAMOND_BACKPACK |
MODULE:<UpgradeId> |
Requires a ModularPacks module item |
MODULE:Magnet |
UPGRADE:<UpgradeId> |
Alternate module token format |
UPGRADE:Crafting |
These tokens are what allow recipes to require actual ModularPacks items instead of only vanilla materials.
Upgrade configuration
Modules are defined under Upgrades:.
Example:
Upgrades:
Magnet:
Enabled: true
Toggleable: true
Range: 6.0
MaxItemsPerTick: 32
CraftingRecipe:
Type: Crafting
Pattern:
- "L R"
- "ITI"
- "III"
Ingredients:
L: LAPIS_LAZULI
R: REDSTONE
I: IRON_INGOT
T: MODULE:CraftingTemplate
OutputMaterial: LEVER
Glint: true
DisplayName: "&aMagnet Upgrade"
Lore:
- "&7Automatically picks up items in a radius of the backpack."
- "{toggleState}"
- "{moduleActions}"
- "{magnetRange}"
CustomModelData: 2002
Common upgrade settings include:
Enabled - whether the module is available
Toggleable - whether the module can be toggled on or off
SecondaryAction - whether the module has a right-click action
CraftingRecipe - recipe used to craft the module
OutputMaterial - material used for the module item
Glint - whether the item should have an enchanted glint
DisplayName - module item name
Lore - module item lore
CustomModelData - optional resource pack model data
Some modules also have their own settings, such as Magnet range, Feeding thresholds, Jukebox playback mode, Pump direction, or Exp Pump behavior.
Language file
Language file:
plugins/ModularPacks/lang/en_us.yml
The language file controls user-facing module action text, toggle labels, mode labels, placeholder expansions, and placed backpack messages.
This lets you change the plugin's tone without editing the source. You can make the messages clean and minimal, more stylized, or match the theme of your server.
Common placeholders
Backpack lore placeholders:
| Placeholder |
Description |
{backpackContents} |
Replaced with current used slots and item count, or an empty message |
{backpackId} |
Shows the backpack UUID |
{installedModules} |
Shows installed module information |
Module lore placeholders:
| Placeholder |
Description |
{moduleActions} |
Default module interaction instructions |
{moduleActionsFeeding} |
Feeding module instructions |
{moduleActionsFluidTank} |
Fluid Tank module instructions |
{moduleActionsExperienceTank} |
Experience Tank instructions |
{moduleActionsJukebox} |
Jukebox module instructions |
{moduleActionsRestock} |
Restock module instructions |
{moduleActionsAutocrafting} |
Autocrafting module instructions |
{moduleActionsPump} |
Pump module instructions |
{moduleActionsExpPump} |
Exp Pump module instructions |
{toggleState} |
Enabled or disabled toggle text |
{magnetRange} |
Magnet range display |
{feedingMode} |
Feeding mode display |
{containedFluid} |
Tank or storage display text |
{jukeboxMode} |
Jukebox play mode |
{restockThreshold} |
Restock threshold value |
{pumpMode} |
Pump or Exp Pump mode |
{expPumpMending} |
Exp Pump mending state |
Placed backpack messages
Placed backpack messages are also configurable:
backpack:
placement:
disabled: "&cPlaceable backpacks are disabled."
no_permission: "&cYou don't have permission to place backpacks."
open:
no_permission: "&cYou don't have permission to open backpacks."
locked: "&cThis backpack is currently open by {player}."
pickup:
no_permission: "&cYou don't have permission to pick up backpacks."
Data storage
ModularPacks uses SQLite and stores data in:
plugins/ModularPacks/backpacks.db
Important tables include:
| Table |
Purpose |
backpacks |
Stores backpack metadata, owner data, contents, sharing data, sorting lock state, and custom backpack name |
backpack_modules |
Stores installed modules, module snapshots, and module state |
voided_items |
Stores recoverable item data for items removed by the Void module |
SQLite is used so server owners do not need to set up MySQL or another external database. The plugin also enables SQLite settings such as WAL mode and a busy timeout to make normal server usage smoother.
Resource pack support
A resource pack is optional.
By default, ModularPacks can use normal Minecraft materials and player heads. If you want custom backpack or module visuals, assign CustomModelData values in config.yml and provide matching models in your resource pack.
Useful config fields for visuals:
OutputMaterial
CustomModelData
DisplayName
Lore
DefaultColor
SkullData
PlacedBackpackRender
This means the plugin can work as a server-side storage system first, then be visually upgraded later without changing the core backpack data.
Developer API
API
ModularPacks includes a public API for other plugins.
External plugins can use the API to:
- Check whether ModularPacks is loaded
- Access the ModularPacks plugin instance
- Register custom modules
- Register custom module item definitions
- Look up modules by ID
- Look up modules by screen type
- Check a player's active module session
- Get the backpack UUID for an active module session
Getting the API
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api == null) {
// ModularPacks is not loaded or not ready.
return;
}
You can also use:
ModularPacksAPI api = ModularPacksAPI.getInstance();
getAPI() performs a plugin manager check first, which is usually safer for soft-depend integrations.
Registering a module implementation
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api != null) {
api.registerModule(new MyCustomModule());
}
This registers the module behavior only. If you want the module to be craftable or available through ModularPacks item creation, register it with an UpgradeDef as well.
Registering a module with an item definition
ModularPacksAPI api = ModularPacksAPI.getAPI();
if (api != null) {
MyCustomModule module = new MyCustomModule();
UpgradeDef def = new UpgradeDef(
"MyModule",
"&6My Custom Module",
Material.DIAMOND,
List.of("&7Custom functionality"),
1001,
false,
true,
true,
false,
ScreenType.GENERIC
);
api.registerModule(module, def);
}
The module ID and the UpgradeDef ID must match. ModularPacks validates this so modules do not register under one ID while their item definition uses another.
Implementing IModule
Custom modules implement:
public interface IModule {
String getModuleId();
ScreenType getScreenType();
boolean hasSession(Player player);
UUID getSessionBackpackId(Player player);
void open(ModularPacksPlugin plugin, Player player, UUID backpackId, String backpackType, UUID moduleId);
void handleClose(ModularPacksPlugin plugin, Player player, Inventory inventory);
boolean isValidInventoryView(InventoryView view);
String getDisplayName();
}
Modules can also override:
default void updateResult(Inventory inventory) {}
default boolean isEnabled() { return true; }
This gives custom modules a consistent way to open screens, save state on close, validate inventory views, and expose display names.
Plugin dependency setup
If your plugin requires ModularPacks, add it as a dependency in your plugin.yml:
depend: [ModularPacks]
If your plugin can run without ModularPacks, use a soft dependency:
softdepend: [ModularPacks]
Then check ModularPacksAPI.getAPI() before using the integration.
Building, publishing, and project status
Building from source
Clone the repository and build with Maven:
git clone https://github.com/TooterTutor/ModularPacks.git
cd ModularPacks
mvn -DskipTests package
The compiled jar will be created in:
target/modularpacks-<version>.jar
Project status
ModularPacks is actively being developed. Configuration keys, module behavior, and API details may evolve as the plugin matures. Server owners should back up plugins/ModularPacks/backpacks.db before major updates.
Credits
Created by TooterTutor.
Inspired by the idea of modded, upgradeable backpacks, but built as a Paper plugin with its own storage model, admin tools, configuration system, and extension API.
评论 0
登录后参与评分
还没有评论,来抢沙发吧