Skip to content

Working with the API

UnderscoreEnchants provides an API for developers to hook into the plugin.

Adding the dependency

The API can be used with Maven or Gradle.

<!-- Repository -->
<repository>
    <id>roughly-underscore</id>
    <url>https://repo.runderscore.com/releases</url>
</repository>

<!-- Dependency -->
<dependency>
    <groupId>com.roughlyunderscore</groupId>
    <artifactId>UnderscoreEnchantsAPI</artifactId>
    <version>2.2.0</version>
</dependency>

// Repository
maven("https://repo.runderscore.com/releases")

// Dependency
implementation("com.roughlyunderscore:UnderscoreEnchantsAPI:2.2.0")

// Repository
maven "https://repo.runderscore.com/releases"

// Dependency
implementation "com.roughlyunderscore:UnderscoreEnchantsAPI:2.2.0"

Getting started

Make sure that your plugin depends on UnderscoreEnchants so that it loads after UnderscoreEnchants does.

depend: [ UnderscoreEnchants ]

To start working with UnderscoreEnchants API, obtain the instance of the API via the Bukkit's services manager.

The code snippets will be shown in both Java and Kotlin, but if possible please use Kotlin when working with UEAPI, since it is written in Kotlin and some interoperability issues may arise when using Java.

lateinit var ueApi: UEAPI

override fun onEnable() {
  ueApi = Bukkit.getServicesManager().getRegistration(UEAPI::class.java)?.provider ?: run {
    Bukkit.getLogger().severe("No UnderscoreEnchants API implementation found!")
    return
  }
}

UEAPI ueApi = null;

@Override
public void onEnable() {
  RegisteredServiceProvider<UEAPI> rsp = Bukkit.getServicesManager().getRegistration(UEAPI.class);
  if (rsp != null) {
    ueApi = rsp.getProvider();
  }

  if (ueApi == null) {
    Bukkit.getLogger().severe("No UnderscoreEnchants API implementation found!");
    return;
  }
}

The Javadocs (Dokka) for the API can be found here.

Common use cases

Enchanting/disenchanting an item

val enchanter = ueApi.enchanter

// Enchanting an item
val response = enchanter.enchant(item, enchantmentKey, level, listOf(
  // Ignored restrictions
  EnchantingRestriction.CONFLICT_RESTRICTION, EnchantingRestriction.UNAPPLICABLE_RESTRICTION
))

if (response.type == ItemStackEnchantResponseType.SUCCESS) {
  val item = response.item
}

// Disenchanting an item
val newItem = enchanter.fullyDisenchant(item)

UEEnchanter enchanter = ueApi.getEnchanter();

// Enchanting an item
ItemStackEnchantResponse response = enchanter.enchant(item, enchantmentKey, level, Arrays.asList(
  // Ignored restrictions
  EnchantingRestriction.CONFLICT_RESTRICTION, EnchantingRestriction.UNAPPLICABLE_RESTRICTION
));

if (response.type == ItemStackEnchantResponseType.SUCCESS) {
  ItemStack item = response.getItem();
}

// Disenchanting an item
ItemStack newItem = enchanter.fullyDisenchant(item);

Toggling an enchantment for a player

val playerManager = ueApi.playerManager

// true to not notify the player in chat
val nowDisabled = playerManager.toggle(player.uniqueId, enchantmentKey, true)

UEPlayerManager playerManager = ueApi.getPlayerManager();

// true to not notify the player in chat
boolean nowDisabled = playerManager.toggle(player.getUniqueId(), enchantmentKey, true);

Loading content from a file

val loader = ueApi.loader

val response = loader.loadEnchantment(file)
if (response == LoadResponse.NOT_FOUND) {
    // Handle failure
}

UELoader loader = ueApi.getLoader();

LoadResponse response = loader.loadEnchantment(file);
if (response == LoadResponse.NOT_FOUND) {
    // Handle failure
}

Adding registrables

Please refer to the creating registrables guide to learn how to create and add registrables.