⚔️ ExecutableItems API

Entry point: com.ssomar.score.api.executableitems.ExecutableItemsAPI

ExecutableItemsManagerInterface manager = ExecutableItemsAPI.getExecutableItemsManager();

Common tasks

Get an item configuration and give it

Optional<ExecutableItemInterface> eiOpt = manager.getExecutableItem("my_sword");
eiOpt.ifPresent(ei -> {
    int dropped = ei.give(player, 3);   // gives 3, drops the overflow at the player's feet
});

give(...) fires AddItemInPlayerInventoryEvent for you. To build the ItemStack yourself:

ItemStack item = ei.buildItem(1, Optional.of(player));
// or with initial variables / custom usage:
Map<String, Object> settings = new HashMap<>();
settings.put("Usage", 5);
settings.put("Variables", Map.of("power", "10"));
ItemStack custom = ei.buildItem(1, Optional.of(player), settings);

Check whether an ItemStack is an ExecutableItem

ExecutableItemObjectInterface eiObject = ExecutableItemsAPI.getExecutableItemObject(itemStack);
if (eiObject.isValid()) {
    String id = eiObject.getConfig().getId();
    int remainingUsage = eiObject.getUsage();
    Map<String, String> variables = eiObject.getVariablesValues();
    Optional<OfflinePlayer> owner = eiObject.getOwnerPlayer();
}

Performance

If you scan lots of items (inventories, chests...) and only care about specific ids, use the whitelisted lookup — custom (name/lore based) recognition only runs for those ids:

ExecutableItemInterface ei = manager.getExecutableItem(itemStack, List.of("my_sword", "my_bow"));

List / validate ids

List<String> ids = manager.getExecutableItemIdsList();
boolean exists = manager.isValidID("my_sword");
List<ExecutableItemInterface> all = manager.getAllExecutableItems();

Cooldowns

ei.addCooldown(player, 10, false);                    // 10 seconds, all activators
ei.addCooldown(player, 200, true, "activator1");      // 200 ticks, one activator

boolean onCd = ei.isInCooldown(player, "activator1");
double secondsLeft = ei.getCooldownRemaining(player, "activator1");

Variables & usage on a specific item

eiObject.updateVariable("power", "25", VariableUpdateType.SET);
eiObject.updateUsage(3);
eiObject.refreshItem();   // re-applies name/lore from the configuration

Create a new ExecutableItem configuration from an ItemStack

Optional<ExecutableItemInterface> created =
        ExecutableItemsAPI.registerNewExecutableItem(itemStack, "generated_id", "myfolder/");

Events

Event	Cancellable	Fired when
ExecutableItemActivateEvent	✅	an activator of an EI is triggered for a player, before conditions run
AddItemInPlayerInventoryEvent	—	an EI enters a player inventory
RemoveItemInPlayerInventoryEvent	—	an EI leaves a player inventory (e.g. usage depleted)
ExecutableItemsPostLoadEvent	—	all EI configurations are loaded (e.getManager() available)
RefreshExecutableItemEvent (in com.ssomar.score.events)	—	an EI is refreshed (by command or auto-update activator)

@EventHandler
public void onActivate(ExecutableItemActivateEvent e) {
    // e.getPlayer(), e.getExecutableItemId(), e.getActivatorId(), e.getItem(), e.getSourceEvent()
    if (isInProtectedRegion(e.getPlayer())) {
        e.setCancelled(true);   // the activator will not run
    }
}

info

If your plugin adds an ExecutableItem to a player inventory without using give(...), please fire AddItemInPlayerInventoryEvent yourself — it powers the EI ENTER IN PLAYER INVENTORY activator.