Boxboy - SpongePowered inventory menu library

This is a discussion topic for the Ore project, Boxboy. View the full project on Ore for downloads and more information.


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.


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

repositories {

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

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


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)))
                "A       A",



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

Button Type Description
Dummy Has no functionality and is purely to display an item.
Action Performs a single action when clicked.
Switch Switches between two states. Internally uses Action buttons; the button representing the state being switched to is executed.
Scroll Switches between multiple states. Internally uses Action buttons; the button representing the state being switched to is executed.
Slot Pretends 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.

Method Description
isAnimated Return 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.
offer Perform an action when an item is offered to the slot by a viewing Player.
onClick Perform an action when the button is clicked.
getRepresentative Returns the ItemStack representing the button in a Menu.
getAnimatedRepresentative Returns 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",
                 "_       _",
    .frame(1000, "_B_B_B_B_",
                 "B       B",

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.

Version Summary
1.0 Initial push to GitHub.
1.0-fix1 Let’s be a plugin, instead of a shaded library.
1.0a Major bug and stability fixes.
1.0b More major stability fixes.
1.1 Menu animations.
1.2 Improved button animations, animation efficiency and bugfixes.
1.3 Deprecation of ToggleButton in favor of SwitchButton.

Very impressed with this library. Compact, powerful, and replicates Sponge’s API design(s) very well so the resulting code looks very uniform.


A new version has been released for Boxboy, it is available for download here.

v1.3: Deprecation of ToggleButton in favor of SwitchButton.