Kupe GUI

Cross-loader, cross-version GUI and Rendering library for Minecraft. For all your navigation needs. Named after the great and legendary navigator Kupe, who sailed to Aotearoa.

This documentation uses Mojang's official mappings.

Packaging

All code is placed in the cc.cosmetica.kupe package. The classes are split into api, impl, and util packages. api classes are the only ones kept stable across environments and versions.

In addition, a few api methods are marked as @LeavesSandbox and return minecraft classes. These are not guaranteed to be completely stable across environments, but will be kept stable where possible. They are provided in case a modder wishes to have greater flexibility than the library itself provides without referencing implementation classes.

Test mod code is in a fourth, testmod package.

Setting Up

You can include Kupe in your project via gradle. First, add the cosmetica maven to your repositories:

repositories {
    maven { url 'https://maven.cosmetica.cc/' }
}

Then, add the mod as a dependency:

dependencies {
    modImplementation 'cc.cosmetica:Kupe:1.0-SNAPSHOT'
}

Creating a Component

All GUI items in Kupe are Components, and extend the base class Component. They are built in the build() method, resized in resize(), and rendered in render(). There are a few more additional methods too:

• renderBackground
• minimumSize
• intrinsicSize
• mouseMoved
• mouseClicked

Element Size

Element size is treated as a modified border-box. Margin is space outside the component and padding is space within the component. Thus if you specify a height of 50 pixels and padding of 2 on all sides, the content size will have a height of 46 pixels. Border is not separated from padding, and will extend into the component region from the padding, in.

• I can modify the current setup to do this by changing

1. Sizing Methods

• Add own padding when determining a dimension with calculations, but not when determining it from a "size" parameter like specified size.
• This applies to both minimum size and intrinsic size methods.

2. Resizing Methods

• Subtract child padding when giving them their content region, rather than adding it.

Creating a Screen

A screen in Kupe is just a top level component. However, the Screen class implements a common component layout for you, so it is recommended to extend that.

The constructor for the screen takes the text to display as the screen title. You can either have a translation key generated by passing the ID, or pass a Text object yourself.

The screen also has a custom build() method that places its result within a Div that spans the screen. By default, this Div has JUSTIFY_CONTENT and ALIGN_ITEMS set to Justify.CENTRE and Align.CENTRE, however these can be changed by manipulating the rootStyle passed.

import cc.cosmetica.kupe.api.Screen;
import cc.cosmetica.kupe.api.ResourceKey;

public class MyScreen extends Screen {
	public MyScreen() {
		super(ID); // will use translation key "screens.examplemod.example"
	}
	
	@Override
	public Component[] build(Style rootStyle) {
		return new Component[] {
		};
	}
	
	public static final ResourceKey ID = new ResourceKey("examplemod", "example");
}

Registering a screen is not required, however it allows you to set the screen using just an ID. The screen can be registered at init by using Screens.registerScreen:

// constant class
Screens.registerScreen(MyScreen.ID, new MyScreen());
// factory
Screens.registerScreen(MyScreen.ID, MyScreen::new)

You can set the screen using Screens.setScreen:

// if registered
Screens.setScreen(MyScreen.ID);
// if not registered
Screens.setScreen(new MyScreen(), MyScreen.ID);

You can also get a Minecraft Screen by using Screens.getMinecraftScreen().

Debugging Screens

Kupe provides a simple screen debugger that lets you browse the component hierarchy with your keyboard. Call Screens.setAllowDebug(true) to enable using the debugger, then hit Ctrl+Shift+I while in a Kupe screen.

Compound Components

You may want to extend Component yourself, or extend Div or LayeredSpace, and override build() to specify your children.

Extending Component and returning a Div or LayeredSpace from build() will īncur slightly different behaviour to extending one of these, as each component in Kupe is added to the tree. Unlike in, for example, React, where returning a div from a component simply puts the div in the DOM. The default sizing and resize behaviour however has been designed such that returning a Div from a component should have minimal difference to extending Div in your custom component.

Leaf Components

Reactive States

Further Examples

For further examples on how to use the library, check out the test mod, in the testmod-common directory. Bootstrap code to register screens can be found in the loader-specific testmod directories. The test mod is provided under CC0, so feel free to steal code from it as much as you like.

The Kupe library itself is licensed under Apache-2.0, an open-source license.

Cosmetica also provides a good example of how to use the library. Its code is licensed under Apache-2.0.