ACSUtils Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Actor property wrappers ======
ACSUtils provides wrapper functions for all [[zdoom>GetActorProperty|actor properties]]. These functions serve several purposes:

  * Save typing and increase readability.
  * Reduce bandwidth use caused by [[zdoom>SetActorProperty]].
  * Provide [[strict type checking]] for actor properties.

For every actor property ACSUtils provides two functions:

  * ''**<type>** GetActor**<property>**(int tid)''
  * ''void SetActor**<property>**(int tid, **<type>** value)''

The only exception is [[zdoom>GetActorViewHeight]], which is a native ZDoom function that takes crouching into account. To access the actual value of the ViewHeight property, use ''GetActorProperty(tid, APROP_ViewHeight)''.

===== Readability increase =====

Now you can write just:

<code>
GetActorHealth(tid);
SetActorHealth(tid, 100);
</code>

instead of:

<code>
GetActorProperty(tid, APROP_Health);
SetActorProperty(tid, APROP_Health, 100);
</code>

===== Network optimization =====

All ''SetActor**<property>**'' functions first call [[zdoom>GetActorProperty]] and compare the new value of the property to the current one. If both values are the same, [[zdoom>SetActorProperty]] is not called. This automatically optimizes bandwidth use in Zandronum multiplayer.

Example implementation of ''SetActorHealth'':

<code>
function void SetActorHealth(int tid, int Health)
{
	if (GetActorProperty(tid, APROP_Health) != Health)
		SetActorProperty(tid, APROP_Health, Health);
}
</code>

Some actor properties are optimized by Zandronum itself. However, the set of optimized actor properties depends on zandronum version, and not all actor properties are currently optimized (https://zandronum.com/tracker/view.php?id=1609). 

All string properties are compared in a case-insensitive way before being set. This means, for example, that ''SetActorNameTag(0, "Thing")'' will not call ''SetActorProperty'' if the **NameTag** property is already set to ''"thing"''.

===== Strict type checking =====

Each ''GetActor**<property>**'' function is declared as returning the same type as the actor property.

Each ''SetActor**<property>**'' function's ''value'' argument is of the same type as the actor property.

If you use ACSUtils with [[strict type checking]] (for example, by using [[BCC]] with [[BCSUtils]]), using actor property wrappers will prevent you from reading an actor property into a variable of incorrect type, or setting an actor property to a value of a different type.

===== List of supported properties =====

If any ZDoom property is missing from this list, please, notify ACSUtils developers.

^ type ^ Name ^
| int | Accuracy |
| str | ActiveSound |
| fixed | Alpha |
| bool | Ambush |
| str | AttackSound |
| fixed | AttackZOffset |
| bool | ChaseGoal |
| int | Damage |
| fixed | DamageFactor |
| fixed | DamageMultiplier |
| str | DamageType |
| str | DeathSound |
| bool | Dormant |
| bool | Dropped |
| fixed | Friction |
| bool | Friendly |
| bool | Frightened |
| fixed | Gravity |
| int | Health |
| fixed | Height |
| bool | Invulnerable |
| fixed | JumpZ |
| int | Mass |
| int | MasterTID |
| fixed | MaxDropOffHeight |
| fixed | MaxStepHeight |
| fixed | MeleeRange |
| str | Nametag |
| bool | NoTarget |
| bool | NoTrigger |
| str | PainSound |
| fixed | Radius |
| int | ReactionTime |
| int | RenderStyle |
| fixed | ScaleX |
| fixed | ScaleY |
| int | Score |
| str | SeeSound |
| int | SpawnHealth |
| str | Species |
| fixed | Speed |
| int | Stamina |
| int | StencilColor |
| int | TargetTID |
| int | TracerTID |
| fixed | ViewHeight* |
| int | Waterlevel |

*See warning about [[zdoom>GetActorViewHeight]] in the beginning of the article.
ACSUtils Wiki

User Tools

Site Tools

Page Tools
