Quick Start

This is the quick guide on how to set up the very basics, if you would like to have more functionality and customization then check the advanced section.

Reference the API

Of course, with any API you need to reference the library, unfortunately, I couldn't get maven to work so you will need to download directly the resource here from spigot and add the jar to your referenced libraries. Once you have done so, now you need to add the dependency to your plugin.yml file like so:

depend: [UIFramework]

Quick rundown

In this guide, I will demonstrate how to create a custom lightsaber that will have the ability to throw it and return to its owner.

You will need to register your custom items, abilities, and crafting recipes within your onEnable method for your items to work. There are three registries you will need to know of, the first is the ability registry which you need to use to register abilities. Next, you need to register your actual custom items with the item registry. Finally, the recipe registry and your custom recipes can only be registered after your items since it needs the item to finish the recipe.

Good to know: UIFramework will automatically save and sync recipes so it does not matter if you register a recipe every time you initialize as it will be handled internally. Even if the user changes a recipe then reregistering it will not overwrite the user's recipe. However, if the user deletes one of your recipes and then you register it again it will reappear, to prevent this you should try to only register your recipe once.

public class Main extends JavaPlugin {

    public void onEnable() {
        registerAbilities();
        registerItems();
        registerRecipes();
        
        //init stuff
    }
    private void registerAbilities() {
        //ability to throw lightsaber
        AbilityType.registerAbility("saber_throw", SaberThrow.class);
    }
    private void registerItems() {
        //the actual lightsaber item
        ItemType.registerItem("green_lightsaber", GreenLightsaber.class);
    }
    private void registerRecipes() {
        //random recipe for the lightsaber
        ShapedRecipe recipe = new ShapedRecipe(new NamespacedKey(this, "recipe1"), ItemType.getItemType("green_lightsaber").getBuilder().getItem());
        recipe.shape("  a", " a ", "b  ");
        //its best to use RecipeChoice here
        recipe.setIngredient('a', new RecipeChoice.ExactChoice(new ItemStack(Material.EMERALD)));
        recipe.setIngredient('b', new RecipeChoice.ExactChoice(new ItemStack(Material.STICK)));
    }
}

Good to know: UIFramework contains an ItemBuilder class to handle items so attached to every ItemType instance is a builder that holds the item. To retrieve the item just call the ItemType.getBuilder() to get the builder and then ItemBuilder.getItem() to retrieve the ItemStack like shown in the shaped recipe object in the above snippet.

Create ability

As you might have noticed in the above code that we are registering an AbilityType with the class SaberThrow. The registry takes the name identifier of our ability and a class object that extends UIFrameworks Ability class. Let me show you an example of an ability class that would be acceptable for the registry object.

This ability is finished for now and can be directly registered as an ability with the code we used above in the onEnable method:

As you have noticed we are overriding a method from the Ability class inside our code public boolean interacted(PlayerInteractEvent event, GenericItem base) This override will trigger if the player interacted in a certain way (More about that later). Here is a list of default methods from the Ability class that can be overridden in your custom abilities class:

Create item

Now we can create our custom item and register it very similarly to how we register abilities, the reason why we register our custom items is to maintain even further control on actions and attributes of items. For the registry of the custom item it takes a string for the name identifier of the item (This will be the name used for the UIF give command in game), and it takes a class object that extends UIFrameworks GenericItem class. Here is an example of our green lightsaber item class:

Good to know: As you can see above in the createItem section the creator has a couple of good things to be aware of. When I use the method registerName, this will set the items name, but I use another method inside UIFUtils.convertString(). This method is part of a utilities class in UIF and will take in any string and convert the chat colors including hex colors input as "(hex:#000000)" whats also really nice about this method is that if the server does not support hex colors (running craftbukkit). Then it will automatically convert hex colors in the string to the closest vanilla color.

This item is finished for now and can be directly registered as an item with the code we used above in the onEnable method:

Initializing your items and abilities

Now even though I showed a very basic way of setting up items and abilities in the onEnable abilities, I highly recommend you initialize them in a slightly different way.

There we go, we fully finished our custom item! To get your item you can simply run this code:

Or in-game, the player can type the command /ui give green_lightsaber since all registered items will automatically be added to the UIF give command. That's it for the basic item and ability setup, pretty quick isn't it?

Further improvement

Now this next part is just to demonstrate the saber throw ability I earlier described, here I will show the code to make a simple ability that will throw the custom item and return it to its holder (This has some other calls and will not work if you copy paste it is just reference code):

Now if we go into the game here is our newly created item and ability in action:

PreviousWelcome!NextItems

Last updated