• Tutorials
  • Home

    • 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:


    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:

    $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:

    $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:

    $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, data)

    Gets one of the ten available user data variables.

    Return value is the value of the variable.