Quickstart

Please read the Prerequisites and Disclaimer before using this API!

To get quickly started with the SuperEnchants API, you'll obviously need to create a new project, this guide assumes you're using IntelliJ, if not follow the steps you would in your IDE to accomplish the same thing.

Assuming you have the Minecraft plugin installed, make absolutely sure you've selected papermc 1.21.1 and the "Use Paper Manifest" checkbox, the plugin will not work without checking that box since we need to use plugin bootstraps in our plugin to register enchantments.

If you did all the steps correctly, your project settings should look like the following

Now that your project is created, you'll need to import the SuperEnchants API into your project so you can use it, in your build.gradle file add the following

dependencies {
    //All other dependencies
    implementation files('libs/SuperEnchants-(most recent version).jar')
}

Then to import the API you'll have to create a /libs folder in your root directory of the project, and inside of that place the .jar file inside of it, it's always recommended to use the latest version of the plugin

And finally to finish off importing the API, add the following to your paper-plugin.yml file

dependencies:
  server:
    SuperEnchants:
      load: AFTER
      required: true
      join-classpath: true

This just makes sure that the SuperEnchants plugin loads before yours does

Now that you have the API in your project, you'll need to created a plugin bootstrap to register your enchantment, as you've hopefully read in the disclaimer, mojang doesn't make this easy for us. We're forced to use plugin bootstraps here, which is why you had to enable Paper Manifest.

In this example we'll be created a "Feather" enchantment which will negate all fall damage, modify the names and namespaces as you wish for whatever enchantment(s) you'd like to create.

The first step is to create a new file that is named after your main project file + "Bootstrap". For example my main file is named SETest, so my bootstrap file would be named SETestBootstrap

Next you'll have to register the new plugin bootstrap in your paper-plugin.yml by adding the following near the top of the file

bootstrapper: com.aznos.setest.SeTestBootstrap

Your entire paper-plugin.yml file should look something like this now

name: setest
version: '0.0.1'
main: com.aznos.setest.SETest
bootstrapper: com.aznos.setest.SETestBootstrap
api-version: '1.21'
authors: [ Aznos ]

dependencies:
  server:
    SuperEnchants:
      load: AFTER
      required: true
      join-classpath: true

Then inside of your bootstrap file, you'll be adding

public class SETestBootstrap implements PluginBootstrap {
    @Override
    public void bootstrap(BootstrapContext bootstrapContext) {
        SuperEnchantsBootstrap.addEnchantment("Feather", "setest.enchant.feather", Material.FEATHER, 1, 3, new NamespacedKey("setest", "feather"), "boots");
    }
}

If you've used the API pre version 3.0.0, you'll notice that registering a custom enchantment is a whole lot easier, but lets go ahead and unpack all the arguments of SuperEnchantsBootstrap.addEnchantment()

Most of everything is self explanitory and are labeled fine, but lets go through them:

enchantName: The name of your enchantment, a-z, A-Z, 0-9 (however numbers are discouraged)

permission: This is the permission of your enchantment, its recommended to install a permission manager alongside your plugin, so you can set and check if players have the correct permissions, the first argument of it should be your plugin name in lowercase, second argument should always be enchant for enchantments, and the third argument should be the name of your custom enchatment

relatedItem: This is the item that will show up the GUI when applying an enchant to an item

maxLevel: This is pretty simple, the maximum level you want the enchantment to go to

anvilCost: How many levels it should take from the player if they're using an anvil to enchant an item

key: For this you'll create a new NamespacedKey, the first parameter of this should be your plugin name in lowercase, and the second parameter should be the enchantment name in lowercase. You'll use this namespaced key later

applicableItems: Here you can define what items you want your item to apply too, in this case we just want it to apply to boots, so we just say "boots". However if you wanted it to be applicable to swords and axes, you could put "sword", "axe"

These are all of the available applicable items: helmet chestplate leggings boots sword axe pickaxe shovel hoe bow crossbow rod

For simplicity we'll just be adding the event listener in the main class of the plugin, but if you have more than one enchantment I really recommend creating a seperate class for each event listener as this can get quite messy.

Go ahead and register the actual listener/event where you want it to be, like I said we'll do this in the main class

At the top of your file add, again make sure the namespace key matches up with everything else.

private final Enchantment featherEnchant = Enchantment.getByKey(new NamespacedKey("setest", "feather"));

And for the listener we'll add

@EventHandler
public void EntityDamage(EntityDamageEvent e) {
    Player player = (Player) e.getEntity();

    if(e.getCause() == EntityDamageEvent.DamageCause.FALL) {
        if(player.getInventory().getBoots() != null) {
            ItemStack boots = player.getInventory().getBoots(); //If you're using another item eg Sword, Axe, use getItemInMainHand()
            ItemMeta itemMeta = boots.getItemMeta();
            if (itemMeta != null && itemMeta.hasEnchant(featherEnchant)) {
                int enchantLevel = itemMeta.getEnchantLevel(featherEnchant); //We aren't doing anything with the level for this since we only have a max level of 1
                CustomEnchantment featherEnchant = EnchantManager.getEnchantByName("feather"); //Case doesn't matter here, but be consistent
                if (!player.hasPermission(featherEnchant.permission())) {
                    player.sendMessage(ChatColor.RED + ConfigMessageHandler.getMessage(ConfigMessageHandler.getMessage("no_perms")));
                    return;
                }

                //Here is where you will actually execute the custom enchantment once all checks have been completed
                e.setCancelled(true); //Just cancel the event since we dont want the player taking damage
            }
        }
    }
}

Great, now we have all of that setup, we need to actually add the permission for it in paper-plugin.yml, its as simple as adding:

permissions:
  setest.enchant.feather:
    default: op

Make sure setest.enchant.feather matches up exactly with what you put when registering the enchantment

And that's it, you should now have a custom feather enchantment that you can apply to your boots by either running /segui or /se feather. Before running this plugin on your server remember to double check that the main superenchants plugin and this plugin are both installed on your server!

If you need any help visit the Help page.