Special Abilities Scripts
See also Special Abilities
Special ability scripts are called with zero parameters. Each has access to parameters via the function $GET_HOOK_PARAM(n).
Parameter number |
Usage |
0 |
Result of previous script called for this hook. |
1 – 4 |
Not used....reserved for enhancements. |
5 - 9 |
Up to 5 parameters for particular hook scripts. The value of these parameters is described in each of the descriptions for particular hooks. Unused parameters will be initialized to empty strings. These five aparameters can be modified by the scripts using $SET_HOOK_PARAM(n). When a hook is activated, several special abilities may be examined and several scripts might be called. These five parameters are set before the call to the first script and are not modified for subsequent calls. Therefore, they may be used to communicate between several scripts. |
Hooks
The rightmost column of this table lists the object or objects searched and the name of the script we search for. For example, 'spell/InvokeSpellOnTarget' means that we search the spell's special abilities looking for any special ability with an associated script named 'InvokeSpellOnTarget'.
Each of the script names listed in the rightmost column of this table is called within an 'SA Context'. This 'SA Context' provides information that the script can use to examine the particular characters, spells, items, etc that might be of interest. The documentation for each hook lists the 'SA contexts' that are valid for that particular hook. For example, a hook that determines if a spell can affect a particular target might like to know details of the spell and the target. There are simple functions to retrieve Special Abilities parameters from the objects represented by the 'SA Contexts' (example $SA_SPELL_GET) and to retrieve identifiers for the objects represented by the 'SA Contexts' (Example $ITEM).
When |
Why |
Special Abilities / Script name |
Display Adventure Menu |
Should we display "CAST" as a possible menu selection. |
|
At start of character's turn in combat. |
We want to determine the maximum number of steps the character or monster may take. |
|
At start of each turn of combat. |
Determine if the combatant is able to fight. Commonly this means not sleeping or held or whatever. |
Character / IsCombatReady Combatant / IsCombatReady |
When a combatant's status is displayed. |
Get the text that describes the combatant's condition. |
|
When a character is deciding to attack. |
Get the number of attacks. |
Character / GetNumberOfAttacks |
When a character has been hit by an item in combat. |
Determine hitpoints to subtract. |
|
When a Spell is cast |
Perform spell actions |
Spell / InvokeSpellOnTarget |
An Item is 'Readied' or 'un-Readied' |
Designer Hook |
|
Start of Combat |
Designer Hook |
Combatant / OnStartCombat |
End of Combat |
Designer Hook |
Combatant / OnEndCombat |
Combat - Last weapon is used |
Designer Hook |
Character / OnUseLastWeapon |
Give Treasure Event |
Should "Detect" be a menu option? |
Memorized spells / CanSpellDetectMagic |
Attack Roll |
Did attack Succeed |
|
Damage Roll |
Adjust damage |
Combatant / ComputeDamage |
Combatant Selects 'Ready' |
Ready Equipment set |
Combatant / OnReadyCombatEquipment |
Start of each combat round |
SA initialization/cleanup |
Combatant / StartCombatRound |
Selecting a target |
Exclude 'blinked', etc |
Combatant / IsValidTarget |
Combatant begins action |
Information only |
Combatant / OnStartCombatantAction |
Combat Move Menu Construction |
Allow or prevent character movement |
Combatant / DrawMoveMenu |
Combatant starts action |
Does Engine control combatant |
Combatant / AutoAction |
After assigning character's Class |
Designer Hook |
|
The player is going to select spells for a new character |
Should a spell be displayed |
|
Display Character Stats |
Modify 'Class' Display |
Character / DisplayCharacterClass |
Additional GPDL functions.
Some discussion of the terms 'ACTOR', 'Combatant ID', and so on is in order here. It is confusing to me so I imagine it will be confusing to you.
ACTOR, ITEM:
These are special values that cannot be treated as a string. Some functions return such values and they cannot be used in any way except as parameters to functions that accept these particular values. For example:
-----------
$VAR me;
me = $MySelf(); /// Illegal. Using ACTOR value as if it were a string.
-----------
$VAR me;
me = $IndexOf($Myself()); // Works OK because '$IndexOf' expects an ACTOR.
-----------
Combatant id
Only in combat, obviously. It is the index of a combatant. This is a number from zero to one less than the number of combatants. Combatants may be added during combat and additional 'combatant id's are assigned. Combatants who die or flee retain their 'combatant id' until the combat is completely finished.
Character id
During combat this is identical to 'combatant id'. Outside of combat, this is a number that uniquely represents a particular character within the party. A character's id never changes as long as he remains in the party. Therefore, as characters are added and deleted, these ids are not necessarily contiguous. For example, a two-character party might have character id of 5 and 7.
Functions that are only useful in Special Abilities Scripts
$SA_PARAM_GET() |
Get parameter value for the special ability that triggered this script. |
$SA_PARAM_SET(value) |
Set the parameter value of the special ability that triggered this script. |
$SA_SA_GET() |
Get the name of the Special Ability that triggered this script. |
$SA_REMOVE() |
Remove the Special Ability that triggered this script |
|
Fetch the parameter for the named special ability in the current SA context. For example $SA_SPELL_GET("Electrical") would search the spell in the current SA spell context for a Special Ability named 'Electrical' and return the parameter associated with that Special Ability. If no such special ability exits then result is "-?-?-". |
$SA_X_SET(Name, value) |
Set the parameter for the named special ability for the object in the current SA context. XXX can be any of the data types listed forSA_XXX_GET. |
$SA_X_DELETE (Name) |
Delete the named special ability from the object in the current context. XXX can be any of the data types listed for SA_XXX_GET. Returns the parameter associated with the deleted special ability or "-?-?-" if no such special ability existed. |
$GET_HOOK_PARAM(n) |
Fetch the value of Hook_Parameter[n] |
$SET_HOOK_PARAM(n, value) |
Set the value of Hook_Parameter[n] |
$Item() |
Get the item id of the item in the current SA item context |
$Spell() |
Get the spell id of the spell in the current SA spell context. |
$Attacker() |
Returns the 'character id' in the current SA Attacker context |
$Combatant() |
Returns the 'Combatant ID' in the current Combatant Context |
Functions that reference Special Abilities for arbitrary objects
|
The the parameter associated with an item's Special Ability. Result is "-?-?-" if none exists. |
|
Give Special Ability named SA, with parameter param, to character id. See $NextCreatureIndex for a discussion of how to use 'id'. |
$SET_COMBATANT_SA(id, SA, param) |
Give Special Ability named SA, with parameter param, to combatant id. See $NextCreatureIndex for a discussion of how to use 'id'. |
Functions that have nothing to do with special abilities
$DebugWrite(string) |
Simply writes the string to the engine debug file "UafErr_Engine.txt". You should supply your own linefeed characters. |
$NextCreatureIndex(creatureIndex, filter) |
|
$RUN_CHAR_SCRIPTS(creatureIndex, scriptName) |
See $IsLegalCreature for the meaning of 'creatureIndex'. This function searches the specified creature's Special Abilities for scripts of the given name. Any that are found are run until one of them returns a value starting with 'N'. If none returns an 'N' then, in combat mode, the associated combatant's Special Abilities are similarly searched and scripts are run in the same way. The scripts that are found share the Hook Parameters with the script containing this function call. Thus you can pass parameters to the called scripts and receive results back via the $GET/SET_HOOK_PARAM functions. The value returned by this function is currently undefined. |
$GET_SPELL_Level(SPELL) |
Get the 'level' of the spell identified by spell ID 'SPELL |
$GET_CHAR_Ready(actor, bodyPosition) |
Gets the name of the item readied at the given body position. |
$SET_CHAR_Ready(actor, bodyPosition, itemName) |
Readies the named item at the given bodyPosition. 'itemName' may be blank to unready any item at that position. |
$AddCombatant(monsterName, friendlyFlag) |
Adds a monster to the combat. Eg: $AddCombatant("Ettin",0) |
$DelimitedStringCount(string) |
The first character of the string is the delimiter. This function counts the number of delimiters in the string. |
$DelimitedStringSubstring(string, n) |
|
$TeleportCombatant(id, x, y) |
In combat only. 'id' is the 'combatant id' of the combatant to teleport to location (x,y). Eg: $TeleportCombatant($IndexOF($Myself()),12,22) |
$Target() |
Returns the 'ACTOR' of the current Target context |
|
|
$SetFriendly(combatantID, value) |
|