interfaces

Building interfaces since 2021.

interfaces is a builder-style user interface library designed to make creation of flexible user interfaces as easy as possible.

This library is currently in a state of constant breaking changes. The API has yet to be finalized, so please keep this in mind when considering using interfaces.

Packages

interfaces-core provides the core API classes.

interfaces-paper implements interfaces using the Paper Minecraft server API. This package provides the capability to construct a variety of Minecraft-based interfaces, including text, inventory (i.e. chests), and books.

Terminology

Interface

An interface is the main class that you'll be interacting with. Interfaces hold a series of transformations and other values that can be used to construct an InterfaceView.

InterfaceView ("view")

An InterfaceView represents a 'rendered' interface. An InterfaceView holds one pane and one InterfaceViewer.

InterfaceViewer ("viewer")

An InterfaceViewer represents an object that can view an interface. InterfaceViewers are provided panes to view.

Pane

A pane holds a collection of elements that make up the visual aspect of an interface.

Transform

A transformation ("transform") operates on a type of pane to add, remove, or change elements. Transformations are used to interact with panes.

Usage

Snapshots of this repository are hosted at https://oss.sonatype.org/content/repositories/snapshots/.

Gradle example:

repositories() {
// ...
maven("https://oss.sonatype.org/content/repositories/snapshots/")
// ...
}
dependencies() {
implementation("org.incendo.interfaces:interfaces-{package}:1.0.0-SNAPSHOT")
}

Examples

Creating an interface

This code creates a chest interface with one row, a background fill, an ItemStackElement containing information about the player, and utilizes an argument provider. This element also tracks how many times it has been clicked.

ChestInterfaceinfoInterface = ChestInterface.builder()
// This interface will have one row.
.rows(1)
// This interface will update every five ticks.
.updates(true, 5)
// Cancel all inventory click events
.clickHandler(ClickHandler.cancel())
// Fill the background with black stained glass panes
.addTransform(PaperTransform.chestFill(
ItemStackElement.of(newItemStack(Material.BLACK_STAINED_GLASS_PANE))
))
// Add some information to the pane
.addTransform((pane, view) -> {
// Get the view arguments// (Keep in mind - these arguments may be coming from a Supplier, so their values can change!)finalStringtime = view.arguments().get(ArgumentKey.of("time", String.class));
finalPlayerplayer = view.arguments().get(ArgumentKey.of("player", Player.class));
finalIntegerclicks = view.arguments().get(ArgumentKey.of("clicks", Integer.class));
ItemStackitemStack = newItemStack(Material.PAPER);
ItemMetaitemMeta = itemStack.getItemMeta();
itemMeta.displayName(Component.text("Item Name", NamedTextColor.GREEN));
ArrayList<Component> lore = newArrayList<>();
lore.add(Component.text("Line 1"));
lore.add(Component.text("Clicks: " + clicks));
itemMeta.lore(lore);
itemStack.setItemMeta(itemMeta);
// Return a pane withreturnpane.element(ItemStackElement.of(itemStack,
// Handle click
(clickHandler) -> {
finalHashMapInterfaceArgumentsarguments = HashMapInterfaceArguments
.with(ArgumentKey.of("clicks", Integer.class), (clickHandler.view().arguments().get(ArgumentKey.of("clicks", Integer.class))) + 1)
.with(ArgumentKey.of("player", Player.class), clickHandler.view().arguments().get(ArgumentKey.of("player", Player.class))).build();
clickHandler.view().backing().open(clickHandler.viewer(), arguments);
}
), 4, 0);
})
// Set the title
.title(Component.text("interfaces demo"))
// Build the interface
.build();

Showing the interface to a player

This code shows the interface created in the previous example being shown to a viewer. As the interface uses arguments, we can pass in supplier functions to the interface argument.

// Open the interface to the player.infoInterface.open(PlayerViewer.of(player),
// Create a HashMapInterfaceArgument with a time argument set to a// supplier that returns the current time printed all nice and pretty.HashMapInterfaceArguments
.with(ArgumentKey.of("player", Player.class), player)
.with(ArgumentKey.of("time", String.class), () -> {
DateTimeFormatterdtf = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
LocalDateTimenow = LocalDateTime.now();
returndtf.format(now);
})
.with(ArgumentKey.of("clicks", Integer.class), 0).build()
);

Video of the result of this code in Minecraft.

Note: these examples may not reflect the latest version of the interfaces API.

Further examples can be found here: https://github.com/Incendo/interfaces/tree/master/examples

Credits

Thanks to kyori and their adventure text library.

Thanks to broccolai for letting me steal his entire Gradle project setup.