Menus & Screens (MultiLoader 1.21+)

Every container GUI in Minecraft, from furnaces to crafting tables, is split into two distinct parts: a menu class that runs on the server and manages the logical slot layout and item transfer rules, and a screen class that runs on the client and handles rendering. This tutorial extends the ExampleBlockEntity from the Block Entities tutorial with a nine-slot item inventory, then wires up a full menu and screen so players can open and interact with it in-game.

Updating the Block Entity

The existing block entity extends BlockEntity directly. To store items and serve as a container, the base class must be changed to BaseContainerBlockEntity. This abstract class already implements Container, Nameable, and MenuProvider. It handles all the slot bookkeeping, the stillValid distance check, and delegates item NBT serialisation to ContainerHelper whenever you call super.saveAdditional(). You only need to supply the backing list and describe the menu to create.

Replace the entire ExampleBlockEntity class with the following:

The critical change is the base class. BaseContainerBlockEntity routes all slot access through getItems(), enforces the stack size limit from getMaxStackSize(), and calls setChanged() automatically when a slot is modified. The stillValid implementation it provides checks that the player is within eight blocks of the block entity, which is the standard Minecraft rule for all containers. You do not need to implement this check yourself.

The Menu Registry

Create a MenuRegistry class in your common registry package. A MenuType maps a registry name to a factory that reconstructs the menu on the client side. The factory takes only a sync ID and the player inventory because the client does not have a reference to the server-side block entity; vanilla populates the slots automatically via the slot-synchronisation packet sent immediately after the menu is opened.

The ExampleMenu::new method reference matches the MenuSupplier<T> functional interface (int syncId, Inventory playerInventory) -> T. This refers to the two-argument client-side constructor you will write in the next section. The FeatureFlags.DEFAULT_FLAGS argument marks the menu as belonging to the default feature set; use FeatureFlags.VANILLA_SET if you ever need to flag it as an experimental feature instead.

In the access transformer and access widener we created back in the Block Entities tutorial, add the following entries to the access transformer:

And in the access widener:

Next, make sure you call MenuRegistry.init() from CommonClass.init() after the block entity registry:

The Menu Class

Create ExampleMenu in a new menu package inside your common project. The menu has two constructors: a server-side constructor that receives the real Container from the block entity, and a client-side constructor called by the MenuType factory that creates a temporary SimpleContainer which vanilla fills via the sync packet:

checkContainerSize throws a descriptive exception at startup if the container reports fewer slots than expected, which catches registration mismatches early. startOpen and stopOpen are used by vanilla to play lid animations on chests; they are no-ops on SimpleContainer but are worth calling so any future Container implementation works correctly.

Slot Layout

Slots are positioned in pixels relative to the top-left corner of the background texture. Vanilla slot rendering draws the 16x16 item icon one pixel inset from the position you provide, so the coordinates mark the top-left corner of the 18x18 slot area (including the 1px border). Adjacent slots are spaced 18px apart.

The slot indices in this.slots follow the order in which you call addSlot:

• 0-8: the nine container slots added by addContainerSlots().
• 9-35: the 27 main player inventory slots (rows 1-3, indices 9-35 of the player's own inventory).
• 36-44: the nine hotbar slots (indices 0-8 of the player's own inventory).

quickMoveStack uses these ranges to route shift-click actions. A click on index 0-8 tries to push the stack into the player inventory (slots 9-44). A click on 9-44 tries to push into the container (slots 0-8). The true argument to moveItemStackTo for the container direction fills slots from the end of the range backwards, matching vanilla's fill order for most containers.

The Screen Class

The screen handles all client-side rendering. Because it extends the vanilla AbstractContainerScreen, which is a pure Minecraft class, it can live in a client.screen package inside your common project rather than in a loader-specific source set. Create ExampleScreen there:

leftPos and topPos are computed by AbstractContainerScreen to centre the GUI on screen. renderBg blits the full background texture starting at those coordinates. renderLabels is called after renderBg with the matrix already translated to (leftPos, topPos), so label positions are relative to the texture origin, not the screen origin.

titleLabelX and titleLabelY default to 8, 6. inventoryLabelX and inventoryLabelY default to 8, imageHeight - 94, which places the "Inventory" label just above the player inventory rows. Override these fields in your constructor if you adjust imageHeight or move the player inventory.

The GUI Texture

Create the texture at src/main/resources/assets/examplemod/textures/gui/example_menu.png inside your common project. The PNG must be exactly 256x256 pixels (the largest power-of-two that contains the 176x166 GUI area). Only the top-left 176x166 region is sampled by the blit call; the rest can be left transparent.

The standard layout for a 176x166 container background:

• A solid stone-grey panel filling the full 176x166 area.
• Nine container slot cutouts at x = 62, 80, 98 and y = 17, 35, 53 (18x18 each, 1px dark border, slightly lighter interior).
• 27 player inventory slots at x = 8 to 152, nine per row at y = 84, 102, 120.
• Nine hotbar slots at x = 8 to 152, y = 142, separated by a 4px gap from the inventory rows above.

You can use the vanilla file assets/minecraft/textures/gui/container/dispenser.png (extract it from the Minecraft client jar, which can be opened as a zip archive) as a colour and style reference which also happens to match our 3x3 layout. Save as a 32-bit PNG with alpha to preserve transparency in the unused region.

Opening the Menu

Add a useWithoutItem override to ExampleBlockEntityBlock. This method is called when a player right-clicks the block without holding an item. The block entity already implements MenuProvider via BaseContainerBlockEntity, so you only need to retrieve it and call openMenu:

Returning InteractionResult.SUCCESS on both sides prevents any held item from being used. The server calls menuProvider.createMenu() internally, assigns a synchronisation ID, sends an OpenScreenPacket to the client, and begins slot-syncing. The client receives the packet, uses the MenuType factory to construct a local ExampleMenu with a temporary SimpleContainer, then opens the registered screen class.

Loader Screen Registration

The association between a MenuType and its screen class must be declared at startup on each loader. This is the one place where loader-specific code is required.

On NeoForge, add the menu screen registry to our ClientEvents class we created in a previous tutorial:

On Fabric, register in your client mod initialiser we created in a previous tutorial:

MenuScreens.register(...) expect a three-argument constructor reference matching (MenuType menu, Inventory inv, Component title) -> AbstractContainerScreen, which matches ExampleScreen exactly.

Dropping Items on Break

By default, breaking the block destroys all items stored in the container. Override onRemove in ExampleBlockEntityBlock to scatter the contents into the world when the block is replaced by a different block:

Containers.dropContents iterates every slot and spawns an item entity at the block position for each non-empty stack. The state.is(newState.getBlock()) check ensures items are only dropped when the block type actually changes; if the same block is replaced (for example, by a block state update), the inventory is preserved.

Testing

Add a lang entry for the container title in the ExampleLangProvider, then re-run the datagen:

Launch a creative-mode world and place the block. Right-click without an item in hand. The GUI should open showing the background texture, nine container slots in a 3x3 grid, the "Example Container" title, and the player inventory below. Place some items in the container slots, close the screen, and reopen to confirm they persist. Log out and back in to confirm they survive a world save.

If the screen opens but shows a blank or black background, verify the texture path is exactly assets/examplemod/textures/gui/example_menu.png and the file is 256x256. If the screen does not open at all, check the client log for an unregistered screen for menu type error, which means the screen registration call in the client setup did not run during startup. Break the block and confirm the stored items drop onto the ground.

You can find the source for this tutorial here: