From 155e6ae0e48fe5cf44f7cd0604004e2a9b4cc9f5 Mon Sep 17 00:00:00 2001 From: agnor99 <36055315+agnor99@users.noreply.github.com> Date: Tue, 3 Oct 2023 17:09:36 +0200 Subject: [PATCH 1/3] create attribute documentation --- docs/entities/_category_.json | 3 ++ docs/entities/attributes.md | 59 +++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/entities/_category_.json create mode 100644 docs/entities/attributes.md diff --git a/docs/entities/_category_.json b/docs/entities/_category_.json new file mode 100644 index 000000000..4be9e355e --- /dev/null +++ b/docs/entities/_category_.json @@ -0,0 +1,3 @@ +{ + "label": "Entities" +} \ No newline at end of file diff --git a/docs/entities/attributes.md b/docs/entities/attributes.md new file mode 100644 index 000000000..dd468a04f --- /dev/null +++ b/docs/entities/attributes.md @@ -0,0 +1,59 @@ +Attributes +========== + +Attributes are ways to modify specific values for living entities in a mod compatible way. + +Existing Attributes +----------- +Vanilla adds the following attributes: + +| Attribute | Description | +|-------------------------------|----------------------------------------------------------------------------------------------| +| `MAX_HEALTH` | how much health the entity has | +| `FOLLOW_RANGE` | how far the entity can track something | +| `KNOCKBACK_RESISTANCE` | how strong knockback is reduced. Ranged between 0 and 1, 1 cancelling all knockback. | +| `MOVEMENT_SPEED` | how fast the entity moves | +| `FLYING_SPEED` | The flying speed of the entity. Not applicable to players who fly with the elytra | +| `ATTACK_DAMAGE` | how much damage the entity deals when attacking | +| `ATTACK_KNOCKBACK` | how much knockback the entity causes when physically attacking | +| `ATTACK_SPEED` | how many full damage attack the entity deals per second | +| `ARMOR` | how many armor points the entity has and how resistant it is to attacks | +| `ARMOR_TOUGHNESS` | how resistant the entity is to strong attacks | +| `LUCK` | changes the chance for treasure, junk and normal fishing loottables | +| `SPAWN_REINFORCEMENTS_CHANCE` | how likely a zombie spawns reinforcements when attacked | +| `JUMP_STRENGTH` | how high the entity jumps. Only applicable for horse like more (including mules and camels). | + +NeoForge adds the following attributes: + +| Attribute | Description | +|------------------------|------------------------------------------------------------------------| +| `SWIM_SPEED` | how fast the entity swims | +| `NAMETAG_DISTANCE` | how far the nametag can be seen for this entity | +| `ENTITY_GRAVITY` | how fast the entity accelerates when not on ground | +| `BLOCK_REACH` | how far the player can interact with the world | +| `ENTITY_REACH` | how far the player can interact with entities | +| `STEP_HEIGHT_ADDITION` | how high the entity can walk up blocks in addition to Entity#maxUpStep | + +Attribute, AttributeInstance and AttributeModifier +----------- + +Attributes have to be [registered][registration] and are used to look up the current `AttributeInstance` for a given LivingEntity. The `AttributeInstance` holds all `AttributeModifier` currently active on the entity. +AttributeModifiers require a UUID that should be unique to this modifier. It's used to ensure that an `AttributeModifier` can only be applied once to a LivingEntity. You should generate a random one once and then hardcode it. They also require an Operation and an amount to perform the calculation. How the calculation works can be read in the next section. +The value of an `Attribute` for a given `LivingEntity` can be obtained by the `AttributeMap` for the LivingEntity and getting the `AttributeInstance` from it and then calling `AttributeInstance#getValue`. + +Operations +----------- + +AttributeInstances can have 3 different operations, `ADDITION`, `MULTIPLY_BASE` and `MULTIPLY_TOTAL`. +First the default value is used and all `ADDITION`-Modifiers are added to it. This is the base value. +`MULTIPLY_BASE`-Modifiers are applied next, they multiply the base value with 1 + the sum of the `MULTIPLY_BASE` modifiers. +`MULTIPLY_TOTAL`-Modifiers are applied last, they multiply the value created with 1+modifier each. + +Applying AttributeModifier +----------- + +AttributeModifiers can be applied for held items and worn armor. +Changing the AttributeModifier for custom Items can be achieved by overriding IForgeItem#getAttributeModifiers. You can also apply AttributeModifiers to ItemStacks by calling ItemStack#addAttributeModifier. +Attribute Modifiers can also be added and removed to LivingEntities directly by obtaining the `AttributeMap` with `LivingEntity#getAttributes` and getting the AttributeInstance with `AttributeMap#getInstance`. You can then remove and add them with the methods present on the AttributeInstance. + +[registration]: ../concepts/registries.md \ No newline at end of file From 63dc054eac12bfd5a641c5aa0c0033cbe8ae1730 Mon Sep 17 00:00:00 2001 From: agnor99 <36055315+agnor99@users.noreply.github.com> Date: Tue, 3 Oct 2023 21:50:47 +0200 Subject: [PATCH 2/3] apply some requested changes --- docs/entities/_category_.json | 2 +- docs/entities/attributes.md | 43 +++++++++++++++++++++-------------- 2 files changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/entities/_category_.json b/docs/entities/_category_.json index 4be9e355e..76b307eea 100644 --- a/docs/entities/_category_.json +++ b/docs/entities/_category_.json @@ -1,3 +1,3 @@ { "label": "Entities" -} \ No newline at end of file +} diff --git a/docs/entities/attributes.md b/docs/entities/attributes.md index dd468a04f..980b22dbd 100644 --- a/docs/entities/attributes.md +++ b/docs/entities/attributes.md @@ -1,10 +1,10 @@ -Attributes -========== +# Attributes -Attributes are ways to modify specific values for living entities in a mod compatible way. +The attribute system is a system to provide values that are modifiable by multiple other things. +Attributes can be used in a mod compatible way to change attack damage, maximum health and other things without each mod setting the value to something they expect and instead use modifications to e.g. add 2 hearts. + +## Existing Attributes -Existing Attributes ------------ Vanilla adds the following attributes: | Attribute | Description | @@ -34,26 +34,35 @@ NeoForge adds the following attributes: | `ENTITY_REACH` | how far the player can interact with entities | | `STEP_HEIGHT_ADDITION` | how high the entity can walk up blocks in addition to Entity#maxUpStep | -Attribute, AttributeInstance and AttributeModifier ------------ +## Attribute, AttributeInstance and AttributeModifier Attributes have to be [registered][registration] and are used to look up the current `AttributeInstance` for a given LivingEntity. The `AttributeInstance` holds all `AttributeModifier` currently active on the entity. -AttributeModifiers require a UUID that should be unique to this modifier. It's used to ensure that an `AttributeModifier` can only be applied once to a LivingEntity. You should generate a random one once and then hardcode it. They also require an Operation and an amount to perform the calculation. How the calculation works can be read in the next section. -The value of an `Attribute` for a given `LivingEntity` can be obtained by the `AttributeMap` for the LivingEntity and getting the `AttributeInstance` from it and then calling `AttributeInstance#getValue`. +AttributeModifiers require a UUID that should be unique to this modifier. It's used to ensure that an `AttributeModifier` can only be applied once to a LivingEntity. If you want to keep track of that modifier to remove it at a later point, then you should generate a random one once and then hardcode it. If you don't need to keep track of the modifier, it is sufficient to use a random UUID. +They also require an Operation and an amount to perform the calculation. How the calculation works can be read in the next section. +```java +double maxHealth = livingentity.getAttribute(Attributes.MAX_HEALTH).getValue() +``` -Operations ------------ +### Calculation AttributeInstances can have 3 different operations, `ADDITION`, `MULTIPLY_BASE` and `MULTIPLY_TOTAL`. -First the default value is used and all `ADDITION`-Modifiers are added to it. This is the base value. -`MULTIPLY_BASE`-Modifiers are applied next, they multiply the base value with 1 + the sum of the `MULTIPLY_BASE` modifiers. -`MULTIPLY_TOTAL`-Modifiers are applied last, they multiply the value created with 1+modifier each. +``` +value = (base + sum(addition))*(1+sum(multiply_base))*(1+z1)*(1+z2)[...] +``` +The base value is set by the attributes default, but is sometimes set by the entity in some other events(e.g. Wolf taming). +z1 and z2 are two multiply_total modifiers and more are calculated the same way. -Applying AttributeModifier ------------ +## Using AttributeModifiers AttributeModifiers can be applied for held items and worn armor. Changing the AttributeModifier for custom Items can be achieved by overriding IForgeItem#getAttributeModifiers. You can also apply AttributeModifiers to ItemStacks by calling ItemStack#addAttributeModifier. -Attribute Modifiers can also be added and removed to LivingEntities directly by obtaining the `AttributeMap` with `LivingEntity#getAttributes` and getting the AttributeInstance with `AttributeMap#getInstance`. You can then remove and add them with the methods present on the AttributeInstance. +Another way to apply AttributeModifiers is by adding them with a `MobEffect`. For that you can call `MobEffect#addAttributeModifier` on the MobEffect to add AttributeModifiers when this MobEffect is applied. The applied AttributeModifier has an effect of x*(1+amplifier) with x being the amplifier value that was passed into `MobEffect#addAttributeModifier`. +Attribute Modifiers can also be added and removed from/to LivingEntities directly: +```java +livingEntity.getAttribute(Attributes.MAX_HEALTH).addPermanentModifier(new AttributeModifier("health upgrade", 10, AttributeModifier.Operation.ADDITION)); +livingEntity.getAttribute(Attributes.MAX_HEALTH).addTransientModifier(new AttributeModifier("health upgrade", 10, AttributeModifier.Operation.ADDITION)); +livingEntity.getAttribute(Attributes.MAX_HEALTH).removeModifier(UUID.fromString("556E1665-8B10-40C8-8F9D-CF9B1667F295")); +``` +Transient modifiers are modifiers that are not serialized and saved, permanent modifiers are saved. [registration]: ../concepts/registries.md \ No newline at end of file From 43e41598e6eb4ccfcd3f4b6f5a58fa83c57de771 Mon Sep 17 00:00:00 2001 From: agnor99 <36055315+agnor99@users.noreply.github.com> Date: Tue, 3 Oct 2023 21:54:08 +0200 Subject: [PATCH 3/3] fix spelling --- docs/entities/attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/entities/attributes.md b/docs/entities/attributes.md index 980b22dbd..7ed2a0e34 100644 --- a/docs/entities/attributes.md +++ b/docs/entities/attributes.md @@ -21,7 +21,7 @@ Vanilla adds the following attributes: | `ARMOR_TOUGHNESS` | how resistant the entity is to strong attacks | | `LUCK` | changes the chance for treasure, junk and normal fishing loottables | | `SPAWN_REINFORCEMENTS_CHANCE` | how likely a zombie spawns reinforcements when attacked | -| `JUMP_STRENGTH` | how high the entity jumps. Only applicable for horse like more (including mules and camels). | +| `JUMP_STRENGTH` | how high the entity jumps. Only applicable for horse like mobs (including mules and camels). | NeoForge adds the following attributes: