AURA

During combat it is possible to place one or more 'AURAs' on the combat map. Each AURA can be the shape and size the designer specifies. The engine keeps track of which combatants are within the effect of the AURA and notifies the designer's Hooks when interesting events take place relative to each AURA. For example, it will notify a hook when a combatant enters or leaves the area affected by the AURA. The hooks are described, one at a time, below.

THE AURA

Each AURA has many properties, some of which can be examined and modified by its associated Hooks.

Some of these properties are:

• Four size parameters to define the size of the AURA.

• A spell name – used to create the graphic associated with the AURA.

• Ten 'User-defined' data variables. Not used or modified by the engine.

• A shape.

• A wavelength

• (((( Eric: Would a timeout be useful? Auto-remove after 5 rounds, for example)

To create an Aura, the designer must use the function “$AURA_Create”:

FUNCTION $AURA_Create(sa, param, d1, d2, d3)

This function takes five parameters:

1. sa – This is the name of a Special Ability that will be initially attached to the AURA.

2. param – This the parameter associated with the special ability 'sa'.

3. d1 – Arbitrary initial user data. Will be assigned to UserData[0];

4. d2 – Arbitrary initial user data. Will be assigned to UserData[1];

5. d3 – Arbitrary initial user data. Will be assigned to UserData[2];

THE HOOKS

Here is how the AURA's hooks are defined and executed:

When an interesting AURA event occurs, the engine will call a hook script with a hard-coded name. For example, when a AURA is created (That is interesting, don't you think?), the engine will call a hook named AURA_Create (not to be confused with the function $AURA_Create). The engine will search the AURA's Special Abilities, looking for a script with the name “AURA_Create”. It will execute all such scripts. The functions within those scripts which reference an AURA will automatically reference the AURA with which the interesting event is associated. So the hook functions can only reference that one particular AURA and need not have any way of identifying it.

Any functions that a Hook performs that changes the nature of the AURA will not take place immediately but will be saved and will be applied after all Hooks are completed. If, for example, several combatants are suddenly excluded from the AURA, then several Hook scripts may be executed (one for each such combatant). If one of those hooks should enlarge the AURA so as to include additional combatants and another Hook should reduce it to its original size so as not to include those same combatants, then absolutely nothing will happen as a result of those changes. This is because the engine only checks for changes after all Hooks have completed and will see no change in the size of the AURA.

AURA_Create

This is the first Hook called when an AURA is created. This Hook will very likely define the position, size, and shape of the AURA.

AURA_Enter

Called when a combatant enters the area affected by the AURA.

This Hook will execute with $CombatantContext() defined.

AURA_Exit

Called when a Combatant exits the area affected by the Aura.

This Hook will execute with $CombatantContext() defined.

AURA_Round

Called at the start of each round of combat. This Hook will likely count the number of rounds and remove the AURA when it has expired. It could also cause the AURA's size to decrease at the start of each round and remove it when the size becomes zero. Or it could change the graphic and weaken the effect of the AURA. Or whatever.

AURA_Effect

Called once at the start of each round of combat for each combatant affected by the AURA.

FUNCTIONS

In addition to $AURA_Create, the following functions are available for use in AURA Hooks:

$AURA_Destroy()

Removes the AURA from the battlefield.

Result value undefined.

$AURA_AddSA(saName, saParameter)

Adds a Special Ability to the AURA.

Result value undefined.

$AURA_GetSA(saName)

Result value is the parameter associated with the Special Ability. IF no such Special Ability exists then the result value is “-?-?-”.

$AURA_RemoveSA(saName)

Removes the Special Ability from the AURA.

Result value is the same as for $AURA_GetSA(saName);

$AURA_Attach(attachType)

Define how the AURA is attached to the battlefield. Possible values are:

• “Combatant” - The AURA originates at the cell occupied by a combatant. Angle zero is to the east.

• “CombatantFacing” is the same as “Combatant” except that angle zero is in the direction the combatant is facing (usually the direction of most recent movement).

• “XY” - The AURA is attached to a fixed point on the battlefield. Angle zero is to the east.

$AURA_Location(x, y)

If the attachment type is “XY” then this defines the point on the battlefield to which the AURA is attached. Otherwise, this location is ignored.

$AURA_Combatant(combatantIndex)

If the attachment type is “Combatant” then this defines the combatant index of the combatant to which the AURA is attached. Otherwise, this is ignored.

$AURA_Size(s1, s2, s3, s4)

Defines the size of the AURA. See the function $AURA_Shape for a discussion of how the four parameters are interpreted.

$AURA_Shape(shape)

Defines the shape of the AURA. Possible values are:

• “AnnularSector” - The AURA is shaped like a circle with an interior circle removed....like a 2-dimensional doughnut. The four size parameters (see $AURA_Size) determine its size as follows: s1 is the radius of the interior circle; s2 is the radius of the outer circle; s3 is the starting angle; s4 is the included angle. Angles are measured starting with a line as described in the description of $AURA_Attach and extending counter-clockwise. The units are degrees. Examples: (0,6,77,360) would be a full circle with radius 6. (0,6,90,90) would be a quarter-circle to the northwest. (5,6,0,360) would be a full doughnut with internal radius 5 and external radius 6.

• “None” - The AURA remains on the battlefield but it has no extent. The size parameters are unchanged but are ignored.

$AURA_Spell(spellName)

Defines a spell whose “Linger Graphic” will be used to show the cells affected by the AURA.

$AURA_Wavelength(waveType)

Defines the wavelength of the radiation used to determine the AURA's extent. The engine starts at the AURA's source and illuminates each of (up to) 104 directions. Different wavelengths of radiation are interrupted by different objects. Possible values for waveType:

• “Visible” - This radiation is interrupted by combatants or walls.

• “Xray” - This radiation passes through combatants but is stopped by walls.

• “Neutrino” - This radiation passes through combatants and walls.

$AURA_SetData(index, data)

Sets one of the ten available user data variables.

Return value is the previous value of the variable.

$AURA_GetData(index)

Gets one of the ten available user data variables.

Return value is the value of the variable.