Boxboy

Inventory menu library for SpongePowered plugins.

If you’re a server owner, you can simply drop this in your mods folder if a mod requests you to. The rest of the information here is for other plugin developers. This README is a direct copy of the one residing in Boxboy’s GitHub page.

You can also skip over to the javadocs.

Setup

The Boxboy dependency can be simply added to the dependencies block. Maven Central should be a repository.

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.github.xemiru.sponge:boxboy:1.2'
}

Be sure to add it as a plugin dependency in your plugin’s metadata.

Usage

Creating a Menu

In general, plugins providing an API are guaranteed to be accessible as soon as the GamePostInitializationEvent fires. When that event fires, the Boxboy instance can be accessed through a call to Boxboy.get().

You have two types of menus you can create through the singleton Boxboy instance.

A Menu is a standard menu that only uses the top inventory and will let the player interact normally with their own inventory on the bottom of the inventory view.

An ExtendedMenu is a menu that uses both the top and bottom inventories. The viewing players’ inventories are temporarily stored away while viewing the menu and will be returned when the menu is closed. It is still a Menu, and does not actually have any extra visible methods.

Both types can be created through the Boxboy instance. The top inventory can be configured to be of different sizes or different inventory types.

Menu menu = Boxboy.get().createMenu(3, Text.of("title"));
Menu extended = Boxboy.get().createExtendedMenu(3, Text.of("title"));

Menu hopper = Boxboy.get().createMenu(InventoryArchetypes.HOPPER, Text.of("title"));

Menu Patterns

While you can simply set the Buttons of a Menu through calls to Menu.setButton(int, Button), it is possible to use a MenuPattern instead to prepare them using templates.

Spaces and the underscore character are special characters for menu patterns. Spaces will cause the pattern to ignore the button currently at the character’s position, but an underscore will forcibly remove the button at the slot.

Menu myMenu = Boxboy.get().createMenu(3, Text.of("title"));

new MenuPattern()
    .setButton('A', DummyButton.of(ItemStack.of(ItemTypes.STAINED_GLASS_PANE, 1)))
    .setPattern("AAAAAAAAA",
                "A       A",
                "AAAAAAAAA")
    .apply(myMenu);

Buttons

There’re five stock Button classes that Boxboy provides, all of which generally cover most use cases.

Should none of these buttons cover a specific need, a custom Button implementation can be written. The methods listed below are methods to be implemented.

A button should implement either offer or onClick to have functionality.

When implementing button functionality, one should keep the Menu’s invalidation flag in mind if the button intends to make any changes to its source Menu. The Menu will not update inventories until it is marked as invalidated either by a Button’s animation or by a call to Menu.invalidate().

Menu Animations

Instead of animating buttons, you can animate the menu itself. Menu animations can be applied through the AnimatedMenuPattern class, in the same way that the MenuPattern class is utilized. Patterns are given as frames instead, functioning similarly to when they’re used with MenuPatterns with an additional frame length parameter provided in milliseconds.

Menu myMenu = Boxboy.get().createMenu(3, Text.of("title"));

new AnimatedMenuPattern()
    .setButton('A', DummyButton.of(ItemStack.of(ItemTypes.IRON_BLOCK, 1)))
    .setButton('B', DummyButton.of(ItemStack.of(ItemTypes.GOLD_BLOCK, 1)))
    .frame(1000, "A_A_A_A_A",
                 "_       _",
                 "A_A_A_A_A")
    .frame(1000, "_B_B_B_B_",
                 "B       B",
                 "_B_B_B_B_")
    .apply(myMenu);

Animations can be removed with a call to Menu.clearAnimations().

Version History

Versions follow semantic versioning, but uses letters for patch versions instead.