Xemiru / Boxboy

SpongePowered inventory menu library.
Download

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);

Menu

Buttons

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

Button TypeDescription
DummyHas no functionality and is purely to display an item.
ActionPerforms a single action when clicked.
SwitchSwitches between two states. Internally uses Action buttons; the button representing the state being switched to is executed.
ScrollSwitches between multiple states. Internally uses Action buttons; the button representing the state being switched to is executed.
SlotPretends to be a functional inventory slot. Executes actions when the item in the slot is changed.

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.

MethodDescription
isAnimatedReturn whether or not the Button is animated. You can still use this for your own implementation of non-static representatives; it is otherwise recommended to implement getAnimatedRepresentative.
offerPerform an action when an item is offered to the slot by a viewing Player.
onClickPerform an action when the button is clicked.
getRepresentativeReturns the ItemStack representing the button in a Menu.
getAnimatedRepresentativeReturns an Animation representing animation data for the button in a Menu.

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);

Animated Menu

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

Version History

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

VersionSummary
1.0Initial push to GitHub.
1.0-fix1Let’s be a plugin, instead of a shaded library.
1.0aMajor bug and stability fixes.
1.0bMore major stability fixes.
1.1Menu animations.
1.2Improved button animations, animation efficiency and bugfixes.
1.3Deprecation of ToggleButton in favor of SwitchButton.

Category: Developer Tools

Published on Jul 16, 2018

611 views

65 total downloads

Licensed under MIT

Pages

Members