A Data-Driven GUI Library for Minecraft Mapmaking

AVAILABLE ON 26.1

Click here to download.

Also available on Modrinth.

For any queries, please use the issues section.

<p align = "center"> <img src="repo/gui.gif" width="350"> </p> <p align = "center"> <i>A GUI made entirely in-game in under 5 minutes.</i> </p>

Overview

This datapack allows mapmakers to create and maintain complex and robust item-based GUIs in-game. This is achieved by dragging and dropping items with custom SNBT in containers within a world, which the datapack can use to generate GUIs. It functions as a black box that treats each item as a graphical widget with predefined properties, and the user is not expected to modify any files. Two types of GUIs can be created:

• Block Entity GUIs: Placed at a fixed position and shared by all players. These are generated upon compilation.
• Chest Boat GUIs: Retrieved from a database and accessible anywhere by specified players only. These are obtained directly from the above by porting GUIs to players.

Benefits:

• SNBT standard for quick and easy creation of advanced item-based GUIs.
• Completely in-game workflow, with the entire datapack being a black box that the mapmaker can ignore.
• Robust design, support for multiplayer, including personalized GUIs, and no interference with player inventories.
• Complete documentation, in-game tutorial, and demos.
• 4+ years of continuous maintenance, built with the most up-to-date practices, and powering prominent maps officially featured on Minecraft Realms.

Installing

After this datapack has been added to the "datapacks" folder of a Minecraft world, /reload needs to be run in-game. A list of the datapack's commands is available via /function ajjgui:__help. By convention, all functions run directly by the mapmaker start with two underscores. Functions starting with a single underscore are aliases that do not give any feedback messages in the chat. These are meant to be used by the mapmaker as part of their own map's datapack. Any functions not listed here are internal and are not meant to be used.

| Function | Description | |:---------------------------------------------------------------|:------------------------------------------------------| | /function ajjgui:__compile | Compiles GUI | | /function ajjgui:__decompile | Decompiles nearest GUI | | /function ajjgui:__help | Displays datapack command list | | /function ajjgui:__install | Installs datapack | | /function ajjgui:__kit | Gives GUI design and compilation kit | | /function ajjgui:__license | Displays datapack license information | | /function ajjgui:__manual | Displays datapack manual link | | /function ajjgui:__open {player:<player_uuid>,id:<gui_id>} | Opens ported GUI | | /function ajjgui:__openself {id:<gui_id>} | Opens ported GUI of executing player | | /function ajjgui:__port {player:<player_uuid>,id:<gui_id>} | Ports nearest GUI | | /function ajjgui:__portself {id:<gui_id>} | Ports nearest GUI to executing player | | /function ajjgui:__reload | Reloads GUIs | | /function ajjgui:__tutorial | Displays GUI design and compilation tutorial | | /function ajjgui:__uninstall | Uninstalls datapack | | /function ajjgui:__version | Displays datapack version | | /function ajjgui:__widget/ | Gives GUI demo widgets | | /function ajjgui:_open {player:<player_uuid>,id:<gui_id>} | Runs /function ajjgui:__open without feedback | | /function ajjgui:_openself {id:<gui_id>} | Runs /function ajjgui:__openself without feedback | | /function ajjgui:_port {player:<player_uuid>,id:<gui_id>} | Runs /function ajjgui:__port without feedback | | /function ajjgui:_portself {id:<gui_id>} | Runs /function ajjgui:__portself without feedback | | /function ajjgui:_reload | Runs /function ajjgui:__reload without feedback |

The datapack can be installed by running /function ajjgui:__install at any location in the world, which generates a shulker box. This needs to be located in a loaded chunk and cannot be destroyed. The shulker box can be relocated by repeating the installation command elsewhere. Any updated versions of the datapack are automatically installed at the same location upon reloading the world. The datapack can be uninstalled using /function ajjgui:__uninstall, which removes all data associated with it from the world and decompiles any existing GUIs.

Creating a GUI

The datapack adopts the concept of graphical widgets, present in real-world user interfaces. Within the scope of Minecraft's item-based GUIs, and this datapack specifically, every item in a GUI corresponds to an interactive element (e.g., a button).

There are 8 types of GUI widgets available:

• Placeholder
• Button
• Counter
• Switch
• Radiobutton
• Itembin
• Itemslot
• Scrollbutton

An in-game tutorial on how to create a GUI is available via /function ajjgui:__tutorial. The tutorial provides the player with premade demo widgets to experiment with. Multiple examples are given, both here and in-game, to help provide a better understanding of their custom SNBT. The following section explains all the different types of widgets available and how they can be customized. Once obtained, these items can be placed inside shulker boxes, with each shulker box corresponding to a different GUI page. The shulker boxes can be arranged based on their page number and compiled to build a functional GUI in-game. This manual can be accessed with /function ajjgui:__manual.

List of GUI Widgets

[!TIP] Some of the following commands are too long to fit in the chat box and need to be executed using a command block.

[!IMPORTANT] For custom SNBT, it is important to check that the right data types are being used (e.g., {ajjgui:{exit:1b}} and not {ajjgui:{exit:1}}), that values are within the specified range (e.g., {ajjgui:{exit:1b}} and not {ajjgui:{exit:2b}}, where ajjgui.exit here can only be 0b or 1b). The GUI compiler is only capable of initializing required SNBT with default values and does not correct errors. While there are cases where errors in custom SNBT, such as incorrect data types, may be internally resolved by the datapack at later stages, this behavior is inconsistent and must not be assumed.

[!NOTE] The ajjgui.command, ajjgui.exit, ajjgui.fixed, ajjgui.lock, ajjgui.page, and ajjgui.relative SNBT are covered separately in later sections.

Placeholder

The placeholder is a widget that cannot be interacted with and is used to display an item.

| Item SNBT | Default | Type | |:------------------|:------------------------------------|:---------------| | ajjgui.fixed | 0b | Byte (Boolean) | | ajjgui.widget | Required ("placeholder" or N/A) | String |

Usage

/give @p <item_id>[minecraft:custom_data={ajjgui:{widget:"placeholder",<optional_ajjgui_snbt>}}]

Example

A placeholder:

/give @p minecraft:black_stained_glass_pane[minecraft:custom_data={ajjgui:{widget:"placeholder"}},minecraft:tooltip_display={hide_tooltip:1b}]

[!TIP] If a GUI slot is empty, it is set to a light gray stained glass pane placeholder with a hidden tooltip.

[!TIP] If the ajjgui.widget SNBT of any item is not specified, it is set to "placeholder" by default. Therefore, the entire ajjgui argument for any placeholder is optional.

Button

The button is a widget that changes the GUI page, exits the GUI and/or runs a GUI command when clicked. More information can be found in the following sections.

| Item SNBT | Default | Type | |:--------------------|:------------------------|:---------------| | ajjgui.command | N/A | String | | ajjgui.exit | 0b | Byte (Boolean) | | ajjgui.fixed | 0b | Byte (Boolean) | | ajjgui.lock | N/A | String | | ajjgui.page | N/A | Byte | | ajjgui.relative | 0b | Byte (Boolean) | | ajjgui.widget | Required ("button") | String |

Usage

/give @p <item_id>[minecraft:custom_data={ajjgui:{widget:"button",<optional_ajjgui_snbt>}}]

Examples

More information about changing GUI pages, exiting GUIs, and running GUI commands.

C