Introduction
LibreUI is my first publicly available plugin resource. LibreUI is a library plugin which gives developers an open source , robust, highly abstract, and easy to use API to create, and display written book based GUIs. LibreUI uses Maven for dependency management and building, and uses the SemVer 2.0.0 versioning scheme. The initial release version (1.1.0) supports all Spigot versions from 1.7.2 to 1.11.2, and may, but does not guarantee to support future versions without updates. The SemVer 2.0.0 versioning scheme was adpoted after the initial development began, therefore 1.0.X will be treated as development versions, as opposed to 0.X.X.
Minecraft written book pages are based off of chat components . LibreUI uses the BungeeCord-Chat API , made by md_5 and is only packaged with Spigot. This unfortunately sacrifices CraftBukkit compatibility, but compatibility can easily be retained by shading the API, in CraftBukkit specific builds. I prefer this option to making my own API, as developers already familiar with this API doesn't have to learn a new similar API, making the LibreUI learning curve easier. LibreUI caches books and pages to improve speed, when displaying similar elements multiple times.
LibreUI in bullet points
Examples using LibreUI
Inventories vs Books
Inventory based GUIs and book based GUIs have a lot of differences, and individual advantages and disadvantages, which you must take into consideration before choosing which you should use. Here's a somewhat comprehensive list of comparisons of their advantages and disadvantages.
How do I use it?
Note: Before starting to use LibreUI, please read the essential Java documentation first.
To use LibreUI you must first download and install it on your server. Unless you have any special needs the plugin should work out-of-the-box. To use it in your plugins, you must add it as a dependency in your plugin.yml file. To access the resource in your plugin code, you must either import the JAR file, or:
Changelog
Links and resources
GitLab repository
BungeeCord-Chat API documentation
LibreUI is my first publicly available plugin resource. LibreUI is a library plugin which gives developers an open source , robust, highly abstract, and easy to use API to create, and display written book based GUIs. LibreUI uses Maven for dependency management and building, and uses the SemVer 2.0.0 versioning scheme. The initial release version (1.1.0) supports all Spigot versions from 1.7.2 to 1.11.2, and may, but does not guarantee to support future versions without updates. The SemVer 2.0.0 versioning scheme was adpoted after the initial development began, therefore 1.0.X will be treated as development versions, as opposed to 0.X.X.
Minecraft written book pages are based off of chat components . LibreUI uses the BungeeCord-Chat API , made by md_5 and is only packaged with Spigot. This unfortunately sacrifices CraftBukkit compatibility, but compatibility can easily be retained by shading the API, in CraftBukkit specific builds. I prefer this option to making my own API, as developers already familiar with this API doesn't have to learn a new similar API, making the LibreUI learning curve easier. LibreUI caches books and pages to improve speed, when displaying similar elements multiple times.
LibreUI in bullet points
- Free! LibreUI is 100% free of cost
- Open sourced under the Apache License 2.0 license
- A library for developer to create and display book GUIs
- Extremely easy for developers to learn and use
- Stable. The API does not mutate
- Decently documented
- Highly compatible. Supports all versions from 1.7.2 to 1.11.2
- Based on, and fully supports chat components for pages
- Extensible, other plugins can implement specific behavior
- Very fast and efficient
Examples using LibreUI
Spoiler: Images
Showcasing the book from the code examples. Video by Rrwery
Inventories vs Books
Inventory based GUIs and book based GUIs have a lot of differences, and individual advantages and disadvantages, which you must take into consideration before choosing which you should use. Here's a somewhat comprehensive list of comparisons of their advantages and disadvantages.
Spoiler: Updating elements
Inventories:
Books:
Inventories are index based, making updating elements really easy, because you can update only the element you want to update. This makes inventories the ideal choice if you need to display dynamically updating data.Click to expand...
Books are compiled whole, requiring them to be recompile each time a modification is made, making it quite expensive to update. Therefore books should only display static data, or snapshots of data., not dynamically updating data. LibreUI does use caching to make recompiling less expensive, but it should still be avoided.
Note: You might be able to display dynamic data using hover events in the page(s).Click to expand...
Spoiler: Pagination
Inventories:
Books:
Implementing pagination with inventories is a more cumbersome and time consuming process, than with book. Additional to that switching between pages feels laggy, since the client must wait for the server, before the switch is done. This applies to localhost servers as well, but is more noticeable on online servers.Click to expand...
Pagination with books is naturally really easy to implement. Aside from being easy to use, click events on text can be used to skip to specific pages, and unlike inventories switching pages is instant on the client, since it already knows the contents of the book.Click to expand...
Spoiler: Information
Inventories:
Books:
With inventories you can easily display item information, and patterns such as craftin patterns, however displaying text based information can be both cumbersome to read, and to navigate navigate around. Additionally inventories can in some cases have a more appealing look, as they are in fact able to display item stacks.Click to expand...
Books display information in a purely text based, with various formatting options. Additional information can be applied to text using HoverEvent s. Check out the HoverEvent class from the BungeeCord Chat API for more information.Click to expand...
Spoiler: Code execution
Executing code is rather trivial for both options. For inventories you can listen for when the player interacts with a specific item stack, and the same can be achieved with books using the RUN_COMMAND action with the ClickEvent class. However this does have restrictions with the vanilla command spam throttle, and is limited to only registered commands, whereas inventories doesn't have these restrictions. Additional item stacks can be interacted with in multiple ways, allowing for multiple different actions per item stack.Click to expand...
How do I use it?
Note: Before starting to use LibreUI, please read the essential Java documentation first.
To use LibreUI you must first download and install it on your server. Unless you have any special needs the plugin should work out-of-the-box. To use it in your plugins, you must add it as a dependency in your plugin.yml file. To access the resource in your plugin code, you must either import the JAR file, or:
- Clone the project
- Install it locally with Maven
- Add it as a dependency in your plugin's pom.xml file.
Spoiler: Code examples
Once the plugin is installed and set up in your project you can access LibreUI using:
To display a book to a player you may use the following code:
Creating a book instance is easy using the Book.Builder class:
Notice that the Book.Builder object must be constructed with a mandatory "front page", this it to assure all Book instances have at least 1 page. The other pages are optional. I also show a variety of possible ways to create chat components, using the BungeeCord Chat API from Spigot by md_5. Also take note that the Page class have some static factory methods to create instances from: BaseComponent, ComponentBuilder, and BaseComponent array objects.
Code (Text):
LibreUI#getAccessor()
Code (Text):
LibreUI.getAccessor().openBook(player, book)
Code (Text):
Book exampleBook = new Book
.Builder(Page.newInstance(new TextComponent("First page")))
.addPage(Page.newInstance(TextComponent.fromLegacyText("§cSecond page")))
.addPage(Page.newInstance(new ComponentBuilder("Third page")
.strikethrough(true)
.color(ChatColor.GOLD)))
.addPage(Page.newInstance(new ComponentBuilder("Look at me!")
.event(new HoverEvent(HoverEvent.Action.SHOW_TEXT,
new BaseComponent[] {
new TextComponent("Hi there!")
}))
.color(ChatColor.AQUA)))
.addPage(Page.newInstance(new ComponentBuilder("Click me to go to the first page")
.event(new ClickEvent(ClickEvent.Action.CHANGE_PAGE, "1"))
.color(ChatColor.AQUA)))
.build();
.Builder(Page.newInstance(new TextComponent("First page")))
.addPage(Page.newInstance(TextComponent.fromLegacyText("§cSecond page")))
.addPage(Page.newInstance(new ComponentBuilder("Third page")
.strikethrough(true)
.color(ChatColor.GOLD)))
.addPage(Page.newInstance(new ComponentBuilder("Look at me!")
.event(new HoverEvent(HoverEvent.Action.SHOW_TEXT,
new BaseComponent[] {
new TextComponent("Hi there!")
}))
.color(ChatColor.AQUA)))
.addPage(Page.newInstance(new ComponentBuilder("Click me to go to the first page")
.event(new ClickEvent(ClickEvent.Action.CHANGE_PAGE, "1"))
.color(ChatColor.AQUA)))
.build();
Changelog
Spoiler: 1.0.0
Initial development version.
All 1.0.X versions are development versions.
All 1.0.X versions are development versions.
Spoiler: 1.0.1-1.0.3
1.0.1 - Fixed issue with SimplePage#newInstance(BaseComponent...)
1.0.2 - Made BookSerializer include empty author and title tags, newer versions require those.
1.0.3 - Made PageSerializer handle different versions of the BungeeCord Chat API more robust.
1.0.2 - Made BookSerializer include empty author and title tags, newer versions require those.
1.0.3 - Made PageSerializer handle different versions of the BungeeCord Chat API more robust.
Spoiler: 1.0.4
Fixed SimplePage#getBackingComponent leaking its real backing component.
Spoiler: 1.0.5
Fixed PageSerializer not serializing newline (\n) characters correctly with backing components without formatting.
Spoiler: 1.0.6
Fixed pom.xml not setting the used Java version correctly.
Spoiler: 1.0.7
Made Book more robust, and fixed some methods not encapsulating Pages.
Spoiler: 1.0.8
Moved static factory methods from SimplePage to Page.
Fixed proper encapsulation of backing components in the static factory methods.
Improved documentation. Replaced {@code } tags with <tt> tags.
Fixed proper encapsulation of backing components in the static factory methods.
Improved documentation. Replaced {@code } tags with <tt> tags.
Spoiler: 1.0.9
Removed redundant Objects#requireNonNull checks.
Fixed Version#newInstance not accepting 0 major versions.
Fixed Version#newInstance not accepting 0 major versions.
Spoiler: 1.1.0
Initial release version.
Spoiler: 1.2.0
Added support for creating Books from JSON representations.
Links and resources
GitLab repository
BungeeCord-Chat API documentation
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.8, 1.9, 1.10
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
LibreUI is a free Minecraft Java mod. Compatible with Minecraft 1.8, 1.9, 1.10, 1.11. Downloaded 366 times (via Spigot). Download it and open it directly in the game.