AtoCustomAttributes

A powerful and flexible Minecraft (Bukkit/Spigot/Paper) plugin that allows server administrators to create and manage fully custom attributes for in-game items. Go beyond vanilla enchantments and create a truly unique item system for your server.

Features

• Dynamic Attribute Creation: Define your own attributes with various types (e.g., numeric, percentage, text) directly through simple configuration files. No coding required.
• Automatic Item Decoration: Attributes are seamlessly displayed on items, primarily by adding formatted lines to the item's lore. Customize the text, colors, and format.
• Conditional Placeholders: A powerful feature that allows lore text to change dynamically based on an attribute's value. For example, you can show different text or colors if a value is within a specific range (e.g., "Damage: +10" vs. "&c&lDamage: +50 [MAX]").
• Developer API: A clean and well-documented API is available for other plugins to interact with, allowing them to read, add, or modify custom attributes on items.
• Admin Commands: Easy-to-use in-game commands for reloading the configuration and managing attributes on the fly.

How it Works

The plugin works by reading attribute definitions from a configuration file. When an item is recognized as having custom attributes, the plugin automatically applies the configured decorators, usually by modifying the item's lore to display the attribute information.

Configuration Example

Attributes are defined in config.yml. You can specify the type, display name, and how it should be formatted in the item's lore.

# Example from config.yml

attributes:
  # A simple numeric attribute
  strength:
    type: "NUMBER"
    display-name: "Strength"
    # The {value} placeholder will be replaced with the attribute's numeric value
    lore-format: "&c+{value} Strength"

  # A percentage-based attribute
  fire-resistance:
    type: "PERCENTAGE"
    display-name: "Fire Resistance"
    lore-format: "&e{value}% Fire Resistance"
  
  # An attribute that uses different text based on the value
  critical-chance:
    type: "NUMBER"
    display-name: "Critical Chance"
    # This example requires setting up conditional placeholders
    lore-format: "&bCritical Chance: &f{value}% {conditions.crit_tier}"

Commands

The following are the primary administrative commands:

• /atoattributes reload - Reloads the plugin's configuration files.
• /atoattributes set <attribute_id> <value> - Sets a custom attribute for the item you are currently holding.
• /atoattributes remove <attribute_id> - Removes a custom attribute from the item you are currently holding.

(Note: Exact command syntax may vary. Use /atoattributes help for details).

Developer API

To use the API in your own plugin, first add AtoCustomAttributes as a dependency. Then, you can access the API to manipulate attributes on items.

API Usage Example

Here is a simple example of how to read a custom attribute from an item a player is holding.

import pl.acctualy.atoCustomAttribute.api.AtoCustomAttributeAPI;
import pl.acctualy.atoCustomAttribute.api.attribute.Attribute;
import pl.acctualy.atoCustomAttribute.api.attribute.AttributedItem;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;

public class MyPluginIntegration {

    public void checkStrengthAttribute(Player player) {
        // Get the API instance
        AtoCustomAttributeAPI api = AtoCustomAttributeAPI.getInstance();

        ItemStack itemInHand = player.getInventory().getItemInMainHand();
        if (itemInHand == null) {
            return;
        }

        // Get the AttributedItem wrapper for the ItemStack
        AttributedItem attributedItem = api.getAttributedItem(itemInHand);

        // Check if the item has the "strength" attribute
        if (attributedItem.hasAttribute("strength")) {
            Attribute strengthAttribute = attributedItem.getAttribute("strength");
            
            // Get the value as a number
            double strengthValue = strengthAttribute.asNumber();
            
            player.sendMessage("Your item has a Strength of " + strengthValue + "!");
        } else {
            player.sendMessage("Your item has no Strength attribute.");
        }
    }
}

Building from Source

This project uses Gradle to manage dependencies and build.

1. Clone the repository: git clone <repository_url>
2. Navigate to the project directory: cd AtoCustomAttributes
3. Run the build command: ./gradlew build

The compiled JAR file will be located in the plugin/build/libs/ directory.