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

## Trigonometry functions

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

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.**frandompick[***identifier***](***float***, ...)**— similar to*randompick*but for float-point values.

*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.**CountInv**- Gets the number of inventory items an actor is holding from a pointer and returns it to the expression.**(New from 2.4.0)****CountProximity**- Similar to A_CheckProximity but returns how many of the actors are found instead of jumping.**(New from 2.4.0)****GetAngle**- Gets the angle which an actor pointer can be found at. Can toggle the relative functionality**(New from 2.4.0)****GetCvar**- Gets a server cvar, internal or user.**(New from 2.4.0)****GetCrouchFactor**- Gets the current crouch factor of a player if the player is a pointer.**(New from 2.4.0)****GetDistance**- Gets the distance from the calling actor to a pointer. Can toggle the Z checking functionality.**(New from 2.4.0)****GetGibHealth**- Gets the gib health property of the calling actor.**(New from 2.4.0)****GetMissileDamage**- Gets the damage of the actor.**(New from 2.4.0)****GetPlayerInput**Performs the same functionality as the ACS GetPlayerInput.**(New from 2.4.0)****GetSpawnHealth**- Gets the spawn health property of the calling actor.**(New from 2.4.0)****GetSpriteAngle**- Gets an Actor pointer's sprite angle.**(New from 2.4.0)****GetSpriteRotation**- Gets an Actor pointer's sprite rotation.**(New from 2.4.0)****GetZAt**- Gets the Z coordinate of a floor or ceiling at a specific set of coordinates.**(New from 2.4.0)****IsPointerEqual**— compares two actor pointers, returning`true`if they reference the same actor.**OverlayID()**- When used in an overlay, retrieves the overlay's layer.**(New from 2.4.0)****OverlayX**- Returns the x position of the specified overlay.**(New from 2.4.0)****OverlayY**- Returns the y position of the specified overlay.**(New from 2.4.0)**

## Variables

As of ** ^{90cc79a}**, it's 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 ** ^{8437313}**, 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*— 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.**(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.**(deprecated in development versions r3eb1af6+, but still valid in official version 2.4.0.)***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.**(New from 2.4.0)***defthreshold*— The actor's DefThreshold.**(New from 2.4.0)****VisibleAngle(Start/End)**- The actor's angle range which the camera must see it to draw the sprite. Requires MASKROTATION flag to have any effect.**(New from 2.4.0)****VisiblePitch(Start/End)**- Same as VisibleAngleStart and VisibleAngleEnd but for pitch instead.**(New from 2.4.0)***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