# DECORATE expressions

DECORATE supports complex mathematical expressions as parameters for codepointers. (Unfortunately, expressions are not supported for the values of properties.) The expression may include standard operators (+, -, *, /, <<, >>, |, ? and : (ternary) etc.), math functions, and certain actor properties (occasionally called “keywords” in the forums) to compare values with. A_JumpIf, in particular, is meant to be used with expressions, but they can be used for any numeric (integer or floating point) parameter. For example, using *velx*, *vely*, and *velz* in A_SpawnItemEx to preserve velocity, or using *args[]* as arguments to a call of ACS_Execute.

## Contents

## 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*:*e*.^{x}**(development version a862f72 only)****log(***x***)**- Returns the natural logarithm of*x*-- the opposite of exp.**(development version a862f72 only)****log10(***x***)**- Returns the common (base-10) logarithm of*x*.**(development version a862f72 only)****ceil(***x***)**- Rounds*x*upward to the next closest integral value. Result is still floating point.**(development version a862f72 only)****floor(***x***)**- Rounds*x*down to the next closest integral value. Result is still floating point.**(development version a862f72 only)****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.**(development version 1ffb7ad only)****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.**(development version 1ffb7ad only)****clamp(***src***,***min***,***max***)**- Returns*src*within the range of*min*and*max*inclusively. All parameters can be ints or floats.**(development version fd78686 only)**

## Trigonometry functions

**cos(***x***)**,**sin(***x***)**,**tan(***x***)**— Returns cosine, sine, or tangent of angle*x*.*x*must be in degrees. Tan is**(development version a862f72 only)****acos(***x***)**,**asin(***x***)**,**atan(***x***)**— Returns the inverse cosine, sine, or tangent of*x*. Returns an angle in degrees.**(development version a862f72 only)****cosh(***x***)**,**sinh(***x***)**,**tanh(***x***)**— Returns the hyperbolic cosine, sine, or tangent of*x*.**(development version a862f72 only)****atan2(***y***,***x***)**- - Similar to atan, but used to get the quadrants the angles are in. Returns in degrees.**(development version e83bc53 only)****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.**(development version e83bc53 only)**

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 roughly equivalent to`random(0, mask) - random(0, mask)`. If no mask is provided (`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.**(New from 2.8.1)****frandompick[***identifier***](***float***, ...)**— similar to*randompick*but for float-point values.**(New from 2.8.1)**

*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

**ACS_ExecuteWithResult**— runs a script and uses its return value.**ACS_NamedExecuteWithResult**— runs a named script and uses its return value.**CallACS**— shorter alias for ACS_NamedExecuteWithResult.

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

**CheckClass**— checks an actor's class name, returning`true`if it matches the passed parameter.**(New from 2.8.1)****CountInv**- Gets the number of inventory items an actor is holding from a pointer and returns it to the expression.**(development version 1ca2293 only)****CountProximity**- Similar to A_CheckProximity but returns how many of the actors are found instead of jumping.**(development version 13fa06f only)****GetAngle**- Gets the angle which an actor pointer can be found at. Can toggle the relative functionality**(development version f5afa30 only)****GetCvar**- Gets a server cvar, internal or user.**(development version ebe3f23 only)****GetCrouchFactor**- Gets the current crouch factor of a player if the player is a pointer.**(development version bb91723 only)****GetDistance**- Gets the distance from the calling actor to a pointer. Can toggle the Z checking functionality.**(development version bd16ccb only)****GetGibHealth**- Gets the gib health property of the calling actor.**(development version 7f57f68 only)****GetPlayerInput**Performs the same functionality as the ACS GetPlayerInput.**(development version 85a34bb only)****GetSpawnHealth**- Gets the spawn health property of the calling actor.**(development version 7f57f68 only)****GetSpriteAngle**- Gets an Actor pointer's sprite angle.**(development version dfed6ac only)****GetSpriteRotation**- Gets an Actor pointer's sprite rotation.**(development version dfed6ac only)****GetZAt**- Gets the Z coordinate of a floor or ceiling at a specific set of coordinates.**(development version 2ba2669 only)****IsPointerEqual**— compares two actor pointers, returning`true`if they reference the same actor.**(New from 2.8.1)**

## Variables

There are a few variables you can use for dynamic data in DECORATE definitions. These are:

- 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**— See GetActorCeilingZ**floorz**— See GetActorFloorZ**pitch**— The actor's pitch in degrees.**roll**- The actor's roll. Currently, this only really affects players such as the rotation of view.**(New from 2.8.1)****(GZDoom only: not supported by ZDoom)**

**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.**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.**(New from 2.8.1)****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.**(development version c940c2b only)****defthreshold**— The actor's DefThreshold.**(development version 43b4d45 only)****Constant Variables**— Constant variables can be defined both inside and outside of an actor.**User Variables**— user 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)

## Examples

See Projectile Trap