Skip to content

Latest commit

 

History

History
419 lines (302 loc) · 12.7 KB

README-en.md

File metadata and controls

419 lines (302 loc) · 12.7 KB
Raw

🎨 ️HashGui

Library that lets you create customized GUIs and items quickly and easily.

This library has two main classes:

  • HashItem: Item builder
  • HashGui: GUI builder

🇫🇷 Egalement disponible en Français !

Installation

After installation, the .jar file is located in the builds/libs/ folder.

Linux / MacOS :

./gradlew make

Windows

.\gradlew.bat make

HashItem

Usage

Custom item creation:

HashItem item = new HashItem(Material.ENDER_PEARL, 10)
  .setName("Hi")
  .setLore(Arrays.asList(
    "Line 1",
    "Line 2"
  ))
  .addLore("Line 3")
  .setFlags(Arrays.asList(
    ItemFlag.HIDE_ATTRIBUTES,
    ItemFlag.HIDE_ENCHANTS
  ))
  .addFlag(ItemFlag.HIDE_UNBREAKABLE)
  .addEnchant(Enchantment.DURABILITY, 3)
  .setUnbreakable(true)
  .build();

Inventory#addItem(item.getItemStack());

Warning

Don't forget to build() the item before using it!
Always import from org.bukkit package.

Tip

ℹ️ Also see Material, ItemFlag and Enchantment enums. (from org.bukkit).

Features

  • setType(): Item
  • setAmount(): Item amount
  • setDurability(): Item's durability
  • setData(): Item's data
  • setName(): Item's name
  • setLore(): Replaces item's description
  • addLore(): Appends a string to item's description
  • setFlags(): Replaces item's flags
  • addFlag(): Adds a flag to the item
  • setUnbreakable(): Makes the item unbreakable
  • addEnchant(): Adds an enchantment to the item
  • removeEnchant(): Removes an enchantment from the item
  • build(): Builds the item so it can be used

Handlers

An Handler is a code snippet which will be executed when a player will perform a certain action
with an item.

Usage (example : Click handler)

ClickHandler clickHandler = new ClickHandler()
    .addClickType(ClickType.LEFT)
    .setClickAction((Player player, HashGui gui, ItemStack clickedItem, int clickedSlot) -> {
        // Actions to perform on click.
    });

HashItem item = new HashItem(Material.COMPASS)
    .addClickHandler(clickHandler);
    .build(guiManager);

Warning

guiManager (in the build() function) must be an instance of HashGuiManager, which must be stored at the root of your plugin. This instance takes care of detecting clicks and executing the appropriate action depending on the item.

Warning

Item targeting is based on its displayName, so be careful not to give the same name to two items if you don't want them to execute the same thing. If two items must have the same name but a different click handler, then mess with the color codes so that it's not visible from the player's point of view 😉 ("§cHi" and "§r§cHi" are different but look the same on player's POV)

Click handler

You can define the action executed when a player clicks on an item in a GUI.

Features :

  • Click type (left click, right click, shift + click...)
ClickHandler#addClickType(ClickType.LEFT);
ClickHandler#addClickTypes(ClickType.SHIFT_LEFT, ClickType.SHIFT_RIGHT); // Adds multiple click types at once.
ClickHandler#addAllClickTypes(); // Adds every click type.

Tip

See ClickType enum (from org.bukkit).

🫱 Interaction handler

You can define the action executed when a player interacts with an item.

Features :

  • Interaction type (left click, right click, in the air, or not...)
InteractHandler#addInteractType(Action.LEFT_CLICK_AIR);
InteractHandler#addInteractTypes(Action.RIGHT_CLICK_AIR, Action.RIGHT_CLICK_BLOCK); // Adds multiple interaction types at once.
InteractHandler#addAllInteractTypes(); // Adds every interaction types.

Tip

See Action enum (from org.bukkit).

🫱 Hold handler

You can define the action executed when a player holds (or takes off) an item in his hand.

Features :

  • Hold action (action executed when the player takes the item in his hand)
HoldAction action = (Player player, ItemStack item, int slot) -> {
    // ...
};

HoldHandler#setHoldAction(action);
  • Not hold action (action executed when the player takes the item off his hand)
HoldAction action = (Player player, ItemStack item, int slot) -> {
    // ...
};

HoldHandler#setNotHoldAction(action);

Caution

Armors are compatible with HoldHandler.
However, if you use the PlayerInventory#setHelmet function (or another method to define an armor piece), HoldHandler will NOT detect it automatically.
You must call the HashGuiHold#refreshArmorState(Player player) function to refresh the detection.

🫱 Hit handler

You can define the action executed when a player hits another player with an item.

Features :

  • Death only (executes the action only if the hit results in a death)
HitHandler#setOnlyKill(true);

🫱 Destroy handler

You can define the action executed when a player breaks a block with an item.

HashGuiManager

In order to make handlers working, you need to create an instance of HashGuiManager at the root of your plugin and give this instance to your custom item build.

Example:

public class Test extends JavaPlugin {
    
    private PluginManager pluginManager;
    private HashGuiManager guiManager;
    
    
    /* Variable initialization at server startup */
    @Override
    public void onEnable()
    {
        this.pluginManager = this.getServer().getPluginManager();
        this.setupGuiManager();
        
        // Your code here
    }
    
    /* Manager initialization and configuration */
    private void setupGuiManager()
    {
        this.guiManager = new HashGuiManager(this, this.pluginManager);
        this.guiManager.setup();
    }
    
    
    /* GUI Manager's getter */
    public HashGuiManager getGuiManager()
    {
        return this.guiManager;
    }
    
}

Tip

It is strongly recommended to only have one instance of HashGuiManager instance in your plugin (in fact, I forbid you to have more than one).

HashSkull

Creation of a player's skull:

HashItem playerSkull = new HashSkull()
    .setOwner("Shuvly") // HashSkull
    .setName("Shuvly's head") // HashItem
    .build();

Tip

Make all changes to HashSkull first before making changes to HashItem.

Creation of a custom skull:

HashItem customSkull = new HashSkull()
    .setTexture("...") // Your texture here
    .setName("Custom head")
    .build();

Texture example (in base64): eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZWY0OGMxOTU1NTUwZWFlZGU1NzEzYTdiY2NjOWE0YWUyZTZlMTcxZTI5YWMxYzcxYzBlM2QxYWJiNzI5MGNjYSJ9fX0=

Tip

Make all changes to HashSkull first before making changes to HashItem.

Tip

You can find custom skulls on Minecraft Heads.
When you're on the head page, scroll down to the "For developers" section to find the texture value in base64.

HashGui

Usage

GUI creation:

HashItem item = new HashItem(Material.SIGN)
  .setName("Settings")
  .addLore("Right click to access parameters")
  .build();

HashGui gui = new HashGui("Menu", 5)
    .setItem(3, item);
    
gui.open(player);

Features

  • open(): Opens the GUI to a player
  • close(): Closes the GUI to a player
  • update(): Refreshes a player's GUI
  • setItem(): Sets an item in the GUI

Masks

Masks (Mask) are used to create a GUI layout.

For example, if you want to make a border like this :

... a normal code would be :

ItemStack glass = new ItemStack(Material.STAINED_GLASS_PANE);
ItemStack grass = new ItemStack(Material.GRASS);
ItemStack glowstone = new ItemStack(Material.GLOWSTONE);
ItemStack bookshelf = new ItemStack(Material.BOOKSHELF);

for (int i = 0 ; i < 10 ; i++) {
    menu.setItem(i, glass);
}
for (int i = 17 ; i < 26 ; i++) {
    menu.setItem(i, glass);
}
menu.setItem(11, grass);
menu.setItem(13, glowstone);
menu.setItem(15, bookshelf);

But it's not really effective...
Here comes the masks. The code above then becomes:

ItemStack glass = new ItemStack(Material.STAINED_GLASS_PANE);
ItemStack grass = new ItemStack(Material.GRASS);
ItemStack glowstone = new ItemStack(Material.GLOWSTONE);
ItemStack bookshelf = new ItemStack(Material.BOOKSHELF);

/*                   ⬇️ Must be a HashGUI instance. */
Mask mask = new Mask(menu);

mask.setItem('s', glass);
    .setItem('g', grass);
    .setItem('l', glowstone);
    .setItem('b', bookshelf);
    
/*            ⬇️ Must be 9 characters long. */
mask.pattern("sssssssss")
    .pattern("s g l b s")
    .pattern("sssssssss");
    
mask.apply();

Way better isn't it?

If a letter has no assigned item, this one will be used:

Caution

Space character ( ) can't be used, as it serves as void.

PaginatedHashGui

PaginatedHashGui is a HashGui with a pagination system.

Usage

String title = "Paginated menu";
int linesAmount = 6;

PaginatedHashGui gui = new PaginatedHashGui(title, linesAmount, guiManager); // guiManager must be an instance of HashGuiManager.

HashItem previousPage = new HashItem(Material.ARROW)
    .setName("Previous page");

HashItem nextPage = new HashItem(Material.ARROW)
    .setName("Next page");

gui.setPreviousPageItem(previousPage); // When clicking on previousPage, the GUI will refresh to the previous page.
gui.setNextPageItem(nextPage); // When clicking on previousPage, the GUI will refresh to the next page.

Features

  • setPreviousPageItem(HashItem item) : Refreshes the GUI to the previous page (if possible)
  • setNextPageItem(HashItem item) : Refreshes the GUI to the next page (if possible)
  • update(Player player) : Refreshes the GUI (for the pages)
  • clearPageContent() : Visually clears current page (used for refreshing)
  • addPage(Page page) : Adds a new page
  • createNewPage() : Creates a fresh new page and adds it
  • clearPages() : Deletes all pages

Pages

Page creation

PaginatedHashGui gui;

Page page = gui.createNewPage(); // Creates a new page and adds it to the GUI

/* OR */

Page page = new Page(gui); // Creates a new page
gui.addPage(page); // Adds it to the GUI

Features

  • addItem(HashItem item) : Adds an item in the page at the first free slot
  • setItem(int slot, HashItem item) : Adds an item in the page at a specific slot
  • removeItem(int slot) : Removes the item linked to a slot
  • clearItems() : Clears page's items

Tip

By default, at the creation of a PaginatedHashGui, a fresh new page will be automatically created and added.

Page management

Page page;

HashItem item1 = new HashItem(Material.BED);
HashItem item2 = new HashItem(Material.BEDROCK);

page.addItem(item1);
page.setItem(8, item2);
page.removeItem(8);

Warning

  • For Page#addItem(), if no slots are free, a IllegalArgumentException will be thrown.
  • For Page#setItem() or Page#removeItem(), if the given slot is not free, the same exception will be thrown.
  • A slot is considered not free if it's not valid (below 0 or greater than the maximum capacity of the GUI) > or if an item is already present at this slot in the parent GUI.

Made with 💜 by Lysandre B. ・ wakatime + wakatime