If you create a new entity, you may have stumbled across the Attribute System, for example if you want a custom max. health value.
Now a detailed explanation on what the Attribute System actually is can be found here: http://minecraft.gamepedia.com/Attribute
Here I will show you how to create your own Attributes for your entity and modify all of them in code.
NOTE: all attribute classes mentioned in this tutorial can be found in the package net.minecraft.entity.ai.attributes.
Create a new Attribute
Step 1:
To create a new attribute, you first need to create a new IAttribute instance (preferably static final in your entity registry class or somewhere). Now you don't need to make a new class which implements that interface!
Minecraft provides us with a standard class currently used for all its own Attributes called RangedAttribute. The constructor of that has the following parameters:
IAttribute parentIn - a parent attribute if available, can be null
String unlocalizedNameIn - the unlocalized name of the attribute. You can't add an attribute with the same name to an entity, so I usually precede the name with my Mod ID separated with a dot like TurretMod.MOD_ID + ".maxAmmoCapacity"
double defaultValue - the default value of the attribute. This value is set as base value when the entity is first created. It can't be lower than the minimum nor higher than the maximum value or else it will throw an IllegalArgumentException
double minimumValueIn - the minimum value of the attribute. This value is usually 0.0D. If the entity's attribute value falls below that, this value is used for it instead. It can't be bigger than the maximum value or else it will throw an IllegalArgumentException
double maximumValueIn - the maximum value of the attribute. This value is usually Double.MAX_VALUE. If the entity's attribute value falls above that, this value is used for it instead. It can't be smaller than the minimum value or else it will throw an IllegalArgumentException
Now at the end, my IAttribute instance variable looks like this:
public static final IAttribute MAX_AMMO_CAPACITY = new RangedAttribute(null, TurretMod.MOD_ID + ".maxAmmoCapacity", 256.0D, 0.0D, Double.MAX_VALUE);
But wait! If you want to share the attribute value and modifiers with the client, you'll need to call setShouldWatch(true) on that variable. The same way you can disable it, for whatever reason, with false instead of true as the parameter value. Conveniently it returns itself, so you can make a neat one-liner like this:
public static final IAttribute MAX_AMMO_CAPACITY = new RangedAttribute(null, TurretMod.MOD_ID + ".maxAmmoCapacity", 256.0D, 0.0D, Double.MAX_VALUE).setShouldWatch(true);
Step 2:
Great, now you have this useless variable the entity doesn't know about. To make it useful and working with the entity, you first need to register it to the entity's attribute list. To do so, override applyEntityAttributes()(if you've not already done so while changing the entity's max. health) and call this.getAttributeMap().registerAttribute(MY_OWN_ATTRIBUTE_VARIABLE), where MY_OWN_ATTRIBUTE_VARIABLE is firstly an overly long name, but more importantly your variable of your attribute instance created in Step 1. Here's an example from my mod:
@Override
protected void applyEntityAttributes() {
super.applyEntityAttributes(); // Make sure to ALWAYS call the super method, or else max. health and other attributes from Minecraft aren't registered!!!
this.getAttributeMap().registerAttribute(TurretAttributes.MAX_AMMO_CAPACITY);
}
Step 3:
The attribute is now instanciated and registered, but how do I use its value? Simple! Just call this.getEntityAttribute(MY_OWN_ATTRIBUTE_VARIABLE).getAttributeValue(). It returns a double. If you want it to be an int, just use the MathHelper from Minecraft, for example MathHelper.ceiling_double_int(doubleVal)
Modify an Attribute
Now, to modify an attribute, there are 2 ways of doing so:
1. modify its base value
This is simple and straight forward, and as mentioned 2 times here so far, you may have already done this via the entity's max. health attribute. But to be complete, here's how you change the base value of an attribute with the example on the max. health:
this.getEntityAttribute(SharedMonsterAttributes.maxHealth).setBaseValue(40.0D); //sets the entity max. health to 40 HP (20 hearts)
Please note: this does NOT get synched with the client! If you need to edit the base value, make sure you use packets if you want it to be shared (or change it on both sides). Otherwise use modifiers!
2. add modifiers to the attribute
This is a "reversable" way of changing the attribute value w/o messing with the base value. What we will do here is essentally this: http://minecraft.gamepedia.com/Attribute#Modifiers
That said, much like the Attribute Instance, we need to create our own AttributeModifier instance variable. Conveniently, there is already a class for us to use called AttributeModifier. It's constructor parameters are as follows:
UUID idIn - the UUID of this modifier, much like the Attribute name, this needs to be unique per Attribute. I usually give it a pre-defined, hardcoded Ver. 4 UUID via UUID.fromString("MY-UUID"), which was generated on this site. Mine looks like this:
UUID.fromString("e6107045-134f-4c54-a645-75c3ae5c7a27")
String nameIn - the Modifier name, can be anything except empty, preferably readable and unique for the Attribute. Since the "uniqueness" of the modifier is already defined in the UUID, you can have duplicate names.
double amountIn - the Modifier value, can be anything. Note that the attribute, as prevously explained, has a min/max value and it can't get past that!
int operationIn - the Operation of the Modifier (careful, magic numbers over here!). Have a direct quote from the Minecraft Wiki:
Brief explanation: Operation number is the value you feed the parameter.
I also made an enum for it complete with javadoc for you to copy (with credits of course) if you want: https://github.com/SanAndreasP/SAPManagerPack/blob/master/java/de/sanandrew/core/manpack/util/EnumAttrModifierOperation.java
Now I've covered the parameters, it's time to make a new instance like this:
MY_CUSTOM_MODIFIER = new AttributeModifier(UUID.fromString("e6107045-134f-4c54-a645-75c3ae5c7a27"), "myCustomModifier420BlazeIt", 0.360D, EnumAttrModifierOperation.ADD_PERC_VAL_TO_SUM.ordinal());
You have the new modifier instance, but what do do with it? You can add or remove modifiers from an attribute like this (method names are self-explanatory):
entity.getEntityAttribute(MY_ATTRIBUTE_INSTANCE).applyModifier(MY_CUSTOM_MODIFIER);
entity.getEntityAttribute(MY_ATTRIBUTE_INSTANCE).removeModifier(MY_CUSTOM_MODIFIER);
Alright, you know now everything there is to know about attributes... wait, there's one more thing: attributes are saved and loaded automatically by the entity, no need to do that manually! Just make sure the client knows about the Attribute (register it properly as I've shown).