Using RelicAPI

The RelicAPI class provides the primary entry point for developers to interact with the Relique system. It allows you to query equipped items, modify slot limits, and safely equip or unequip relics for any LivingEntity.

Because Relique supports custom entities and mobs, all API methods accept a LivingEntity rather than strictly a Player.

Retrieving Equipped Relics

When retrieving items through the API, the returned ItemStack instances are safe clones. Modifying the returned items will not alter the entity's actual equipment. If you need to update an item's data, you must modify the clone and pass it back through equip().

Method	Description
`getEquipped(LivingEntity, String slotId)`	Returns a list of all items currently equipped in the specified slot. Empty slots are represented by `ItemStack.empty()`.
`getEquipped(LivingEntity, String slotId, int index)`	Returns an `Optional<ItemStack>` for a specific index within a slot.
`getAllEquipped(LivingEntity)`	Returns a flat list of `SlotResult` records, detailing every relic equipped across all of the entity's active slots. Empty spaces are omitted.

Example:

// Print all equipped relics to the console
for (RelicAPI.SlotResult result : RelicAPI.getAllEquipped(entity)) {
    System.out.println("Slot: " + result.slotId() + " | Item: " + result.item().getType());
}

Managing Equipment

The API provides methods to safely equip and unequip items. Using these methods guarantees that all necessary events (RelicEquipEvent, RelicUnequipEvent) are fired, attribute modifiers are correctly applied or removed, and equip sounds are played.

Method	Description
`equip(LivingEntity, String slotId, int index, ItemStack)`	Attempts to equip an item into the specified slot and index. Returns `true` if successful. Fails if the item fails validation, the index exceeds the slot limit, or the current item cannot be unequipped (e.g., Curse of Binding).
`unequip(LivingEntity, String slotId, int index)`	Removes and returns the item at the specified slot index. Returns `ItemStack.empty()` if the slot is empty or the item cannot be removed.
`canUnequip(LivingEntity, String slotId, int index)`	Checks if the item at the index can be unequipped. Evaluates the Curse of Binding enchantment and Creative mode bypasses.

Modifying Slot Limits

Slot capacities are backed by AbyssalLib entity attributes. This means limits are persistent, and can be modified dynamically per-entity.

Method	Description
`getSlotLimit(LivingEntity, String slotId)`	Returns the maximum number of items the entity can hold in the specified slot.
`addSlotLimit(LivingEntity, String slotId, int amount)`	Increases the capacity of the specified slot.
`removeSlotLimit(LivingEntity, String slotId, int amount)`	Decreases the capacity of the specified slot.
`setSlotLimit(LivingEntity, String slotId, int amount)`	Explicitly sets the capacity of the specified slot.

Utilities and Validation

These methods allow you to query the global configuration of the Relique ecosystem and validate items against slot rules.

Method	Description
`isValid(LivingEntity, String slotId, ItemStack)`	Runs the item through all registered `RelicValidator` logic for the specified slot. Returns `true` if the item is permitted to be equipped.
`getAvailableSlots()`	Returns a sorted list of all registered slot IDs across all loaded namespaces.
`getSlotDefinition(String slotId)`	Returns the immutable `RelicSlot` configuration record (containing the drop rule, order, base size, and icon) for a specific ID.

07 May 2026