Skip to main content

API: Item Management

Methods for validating and working with items.

Item Validation​

validateItem​

Validate if an item matches order requirements.

Signature:

boolean validateItem(ItemStack item, OrderItem orderItem)

Parameters:

  • item - The item to validate
  • orderItem - The order item to match against

Returns: true if item matches, false otherwise

Example:

OrderItem orderItem = order.getItems().get(0);
ItemStack playerItem = player.getInventory().getItemInMainHand();

if (ordersAPI.validateItem(playerItem, orderItem)) {
    // Item matches order requirements
    player.sendMessage("Item is valid for this order!");
} else {
    // Item doesn't match
    player.sendMessage("Item doesn't match order requirements!");
}

Validation Checks:

  • Material matches
  • Enchantments match (if specified)
  • Custom item ID matches (if ItemsAdder item)

NBT Data​

hasNBTData​

Check if an item has NBT data.

Signature:

boolean hasNBTData(ItemStack item)

Parameters:

  • item - The item to check

Returns: true if item has NBT data, false otherwise

Example:

ItemStack item = player.getInventory().getItemInMainHand();

if (ordersAPI.hasNBTData(item)) {
    // Item has custom name, lore, enchantments, etc.
    player.sendMessage("Item has NBT data!");
}

Inventory Operations​

countItems​

Count items of a specific material in an inventory.

Signature:

int countItems(Inventory inventory, Material material)

Parameters:

  • inventory - The inventory to check
  • material - The material to count

Returns: Total count of items

Example:

int diamondCount = ordersAPI.countItems(
    player.getInventory(),
    Material.DIAMOND
);

player.sendMessage("You have " + diamondCount + " diamonds");

removeItems​

Remove items from an inventory.

Signature:

int removeItems(Inventory inventory, Material material, int amount)

Parameters:

  • inventory - The inventory to remove from
  • material - The material to remove
  • amount - Amount to remove

Returns: Amount actually removed

Example:

int removed = ordersAPI.removeItems(
    player.getInventory(),
    Material.DIAMOND,
    64
);

if (removed == 64) {
    player.sendMessage("Removed 64 diamonds");
} else {
    player.sendMessage("Only removed " + removed + " diamonds");
}

Complete Example​

// Get order
CompletableFuture<Order> orderFuture = ordersAPI.getOrder(orderId);

orderFuture.thenAccept(order -> {
    if (order == null) {
        player.sendMessage("Order not found!");
        return;
    }
    
    OrderItem orderItem = order.getItems().get(0);
    Inventory inventory = player.getInventory();
    
    // Count available items
    int available = ordersAPI.countItems(
        inventory,
        orderItem.getMaterial()
    );
    
    if (available < orderItem.getAmount()) {
        player.sendMessage("Not enough items! Need " + 
            orderItem.getAmount() + ", have " + available);
        return;
    }
    
    // Validate item
    ItemStack item = inventory.getItemInMainHand();
    if (!ordersAPI.validateItem(item, orderItem)) {
        player.sendMessage("Item doesn't match order!");
        return;
    }
    
    // Remove items
    int removed = ordersAPI.removeItems(
        inventory,
        orderItem.getMaterial(),
        orderItem.getAmount()
    );
    
    // Deliver items
    ordersAPI.deliverItems(
        orderId,
        orderItem.getId(),
        removed,
        player.getUniqueId(),
        player.getName()
    ).thenAccept(success -> {
        if (success) {
            player.sendMessage("Delivered " + removed + " items!");
        }
    });
});

Best Practices​

  1. Validate Before Operations: Always validate items before processing
  2. Check Inventory: Verify items exist before removal
  3. Handle Partial Removal: removeItems may remove less than requested
  4. NBT Awareness: Be aware of NBT data when validating items
  5. Error Handling: Handle validation failures gracefully