Home

Getting Started

Maven

<repository>
  <id>pvphub-releases<id/>
  <name>PvPHub Development<name/>
  <url>https://maven.pvphub.me/releases<url/>
<repository/>

<dependency>
  <groupId>com.mattmx<groupId/>
  <artifactId>ktgui<artifactId/>
  <version>${version}<version/>
<dependency/>

To avoid issues, make sure you do not shade KtGUI.

You are also required to provide the Kotlin Standard Library your self.

I recommend you do this with the use of this plugin

View other dependency managers

In the onEnable() function of the main class of your plugin, make sure to call

GuiManager.init(this)

Where this is the plugin instance.

Creating a GUI

To create a GUI, we can either extend GuiScreen, or build it dynamically from DSL or otherwise.

The ! bang operator we are using in this example simply calls String#component, translating color codes and formatting, converting your String into a Component, which are required in Paper.

Extending GuiScreen

class CustomAnvilGUI : GuiScreen(!"Example GUI", type = InventoryType.ANVIL) {

}

val guiWithTwoRows = gui {
    title = !"Example GUI"
    rows = 2
}

Adding buttons

You can add anything extending GuiButton to a screen.

To look at labelled gui slots, look here.

class CustomGUI : GuiScreen(!"Example GUI", 4) {
    init {
        GuiButton(Material.DIRT) named !"&7Foo" slot 0 childOf this

        // alternatively:
        button(Material.DIRT) {
            named(!"&7Foo")
        } slot 0
    }
}

Make sure to include childOf in order to register the button to the GUI. The GuiScreen#button() method will do it for you.

Adding Click events.

We've made a button, now let's add some interactivity.

class CustomGUI : GuiScreen(!"Example GUI", 4) {
    init {
        GuiButton(Material.DIRT)
            .click {
                ClickType.LEFT + ClickType.RIGHT {
                    player.sendMessage(!"&cHello, world")
                }
            } named !"&7Foo" slot 0 childOf this

        // alternatively:
        button(Material.DIRT) {
            named(!"&7Foo")
        } slot 0
    }
}

The library supports every type of click event.

You can find a list of their names here.

Opening the GUI

In order to give more options, you can make GUIs defined once, and then clone them to behave differently depending on who opens them.

If you are creating a new instance per GUI then simply do the following.

CustomGUI().open(player)

If you are sharing GUIs instead of making a new instance per gui, do this.

// gui is the gui instance
gui.createCopyAndOpen(player)

Creating custom GUI buttons

Creating custom GUI buttons is a nice thing we offer.

To get started, create a new class extending GuiButton or IGuiButton.

class CustomGUIButton() : GuiButton() {

}

This object can now already be added to GUIs with the same functionality as a normal GuiButton object.

Let's add some custom functionality.

class CustomGuiButton() : GuiButton() {
    private var clicked = false

    override fun thisClicked(e: ButtonClickedEvent) {
        if (clicked) return
        clicked = true
        item = ItemBuilder(Material.STONE).name("&7Unavailable").make()
        // Update the item for the player
        update(e.player)
        // Call this if you want other events to be called
        super.thisClicked(e)
    }

    override fun copy(parent: IGuiScreen): CustomGuiButton {
        val button = CustomGuiButton()
        button.clicked = clicked
        return button
    }

}

For this button to be used in a cloned context, we need to override the copy method and return a cloned button.

This will make it so the button can only be clicked once, then it will turn to stone.