From 3597af34f9d59d3749204b5d074adf490dbc5667 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=ABsFot?= Date: Tue, 17 Nov 2020 15:52:20 +0100 Subject: [PATCH] Add comments to attribute system --- .../minestom/server/attribute/Attribute.java | 65 +++++++++++++++++++ .../server/attribute/AttributeInstance.java | 51 +++++++++++++++ .../server/attribute/AttributeModifier.java | 38 +++++++++++ .../minestom/server/attribute/Attributes.java | 7 ++ .../minestom/server/entity/LivingEntity.java | 5 ++ 5 files changed, 166 insertions(+) diff --git a/src/main/java/net/minestom/server/attribute/Attribute.java b/src/main/java/net/minestom/server/attribute/Attribute.java index 2e4c9903a..071431083 100644 --- a/src/main/java/net/minestom/server/attribute/Attribute.java +++ b/src/main/java/net/minestom/server/attribute/Attribute.java @@ -6,6 +6,9 @@ import java.util.Map; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +/** + * Represent a {@link net.minestom.server.entity.LivingEntity living entity} attribute. + */ public class Attribute { private static final Map ATTRIBUTES = new HashMap<>(); @@ -15,10 +18,28 @@ public class Attribute { private final float maxValue; private final boolean shareWithClient; + /** + * Create a new attribute with a given key and default. + *

+ * By default, this attribute will be sent to the client. + *

+ * + * @param key the attribute registry key + * @param defaultValue the default value + * @param maxValue the maximum allowed value + */ public Attribute(@NotNull String key, float defaultValue, float maxValue) { this(key, true, defaultValue, maxValue); } + /** + * Create a new attribute with a given key and default. + * + * @param key the attribute registry key + * @param shareWithClient whether to send this attribute to the client + * @param defaultValue the default value + * @param maxValue the maximum allowed value + */ public Attribute(@NotNull String key, boolean shareWithClient, float defaultValue, float maxValue) { if (defaultValue > maxValue) { throw new IllegalArgumentException("Default value cannot be greater than the maximum allowed"); @@ -29,39 +50,83 @@ public class Attribute { this.maxValue = maxValue; } + /** + * Gets the attribute unique key. + * + * @return the attribute key + */ @NotNull public String getKey() { return key; } + /** + * Gets the attribute default value that should be applied. + * + * @return the attribute default value + */ public float getDefaultValue() { return defaultValue; } + /** + * Gets the maximum value applicable to an entity for this attribute. + * + * @return the maximum value of this attribute + */ public float getMaxValue() { return maxValue; } + /** + * Gets whether this attribute's instances should be sent to clients. + * + * @return if this attribute is to be shared + */ public boolean isShared() { return shareWithClient; } + /** + * Register this attribute. + * + * @see #fromKey(String) + * @see #values() + * + * @return this attribute + */ @NotNull public Attribute register() { ATTRIBUTES.put(key, this); return this; } + /** + * Retrieves an attribute by its key. + * + * @param key the key of the attribute + * @return the attribute for the key or null if not any + */ @Nullable public static Attribute fromKey(@NotNull String key) { return ATTRIBUTES.get(key); } + /** + * Retrieves all registered attributes. + * + * @return an array containing all registered attributes + */ @NotNull public static Attribute[] values() { return ATTRIBUTES.values().toArray(new Attribute[0]); } + /** + * Retrieves registered attributes that are shared with the client. + * + * @return an array containing registered, sharable attributes + */ @NotNull public static Attribute[] sharedAttributes() { return ATTRIBUTES.values().stream().filter(Attribute::isShared).toArray(Attribute[]::new); diff --git a/src/main/java/net/minestom/server/attribute/AttributeInstance.java b/src/main/java/net/minestom/server/attribute/AttributeInstance.java index a34aac776..f20e94cba 100644 --- a/src/main/java/net/minestom/server/attribute/AttributeInstance.java +++ b/src/main/java/net/minestom/server/attribute/AttributeInstance.java @@ -9,6 +9,9 @@ import java.util.function.Consumer; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +/** + * Represents an instance of an attribute and its modifiers. + */ public class AttributeInstance { private final Attribute attribute; @@ -24,15 +27,31 @@ public class AttributeInstance { this.baseValue = attribute.getDefaultValue(); } + /** + * Gets the attribute associated to this instance. + * + * @return the associated attribute + */ @NotNull public Attribute getAttribute() { return attribute; } + /** + * The base value of this instance without modifiers + * + * @see #setBaseValue(float) + * + * @return the instance base value + */ public float getBaseValue() { return baseValue; } + /** + * Sets this instance dirty to trigger calculation of the new value. + * Triggers the {@link #propertyChangeListener}. + */ private void setDirty() { if (!dirty) { dirty = true; @@ -42,6 +61,13 @@ public class AttributeInstance { } } + /** + * Sets the base value of this instance. + * + * @see #getBaseValue() + * + * @param baseValue the new base value + */ public void setBaseValue(float baseValue) { if (this.baseValue != baseValue) { this.baseValue = baseValue; @@ -49,22 +75,42 @@ public class AttributeInstance { } } + /** + * Add a modifier to this instance. + * + * @param modifier the modifier to add + */ public void addModifier(@NotNull AttributeModifier modifier) { if (modifiers.putIfAbsent(modifier.getId(), modifier) == null) { setDirty(); } } + /** + * Remove a modifier from this instance. + * + * @param modifier the modifier to remove + */ public void removeModifier(@NotNull AttributeModifier modifier) { if (modifiers.remove(modifier.getId()) != null) { setDirty(); } } + /** + * Get the modifiers applied to this instance. + * + * @return the modifiers. + */ public Collection getModifiers() { return modifiers.values(); } + /** + * Gets the value of this instance calculated with modifiers applied. + * + * @return the attribute value + */ public float getValue() { if (dirty) { cachedValue = processModifiers(); @@ -73,6 +119,11 @@ public class AttributeInstance { return cachedValue; } + /** + * Recalculate the value of this attribute instance using the modifiers. + * + * @return the attribute value + */ protected float processModifiers() { float base = getBaseValue(); diff --git a/src/main/java/net/minestom/server/attribute/AttributeModifier.java b/src/main/java/net/minestom/server/attribute/AttributeModifier.java index 537603db5..566ca8a44 100644 --- a/src/main/java/net/minestom/server/attribute/AttributeModifier.java +++ b/src/main/java/net/minestom/server/attribute/AttributeModifier.java @@ -6,6 +6,9 @@ import io.netty.util.internal.ThreadLocalRandom; import net.minestom.server.utils.UniqueIdUtils; import org.jetbrains.annotations.NotNull; +/** + * Represent an attribute modifier. + */ public class AttributeModifier { private final float amount; @@ -13,10 +16,25 @@ public class AttributeModifier { private final AttributeOperation operation; private final UUID id; + /** + * Creates a new modifier with a random id. + * + * @param name the name of this modifier + * @param amount the value of this modifier + * @param operation the operation to apply this modifier with + */ public AttributeModifier(@NotNull String name, float amount, @NotNull AttributeOperation operation) { this(UniqueIdUtils.createRandomUUID(ThreadLocalRandom.current()), name, amount, operation); } + /** + * Creates a new modifier. + * + * @param id the id of this modifier + * @param name the name of this modifier + * @param amount the value of this modifier + * @param operation the operation to apply this modifier with + */ public AttributeModifier(@NotNull UUID id, @NotNull String name, float amount, @NotNull AttributeOperation operation) { this.id = id; this.name = name; @@ -24,20 +42,40 @@ public class AttributeModifier { this.operation = operation; } + /** + * Gets the id of this modifier. + * + * @return the id of this modifier + */ @NotNull public UUID getId() { return id; } + /** + * Gets the name of this modifier. + * + * @return the name of this modifier + */ @NotNull public String getName() { return name; } + /** + * Gets the value of this modifier. + * + * @return the value of this modifier + */ public float getAmount() { return amount; } + /** + * Gets the operation of this modifier. + * + * @return the operation of this modifier + */ @NotNull public AttributeOperation getOperation() { return operation; diff --git a/src/main/java/net/minestom/server/attribute/Attributes.java b/src/main/java/net/minestom/server/attribute/Attributes.java index 07eb2ccc4..a2c2b8ce1 100644 --- a/src/main/java/net/minestom/server/attribute/Attributes.java +++ b/src/main/java/net/minestom/server/attribute/Attributes.java @@ -1,5 +1,8 @@ package net.minestom.server.attribute; +/** + * The Minecraft, vanilla, standards attributes. + */ public final class Attributes { public static final Attribute MAX_HEALTH = (new Attribute("generic.max_health", true, 20, 1024)).register(); @@ -15,4 +18,8 @@ public final class Attributes public static final Attribute LUCK = (new Attribute("generic.luck", true, 0, 1024)).register(); public static final Attribute HORSE_JUMP_STRENGTH = (new Attribute("horse.jump_strength", true, 0.7f, 2)).register(); public static final Attribute ZOMBIE_SPAWN_REINFORCEMENTS = (new Attribute("zombie.spawn_reinforcements", true, 0, 1)).register(); + + private Attributes() throws IllegalAccessException { + throw new IllegalAccessException("Cannot instantiate a static class"); + } } diff --git a/src/main/java/net/minestom/server/entity/LivingEntity.java b/src/main/java/net/minestom/server/entity/LivingEntity.java index b50c7931b..c9df6ee46 100644 --- a/src/main/java/net/minestom/server/entity/LivingEntity.java +++ b/src/main/java/net/minestom/server/entity/LivingEntity.java @@ -405,6 +405,11 @@ public abstract class LivingEntity extends Entity implements EquipmentHandler { return attributeModifiers.get(attribute.getKey()); } + /** + * Callback used when an attribute instance has been modified. + * + * @param instance the modified attribute instance + */ protected void onAttributeChanged(@NotNull AttributeInstance instance) { } /**