Actor property wrappers

ACSUtils provides wrapper functions for all actor properties. These functions serve several purposes:

• Save typing and increase readability.
• Reduce bandwidth use caused by 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 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).

Now you can write just:

GetActorHealth(tid);
SetActorHealth(tid, 100);

instead of:

GetActorProperty(tid, APROP_Health);
SetActorProperty(tid, APROP_Health, 100);

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

Example implementation of SetActorHealth:

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

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

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.

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

*See warning about GetActorViewHeight in the beginning of the article.