ModularPacks

插件

· 作者 TooterTutor

为 Paper 服务器带来模组风格的背包系统,包含可升级的实体背包物品、可配置的模块、SQLite 存储、共享功能以及放置与回收工具。

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

最新 2.7.7 · 26.3 · Paper

一键开服(送7天)

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 是唯一受支持的目标平台。

安装

  1. 下载插件 jar 文件。

  2. 将其放入服务器的 plugins/ 文件夹中。

  3. 启动服务器一次。

  4. ModularPacks 将生成其数据文件夹和默认文件:

    • plugins/ModularPacks/config.yml
    • plugins/ModularPacks/lang/en_us.yml
    • plugins/ModularPacks/backpacks.db,在首次使用背包数据时创建
  5. 根据需要编辑 config.yml 和 lang/en_us.yml。

  6. 重启服务器,或运行:

/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。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源