create attribute documentation #15

agnor99 · 2023-10-03T15:11:24Z

This adds documentation for the vanilla attribute system

Preview URL: https://pr-15.neoforged-docs-previews.pages.dev

ChampionAsh5357

Take a look at #14 for the current draft standards.

In general, I think this needs more work on explaining what an attribute is, why do we use it, and how we do so.

ChampionAsh5357 · 2023-10-03T15:34:09Z

docs/entities/_category_.json

@@ -0,0 +1,3 @@
+{
+    "label": "Entities"
+}


New line at EOF.

ChampionAsh5357 · 2023-10-03T15:36:57Z

docs/entities/attributes.md

+Attributes
+==========
+
+Attributes are ways to modify specific values for living entities in a mod compatible way. 


That's not really what an attribute is. That's what we use it for, yes, but it's not the intended purpose. Iirc, attributes are a property defined on an entity that is meant to apply the greatest modifier without stacking to the player.

Please correct me if I'm wrong, I can't look on my computer because it's a hot brick.

nope, it's not about the greatest modifier, all active AttributeModifiers are considered. addition stacks by just addition, multiply_base stacks by adding the factors (+20% and +20% combine to +40%) and multiply_total stacks by multiplication (+20% and +20% combine to +44%)

Okay. So the AttributeMap has a map of Attributes to AttributeInstances, which in turn hold a set of AttributeModifiers, unique by their id, grouped by operation.

Okay then, then it should still be something like: attributes are a property defined on an entity that can be modified by many different elements at the same time. Each element can be applied and removed depending on their intent.

There's probably a better way to word that, but it's what I'm thinking rn.

An apt description is "Attributes are properties of an entity which correspond to a value. This value can be modified by multiple sources at once through Attribute Modifiers, allowing for simple cross-mod compatibility."

ChampionAsh5357 · 2023-10-03T15:37:56Z

docs/entities/attributes.md

+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). |


I have no idea how useful this is. This makes sense in parchment, but I feel like this could also just be said it's in the attributes file and list some examples.

I do believe that the list of attributes and what they do is useful. There are already parchment comments for them, but giving people examples for what mojang and neo use attributes for, so people can easier understand, what things attributes can be used for and therefore be used for their use cases

This is one of those instances where I'm inclined to agree that the docs should delegate to the code for listing the attributes. This is almost guaranteed to go stale, while a reference to the Attributes class will always be accurate.

ChampionAsh5357 · 2023-10-03T15:38:29Z

docs/entities/attributes.md

+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 |


Again, same issue here. This one makes more sense though to have in the documentation.

ChampionAsh5357 · 2023-10-03T15:39:18Z

docs/entities/attributes.md

+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`.


Probably best to give an example on how to do so.

This is overly verbose IMO. The quick method to retrieve the value of an attribute is LivingEntity#getAttributeValue(Attribute)

ChampionAsh5357 · 2023-10-03T15:39:40Z

docs/entities/attributes.md

+-----------
+
+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.


Why should I hardcode the UUID?

The question of "should I hardcode the UUID" is implementation dependent on the answer of what will you need to do with that modifier in the future.

If you are performing a one-off permanent modifier addition (to say, an entity when it is being spawned), there is no need to use a static UUID.
If you are adding attribute modifiers to an item, you must use a static UUID otherwise the modifier will not be removed when the item is unequipped.

Attributes also only permit one modifier with the same UUID (though one UUID can be used across Attributes), so it can be useful to prevent re-application.

ChampionAsh5357 · 2023-10-03T15:39:51Z

docs/entities/attributes.md

+-----------
+
+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.


Operation can be explained in a subcategory here.

I have an apt description of Operation here: https://github.com/Shadows-of-Fire/Apothic-Attributes/blob/1.20/src/main/java/dev/shadowsoffire/attributeslib/api/AttributeHelper.java#L52-L63

ChampionAsh5357 · 2023-10-03T15:41:25Z

docs/entities/attributes.md

+
+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`.


Example. Also, I don't think this is as useful as explaining what methods in the entity provide this.

ChampionAsh5357 · 2023-10-03T15:41:35Z

docs/entities/attributes.md

+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.


Show maths.

ChampionAsh5357 · 2023-10-03T15:41:58Z

docs/entities/attributes.md

+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.


Examples. This is highly unclear. Also, what happened to potions or effects?

neoforged-pages-deployments · 2023-10-03T20:10:22Z

Deploying with Cloudflare Pages

Name	Result
Last commit:	63dc054eac12bfd5a641c5aa0c0033cbe8ae1730
Status:	✅ Deploy successful!
Preview URL:	https://1400ea5a.neoforged-docs-previews.pages.dev
PR Preview URL:	https://pr-15.neoforged-docs-previews.pages.dev

Shadows-of-Fire · 2023-10-04T00:56:27Z

Fair amount of work probably needed here.

The current state is unfortunately inbetween "too technical" and "too simple" in that it is not technical enough for advanced users to gain anything that they would not have inferred on their own, but also too verbose for new users.

create attribute documentation

155e6ae

ChampionAsh5357 requested changes Oct 3, 2023

View reviewed changes

agnor99 added 2 commits October 3, 2023 21:50

apply some requested changes

63dc054

fix spelling

43e4159

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) October 3, 2023 20:10 Active

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

create attribute documentation #15

create attribute documentation #15

agnor99 commented Oct 3, 2023 •

edited by neoforged-pages-deployments bot

ChampionAsh5357 left a comment

ChampionAsh5357 Oct 3, 2023

ChampionAsh5357 Oct 3, 2023

agnor99 Oct 3, 2023

ChampionAsh5357 Oct 3, 2023

Shadows-of-Fire Oct 4, 2023

ChampionAsh5357 Oct 3, 2023

agnor99 Oct 3, 2023

Shadows-of-Fire Oct 4, 2023

ChampionAsh5357 Oct 3, 2023

ChampionAsh5357 Oct 3, 2023

Shadows-of-Fire Oct 4, 2023

ChampionAsh5357 Oct 3, 2023

Shadows-of-Fire Oct 4, 2023

ChampionAsh5357 Oct 3, 2023

Shadows-of-Fire Oct 4, 2023

ChampionAsh5357 Oct 3, 2023

ChampionAsh5357 Oct 3, 2023

ChampionAsh5357 Oct 3, 2023

neoforged-pages-deployments bot commented Oct 3, 2023

Shadows-of-Fire commented Oct 4, 2023

create attribute documentation #15

Are you sure you want to change the base?

create attribute documentation #15

Conversation

agnor99 commented Oct 3, 2023 • edited by neoforged-pages-deployments bot

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neoforged-pages-deployments bot commented Oct 3, 2023

Deploying with Cloudflare Pages

Shadows-of-Fire commented Oct 4, 2023

agnor99 commented Oct 3, 2023 •

edited by neoforged-pages-deployments bot