diff --git a/java/noppes/npcs/api/entity/IPlayer.java b/java/noppes/npcs/api/entity/IPlayer.java index eb0478c..b3ee09a 100644 --- a/java/noppes/npcs/api/entity/IPlayer.java +++ b/java/noppes/npcs/api/entity/IPlayer.java @@ -657,4 +657,11 @@ public interface IPlayer extends IEntityLivingBase, * @return The magic data. */ IMagicData getMagicData(); + + /** + * Returns the player's item attribute combination + * + * @return Player Attributes Data + */ + IPlayerAttributes getAttributes(); } diff --git a/java/noppes/npcs/api/handler/IAttributeHandler.java b/java/noppes/npcs/api/handler/IAttributeHandler.java new file mode 100644 index 0000000..0ff0068 --- /dev/null +++ b/java/noppes/npcs/api/handler/IAttributeHandler.java @@ -0,0 +1,40 @@ +package noppes.npcs.api.handler; + +import noppes.npcs.api.entity.IPlayer; +import noppes.npcs.api.handler.data.IAttributeDefinition; +import noppes.npcs.api.handler.data.IPlayerAttributes; + +/** + * Handles registration and lookup of attribute definitions as well as + * retrieval of player attributes. + *

+ * Maintain a unique registry of attribute definitions and provide methods to + * retrieve a player's aggregated attributes. + *

+ */ +public interface IAttributeHandler { + + /** + * Returns the aggregated attributes for a given player. + * + * @param player the player whose attributes are requested + * @return an {@link IPlayerAttributes} instance containing all custom attributes for the player, + * or null if the player is invalid + */ + IPlayerAttributes getPlayerAttributes(IPlayer player); + + /** + * Returns the attribute definition corresponding to the given key. + * + * @param key the unique key identifying the attribute (e.g., "health", "movement_speed") + * @return the {@link IAttributeDefinition} instance for the specified key, or null if not found + */ + IAttributeDefinition getAttributeDefinition(String key); + + /** + * Returns an array of all registered attribute definitions. + * + * @return an array of {@link IAttributeDefinition} objects representing all attributes + */ + IAttributeDefinition[] getAllAttributesArray(); +} diff --git a/java/noppes/npcs/api/handler/data/IAttributeDefinition.java b/java/noppes/npcs/api/handler/data/IAttributeDefinition.java new file mode 100644 index 0000000..115f683 --- /dev/null +++ b/java/noppes/npcs/api/handler/data/IAttributeDefinition.java @@ -0,0 +1,39 @@ +package noppes.npcs.api.handler.data; + +/** + * Defines the blueprint for an attribute. + *

+ * An attribute definition contains identifying information such as a unique key, + * a human-readable display name, a translation key for localization, and a color code. + *

+ */ +public interface IAttributeDefinition { + + /** + * Returns the unique key that identifies this attribute. + * + * @return a String representing the attribute key + */ + String getKey(); + + /** + * Returns the human-readable display name for this attribute. + * + * @return a String representing the display name + */ + String getDisplayName(); + + /** + * Returns the translation key used for localizing this attribute. + * + * @return a String representing the translation key + */ + String getTranslationKey(); + + /** + * Returns the color code associated with this attribute. + * + * @return a char representing the color code + */ + char getColorCode(); +} diff --git a/java/noppes/npcs/api/handler/data/ICustomAttribute.java b/java/noppes/npcs/api/handler/data/ICustomAttribute.java new file mode 100644 index 0000000..e85e903 --- /dev/null +++ b/java/noppes/npcs/api/handler/data/ICustomAttribute.java @@ -0,0 +1,25 @@ +package noppes.npcs.api.handler.data; + +/** + * Represents an instance of a custom attribute. + *

+ * A custom attribute instance encapsulates an {@link IAttributeDefinition} + * along with its current calculated value (which may be affected by modifiers). + *

+ */ +public interface ICustomAttribute { + + /** + * Returns the attribute definition associated with this custom attribute. + * + * @return the {@link IAttributeDefinition} instance defining this attribute + */ + IAttributeDefinition getAttribute(); + + /** + * Returns the current value of this attribute. + * + * @return the float value representing the attribute's current state + */ + float getValue(); +} diff --git a/java/noppes/npcs/api/handler/data/IPlayerAttributes.java b/java/noppes/npcs/api/handler/data/IPlayerAttributes.java new file mode 100644 index 0000000..c0855c0 --- /dev/null +++ b/java/noppes/npcs/api/handler/data/IPlayerAttributes.java @@ -0,0 +1,49 @@ +package noppes.npcs.api.handler.data; + +import noppes.npcs.api.entity.IPlayer; + +/** + * Represents a collection of a player's custom attributes. + *

+ * Expose methods to retrieve all attribute instances as an array, look up individual attributes by key, + * and check for the presence of a specific attribute. + *

+ */ +public interface IPlayerAttributes { + + /** + * Recalulates Item Attributes on a Player + */ + void recalculate(IPlayer player); + + /** + * Returns an array of all custom attribute instances associated with the player. + * + * @return an array of {@link ICustomAttribute} objects + */ + ICustomAttribute[] getAttributes(); + + /** + * Returns the value of the attribute identified by the given key. + * + * @param key the attribute key (e.g., "health", "movement_speed") + * @return the float value of the attribute, or 0 if the attribute is not found + */ + float getAttributeValue(String key); + + /** + * Checks whether an attribute with the given key exists. + * + * @param key the attribute key to check + * @return true if the attribute exists, false otherwise + */ + boolean hasAttribute(String key); + + /** + * Returns the custom attribute instance identified by the given key. + * + * @param key the attribute key (e.g., "health", "movement_speed") + * @return the corresponding {@link ICustomAttribute} instance, or null if not found + */ + ICustomAttribute getAttribute(String key); +} diff --git a/java/noppes/npcs/api/item/IItemStack.java b/java/noppes/npcs/api/item/IItemStack.java index 84991cc..38aed83 100644 --- a/java/noppes/npcs/api/item/IItemStack.java +++ b/java/noppes/npcs/api/item/IItemStack.java @@ -4,144 +4,381 @@ import net.minecraft.item.ItemStack; import net.minecraft.nbt.NBTTagCompound; import noppes.npcs.api.INbt; +/** + * Represents an item stack with extended functionality: + * enchantments, lore, and additional item data. + */ public interface IItemStack { String getName(); /** - * @return Returns the stacksize + * @return Returns the stack size. */ int getStackSize(); /** - * @return Return whether the item has a custom name + * @return Returns whether the item has a custom name. */ boolean hasCustomName(); /** - * @param name The custom name this item will get + * Sets the custom name for the item. + * + * @param name The custom name. */ void setCustomName(String name); /** - * @return Return the ingame displayed name. This is either the item name or the custom name if it has one. + * @return Returns the in-game displayed name. This is either the item name or the custom name if set. */ String getDisplayName(); /** - * @return Get the items ingame name. Use this incase the item ingame has custom name and you want the original name. + * @return Returns the base item name, regardless of any custom name. */ String getItemName(); /** - * @param size The size of the itemstack. A number between 1 and 64 + * Sets the stack size of the item. + * + * @param size The new stack size (between 1 and 64). */ void setStackSize(int size); + /** + * @return Returns the maximum stack size for this item. + */ int getMaxStackSize(); /** - * @return Returns the item damage of this item. For tools this is the durability for other items the color and more. + * @return Returns the item damage. For tools, this represents durability. */ int getItemDamage(); /** - * @param value The value to be set as item damage. For tools this is the durability for other items the color and more. + * Sets the item damage value. + * + * @param value The new damage value. */ void setItemDamage(int value); /** - * @param key The key of this NBTTag - * @param value The value to be stored. Can be a Number or String + * Sets an NBT tag for this item. + * + * @param key The tag key. + * @param value The value to store (Number or String). */ void setTag(String key, Object value); /** - * @param key The key of the NBTTag - * @return Returns whether or not the key exists + * Checks if the item has an NBT tag with the specified key. + * + * @param key The tag key. + * @return true if present, false otherwise. */ boolean hasTag(String key); /** - * @param key The key of the NBTTag - * @return Returns the value associated with the key. Returns null of it doesnt exist + * Returns the value of the NBT tag with the specified key. + * + * @param key The tag key. + * @return The tag value, or null if not present. */ Object getTag(String key); + /** + * Removes all custom tags from the item and returns the removed NBT data. + * + * @return The removed NBT data. + */ INbt removeTags(); + /** + * @return Returns whether the item is enchanted. + */ boolean isEnchanted(); /** - * @since 1.7.10d - * @param id The enchantment id - * @return + * Checks if the item has the specified enchantment. + * + * @param id The enchantment id. + * @return true if present, false otherwise. */ boolean hasEnchant(int id); + /** + * Adds an enchantment to the item. + * + * @param id The enchantment id. + * @param strength The enchantment strength. + */ void addEnchant(int id, int strength); + // --- Default MC Attribute Handling (legacy) --- + + /** + * Sets an attribute on the item using the default MC attribute system. + * + * @param name The attribute key. + * @param value The attribute value. + */ void setAttribute(String name, double value); + /** + * Retrieves the attribute value using the default MC attribute system. + * + * @param name The attribute key. + * @return The attribute value. + */ double getAttribute(String name); - String[] getLore(); - - boolean hasLore(); - - void setLore(String[] lore); - + /** + * Checks if the item has an attribute (using the default MC attribute system). + * + * @param name The attribute key. + * @return true if present, false otherwise. + */ boolean hasAttribute(String name); + + /** + * Sets the custom attribute value for the given key. + * The value is stored in the item's custom NBT structure. + * + * @param key The custom attribute key. + * @param value The attribute value. + */ + void setCustomAttribute(String key, double value); + + + /** + * Checks whether the item has a custom attribute with the specified key. + * + * @param key The custom attribute key. + * @return true if the attribute exists, false otherwise. + */ + boolean hasCustomAttribute(String key); + + /** + * Returns the custom attribute object associated with the given key. + * This may be a raw value or a more complex structure. + * + * @param key The custom attribute key. + * @return The attribute object value + */ + float getCustomAttribute(String key); + + /** + * Removes the custom attribute with the specified key from the item. + * + * @param key The custom attribute key. + */ + void removeCustomAttribute(String key); + + /** + * Sets the magic attribute value for the given key and magic identifier. + * The value is stored in the item's custom NBT under "RPGCore" -> "Magic". + * + * @param key The magic attribute key. + * @param magicId The magic identifier. + * @param value The attribute value. + */ + void setMagicAttribute(String key, int magicId, double value); + + + /** + * Checks whether the item has a magic attribute with the given key and magic identifier. + * + * @param key The magic attribute key. + * @param magicId The magic identifier. + * @return true if the attribute exists, false otherwise. + */ + boolean hasMagicAttribute(String key, int magicId); + + /** + * Returns the magic attribute object (typically a Float value) associated with the given key and magic identifier. + * + * @param key The magic attribute key. + * @param magicId The magic identifier. + * @return The attribute object, or null if not present. + */ + float getMagicAttribute(String key, int magicId); + + /** + * Removes the magic attribute with the specified key and magic identifier from the item. + * + * @param key The magic attribute key. + * @param magicId The magic identifier. + */ + void removeMagicAttribute(String key, int magicId); + + /** + * Sets (or applies) a requirement for the item using the given requirement key and value. + * The requirement data is stored under "RPGCore" → "Requirements" in the item's NBT. + * + * @param reqKey The requirement key. + * @param value The requirement value (Number or String). + */ + void setRequirement(String reqKey, Object value); + + /** + * Checks whether the item has a requirement with the specified key. + * + * @param reqKey The requirement key. + * @return true if the requirement exists, false otherwise. + */ + boolean hasRequirement(String reqKey); + + /** + * Retrieves the requirement value for the specified key. + * + * @param reqKey The requirement key. + * @return The requirement value as an Object (or null if not present). + */ + Object getRequirement(String reqKey); + + /** + * Removes the requirement with the specified key from the item. + * + * @param reqKey The requirement key. + */ + void removeRequirement(String reqKey); + + /** + * Returns an array of all custom attribute keys stored on the item. + * + * @return an array of custom attribute keys. + */ + String[] getCustomAttributeKeys(); + + /** + * Returns an array of all magic attribute keys (as strings) for the specified magic attribute key. + * + * @param key the magic attribute key (e.g. "magic_damage"). + * @return an array of magic identifier keys as strings. + */ + String[] getMagicAttributeKeys(String key); + + /** + * Returns an array of all requirement keys stored on the item. + * + * @return an array of requirement keys. + */ + String[] getRequirementKeys(); + + /** + * @return Returns the lore (descriptive text) for the item. + */ + String[] getLore(); + + /** + * @return Returns whether the item has lore. + */ + boolean hasLore(); + + /** + * Sets the lore for the item. + * + * @param lore An array of lore strings. + */ + void setLore(String[] lore); + + /** + * Creates a deep copy of this item stack. + * + * @return A copy of the item stack. + */ IItemStack copy(); + /** + * @return Returns the maximum damage the item can sustain. + */ int getMaxItemDamage(); /** - * @since 1.7.10d - * @return Returns whether this item is a book + * @return Returns whether the item is a written book. */ boolean isWrittenBook(); /** - * @since 1.7.10d - * @return Returns the books title + * @return Returns the book's title. */ String getBookTitle(); /** - * @since 1.7.10d - * @return Returns the books author + * @return Returns the book's author. */ String getBookAuthor(); /** - * @since 1.7.10d - * @return If the item is a book, returns a string array with book pages + * @return If the item is a book, returns the book pages. */ String[] getBookText(); /** - * @return Returns whether or not this item is a block + * @return Returns whether the item represents a block. */ boolean isBlock(); + /** + * Returns an INbt instance representing the item's custom NBT data. + * + * @return The custom NBT data. + */ INbt getNbt(); + /** + * Returns an INbt instance representing the full NBT data of the item. + * + * @return The complete NBT data. + */ INbt getItemNbt(); /** - * No support is given for this method. Dont use if you dont know what you are doing. - * @return Minecraft ItemStack + * Returns the underlying Minecraft ItemStack. + *

No support is given for this method. Use with caution.

+ * + * @return The Minecraft ItemStack. */ ItemStack getMCItemStack(); + /** + * Returns a hash value for the item. + * + * @return The item's hash code. + */ int itemHash(); + /** + * Returns the underlying Minecraft NBTTagCompound for the item. + * + * @return The NBTTagCompound. + */ NBTTagCompound getMCNbt(); + /** + * Sets the underlying Minecraft NBTTagCompound for the item. + * + * @param compound The NBTTagCompound to set. + */ void setMCNbt(NBTTagCompound compound); - public boolean compare(IItemStack item, boolean ignoreNBT); + /** + * Compares this item with another item, with an option to ignore NBT data. + * + * @param item The item to compare. + * @param ignoreNBT true to ignore NBT data. + * @return true if the items are considered equal, false otherwise. + */ + boolean compare(IItemStack item, boolean ignoreNBT); + /** + * Compares this item with another item, with options to ignore damage and/or NBT data. + * + * @param item The item to compare. + * @param ignoreDamage true to ignore damage values. + * @param ignoreNBT true to ignore NBT data. + * @return true if the items are considered equal, false otherwise. + */ boolean compare(IItemStack item, boolean ignoreDamage, boolean ignoreNBT); }