Custom Screens

INFO

This page refers to normal screens, not handled ones - these screens are the ones that are opened by the player on the client, not the ones that are handled by the server.

Screens are essentially the GUIs that the player interacts with, such as the title screen, pause screen etc.

You can create your own screens to display custom content, a custom settings menu, or more.

Creating a Screen

To create a screen, you need to extend the Screen class and override the init method - you may optionally override the render method as well - but make sure to call it's super method or it wont render the background, widgets etc.

You should take note that:

• Widgets are not being created in the constructor because the screen is not yet initialized at that point - and certain variables, such as width and height, are not yet available or not yet accurate.
• The init method is called when the screen is being initialized, and it is the best place to create widgets.
  • You add widgets using the addDrawableChild method, which accepts any drawable widget.
• The render method is called every frame - you can access the draw context, and the mouse position from this method.

As an example, we can create a simple screen that has a button and a label above it.

public class CustomScreen extends Screen {
	public CustomScreen(Text title) {
		super(title);
	}

	@Override
	protected void init() {
		ButtonWidget buttonWidget = ButtonWidget.builder(Text.of("Hello World"), (btn) -> {
			// When the button is clicked, we can display a toast to the screen.
			this.client.getToastManager().add(
					SystemToast.create(this.client, SystemToast.Type.NARRATOR_TOGGLE, Text.of("Hello World!"), Text.of("This is a toast."))
			);
		}).dimensions(40, 40, 120, 20).build();
		// x, y, width, height
		// It's recommended to use the fixed height of 20 to prevent rendering issues with the button
		// textures.

		// Register the button widget.
		this.addDrawableChild(buttonWidget);

	}

	@Override
	public void render(DrawContext context, int mouseX, int mouseY, float delta) {
		super.render(context, mouseX, mouseY, delta);

		// Minecraft doesn't have a "label" widget, so we'll have to draw our own text.
		// We'll subtract the font height from the Y position to make the text appear above the button.
		// Subtracting an extra 10 pixels will give the text some padding.
		// textRenderer, text, x, y, color, hasShadow
		context.drawText(this.textRenderer, "Special Button", 40, 40 - this.textRenderer.fontHeight - 10, 0xFFFFFFFF, true);
	}
}

Opening the Screen

You can open the screen using the MinecraftClient's setScreen method - you can do this from many places, such as a key binding, a command, or a client packet handler.

MinecraftClient.getInstance().setScreen(
  new CustomScreen(Text.empty())
);

Closing the Screen

If you want to close the screen, simply set the screen to null:

MinecraftClient.getInstance().setScreen(null);

If you want to be fancy, and return to the previous screen, you can pass the current screen into the CustomScreen constructor and store it in a field, then use it to return to the previous screen when the close method is called.

public Screen parent;
public CustomScreen(Text title, Screen parent) {
	super(title);
	this.parent = parent;
}

@Override
public void close() {
	this.client.setScreen(this.parent);
}

Now, when opening the custom screen, you can pass the current screen as the second argument - so when you call CustomScreen#close - it will return to the previous screen.

Screen currentScreen = MinecraftClient.getInstance().currentScreen;
MinecraftClient.getInstance().setScreen(
  new CustomScreen(Text.empty(), currentScreen)
);