CustomGuiReworked

插件

· 作者 AMPEMETER

一个用于创建自定义 GUI 库存界面并具备数据存储功能的简单插件

0 本站下载 0 关注 更新于 1 个月前

最新 2.4.5 · 26.3 · Paper / Purpur

一键开服(送7天)

CustomGuiReworked — 基于骨架的 GUI 框架,适用于 Paper

可视化游戏内编辑器 · 5 种存储类型 · ItemsAdder 与 CraftEngine 方块 · 高性能存储 · 库就绪 API

CustomGuiReworked 是一个现代化的、基于骨架的 GUI 框架,适用于 Paper 26.2+ (Java 25)。在游戏中创建完全持久的自定义容器,将其绑定到自定义方块上,并作为库从你自己的插件中使用。无闪烁、无数据丢失、无重复物品。

Paper: 26.2.build.123+ | Java: 25 | 许可证: MIT


✨ 为什么选择 CustomGuiReworked?

  • ? 真正的游戏内编辑器 — /gui create <name> → 设置大小、骨架、设计、标题、存储、方块绑定、实时预览。所有内容即时保存。
  • ? 骨架系统 — 每个槽位都有一个定义行为的类型,而非启发式算法。
  • ? 5 种存储引擎 — 方块、个人、全局、团队、临时。从个人金库到共享银行应有尽有。
  • ⚡ 零延迟存储 — 内存缓存、异步合并写入(1000ms)、逐槽位差异比较、原子操作 tmp + ATOMIC_MOVE、自动保存 + 关闭/退出/关机时保证保存。
  • ? 自定义方块 — 右键点击 ItemsAdder 或 CraftEngine 方块即可打开 GUI。破坏方块会掉落内容并关闭查看者。无硬依赖。
  • ? 智能物品编解码器 — n1: NBTAPI(完整保真度)/ b2: Paper serializeAsBytes() + Base64(回退机制)/ b1: 只读旧版。标记的有效载荷在安装/移除 NBTAPI 后依然存活。
  • ? 库就绪 API — 通过 Bukkit Services 获取 GuiService + GuiBuilder + 事件。作为 compileOnly 使用,切勿阴影打包(shade)。
  • ? Skript 与 Denizen — on cgui open/close/click/drag 事件、条件、表达式、<cgui.*> 标签。

? 可视化编辑器

/gui create <name>  # 创建并打开编辑器
/gui edit <name>    # 编辑现有 GUI
/gui open <name>    # 以玩家身份打开
/gui                # 带有分页和聊天搜索的管理菜单

编辑器屏幕:

  • 大小 — 9 / 18 / 27 / 36 / 45 / 54,调整大小时现有槽位保留
  • 骨架 — 单击循环切换 Design → Container → Craft → Result → Fuel,Shift+单击强制设为 Design
  • 设计 — 从你的背包拖拽物品,Shift+单击,右键清除,双击被阻止以防止盗窃
  • 标题 — 聊天提示,输入 /cancel 中止
  • 存储 — 选择类型
  • 自定义方块 — 绑定/解绑 my_block 或 craftengine:my_block
  • 预览 / 删除 — 以玩家视角即时预览

无窗口闪烁——所有更新均为就地完成。


? 数据存储

类型 范围 存储位置 用例
BLOCK 单个方块 <world>/CustomGuiReworked/blocks/<x/16>_<z/16>.json 箱子、熔炉、ATM
PERSONAL 每位玩家 data/players/<player>_<table>.json 个人金库、设置
GLOBAL 全服务器 data/globals/<table>.json 全球银行、拍卖行
TEAM 记分板团队 data/teams/<team>_<table>.json 氏族存储
TEMPORARY 会话期间 不持久化,关闭时归还物品 表单、临时菜单

保存机制:

  • 写入基于差异——仅重新序列化受影响的槽位(1 次 NBT 调用,而非 54 次)
  • 点击爆发 → 一次磁盘写入(合并 storage.coalesce-ms: 1000)
  • 在关闭 / 退出 / WorldUnload / 关机时执行 saveNow() ——永不丢失
  • 写入失败保持脏状态,并在 5 秒后重试
  • 方块的区域文件会被缓存,并在 WorldUnloadEvent 时刷新

? 槽位骨架

类型 玩家可操作 是否持久化 用途
DESIGN 仅点击(按钮) ❌ 装饰,标记 PDC 以防止双击盗窃
CONTAINER 放入 / 取出 ✅ 存储
CRAFT 放入 / 取出 ✅ 配方原料(语义层面)
RESULT 仅取出 ❌ 结果 / 商店商品——无法通过任何方法插入(光标、数字键、副手交换、拖拽)
FUEL 放入 / 取出 ✅ 燃料(语义层面)

Shift+单击 行为类似原版但更安全:从 GUI → 玩家背包是原生操作;从玩家 → GUI 仅填充 CONTAINER/CRAFT/FUEL,跳过 DESIGN/RESULT。
双击 正常收集相似物品,但由于隐藏的 PDC 标记和 maxStackSize == amount,DESIGN 物品的 isSimilar == false。


? 命令

命令 权限
/gui — 管理菜单 cgui.command
/gui create <name> cgui.create
/gui edit <name> cgui.edit
/gui open <name> [player] cgui.open
/gui delete <name> cgui.delete
/gui list —
/gui command add <slot> <gui> [delay] <command...> cgui.command
/gui command get <slot> <gui> [index] cgui.command
/gui command delete <slot> <gui> <index> cgui.command
/gui reload cgui.reload

槽位命令中的占位符:%player%, %slot%

tables/shop.yml 中的示例:

commands:
  - slot: 10
    command: "give %player% diamond 1"
    delay: 5

? 自定义方块 — ItemsAdder & CraftEngine

  • 通过编辑器或 API 绑定:myblocks:shop, craftengine:atm
  • 右键点击方块 → 打开带有 BLOCK 存储的 GUI (world:x,y,z)
  • 破坏方块 → 先同步打开的 GUI 到区域缓存(防重复:光标上的物品不会掉落两次)→ 物品掉落 → 删除区域数据
  • 查找 O(1),不区分大小写,冒号 : 后支持后缀回退
  • Hook 通过反射加载——无硬依赖,如果插件缺失也不会崩溃
CustomGuiAPI.registerBlockGui("itemsadder:ruby_ore", "shop");
CustomGuiAPI.registerBlockGui("craftengine:atm", "bank");

⚡ 性能与安全

  • <50ms GUI 打开(异步预加载,已修复过时请求竞态问题)
  • ~2-5KB 每个 GUI 占用的内存
  • 1000+ 并发查看者(每人拥有独立的库存实例,基于差异的保存不会覆盖彼此的槽位)
  • 无重复: DESIGN 受 PDC + maxStackSize + 下一刻救援机制保护,RESULT 从所有方向被阻止,方块破坏时在下落前同步查看者,关闭前最终刷写前关闭所有菜单
  • 无损坏: 所有文件通过唯一的 .tmp-<uuid> + ATOMIC_MOVE 写入,启动时清理孤立的临时文件
  • 无卡顿: 单个 CguiStorageIO 线程,主线程从不接触磁盘

配置文件 plugins/CustomGuiReworked/config.yml:

storage:
  autosave-ticks: 600
  max-cached-views: 10000
  coalesce-ms: 1000
commands:
  execute-as-op: false
integration:
  skript: true
  denizen: true

? 开发者 API

完整指南: GitHub API.md 和 MECHANICS.md

Gradle (Kotlin)

repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
    maven("https://jitpack.io")
}
dependencies {
    compileOnly("io.papermc.paper:paper-api:26.2.build.123-stable")
    compileOnly("com.github.amper24:CustomGuiReworked:2.3.0")
}

Gradle (Groovy)

repositories {
    maven { url = 'https://repo.papermc.io/repository/maven-public/' }
    maven { url = 'https://jitpack.io' }
}
dependencies {
    compileOnly 'io.papermc.paper:paper-api:26.2.build.123-stable'
    compileOnly 'com.github.amper24:CustomGuiReworked:2.3.0'
}

Maven

<repositories>
  <repository><id>papermc</id><url>https://repo.papermc.io/repository/maven-public/</url></repository>
  <repository><id>jitpack.io</id><url>https://jitpack.io</url></repository>
</repositories>
<dependencies>
  <dependency>
    <groupId>com.github.amper24</groupId>
    <artifactId>CustomGuiReworked</artifactId>
    <version>2.3.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

plugin.yml:

softdepend: [CustomGuiReworked]

用法

// Fluent builder
Gui gui = GuiBuilder.named("shop")
        .title("§6Shop")
        .size(27)
        .storage(StorageType.PERSONAL)
        .slot(10, SlotType.CONTAINER)
        .slots(List.of(11,12,13), SlotType.CONTAINER)
        .slot(22, SlotType.RESULT)
        .design(0, new ItemStack(Material.BLACK_STAINED_GLASS_PANE))
        .command(22, "give %player% diamond 1", 5)
        .blockId("myblocks:shop")
        .build();
CustomGuiAPI.registerGui(gui, true); // custom/shop.yml, survives restart

// Open
CustomGuiAPI.openGui(player, "shop");
CustomGuiAPI.openGui(player, "shop", StorageType.TEMPORARY); // override
CustomGuiAPI.openGui(player, "shop", blockLocation); // BLOCK

// Storage without GUI
List<ItemStack> items = CustomGuiAPI.readStorage(StorageType.GLOBAL, "", "shop.yml");
CustomGuiAPI.writeStorage(StorageType.GLOBAL, "", "shop.yml", items);

// Events
@EventHandler
public void onOpen(GuiOpenEvent e) {
    if (!e.getPlayer().hasPermission("shop.use")) e.setCancelled(true);
}
@EventHandler
public void onClick(GuiSlotClickEvent e) {
    if (e.getSlotType() == SlotType.RESULT && e.getClick().isRightClick()) {
        e.setInteractionCancelled(true); // cancel both commands and vanilla click
    }
}

API 表面: GuiService, CustomGuiAPI, Gui, GuiBuilder, SlotType, StorageType, SlotCommand, GuiOpenEvent, GuiCloseEvent, GuiSlotClickEvent, GuiDragEvent, block API, storage API.


? Skript & Denizen

Skript:

on cgui open:
    broadcast "%event-player% opened %event-string%"

on cgui click:
    if event-string is "shop":
        if event-number is 22:
            cancel event

open cgui "shop" to player with storage temporary
close cgui of player

Denizen:

on cgui click:
    - if <context.gui> == shop:
        - if <context.slot> == 22:
            - determine cancelled

on cgui drag:
    - announce "drag over <context.slots>"

Tags: <cgui.guis>, <cgui.exists[shop]>, <cgui.size[shop]>, <cgui.title[shop]>, <cgui.storage[shop]>, <cgui.open_of[<player>]>


? 依赖

Plugin Version Required
Paper 26.2+ (Java 25) ✅
NBTAPI 2.16+ ❌ recommended for full NBT
ItemsAdder 4.x ❌ for custom blocks
CraftEngine 26.x ❌ for custom blocks
Skript 2.14+ ❌
Denizen 1.3.x ❌

? 安装

  1. 从 Modrinth / GitHub Releases 下载 CustomGuiReworked-x.y.z.jar
  2. (推荐)安装 NBTAPI
  3. 放入 plugins/ 并启动服务器
  4. 配置自动创建:
    • plugins/CustomGuiReworked/config.yml
    • lang/en.yml, ru.yml
    • tables/ (editor GUIs), custom/ (API GUIs), data/ (players/teams/globals)
    • <world>/CustomGuiReworked/blocks/ (block regions)

? 链接

  • GitHub:
  • Full API Guide:
  • Mechanics Deep Dive:
  • Issues:
  • JitPack:

? 许可证

MIT — see LICENSE file.

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源