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 |
❌ |
? 安装
- 从 Modrinth / GitHub Releases 下载
CustomGuiReworked-x.y.z.jar
- (推荐)安装 NBTAPI
- 放入
plugins/ 并启动服务器
- 配置自动创建:
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.
CustomGuiReworked — Skeleton GUI Framework for Paper
Visual in-game editor · 5 storage types · ItemsAdder & CraftEngine blocks · High-performance storage · Library-ready API
CustomGuiReworked is a modern, skeleton-based GUI framework for Paper 26.2+ (Java 25). Create fully persistent custom inventories in-game, bind them to custom blocks, and use them as a library from your own plugins. No flicker, no data loss, no dupe.
Paper: 26.2.build.123+ | Java: 25 | License: MIT
✨ Why CustomGuiReworked?
- ? True in-game editor —
/gui create <name> → size, skeleton, design, title, storage, block bindings, live preview. Everything saves instantly.
- ? Skeleton system — every slot has a type that defines behavior, not heuristics.
- ? 5 storage engines — block, personal, global, team, temporary. From personal vaults to shared banks.
- ⚡ Zero-lag storage — in-memory cache, async coalesced writes (1000ms), per-slot diff, atomic
tmp + ATOMIC_MOVE, autosave + guaranteed save on close/quit/shutdown.
- ? Custom blocks — right-click ItemsAdder or CraftEngine block to open GUI. Breaking drops contents and closes viewers. No hard dependencies.
- ? Smart item codec —
n1: NBTAPI (full fidelity) / b2: Paper serializeAsBytes() + Base64 (fallback) / b1: legacy read-only. Tagged payloads survive installing/removing NBTAPI.
- ? Library-ready API —
GuiService via Bukkit Services + GuiBuilder + events. Use as compileOnly, never shade.
- ? Skript & Denizen —
on cgui open/close/click/drag, conditions, expressions, <cgui.*> tags.
? Visual Editor
/gui create <name> # create + open editor
/gui edit <name> # edit existing
/gui open <name> # open as player
/gui # management menu with pagination & chat search
Editor screens:
- Size — 9 / 18 / 27 / 36 / 45 / 54, existing slots survive resize
- Skeleton — click cycles
Design → Container → Craft → Result → Fuel, shift-click forces Design
- Design — drag items from your inventory, shift-click, right-click clears, double-click blocked to prevent theft
- Title — chat prompt,
/cancel to abort
- Storage — choose type
- Custom blocks — bind/unbind
my_block or craftengine:my_block
- Preview / Delete — instant preview as player sees it
No window flicker — all updates are in-place.
? Data Storage
| Type |
Scope |
Where it lives |
Use case |
BLOCK |
one block |
<world>/CustomGuiReworked/blocks/<x/16>_<z/16>.json |
chests, furnaces, ATMs |
PERSONAL |
per-player |
data/players/<player>_<table>.json |
personal vaults, settings |
GLOBAL |
server-wide |
data/globals/<table>.json |
global bank, auction |
TEAM |
per scoreboard team |
data/teams/<team>_<table>.json |
clan storages |
TEMPORARY |
session |
nowhere, items returned on close |
forms, temporary menus |
How it saves:
- Write is diff-based — only touched slots are re-serialized (1 NBT call, not 54)
- Burst of clicks → one disk write (coalesce
storage.coalesce-ms: 1000)
saveNow() on close / quit / WorldUnload / shutdown — never lost
- Failed write stays dirty and retries after 5s
- Region files for blocks are cached, flushed on
WorldUnloadEvent
? Slot Skeleton
| Type |
Player can |
Persisted |
Purpose |
DESIGN |
only click (button) |
❌ |
decoration, PDC-marked to block double-click theft |
CONTAINER |
put / take |
✅ |
storage |
CRAFT |
put / take |
✅ |
recipe ingredient (semantic) |
RESULT |
only take |
❌ |
result / shop product — cannot be inserted by any method (cursor, number keys, offhand swap, drag) |
FUEL |
put / take |
✅ |
fuel (semantic) |
Shift-click is vanilla-like but safe: from GUI → player inventory is native; from player → GUI fills only CONTAINER/CRAFT/FUEL, skips DESIGN/RESULT.
Double-click collects similar items normally, but DESIGN items are isSimilar == false due to hidden PDC marker and maxStackSize == amount.
? Commands
| Command |
Permission |
/gui — management menu |
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 |
Placeholders in slot commands: %player%, %slot%
Example in tables/shop.yml:
commands:
- slot: 10
command: "give %player% diamond 1"
delay: 5
? Custom Blocks — ItemsAdder & CraftEngine
- Bind via editor or API:
myblocks:shop, craftengine:atm
- Right-click block → opens GUI with
BLOCK storage (world:x,y,z)
- Break block → open GUIs are synced to region cache first (anti-dupe: item on cursor won't drop twice) → items drop → region data deleted
- Lookup O(1), case-insensitive, suffix fallback after
:
- Hooks loaded reflectively — no hard dependency, no crash if plugin missing
CustomGuiAPI.registerBlockGui("itemsadder:ruby_ore", "shop");
CustomGuiAPI.registerBlockGui("craftengine:atm", "bank");
⚡ Performance & Safety
- <50ms GUI open (async preload, stale request race fixed)
- ~2-5KB per GUI in memory
- 1000+ concurrent viewers (each has own inventory instance, diff-based saves don't overwrite each other's slots)
- No dupe: DESIGN protected by PDC + maxStackSize + rescue on next tick, RESULT blocked from all directions, block break syncs viewers before drop, all menus closed on shutdown before final flush
- No corruption: all files written via unique
.tmp-<uuid> + ATOMIC_MOVE, orphaned tmps swept on startup
- No lag: single
CguiStorageIO thread, main thread never touches disk
Config 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
? Developer API
Full guide: GitHub API.md and 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]
Usage
// 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 surface: 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>]>
? Requirements
| 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 |
❌ |
? Installation
- Download
CustomGuiReworked-x.y.z.jar from Modrinth / GitHub Releases
- (Recommended) Install NBTAPI
- Put into
plugins/ and start server
- Config auto-creates:
plugins/CustomGuiReworked/config.yml
lang/en.yml, ru.yml
tables/ (editor GUIs), custom/ (API GUIs), data/ (players/teams/globals)
<world>/CustomGuiReworked/blocks/ (block regions)
? Links
- GitHub:
- Full API Guide:
- Mechanics Deep Dive:
- Issues:
- JitPack:
? License
MIT — see LICENSE file.
评论 0
登录后参与评分
还没有评论,来抢沙发吧