Skip to content

Commit

Permalink
better attribute modifiers docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mcmonkey4eva
mcmonkey4eva committed Aug 30, 2021
1 parent 848b41f commit 24a832a
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 16 deletions.
5 changes: 5 additions & 0 deletions ...n/java/com/denizenscript/denizen/objects/properties/entity/EntityAttributeBaseValues.java
View file
Expand Up @@ -82,6 +82,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// @description
// Returns whether the entity has the named attribute.
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("has_attribute") && attribute.hasContext(1)) {
AttributeInstance instance = ((Attributable) entity.getBukkitEntity()).getAttribute(
Expand All @@ -98,6 +99,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// Returns the final calculated value of the named attribute for the entity.
// See also <@link tag EntityTag.has_attribute>.
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("attribute_value") && attribute.hasContext(1)) {
org.bukkit.attribute.Attribute attr = org.bukkit.attribute.Attribute.valueOf(attribute.getContext(1).toUpperCase());
Expand All @@ -118,6 +120,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// Returns the base value of the named attribute for the entity.
// See also <@link tag EntityTag.has_attribute>.
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("attribute_base_value") && attribute.hasContext(1)) {
org.bukkit.attribute.Attribute attr = org.bukkit.attribute.Attribute.valueOf(attribute.getContext(1).toUpperCase());
Expand All @@ -138,6 +141,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// Returns the default value of the named attribute for the entity.
// See also <@link tag EntityTag.has_attribute>.
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("attribute_default_value") && attribute.hasContext(1)) {
org.bukkit.attribute.Attribute attr = org.bukkit.attribute.Attribute.valueOf(attribute.getContext(1).toUpperCase());
Expand All @@ -163,6 +167,7 @@ public void adjust(Mechanism mechanism) {
// Sets the base value of an entity's attributes.
// Specify a MapTag where the keys are attribute names, and values are the new base values.
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// See also <@link language attribute modifiers>.
// @tags
// <EntityTag.has_attribute>
// <EntityTag.attribute_default_value>
Expand Down
52 changes: 44 additions & 8 deletions ...in/java/com/denizenscript/denizen/objects/properties/entity/EntityAttributeModifiers.java
View file
Expand Up @@ -166,6 +166,46 @@ public String getPropertyId() {
return "attribute_modifiers";
}


// <--[language]
// @name Attribute Modifiers
// @group Properties
// @description
// In minecraft, the "attributes" system defined certain core numerical values on entities, such as max health or attack damage.
// The value of an "attribute" is determined by its "base value" modified mathematically by each of its "attribute modififers".
// "Attribute modifiers" can be added either directly to the entity, or onto items - when on an item, an entity can equip it into the correct slot to automatically apply the modifier.
//
// These can be read via such tags as <@link tag EntityTag.attribute_modifiers>, <@link tag ItemTag.attribute_modifiers>,
// <@link tag EntityTag.has_attribute>, <@link tag EntityTag.attribute_value>, <@link tag EntityTag.attribute_base_value>, <@link tag EntityTag.attribute_default_value>, ...
//
// These can be modified by such mechanisms as <@link mechanism EntityTag.attribute_base_values>, <@link mechanism EntityTag.attribute_modifiers>, <@link mechanism EntityTag.add_attribute_modifiers>,
// <@link mechanism EntityTag.remove_attribute_modifiers>, <@link mechanism ItemTag.attribute_modifiers>, <@link mechanism ItemTag.add_attribute_modifiers>, <@link mechanism ItemTag.remove_attribute_modifiers>, ...
//
// The input format of each of the 'add' and set mechanisms is slightly complicated: a MapTag where the keys are attribute names, and values are a ListTag of modifiers,
// where each modifier is itself a MapTag with required keys 'operation' and 'amount', and optional keys 'name', 'slot', and 'id'.
//
// Valid operations: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1
// Valid slots: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// The default ID will be randomly generated, the default name will be the attribute name, the default slot is any.
//
// For a quick and dirty in-line input, you can do for example: [generic_max_health=<list[<map[operation=ADD_NUMBER;amount=20;slot=HEAD]>]>]
//
// For more clean/proper input, instead do something like:
// <code>
// - definemap attributes:
// generic_max_health:
// 1:
// operation: ADD_NUMBER
// amount: 20
// slot: head
// - inventory adjust slot:head add_attribute_modifiers:<[attributes]>
// </code>
//
// When pre-defining a custom item, instead of any of this, simply use an item script: <@link language item script containers>. That page shows an example of valid attribute modifiers on an item script.
//
// -->

@Override
public ObjectTag getObjectAttribute(Attribute attribute) {

Expand All @@ -182,6 +222,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// Returns a map of all attribute modifiers on the entity, with key as the attribute name and value as a list of modifiers,
// where each modifier is a MapTag containing keys 'name', 'amount', 'slot', 'operation', and 'id'.
// This is formatted in a way that can be sent back into the 'attribute_modifiers' mechanism.
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("attribute_modifiers")) {
return getAttributeModifiers().getObjectAttribute(attribute.fulfill(1));
Expand Down Expand Up @@ -225,13 +266,7 @@ public void adjust(Mechanism mechanism) {
// @description
// Sets the attribute modifiers of an entity.
// This is a SET operation, meaning pre-existing modifiers are removed.
// Specify a MapTag where the keys are attribute names, and values are a ListTag of modifiers (or a numbered-index MapTag),
// where each modifier is itself a MapTag with required keys 'operation' and 'amount', and optional keys 'name', 'slot', and 'id'.
// Valid operations: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1
// Valid slots: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// The default ID will be randomly generated, the default name will be the attribute name, the default slot is any.
// Example of valid input: [generic_max_health=<list[<map[operation=ADD_NUMBER;amount=20]>]>]
// For input format details, refer to <@link language attribute modifiers>.
// @tags
// <EntityTag.has_attribute>
// <EntityTag.attribute_modifiers>
Expand Down Expand Up @@ -267,7 +302,7 @@ public void adjust(Mechanism mechanism) {
// @input MapTag
// @description
// Adds attribute modifiers to an entity without altering existing modifiers.
// All input is the same as <@link mechanism EntityTag.attribute_modifiers>.
// For input format details, refer to <@link language attribute modifiers>.
// @tags
// <EntityTag.has_attribute>
// <EntityTag.attribute_modifiers>
Expand Down Expand Up @@ -300,6 +335,7 @@ public void adjust(Mechanism mechanism) {
// @input ListTag
// @description
// Removes attribute modifiers from an entity. Specify a list of attribute names or modifier UUIDs as input.
// See also <@link language attribute modifiers>.
// @tags
// <EntityTag.has_attribute>
// <EntityTag.attribute_modifiers>
Expand Down
12 changes: 4 additions & 8 deletions ...c/main/java/com/denizenscript/denizen/objects/properties/item/ItemAttributeModifiers.java
View file
Expand Up @@ -89,6 +89,7 @@ public ObjectTag getObjectAttribute(Attribute attribute) {
// Returns a map of all attribute modifiers on the item, with key as the attribute name and value as a list of modifiers,
// where each modifier is a MapTag containing keys 'name', 'amount', 'slot', 'operation', and 'id'.
// This is formatted in a way that can be sent back into the 'attribute_modifiers' mechanism.
// See also <@link language attribute modifiers>.
// -->
if (attribute.startsWith("attribute_modifiers")) {
return getAttributeModifiers().getObjectAttribute(attribute.fulfill(1));
Expand Down Expand Up @@ -121,13 +122,7 @@ public void adjust(Mechanism mechanism) {
// @description
// Sets the attribute modifiers of an item.
// This is a SET operation, meaning pre-existing modifiers are removed.
// Specify a MapTag where the keys are attribute names, and values are a ListTag of modifiers,
// where each modifier is itself a MapTag with required keys 'operation' and 'amount', and optional keys 'name', 'slot', and 'id'.
// Valid operations: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1
// Valid slots: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY
// Valid attribute names are listed at <@link url https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html>
// The default ID will be randomly generated, the default name will be the attribute name, the default slot is any.
// Example of valid input: [generic_max_health=<list[<map[operation=ADD_NUMBER;amount=20;slot=HEAD]>]>]
// For input format details, refer to <@link language attribute modifiers>.
// @tags
// <ItemTag.attribute_modifiers>
// -->
Expand All @@ -149,7 +144,7 @@ public void adjust(Mechanism mechanism) {
// @input MapTag
// @description
// Adds attribute modifiers to an item without altering existing modifiers.
// All input is the same as <@link mechanism ItemTag.attribute_modifiers>.
// For input format details, refer to <@link language attribute modifiers>.
// @tags
// <ItemTag.attribute_modifiers>
// -->
Expand All @@ -169,6 +164,7 @@ public void adjust(Mechanism mechanism) {
// @input ListTag
// @description
// Removes attribute modifiers from an item. Specify a list of attribute names or modifier UUIDs as input.
// See also <@link language attribute modifiers>.
// @tags
// <ItemTag.attribute_modifiers>
// -->
Expand Down

0 comments on commit 24a832a

Please sign in to comment.