1. Essentials

Essentials

The GUISlot refers to the actual positional slot in which a GUIComponent is placed.

GUI-Components are placed into GUI-Slots.

---

Creating a UI

import me.tech.mcchestui.GUI

fun render(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { /* GUI options */ }
}

If you do not declare Singleton instances within your application you can similarly use JavaPlugin#getPlugin to get an instance of your plugin.

Positional Rendering

fun render(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { 
    slot(1, 1) { /* GUIComponent options */ }
  }
}

The slot function is a one-indexed X/Y coordinate representing the position to render in the UI. For example, the position 1, 1 will always render in the top-left of a Chest UI.

Rendering Basic Component Within Slot

fun render(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { 
    slot(1, 1) { 
      item = item(Material.CAKE) { /* GUIItem Options */ }
    }
  }
}

A GUISlot takes in our GUIComponent which itself takes a GUIItem to display.

Detecting GUISlot Interactions

fun render(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { 
    slot(1, 1) { 
      item = item(Material.CAKE) { /* GUIItem Options */ }

      onClick = {
        it.sendMessage("You have clicked on the Cake!")
      }
    }
  }
}

Similarly our GUIComponent can initialize a onClick property (which has it referencing the Player) that detects whenever somebody clicks on the GUISlot.

Conditional Rendering

fun render(shouldRender: Boolean): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { 
    slot(1, 1) { /* GUIComponent options */ }

    if(shouldRender) {
      slot(1, 2) { /* GUIComponent options */ }
    }
  }
}

The lambda function used with our gui helper function is practically treated like its own function block, you can run normal Kotlin code within it and have it conditionally render elements of the UI.

Refreshing UI Changes

fun render(): GUI {
  var shouldRender = false  

  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { 
    slot(1, 1) {
      onClick {
        shouldRender = !shouldRender // invert boolean.

        refresh()
      }
    }

    if(shouldRender) {
      slot(1, 2) { /* GUIComponent options */ }
    }
  }
}

After modifying the current state of the UI you should refresh it in order to display the changes. This will cause a full re-render of the UI.

UI Types

There are currently 3 different UI types, CHEST, DISPENSER and HOPPER.

GUIType#Chest is the only one that takes a parameter, which is its rows.

fun renderChest(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Chest(rows = 3)
  ) { /* GUI options */ }
}

fun renderDispenser(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Dispenser
  ) { /* GUI options */ }
}

fun renderHopper(): GUI {
  return gui(
    plugin = instance,
    title = Component.text("Rendered UI"),
    type = GUIType.Hopper
  ) { /* GUI options */ }
}