View source for Modding:Entity instance attributes

Entity instance attributes are key values that can be set on any entity in the world. They can only be modified with server commands and code mods. These are different from [[Modding:Entity_Json_Properties#p_attributes|entity type attributes]], which apply to entity types (a pattern used to spawn an entity into the world). Unlike entity type attributes, entity instance attributes cannot be set in the json files, because they are unique to every instance of the entity.

For each entity, there are 3 kinds of entity instance attributes:
; WatchedAttributes : the most commonly used entity instance attributes. Modifications on the server side are stored in the save game and synchronized to the clients. Modifications on the client side are not synchronized to the server, and they are lost the next time the server synchronizes the entity attributes.
; DebugAttributes : only used if the EntityDebugMode is enabled. The base game uses this to show the active [[Modding:Entity_Behavior_taskai#Debugging|AI tasks]] and animations for entities. When enabled, bulk changes to these attributes on the server side are synchronized to the client, but small changes are dropped due to a bug in the synchronization code (in ServerPackets.GetBulkEntityDebugAttributesPacket in VintagestoryLib.dll).
; Attributes : stored to the save game on the server side, but not synchronized to the client. Modifications on the client side are kept until the entity is unloaded.

== Debug commands ==
Server admins can read WatchedAttributes of the currently selected entity with this [[List_of_server_commands#/entity|server command]]:
<code>/entity cmd l[] attr [attribute name]</code>

WatchedAttributes of the currently selected entity can be modified with this command:
<code>/entity cmd l[] setattr string [attribute name] [value]</code>

== Modifying attributes in code ==
The entity instance attributes are read and modified like any other [[Modding:TreeAttribute|TreeAttributes]]. An attribute can hold many different types. '''int''', '''float''', and '''string''' are common types. Here's an example from [https://github.com/anegostudios/vsapi/blob/master/Common/Entity/Entity.cs#L843 Entity.cs] where the '''onHurtCounter''' attribute is read and set.
<syntaxhighlight lang="csharp">
                    WatchedAttributes.SetInt("onHurtCounter", WatchedAttributes.GetInt("onHurtCounter") + 1);
</syntaxhighlight>

== Synchronization packets ==
[[File:EntityBulkAttributes_Packet.png|thumb|EntityBulkAttributes showing a partial update of the WatchedAttributes for one entity and a full update for another entity]]

When the entity is first spawned, the WatchedAttributes are sent to the client in the '''Entity''' packet, along with everything else about the entity. After that, changes to individual attributes are sent in the '''partialUpdates''' field of the '''BulkEntityAttributes''' packet. However, if [https://github.com/anegostudios/vsapi/blob/master/Datastructures/AttributeTree/Other/SyncedTreeAttribute.cs#L91 10] or more attributes are modified before the next '''BulkEntityAttributes''' packet is sent, then instead all of the entity's WatchedAttributes are sent in the '''fullUpdates''' field of the '''BulkEntityAttributes''' packet.

Because the server supports partial updates, modders can generally add extra WatchedAttributes without worrying about the network cost.

== Listening to changes ==
Listeners can be registered for all 3 kinds of instance attributes to get notifications when the attribute changes. Although, the client will only get notifications for server modifications if the attributes are synchronized from the server to client (basically just WatchedAttributes).

Use [https://apidocs.vintagestory.at/api/Vintagestory.API.Datastructures.SyncedTreeAttribute.html#Vintagestory_API_Datastructures_SyncedTreeAttribute_RegisterModifiedListener_System_String_System_Action_ RegisterModifiedListener] to register a listener. The listener is added to the attribute for one entity (not entity type), so one needs to somehow find the entity first in order to add the listener. Listeners can be removed with the [https://apidocs.vintagestory.at/api/Vintagestory.API.Datastructures.SyncedTreeAttribute.html#Vintagestory_API_Datastructures_SyncedTreeAttribute_UnregisterListener_System_Action_ UnregisterListener]. Note that listeners are registered for specific attributes, but unregistering a listener removes it from all attributes.

As an example, [https://github.com/anegostudios/vsessentialsmod/blob/master/Systems/CharacterExtraDialogs.cs#L68-L79 CharacterExtraDialogs] adds listeners on the client side to the '''hunger''', '''stats''', and '''bodyTemp''' attributes when the dialog is opened. It does this so that it can redraw the health bars in the dialog. Since the WatchedAttributes are synchronized, the dialog is redrawn on the client side when the character is hurt on the server side. When the dialog is closed, the listeners are unregistered.
<syntaxhighlight lang="csharp">
        private void Dlg_OnClosed()
        {
            capi.World.Player.Entity.WatchedAttributes.UnregisterListener(UpdateStatBars);
            capi.World.Player.Entity.WatchedAttributes.UnregisterListener(UpdateStats);
        }

        private void Dlg_OnOpened()
        {
            capi.World.Player.Entity.WatchedAttributes.RegisterModifiedListener("hunger", UpdateStatBars);
            capi.World.Player.Entity.WatchedAttributes.RegisterModifiedListener("stats", UpdateStats);
            capi.World.Player.Entity.WatchedAttributes.RegisterModifiedListener("bodyTemp", UpdateStats);
        }
</syntaxhighlight>

Even if an attribute is set to it's current value (essentially the value is unchanged), the modification listeners are still invoked. The '''onHurt''' listeners rely on this; the listeners are triggered whenever the entity is hurt, even if the damage is the same as last time ('''onHurt''' is set to its current value).

If the modifications are sent to the client through the '''fullUpdates''' field (because 10 or more attributes were changed), then the client cannot tell which fields were really modified. So the client invokes all registered listeners, even if the field did not change. So the listeners have to be aware that they may get spurious notifications. The '''onHurt''' listener in Entity.cs uses the '''onHurtCounter''' to filter out spurious notifications (it ignores the '''onHurt''' notification if '''onHurtCounter''' was not modified). This strategy can be used for modders adding new attributes, but none of the existing attributes (except for '''onHurt''') have a corresponding counter attribute.
<syntaxhighlight lang="csharp">
            WatchedAttributes.RegisterModifiedListener("onHurt", () => {
                float damage = WatchedAttributes.GetFloat("onHurt", 0);
                if (damage == 0) return;
                int newOnHurtCounter = WatchedAttributes.GetInt("onHurtCounter");
                if (newOnHurtCounter == onHurtCounter) return;

                onHurtCounter = newOnHurtCounter;
...
            });
</syntaxhighlight>

== Base game attributes ==
Code mods can create new attributes with any name. These are the attributes from the base game. In the below list, a dot is used to signify a subattribute of a TreeAttribute. To read these attributes, one needs to read the parent attribute with '''GetTreeAttribute''', then get the child from it; the game does not parse the dot notation shown below. Attribute names are case sensitive.

=== WatchedAttributes ===
; '''entityDead'''&#58; (int) : 0 if the entity is alive, or 1 if the entity is dead.
; '''idleSoundChanceModifier'''&#58; (float)
; '''animations'''&#58; (TreeAttribute)
; '''extraInfoText'''&#58; (TreeAttribute)
; '''onHurt'''&#58; (float) : the amount of damage applied last time the entity was hurt. Listen to this to get notifications when the entity is hurt.
; '''onHurtCounter'''&#58; (int) : the number of times the entity has been hurt. This is used to detect spurious notifications.
; '''onHurtDir'''&#58; (float) : angle that the damage came from, measured from the top down view.
; '''onFire'''&#58; ()
; '''grow'''&#58; (TreeAttribute)
; '''textureIndex'''&#58; (int)
; '''kbdirX'''&#58; (double) : X component of the direction that the entity is currently getting knocked back.
; '''kbdirY'''&#58; (double) : Y component of the direction that the entity is currently getting knocked back.
; '''kbdirZ'''&#58; (double) : Z component of the direction that the entity is currently getting knocked back.
; '''hunger.currentsaturation'''&#58; (float) : how full the player is.
; '''hunger.maxsaturation'''&#58; (float) : maximum fullness that the player can have.
; '''bodyTemp.bodytemp'''&#58; (float) : player temperature.
; '''wetness'''&#58; (float) : wetness in the range of 0 to 1.
; '''health.currenthealth'''&#58; (float) : current hit points.
; '''health.maxhealth'''&#58; (float) : maximum hit points.
; '''stats.walkspeed'''&#58; (TreeAttribute with all entries of float type)
; '''stats.healingeffectivness'''&#58; (TreeAttribute with all entries of float type)
; '''stats.hungerrate'''&#58; (TreeAttribute with all entries of float type)
; '''stats.rangedWeaponsAcc'''&#58; (TreeAttribute with all entries of float type)
; '''stats.rangedWeaponsSpeed'''&#58; (TreeAttribute with all entries of float type)
; '''stats.rangedWeaponsSpeed'''&#58; (TreeAttribute with all entries of float type)
; [[Modding:Entity_Attribute_guardedPlayerUid|guardedEntityId]]&#58; (long) : the target entity that the guard entity is guarding.
; [[Modding:Entity_Attribute_guardedPlayerUid|guardedPlayerUid]]&#58; (string) : the target player that the guard entity is guarding.

=== Attributes ===
; '''dmgkb'''&#58; (int) : set to 1 if a knockback should be started on the entity's next physics tick. It is set back to 0 when the knockback is started.

{{navbox/codemodding}}