Skip to content

Commit

Permalink
docs: update readme to include documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@DebitCardz
DebitCardz authored Aug 26, 2023
1 parent 13a5b85 commit 6e37cb5
Showing 1 changed file with 14 additions and 218 deletions.
232 changes: 14 additions & 218 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ by, [**hazae41**](https://github.com/hazae41/).
The primary aim of this project was to add additional features to the original project and redo a few elements to better
suite my own personal needs from the project.

### Documentation
Documentation of features of the library can be found [**here**](https://github.com/DebitCardz/mc-chestui-plus/wiki).

### Gradle

```kts
Expand Down Expand Up @@ -61,233 +64,26 @@ Changes within the GUI are as following

* Switched from using Strings to using Kyori TextComponents for all text.

Thanks for checking out this project! And for further examples of what you can do you can checkout the original page
for [**mc-chestui**](https://github.com/hazae41/mc-chestui).

# Examples
Thanks for checking out this project! And for further examples of what you can do you can checkout the [**documentation**](https://github.com/DebitCardz/mc-chestui-plus/wiki).

## GUI Creation
## Basic Usage

```kotlin
fun mainGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Example GUI", NamedTextColor.GOLD),
// plugin instance.
plugin = this, // plugin instance
// inventory title.
title = Component.text("Rendered UI"),
// 1 row chest inventory.
type = GUIType.Chest(rows = 1)
) {
slot(1, 1) {
item = item(Material.STONE) {
name = Component.text("Cool stone!")
}
}
}
}
```

## Hoppers & Dispensers Are Supported

```kotlin
fun hopperGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Hopper GUI", NamedTextColor.GOLD),
type = GUIType.Hopper
) {
slot(1, 1) {
item = item(Material.CAKE) {
name = Component.text("Cooler Cake")
}
}
}
}
```

```kotlin
fun dispenserGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Dispenser GUI", NamedTextColor.GOLD),
type = GUIType.Dispenser
) {
slot(1, 1) {
item = item(Material.CAKE) {
name = Component.text("Dispensed Cake")
}
}
}
}
```

You don't need to specify the rows with these types since their rows will stay static.

## Skull Support

```kotlin
fun headGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Head GUI", NamedTextColor.GOLD),
type = GUIType.Dispenser
) {
// Middle of the dispenser.
slot(2, 2) {
item = item(Material.PLAYER_HEAD) {
name = Component.text("Your head!", NamedTextColor.RED)
skullOwner = player
}
}
}
}
```

We use a Player or OfflinePlayer object to assign the skull owner, this also supports Player Profiles for skulls.

## Glowing Items Support

```kotlin
fun glowingHeadGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Glowing Head GUI", NamedTextColor.GOLD),
type = GUIType.Dispenser
) {
slot(2, 2) {
item = item(Material.PLAYER_HEAD) {
name = Component.text("Your glowing head!", NamedTextColor.GOLD)
skullOwner = player
glowing = true
// render in first slot.
slot(1, 1) {
item = item(Material.STONE) {
name = Component.text("Rendered Stone")
}
}
}
}
```

You can make items glow in a GUI, it automatically hides the enchantments of the item if you do this as well.

## Fill The Border Of Your GUI

```kotlin
fun filledBorderGUI(): GUI {
return gui(
plugin = this,
title = Component.text("Chest GUI", NamedTextColor.GOLD),
type = GUIType.Chest(rows = 3)
) {
fillBorder {
item = item(Material.GRAY_STAINED_GLASS_PANE) {
name = Component.empty()
}
}
}
}
```

This'll automatically outline your GUI with whatever item you put as input.

## Set the Next Available Slot in a GUI

```kotlin
fun nextAvailableSlotUi(): GUI {
return gui(
plugin = this,
title = Component.text("Chest GUI", NamedTextColor.GOLD),
type = GUIType.Chest(rows = 3)
) {
fillBorder {
item = item(Material.GRAY_STAINED_GLASS_PANE) {
name = Component.empty()
}
}

for(_ in 0..5) {
nextAvailableSlot {
item = item(Material.STONE)
}
}
}
}
```

This will avoid the slots already filled by the border glass and fill the slots of
the inventory that are AIR. Any null item slot will be overridden as this method only
checks for slots occupied by an ItemStack.

## Check when ItemStacks are placed into the GUI

```kotlin
fun itemPlacement(): GUI {
return gui(
plugin = this,
title = Component.text("Chest GUI", NamedTextColor.GOLD),
type = GUIType.Chest(rows = 3)
) {
allowItemPlacement = true

onPlaceItem = { player, item, slot ->
player.sendMessage("You have placed ${item.type.name} in slot ${slot}.")

false // will not cancel the event.
}
}
}
```

Allow for items to be placed into the GUI and check when they are placed with a simple anonymous function, if it is placed over a slot that is taken (even if the slot is AIR) the event will be cancelled.

## Check when ItemStacks are dragged into the GUI

```kotlin
fun itemDrag(): GUI {
return gui(
plugin = this,
title = Component.text("Chest GUI", NamedTextColor.GOLD),
type = GUIType.Chest(rows = 3)
) {
allowItemPlacement = true
allowItemDrag = true

// items is a Map of <Int, ItemStack>.
onDragItem = { player, items ->
for((slot, itemStack) in items) {
player.sendMessage("You have placed ${item.type.name} in slot ${slot}.")
}

false // will not cancel the event.
}
}
}
```

Similarly to `onPlaceItem` we can also detect when items are dragged into the GUI, if they are dragged over a slot that is taken (even if the slot is AIR) the event will be cancelled.

## Prevent GUI Listener from being unregistered

```kotlin
fun singleInstanceGui(): GUI {
return gui(
plugin = this,
title = Component.text("Chest GUI", NamedTextColor.GOLD),
type = GUIType.Chest(rows = 3)
) {
singleInstance = false

slot(4, 1) {
item = item(Material.CAKE) {
name = Component.text("Cake", NamedTextColor.GOLD)
}
}
}
}

val gui = singleInstanceGui()

getCommand("openUi").setExecutor(object : CommandExecutor {
override fun onCommand(sender: Player) {
sender.openGUI(gui)
}
})
```

If a single instance of a GUI is being used to be opened to multiple people or is cached it's
extremely important to mark `automaticallyUnregisterListener` as false or the `Listener` attached to the `GUI`
will be unregistered once all initial viewers of the `GUI` exit the menu resulting in undefined behavior.

0 comments on commit 6e37cb5

Please sign in to comment.