DECORATE expressions

From ZDoom Wiki
Jump to navigation Jump to search

ZScript and DECORATE support complex mathematical expressions as parameters for codepointers. The expression may include standard operators, math functions, and certain actor properties (occasionally called "keywords" in the forums) to compare values with.

These expressions can be used for any numeric parameter in any dynamic context. (That means, they cannot be used as a value for Actor properties or Actor flags in the Default block, with the exception of DamageFunction.)

Mathematical functions

  • abs(x)
Returns the absolute value of x.
  • exp(x)
Returns the base-e exponential function of x, which is e raised to the power x: ex .
  • log(x)
Returns the natural logarithm of x -- the opposite of exp.
  • log10(x)
Returns the common (base-10) logarithm of x.
  • ceil(x)
Rounds x upward to the next closest integral value. Result is still floating point.
  • floor(x)
Rounds x down to the next closest integral value. Result is still floating point.
  • round(x)
Rounds x to the closest integral value. Result is still floating point.
  • sqrt(x)
Returns the square root of x.
  • min(float or int, ...)
Gets the smallest value of all values listed. Can take any amount of numbers, and can solve both ints and floats.
  • max(float or int, ...)
Gets the largest value of all values listed. Can take any amount of numbers, and can solve both ints and floats.
  • clamp(src, min, max)
Returns src within the range of min and max inclusively. All parameters can be ints or floats.

Trigonometry functions

  • cos(x)
  • sin(x)
  • tan(x)
Returns cosine, sine, or tangent of angle x. x must be in degrees.
  • acos(x)
  • asin(x)
  • atan(x)
Returns the inverse cosine, sine, or tangent of x. Returns an angle in degrees.
  • cosh(x)
  • sinh(x)
  • tanh(x)
Returns the hyperbolic cosine, sine, or tangent of x.
  • atan2(y, x)
Similar to atan, but used to get the quadrants the angles are in. Returns in degrees.
  • VectorAngle(x, y)
Like atan2, only with x first instead of y. Can be used to calculate an angle, for example, by passing coordinates to it.
VectorAngle(user_x[0] - user_x[1], user_y[0] - user_y[1])

Random number functions

  • random[identifier](min, max)
Returns a random integer value between min and max.
  • random2[identifier](mask)
Returns a random integer value between -mask and +mask. It is equivalent to (random() & mask) - (random() & mask). If no mask is provided, i.e, random2(), the maximum value of 255 is used instead. Mask is used as a binary mask, e.g. if 9 is used, the random results can be [0, 1, 8, 9] - [0, 1, 8, 9], so it is advised to use as a mask values one less than a power of two, such as 1, 3, 7, 15, 31, 63, or 127.
  • frandom[identifier](min, max)
Returns a random floating point value between min and max.
  • randompick[identifier](int, ...)
Picks a number from the numbers placed in it. This can take an unlimited amount of parameters, i.e. randompick(1, 4, 12, 16) will choose one of the four numbers.
  • frandompick[identifier](float, ...)
Similar to randompick but for float-point values.
  • SetRandomSeed[identifier](seedvalue)
Used if a guaranteed sequence of random numbers is desired. When a specific number is set as seed, the random-number generator (RNG) will always produce the same numbers. Useful for cases where an RNG may be used for purposes where total randomness is not wanted.

identifier is optional. Calls to a random function with an identifier do not interfere with the RNG for calls with a different identifier, which can be used to make the outcome of some events unaffected by others.

ACS functions

Runs a script and uses its return value.
Runs a named script and uses its return value.
Shorter alias for ACS_NamedExecuteWithResult.

Information functions

ZScript

Gets the number of inventory items an actor is holding from a pointer and returns it to the expression.
Similar to A_CheckProximity but returns how many of the actors are found instead of jumping.
Using a BlockThingsIterator provides more control.
Distance2D
Gets the distance from the calling actor to a pointer.
Gets the gib health property of the calling actor.
This is preferable over reading gibhealth directly, because this is a virtual function, which can be overridden to add custom behavior.
Returns a bit field containing the buttons pressed by the player, if the calling actor is a PlayerPawn.
Gets the spawn health property of the calling actor.
Gets the Z coordinate of a floor or ceiling at a specific set of coordinates.
  • OverlayID()
When used in PSprite, it retrieves the layer's index.
Returns the x position of the specified overlay. Same as obtaining the PSprite pointer first and reading its x field.
Returns the y position of the specified overlay. Same as obtaining the PSprite pointer first and reading its y field.

See also ZScript operators and ZScript statements.

DECORATE functions

These functions are not like regular DECORATE action functions. They can be used just like expressions (i.e. randompick) inside of action functions directly such as A_SetUserVar.

Checks an actor's class name, returning true if it matches the passed parameter.
Gets the number of inventory items an actor is holding from a pointer and returns it to the expression.
Similar to A_CheckProximity but returns how many of the actors are found instead of jumping.
Gets the angle which an actor pointer can be found at. Can toggle the relative functionality
Gets a server cvar, internal or user.
Gets the current crouch factor of a player if the player is a pointer.
Gets the distance from the calling actor to a pointer. Can toggle the Z checking functionality.
Gets the gib health property of the calling actor.
Gets the damage of the actor.
Performs the same functionality as the ACS GetPlayerInput.
Gets the spawn health property of the calling actor.
Gets an Actor pointer's sprite angle.
Gets an Actor pointer's sprite rotation.
Gets the Z coordinate of a floor or ceiling at a specific set of coordinates.
Compares two actor pointers, returning true if they reference the same actor.
  • OverlayID()
When used in an overlay, it retrieves the overlay's layer index.
Returns the x position of the specified overlay.
Returns the y position of the specified overlay.

Variables

ZScript

Variables defined in the class can be manipulated directly. Any variable can be read from the class itself, and, provided it's not protected by a specific access modifer, it can be read from other classes instead.

A lot of variables can be modified directly, but most of those defined as internal, readonly or meta will still rely on specific functions, like SetOrigin, A_Warp and others.

Some common Actor variables include:

Note: This is only a brief list, covering only some of the Actor class fields, added for informational purposes only. The absolute majority of variables defined in a class are readable and modifiable. You can find the full definition of the Actor class on GZDoom wiki.
Field name Data type How to modify Description
args static int array Directly modifiable
Can be set in the map editor
A_SetArg
Arguments of the actor. This is a static array with the size of 5.
Items are accessible as args[0], args[1], args[3], args[4].
target Actor Directly modifiable The actor's target pointer.
master Actor Directly modifiable The actor's master pointer.
tracer Actor Directly modifiable The actor's tracer pointer.
pos Vector3 SetOrigin
A_Warp
Warp (ZScript)
SetZ
Actor's current position in the world. Has .x, .y and .z components.
vel Vector3 Directly modifiable
A_ChangeVelocity
Actor's current absolute velocity. Has .x, .y and .z components.
angle double Directly modifiable
A_SetAngle
Actor's absolute facing angle. Note, it can go beyond the 0-360 range.
pitch double Directly modifiable
A_SetPitch
Actor's absolute pitch. Limited to [-90, 90] range.
roll double Directly modifiable
A_SetRoll
Actor's current roll in a [0, 360] range.
For actor sprites to follow the roll, the ROLLSPRITE flag must be used.
For 3D models to have effect, the model will need the USEACTORROLL in MODELDEF.
alpha double Directly modifiable
A_FadeOut
A_FadeIn
[[A_SetRenderStyle
The opacity of the actor's current sprite (1.0 = opaque, 0.0 = invisible).
Modifying it has no effect if the actor's RenderStyle is 'Normal'.
scale Vector2 Directly modifiable
A_SetScale
The actor's visual scale which affect how its sprites are rendered.
Has .x (horizontal) and .y (vertical) components.
height double Directly modifiable
A_SetSize
Height of the actor's collision box.
radius double A_SetSize Width of the actor's collision box.
VisibleStartAngle double Directly modifiable Beginning of the actor's angle range which the camera must see it to draw the sprite.
Requires MASKROTATION flag to have any effect.
VisibleEndAngle double Directly modifiable End of the actor's angle range which the camera must see it to draw the sprite.
Requires MASKROTATION flag to have any effect.
VisibleStartPitch double Directly modifiable Same as VisibleStartAngle, but for pitch.
VisibleEndPitch double Directly modifiable Same as VisibleEndAngle, but for pitch.
health int A_SetHealth
The actor's current health.

Warning: Modifying the actor's health is NOT the same as healing and damaging. Modifying this field simply changes its base value.
To heal the actor, see GiveBody.
To damage the actor, see DamageMobj.
damage int SetDamage The actor's current damage. Note, if the actor's damage was set with DamageFunction,
calling SetDamage will completely override that formula.
mass double Directly modifiable
A_SetMass
The actor's mass.
speed double Directly modifiable
A_SetSpeed
The actor's Speed property.
Note, this is not the current velocity. Modifying Speed will have no effect on the speed of the actor's current movement.
For that, you need to modify vel.
meleerange double Directly modifiable The actor's MeleeRange.
reactiontime int Directly modifiable The actor's ReactionTime.
stamina int Directly modifiable The actor's Stamina.
special int Directly modifiable
A_SetSpecial
The special attached to the actor.
species name A_SetSpecies The actor's Species.
waterlevel int Readonly How "submerged" the actor is in a Transfer_Heights or 3D floor water pool:
*0: Not submerged at all (e.g. standing on solid ground or on shallow TERRAIN-based water)
*1: Less than half submerged ("ankle deep")
*2: At least half submerged ("waist deep")
*3: Entirely submerged (completely underwater)
waterdepth double Readonly The exact depth that the actor is at inside of a Transfer_Heights or 3D floor water volume.
Can be used for more detailed depth checks than waterlevel.
TID int Readonly The actor's TID.
TIDtoHate int Readonly TID of the actor to hate (see Thing_Hate).
cursector Sector Readonly Sector the actor is currently in.

DECORATE reference

As of GZDoom 2.2.0, it is possible to directly modify some of the variables with assignment operators.

  • Bold - Read and write variables. Allows direct assignment operators.
  • Italics - Read-only variables.

Read-only variables must still rely upon the action function used to manipulate them (e.g. A_Warp for x/y/z, A_ChangeVelocity for velx/vely/velz). As of GZDoom 2.2.0, unary increment/decrement operators (user_test++, --user_test, etc.) may be used, as well.

NOTE: Direct variable modifications will not be interpolated or have any other effects performed upon them. If these effects are desired, use the action function associated with the variable(s) instead (such as A_SetAngle for interpolating angle changes).

The following is dynamic data for use in DECORATE definitions and expressions:

Actor position and movement
  • x — The actor's X position in the world.
  • y — Same, but for Y.
  • z — Same, but for Z.
  • angle — Actor's angle, in degrees
  • ceilingz — returns Z height of the ceiling above the calling actor as an absolute double value (portal- and 3D-floor-aware)
  • floorz — returns Z height of the floor underneath the calling actor as an absolute double value (portal- and 3D-floor-aware)
  • pitch — The actor's pitch in degrees.
  • roll - The actor's roll. Currently, this only really affects players such as the rotation of view.
  • velx or momx — Actor's velocity along the absolute X axis. The "mom" names are (deprecated).
  • vely or momy — Same, but for Y.
  • velz or momz — Same, but for Z.
Actor properties
  • accuracy — The accuracy of the Actor.
  • alpha — The Alpha value of the Actor.
  • args[] — Arguments passed to the thing special; args[0] through args[4] are valid.
  • damage — The actor's Damage. (deprecated)
  • health — How much health the Actor has left.
  • height — The actor's Height.
  • mass — The actor's Mass.
  • meleerange — The actor's MeleeRange.
  • radius — The actor's Radius.
  • reactiontime — The actor's ReactionTime.
  • scaleX — The actor's horizontal scale. See A_SetScale.
  • scaleY — The actor's vertical scale. See A_SetScale.
  • score — The actor's score.
  • special — ID of the special currently assigned to this actor.
  • speed — The actor's Speed.
  • stamina — The stamina of the Actor.
  • tid — The actor's TID.
  • tidtohate — TID of the current assigned target. (see Thing_Hate.)
  • threshold — The actor's Threshold.
  • defthreshold — The actor's DefThreshold.
  • VisibleStartAngle/VisibleEndAngle - The actor's angle range which the camera must see it to draw the sprite. Requires MASKROTATION flag to have any effect.
  • VisibleStartPitch/VisibleEndPitch - Same as VisibleStartAngle and VisibleEndAngle but for pitch instead.
  • Constant VariablesConstant variables can be defined both inside and outside of an actor.
  • User Variablesuser variables are defined as "var int user_(name);" in actor properties.
  • User Arrays — user arrays are defined as "var int user_(name)[(size)];" in actor properties.
  • waterlevel — How "submerged" the actor is in a Transfer_Heights or 3D floor water pool:
0: Not submerged at all (e.g. standing on solid ground or on shallow TERRAIN-based water)
1: Less than half submerged ("ankle deep")
2: At least half submerged ("waist deep")
3: Entirely submerged (completely underwater)
  • waterdepth — The exact depth that the actor is at inside of a Transfer_Heights or 3D floor water volume. Returns an floating point number. Can be used for more detailed depth checks than waterlevel.

Examples

See Projectile Trap