Table of Contents

Function script (XG)

XG functions are functions in a mathematical sense. They evaluate to a number that might change as time goes by. XG functions are strings. Some characters are interpreted as control characters and others represent values from zero to one. Sectors can use functions to change their light level, color, the height of the floor and ceiling planes and to send Chain events.

Symbols

The table below lists all the symbols that can be used in functions. There can be any number of spaces between two symbols. Often adding a couple of spaces makes the function easier for humans to understand.

Symbol Meaning
a … z Values from zero to one. Values between two consecutive lowercase letters will be interpolated. Example: az will smoothly blend from zero to one, but aZ and Az will not.
A … Z Values from zero to one. Won't be interpolated between steps.
/ Exact value. A floating point number must immediately follow. Corresponds a lowercase letter, so interpolation will be done. Example: z/0.355a would interpolate from 1 to 0.355 and then to zero. /1 is the same as z.
% Exact value. A floating point number must immediately follow. Corresponds an uppercase letter, so there will be no interpolation. Example: %1 is the same as Z.
(number) Repeat the following value this many times. The value must follow the number immediately. Example: 12A equals AAAAAAAAAAAA. The smallest number that can be used this way is one, but 1a equals a, so there isn't much point in using it.
. Break interpolation. Placing a period after a lowercase letter will cause the evaluator to skip the letter. Example: azaz will smoothly blend from 0 to 1, then from 1 to 0 and finally from 0 to 1. az.az will smoothly blend from 0 to 1 and then again from 0 to 1. The second interpolation that would go from 1 to 0 is broken by the period.
# Set step timer. A number must immediately follow a # symbol. Example: AB#14CD will set the step timer for the C step to 14 tics. This means the step will be in effect for 14 tics (0.4 seconds).
? Random step timer. A number must immediately follow a ? symbol. The step timer for the next step of the function will be set to a random number between zero and the given value. Example: AB?6CD will set the step timer for the C step to a random number between zero and six.
> Begin of repeat sequence marker. The evaluator skips this.
< Repeat. Makes the evaluator jump to the beginning of the function or to the latest > marker. Example: az>mz< will smoothly blend from 0 to 1, then from 1 to 0.48 and finally repeat blending back and forth between 0.48 and 1. AZ< as a light function could be used for a strobo effect.
! Chain event. A line type ID must immediately follow the exclamation point ! . The event will be an activating one and it will be sent in the beginning of the step (when the evaluator arrives at the value following the ! symbol). Example: a!5210z will first interpolate from 0 to 1 and then send the Chain event 5210.

The first character of a function string can also be a special character:

Symbol Meaning
= Linked function. The value of the function is linked to the value of another function of the same sector (their values are always equal). The character following the equal sign = determines which function this one will be linked to:
- f: Floor fn
- c: Ceiling fn
- r: Red fn
- g: Green fn
- b: Blue fn
- l: Light fn
Example: the function =b would be linked to the Blue function of the sector.
+ Dynamic offset. When the function is initialized (at the beginning of the level or when the sector type is set) its offset will be modified depending on the character following the plus sign +. Evaluation of the function will begin from the third character of the function string.
- f: Original floor height
- c: Original ceiling height
- r: Original red color
- g: Original green color
- b: Original blue color
- l: Original light level
Example: beginning a function with +f would add the original floor height of the sector to the function offset.

Evaluation of functions

The first actual symbol of a (non-linked) function string must be a value (an uppercase or a lowercase letter or an exact value). It is the initial value of the function.

Each value symbol defines a step. The evaluator advances to the next step when the timer for the current one reaches zero. The type definition specifies the minimum and maximum number of tics for each step. If the step timer isn't set with the # or ? symbols, it will be set to a random number between the minimum and maximum tics for each step. Interpolation is always done between the current step and the next one. If both are interpolateable (lowercase letter or an exact value defined with a slash / ) the value of the function will gradually blend from the current step's value to the next one's.

The current value of a step will be multiplied with a scaling factor and an offset will be added. Acceptable values for the function depend on the context: for example, light and color functions are automatically scaled with 255 and have no offset. The floor and ceiling functions' scale and offset can be specified in the type definition.

Examples:

Function Meaning
zaN Interpolate from 1 to 0, wait one step at 0 (won't interpolate from a to N) and stay at 0.52.
za.N Interpolate from 1 to 0, stay at 0.52.
A.Z The same as AZ : one step at 0, stay at 1.
az.< Repeat interpolating from 0 to 1. The period breaks the interpolation that would happen from 1 to 0 (over the repeat marker).
+f m ?35m > miecbceimqtwyzywtq < Dynamic offset to the original floor height of the sector. Initial value (the first step) is 0.48. The second step has the same value, but a random timer with at most 35 tics (one second). Start repeating an interpolated approximation of a sine wave.
z5/1>#1%0.333?7%1< Initial value is 1. The first step is followed by 5 steps, each of which has the exact value of 1 (same as z). Start repeating a sequence whose first step is one tic long and has the exact non-interpolating value of 0.333. The second step of the sequence is a random length one (up to 7 tics) with the non-interpolating exact value of one (same as Z).

See also