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.

When

Why

Special Abilities / Script name

Display Adventure Menu

Should we display "CAST" as a possible menu selection.

Script Name: CanCastSpells

Search List:

1. Combatant (in combat only)

2. Character

3. Character's class

Display Party Location and Time

Allow designer to modify text, text location , and color

See: DisplayPartyLocation

Drawing indoor adventure screen

Allow additional designer graphic to be drawn

UpdateIndoorView/SpecialGraphic

Display MAGIC menu

Party Resting

Should we display “MEMORIZE” as a menu option.

Should character memorize spells while resting

Character / CanMemorizeSpells

class / CanMemorizeSpells

Global_Memorize / CanMemorizeSpells

At start of character's turn in combat.

We want to determine the maximum number of steps the character or monster may take.

Character / GetAdjMaxMovement

combatant / GetAdjMaxMovement

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.

CharDisplayStatus

Whenever gametime is incremented

Perform time-related operations such as automatically healing party members.

Global_Time / OnTimeElapsed

At the start of a combat round and during character creation.

Determine the number of attacks per combat round.

Character / GetNumberOfAttacks

Combatant / GetNumberOfAttacks

When a character has been hit by an item in combat.

Determine hitpoints to subtract.

Target / GetITemTargetHitBonus

item / GetITemTargetHitBonus

When a Spell is cast

Perform spell actions

Spell / InvokeSpellOnTarget

Character casts 'Saving Throw'

Compute adjustment to Dice Roll

We search the caster, target, spell, and monster type for scripts that modify the five different types of saving throw.

See SaveVsXxxxx

Action Initiative assigned at start of combat round

Adjust initiative

Combatant / AdjustInitiative

Character / AdjustInitiative

MonsterType / AdjustInitiative

The player attempts to Ready or UnReady an item.

Decide if the action is allowed and print a message.

Item / CanReady

An Item is 'Readied' or 'un-Readied'

Designer Hook

Item / OnReady or OnUnReady

Start of Combat

Designer Hook

Combatant / PreStartCombat

Combatant / OnStartCombat

End of Combat

Designer Hook

Combatant / OnEndCombat

Combat - Last weapon is used

Designer Hook

Character / OnUseLastWeapon

Give Treasure Event

Should Magical items be flagged

Active character / CanCharacterDetectMagic

Attack Roll

Attack with hands or weapon

Did attack Succeed

DoesAttackSucceed

Search List:

1. Attacking Combatant

2. Attacking Character

3. Target Combatant

4. Target Character

5. Weapon

6. Attacker's Class

7. Attacker's Race

8. Target's Class

9. Target's Race

Spell effects being applied to a target.

Did spell work? Display text.

Spell / DoesSpellAttackSucceed

Search List:

1. The Spell being cast

2. Target's Race

3. Target's Monster Type

4. Target Character

Damage Roll

Adjust damage

Script: ComputeDamage

Search List:
1 – Weapon
2 – Target Monster Type (Eg: Orc)
3 – Target Combatant

Damage Roll

Adjust Damaged based on baseclass skill

Script: RangerDamageBonus

Search List: Baseclasses that define RangerBonusLevel

Spell Applied to Character

Adjust modification to character attribute

Script: ComputeSpellDamage

Search List:

1 – Spell

2 – Monster Type

3 – Target Combatant

4 – Attacker Character

5 – Target Character

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

About to Display Combat Menu or combatant moving into another combatant

Information Only

Combatant/CombatMainMenu

For each combatant when player selects a 'Special Action'

Perform special action on each combatant and display special message.

Combatant (Attacker) / CombatSpecialAction

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

See CreateCharacterHooks

Character Creation. Before displaying allowed classses

Allow/Disallow classes

See CreateCharacterHooks

After character is created and is about to be saved.

Last chance to modify newly created character.

See CreateCharacterHooks

Character is allowed to add spells to his spellbook

Control number of spells and which spells can be added

See Learn Spells

The character might be eligible to add spells to his 'Knowable' list.

Control the number of spells and which spells can be added.

Class / KnowableSpellsMinMax

Class / KnowableSpells

Spell / KnowableSpells

See Knowable Spells Hook

The player is going to select spells for a new character

Should a spell be displayed

Character / CanKnowSpell

Spell / CanKnowSpell

Display Character Stats

Modify 'Class' Display

Character / DisplayCharacterClass

Display Character Stats

Modify the 'Race' display

Character / DisplayCharacterRace

Display Character Stats

Modify the 'Baseclass' display

Baseclass / DisplayCharacterBaseclass

Selecting Character Race

Remove Choice of Race

Race / SelectCharacterRace

Selecting Character Class

Remove Choice of Class

Class / SelectCharacterClass

Character Trains

Designer Hook

Character / TrainingCharacter

Character Changes Class

Designer Hook

Class / ChangeClassFrom

Class / ChangeClassTo

Party transferred by Transfer Module

Replace Text or Remove Drow Equipment

We search the Global Special Abilities for an ability named “Global_Transfer” with script named “TransferModule”

Combat Begins

Determine arrangement of party members on playing field

We search the Global Special Abilities for an ability named “Global_Combat” with a script named “PartyArrangement”. We also call 'Global_Combat scripts named “PartyOriginxxx”.

Combat Begins or a monster is added to the combat

Determine where the monster should be placed.

We search the Global Special Abilities for an ability named “MonsterPlacement” with a script named

PlaceMonsterClose

PlaceMonsterNear

PlaceMonsterFar

Spell Missile arrives at target

Allow missile to be redirected to a different target.

Character (target) / RedirectSpell

Spell / RedirectSpell

Display Magic Menu

Control “Scribe” menu option

Character (Active) / CanScribeOrWhatever

Class (of active character) / CanScribeOrWhatever

Player selects 'SCRIBE' on Magic menu

Control results of 'SCRIBE' selection

Character (Active) / ScribeOrWhatever

Class (of active character) / ScribeOrWhatever

Display 'View Character' menu

Control 'CURE' menu option

Character (Active) / CanCureOrWhatever

Class (of active character) / CanCureOrWhatever

Player selects 'CURE' on View Character menu

Control results of 'CURE' selection

Character (Active) / CureOrWhatever

Class (of active character) / CureOrWhatever

Display 'View Character' menu

Control 'LAY' menu option

Character (Active) / CanLayOrWhatever

Class (of active character) / CanLayOrWhatever

Display VIEW/ITEMS menu

Control “Examine” option

Character / CanExamineOrWhatever

Item / Can ExamineOrWhatver

Player selects “Examine” in VIEW/ITEMS menu

Control results of “Examine” selection

Character / ExamineOrWhatever

Item / ExamineOrWhatever

Player selects 'LAY' on View Character menu

Control results of 'LAY' selection

Character (Active) / LayOrWhatever

Class (of active character) / LayOrWhatever

Monster Added to Combat

Modify monster characteristics

Global_CreateMonsterCombatant / CreateMonsterCombatant

MonsterType / CreateMonsterCombatant

Player Selects “FIX”

Control Spell casting

Spell / FixCharacter

Combatant considers entering a cell

Decide if lingering spell blocks movement

Spell / SpellLingerBlockage

A character joins (or re-joins) the party

Designer control

Character / JoinParty

Combatant Moves

Frighten nearby opponents

Combatant / OnStep

Player selects “AIM” in combat

Allow or disallow a combatant to take aim on a target.

Item (in weapon hand) / CanAim

Character (attacker) / CanAim

A spell is cast.

Determine the duration of the spell's effects.

Spell / SpellDuration

A spell is cast.

Determine the range of the spell.

Spell / SpellRange

A spell is cast

Determine the number of targets of the spell

Spell / SpellNumTargets

A Spell is cast

Determine caster's class level

Spell / SpellCasterLevel

A Spell is cast

Cancel effects of previous spells

Script: SpellLingeringScripts

Search List: Spell

Guarding attacks

Free attacks

Several hooks

Guarding

Player examines characters items

Decide if player can identify an item

Character / IdentificationHooks

Player selects a spell to cast

Give the player options

Spell / OverrideSpellSelection

Player Selects Spell Target in Combat

Give the player choices

Spell/OverrideSpellTarget

Spell/ProcessSpellTargetOverride

Combat Character has option to Turn Undead

Should the option “TURN” be displayed?

Combatant / CanTurn

Combat Character selects the “TURN” option

Which monsters should be turned?

Combatand / TurnAttempt

Party encounters a door that is 'Spell Locked'

Does the party have a spell that will open the door?

Memorized Spells/UnlockSpells

WhoTries event

Does the selected character succeed

$EVENT_WhoTries_Attempt / EventHooks

Party Rests

Rest Period Starts; Adjust effects such as poison.

Character/BeginResting

Aura Effects in Combat

Manipulate Aura Effects

See AURA

Training Hall-Change Class

Decide which classes should be allowed

Global Special Ability 'ChangeClass'

Class / CanChangeFromClass

Class / CanChangeToClass

Drawing 3D Viewport

Substitute wall graphics

Global Special Ability “WallSubstitutions”

Script name is “Wall<nnnn> where nnnn is the 4-digit wall number.

Example: the script “Wall0001” might return “4” if the time is between midnight and 1 AM.

Drawing 3D Viewport

Substitute backdrop graphics

Global Special Ability “BackdropSubstitutions”

Script name is “Backdrop<nnnn> where nnnn is the 4-digit backdrop number.

Example: the script “Backdrop0005” might return “6” if the party is subject to the 'Blindness' spell..

Event menu is displayed

Modify text of menu items

EventMenuText

Player “Drinks” in Tavern

Replace standard 'DRINK' text

EventTavernDrink

Event Text is Displayed

Replace Event Text

EventText1

EventText2

EventText3

$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_NAME()

Get the name of the Special Ability that triggered this script.

$SA_SOURCE_TYPE()

The type of object that contained the Special Ability that triggered this script. For example: “COMBATANT” or “SPELL”.

$SA_SOURCE_NAME()

The name of the object that contained the Special Ability triggered this script. For example: “George of the Jungle” or “Heal Minor Wounds”.

$SA_REMOVE()

Remove the Special Ability that triggered this script

$SA_X_GET (Name)

$GET_X_SA (object, Name)

$SET_Y_SA (object, Name, value)

$DELETE_Y_SA (object, Name)

'X' can be any of the following:

CHARACTER

COMBATANT

ITEM

SPELL

SPELLGROUP

MONSTERTYPE

RACE

ABILITY

TRAIT

CLASS

'Y can be any of the following:

CHARACTER

COMBATANT

'Name' is a string containing a special ability name.

'object' is a string naming the object except that for characters and combatants it is an 'actor'.

$SA_X_GET uses the script context to search for special abilities. For example, $SA_ITEM_GET will only work if the script is running in the context of an item and it will search that item for the named special ability.

The other three functions require that you name the object (ITEM, CHARACTER, etc) that is to be searched.

$GET_X_SA fetches the parameter value of the special ability. If no such special ability exists then the function returns the value “-?-?-”

$SET_Y_SA either replaces the parameter value of the named special ability if it already exists or inserts a new special ability with the specified parameter value.

$DELETE_Y_SA removes the special ability completely if it exists.

$SA_SPELL_GET("Electrical") would search the spell in the current 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 "-?-?-".

$GET_SPELL_SA (“Fireball”, “”Toast”) would search the spell name 'Fireball' for a special ability named 'Toast' and would return the associated parameter value which might be “Dark”.

$DUMP_CHARACTER_SAS(actor)

Print a list of one character's Special Abilities along with the value of each. This list is printed to the same file as output produced by $DEBUG(). (Currently into “data\interp.log”)

$GET_HOOK_PARAM(n)

Fetch the value of Hook_Parameter[n]

$SET_HOOK_PARAM(n, value)

Set the value of Hook_Parameter[n]

$ItemContext()

The name of the item in the current SA item context

$SpellContext()

The name of the spell in the current SA spell context.

$AttackerContext()

Returns the 'actor' of the current combatant in the 'Attacker' context.

$CombatantContext()

Returns the actor in the current combatant in the 'Combatant' Context

$TargetContext()

Returns the 'actor' of the current combatant in the 'Target' context

$CharacterContext()

Returns the 'actor' of the current character in the 'Character' context

$SpellgroupContext()

The name of the spellgroup in the spellgroup context

$MonsterTypeContext()

The name of the monster type in the nonsterType context

$RaceContext()

The name of the race in the race context.

$TraitContext()

The name of the trait in the trait context

$AbilityContext()

The name of the ability in the ability context

$DebugWrite(string)

Simply writes the string to the engine debug file "UafErr_Engine.txt". You should supply your own linefeed characters.

$IndexToActor(string)

The opposite of $IndexOf(actor). In combat it converts a combatant index to an actor. Currently undefined outside of combat.

$NextCreatureIndex(creatureIndex, filter)

Given a creatureIndex, this function returns the next index or the empty string if there are no more. To get the index of the first creature, start with an empty string. The filter parameter allows you to skip over certain creatures. A value of 1 skips over dead creatures. A value of 2 skips over creatures friendly to the party. A value of 4 skips over creatures that are non-friendly. A value of 8 skips over creatures that are off the map. You add these values to skip over combinations. To skip over dead creatures and creatures off the map, specify 9. Other filter functions can be added if you find something useful. So, to look through all the living creatures you should start with an empty string and do $NextCreatureIndex until you get another empty string.

index = $NextCreatureIndex("", 1)

$WHILE (index != "")

{

index = $NextCreatureIndex(index, 1)

};

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

$RUN_CHAR_SE_SCRIPTS(actor, scriptName)

Certain spells attach a 'Spell Effect' (SE) to the target of the spell. This function examines each such SE attached to a character, finds the spell that caused the SE, and runs any of that spell's scripts with the provided name. These scripts run in the context of the spell and of the character to which the SE is attached. Hook parameter[5] will be set to an identifier that uniquely identifies the SE, so that,

for example, the script could use $REMOVE_SPELL_EFFECT() to remove the SE from the character.

$RUN_CHAR_PS_SCRIPTS(actor, scriptName)

When a spell is cast in combat, it may take some time for the casting to actually occur. During this time, the spell is kept in the caster's 'Pending Spell' (PS) list. This function ($RUN_CHAR_PS_SCRIPTS) examines a character's Pending Spell List and, for each entry in the list it searches the associated spell for a script by the provided name. These scripts are run in the context of the spell that is pending and in the context of the combatant who originally cast the spell.

If the return value of this function contains the letter 'R' then the spell is 'R'emoved from the combatant's Pending Spell List and the combatant continues to participate in the combat as if the casting time had expired but the spell fizzled.

$RUN_AREA_SE_SCRIPTS(scriptName, combatantIndex);

Can only be used in combat.

Some spells leave lingering effects on the combat map. These effects may affect the combatants who occupy the cells. A script can determine the effects on a combatant by running scripts associated with the spell that caused the lingering effects. See detailed documentation and example at $RUN_AREA_SE_SCRIPTS.

$REMOVE_SPELL_EFFECT(actor, SEIdentifier)

See $RUN_CHAR_SE_SCRIPTS(). This function removes a 'Spell Effect' (SE) from a character.

$CALL_GLOBAL_SCRIPT (SpecialAbilityName, ScriptName)

This function searches the Special Ability database for the specified script belonging to the specified Special Ability and runs it as a “Subroutine” of the calling script. In particular, the hook parameters are the same hook parameters and the context is the same context. It is very much as if you entered the text of the called script into the calling script itself. This feature allows you to have one copy of complex code rather than having to duplicate it in each script that needs the code.

The value returned by this function is the value returned by the called script. If no such script exists, then the value will be whatever is in hookParameter[0].

The word 'GLOBAL' only means that the script belongs to a Special Ability that is defined in the database but is not necessarily attached to any character, spell, etc.

$GET_SPELL_Level(SPELL)

Get the 'level' of the spell identified by spell ID 'SPELL

$GET_CHAR_Ready(actor, bodyLocation, itemNumber)

Gets the name of the item readied at the given body location. Because there may be several items readied at a particular body location, you must specify which – by providing an 'itemNumber'. '0' is the first item at that location, '1' is the second, etc.

$GET_EVENT_Attribute(depth, name)

In general there is always an event active. Even while the party is wandering around the dungeon, an “Adventure” event is active, although it is not editable. Events can have a list of attributes (See the first page of the Event Editor). This function allows a script to retrieve the value of an Event Attribute. The depth parameter will generally be zero, to retrieve an attribute from the active event. On occasion one event will start another event and wait for its results. The event that is waiting is at depth one. 'name' is the name of the attribute and the function returns the value of that attribute of “-?-?-” if no such attribute is found.

$SET_CHAR_Ready(actor, bodyLocation, itemName)

Readies the named item at the body location defined for the item in the item editor. If you specify a blank itemName then the item at the bodyLocation specified as a parameter will be 'unreadied'.

$MODIFY_CHAR_<attr>

Applies a temporary modification to a character's attribute (such as Strength) See $ModifyCharacterAttributes

$GET_PARTY_LOCATION()

Returns the party location in the form:

“/level/x/y”

For example “/3/14/5”

$COMBATANT_AVAILATTACKS(actor, value, function)

Examines/Modifies the number of attacks a combatant has available in the current combat round.

Function = 0 : Set Available Attacks to value.

Function = 1 : Add value to Available Attacks

Function returns new value of Available Attacks.

So, to examine Available Attacks, you should add zero.

$AddCombatant(monsterName, friendlyFlag)

Adds a monster to the combat. Eg: $AddCombatant("Ettin",0)

Delimited String Manipulation

See DelimitedStrings

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

$DialogSelect(string type);

$DialogSet(string id, string value);

$DialogDisplay();

$DialogGet(string id);

'type' is dialog window type. (“0” for now)

'id' is index of control within the dialog.

'value' is the text to display for a control.

See GPDLDialog for more details.

$SetFriendly(combatantID, value)

Value

0=No modification (default)

1=Unconditionally friendly

2=Unconditionally un-friendly

3=Toggle default friendly

any other=no change

Returns old value

$GetCombatRound()

Returns the current Round number. This number starts at zero and in incremented for each round of combat. The turn number can be computed by dividing the round number by 10.

$ComputeAttackDamage(attackerID, targetID)

Both Ids are combatant Ids. Perform the standard ToHit and Damage computations as if the attacker had attacked the target. Returns resultant HitPoint damage.

$ListAdjacentCombatants(combatantID)

In Combat only. List the 'CombatantID's of all combatants that are immediately adjacent to the parameter combatant. The result is a 'Delimited String'. For Example “|2|4|5|8”.

$DAT_Baseclass_Experience(class, level)

$DAT_Baseclass_Level(class, experience)

Fetches information from the 'baseclass.dat' file.

Example:

$DAT_Baseclass_Experience(“Cleric”, 5)

fetches the minimum experience requirement for a level 7 cleric.

$IsLineOfSight(x1, y1, x2, y2, unused)

Combat only. Returns “” or “1” depending on whether a character can see the location (x2,y2) from (x1,y1). The unused parameter may be used someday to add flags such as “Character can see over Orcs less than two inches tall”.

$GET_SPELLBOOK(actor, delimiters)

Gets information that the player would see on the “Memorize” page during the game: See GPDL$GET_SPELLBOOK

$SelectSpell(actor , string)

Increments the 'Select Count' for the named spell in the character's spellbook.

$CastSpellOnTarget(Target, Spell)

$CastSpellOnTargetAs(Target, Spell, Caster)

Provides a way that a script can cast a spell on a character.

Target and Caster are actors.

Spell is the name of a spell.

If a Caster is provided then that character casts the spell; otherwise, a fake, high-level Cleric-Mage is temporarily created to cast the spell.

$Memorize(actor)

Memorize selected spells

$SetMemorizeCount(string spell,adj)

Sets the 'Memorized' count for a particular spell in a particular character's spellbook. The “adj” parameter can be an absolute number or a number preceeded by a plus or minus sign to add or subtract from the current count. The result of the function is the new memorized count, which will be limited to non-negative values. If the character does not have such a spell, then the function will return “-1” (minus one).

$MonsterPlacement(string)

Place monsters in combat.

$SetWall (level,x,y,facing,value)

$SetDoor

$SetOverlay

$SetBackground

$SetBlockage

$GetWall(level,x,y,facing)

$GetDoor

$GetOverlay

$GetBackground

$GetBlockage

Provide 'overrides' for the wall, door, etc that is displayed in a dungeon cell. For the Wall, Door, and Overlay the value is a wall-slot number. The $SetDoor will cause the door associated with the specified wall-slot to be displayed.

The levels are numbered starting with 1. The 'facing' is 0=North, 1=East, 2=South, and 3=West. The x and y values will be taken modulo the width and height of the level. Thus, if x is negative one, it will be interpreted as the rightmost cell on the level. This makes it easier to supply overrides for both sides of a wall because you need not worry about the level actually having the topology of a torus.

If you provide a value equal to 255, the override will be removed and the display will return to that provided by the editor.

The values for $SetBlockage are taken from the editor's display of the choices:

0 = Open

1 = Open,Secret

2 = Blocked

3 = False Door

4 = Locked

5 = Locked and Secret

6 = Locked, Use Spell to Unlock

7 = Locked and Secret, Use Spell to Unlock

8 = Locked, Key 1

9 = Locked, Key 2

10 = Locked, Key 3

11 = Locked, Key 4

12 = Locked, Key 5

13 = Locked, Key 6

14 = Locked, Key 7

15 = Locked, Key 8

The $SetBlockage can be used to force the area view to force particular area view drawing. By adding a constant to the blockage value:

00 - Normal processing - Normal blockage
16 - Never draw a wall here
32 - Always draw a wall here - Normal blockage
48 - Normal processing - No blockage
64 - Always draw a wall here - No blockage
80 - Normal processing - Blocked
96 = Always draw a wall - Blocked

'Blocked' means the graphic representation in the area view only and has nothing to do with whether the party can pass.

'Normal processing' means to draw a wall if one exists (or has an override) and it is designated as 'draw Area View' in editor.

'Normal Blockage' is blockage defined for the wall in the editor (or override).

$IntegerTable(SAName,table,value,operation)

This function allow you to lookup and search tables of integers. A table is defined in a Special Ability, in an entry marked as an 'Integer Table', containing integers, one to a line. Each integer can be followed by a non-numeric character followed by a comment. For example, an experience table might look like this:

0

1000 ; Experience for level 1 Cleric.

2000

4000

8000

The table entries are indexed starting at zero. In the example, the entry corresponding to index 3 would be 4000.

The function takes four parameters:

1. Name of the Special Ability that contains the table.

2. Name of the Table

3. An integer value used to find the desired line of the table. (See below)

4. A search operation. The engine only examines the first character of the operation so you can abbreviate it or misspell it if you like that sort of thing.

The Operation

“Index” - This operation uses the integer value as an index into the table and the function returns the value of the corresponding table entry. If the specified index is greater than or equal to the number of entries in the table then the last entry in the table will be returned. If there are no entries in the table then -1 is returned.

“Equal” - this operation returns the index of the table entry that equals the specified value. If none is equal then it returns -1.

“Greater” - This operation returns the index of the first entry greater than the specified value. If none is greater then it returns the number of entries in the table.

“Less” - This operation returns the index of the first table entry less than the specified value. If none is less, then it returns the number of entries in the table.

Errors

The function can return several different error codes which will be negative:

• -1 No 'Equal' entry was found in the table

• -2 Special Ability entry was not marked as being an 'Integer Table”

• -3 No Special Ability entry found with the specified Table Name

• -4 No Special Ability was found with the specified SAName.

$SET_PARTY_XY(x, y)

Sets the Party location on the current level. To change the party's level, you can put a Transfer Event somewhere on the same level and $Set_PARTY_XY to the location of that Transfer Event.

This function works under the following circumstances:

• When executed in a GPDL Function used as an 'Event Trigger' in an Event Chain.

• When executed within a Logic Block Event

• When executed in a 'Begin Script' for a Spell that is 'CAST' while the party is 'ENCAMPED'.

• When executed in the 'Begin Script' of a Spell attached to an Item that a PC 'USES' in Combat.

In all cases, the party is moved as quickly as possible without further processing of the event chain or the spell. For example, a 'Heal' spell that contains this function in its Begin Script will do no healing.

If the Party is moved to a cell containing a Transfer Event and you do not want the player to see that cell before being transferred, then the Transfer Event should have the 'Activate when Party attempts entry' option selected.

$ForEachPartyMember (SpecialAbilityName, ScriptName)

For each character in the party, this function runs the script described by the two parameters. The script will run with $CharacterContext defined for that character.

HookParameter[0] is set to an empty string for the first character and, for each subsequent character, contains the result from the previous character. This makes it easy to do 'AND' and 'OR' and other logic operations or to count the number of characters that meet particular criteria. For example, you might count the number of party members who are at least level 3 Ninjas.

$ForEachPossession(actor, scriptName)

For each item in the character' possession, this function will search the item's Special Abilities and run any scripts with the given name. The scripts will run with $CharacterContext and $ItemContext. The $ItemContext will be specific for each possession so that if the character possesses two items with the same name, the script will be run twice and each $ItemContext will indicate one item the first time and a different item the second time.

$GetCombatantState(actor)

'actor' is a combatant context.

This function returns one of the following:

"ICS_None" – Waiting for player choice

"ICS_Casting"

"ICS_Attacking"

"ICS_Guarding"

"ICS_Bandaging"

"ICS_Using"

"ICS_Moving"

"ICS_Turning"

"ICS_Fleeing"

"ICS_Fled"

"ICS_ContinueGuarding" – Continue guard into new round

$IsIdentified(actor, key, what)

See: Identification Hooks

$GetFriendly(combatantIndex, type)

• Actor should be a character in combat or a combatant

• type is the type of data you want.

Each combatant starts combat with a 'basic' friendliness. Monsters are generally not friendly and party members are generally friendly. A script can adjust the friendliness of a combatant with the $SetFriendly function.

If (type == "B") result is Basic friendliness

0 = not friendly

1 = friendly

If (type == "A") result is Adjustment to friendliness

0 = no adjustment

1 = forced to be friendly

2 = forced to be not friendly

3 = toggle friendly

If (type == "F") result is Final adjusted friendliness

0 = not friendly

1 = friendly

Else result is "Huh?";

$SkillAdj(actor, skill, id, type, value)

• actor identifies the character to modify.

• skill is the name of the skill to be adjusted. For example: “TightRopeWalker”.

• id is an arbitrary string you can use to identify the adjustment. A skill may have many adjustments and the id would be used to identify a particular adjustment to be added/modified/removed and to determine the order that the adjustments are made.

• type defines the type of adjustment to be made to the skill

1. '+' : the value will be added to the skill.

2. '-' : the value will be subtracted from the skill

3. '*' : The skill will be multiplied by the value

4. 'D' : the adjustment will be deleted.

5. '% : the adjustment is a percentage adjustment. For example 110 would cause the skill to be increased by 10 percent. Thee result is rounded to the nearest integer value.

6. '=' : the skill will be set to an absolute value.

7. 'F' : Compute the 'F'inal skill value after all modifications and adjustments have been made.

8. 'A' : return the named 'A'djustment for a particular id. This option does not check to see that such a skill exists or if basclass-level or ability-score adjustments exist. It only retrieves the adjustment created with the specified id. If no such 'named' adjustment exists, the return value is “noSkill”.

9. 'B' : Return the highest skill value including any baseclass and race modifications but 'B'efore any &SkillAdj() adjustments. If there is none, then it returns an empty string.

• value is the numeric adjustment to be made.

The function returns a value for the 'B', 'F', and 'A' cases and otherwise an empty string. A special reserved value of “NoSkill” is returned when the character has no such skill. If this special value is interpreted as an integer, it will result in a numeric value of zero.

A character can have any number of skills. Generally, the skills are defined in the baseclass data (for example, a thief might have a 'PickPocket' skill) but can also be defined in the race database.

The baseclass and race databases can also define modifications to the skill's value based on ability scores and baseclass levels.

In addition, there can be temporary adjustments to each skill which are added/modified/deleted using the $SkillAdj() function in scripts.

When a skill is required, the engine finds the highest skill value definition among the character's baseclasses and race (There are exceptions for some system-defined skills. For example, MaxLevel$SYS$ uses the smallest value.). It then applies (in this order) the race, baseclass, and ability adjustments, first from the race database and then from the baseclass databases in alphabetical order (Again, exceptions may exist for system-defined skills. For example, MaxLevel$SYS only uses one baseclass for multi-baseclass characters.). Then the final value is subject to adjustments specified by $SkillAdj(). If there are several $SkillAdj() adjustments for a single skill, then they are performed in alphabetical order of the associated 'id' identifiers.

$SkillAdj() can add a skill to a character that he would otherwise not have. The skill need not appear in the baseclass or race database. The skill value will then be assumed to be zero before the adjustment is applied.

Adjustments for a character must be unique in the skill name and id. If $SkillAdj() attempts to add an adjustment for a skill/id that already exists, then the old type and value are replaced.

$SpellAdj(actor,school,id,first,last,p,b)

For an individual character, we compute the number of spells he can cast in each spell school and at each spell level.  For each individual character and each spell school and for each spell level within that school you want this number to be temporarily or permanently modified.

So we provide a two-dimensional matrix for each character....

The row names the spell school.
There is a column for each spell level.

Each entry gives the adjustment to the computed number of spells allowed for that school and spell level. And each entry might have several modifications (A red magic wrench might halve an entry and a blue magic wrench might double it; canceling each other).

This function that provides seven parameters.

1. The Character (actor)

2. The spell School (or "*" for all)

3. An Identification (In case there are multiple modifications for a single school/level)

4. The first spell level to modify.

5. The last spell level to modify.

6. Two constants (p and b) defining a linear
   transformation (999999,n to remove
   the n-th layer of transformation with the
   specified Identification.)
   newValue = p*oldValue/100 + b
   
   p= percent
   b = bonus
   
   To double use: a=200 b=0
   To halve use: a=50 b=0
   To disable use: a=0 b=0
   To add 3 use: a=100 b=3
   To subtract one use: a=100 b=-1
   To set to 5 use: a=0 b=5
   To remove oldest adjustment use: a=999999 b=0
   
   Adjustments would be made in alphabetic order
   of Identification and first-in/first-out
   (adjustments with the same identification get
   done in the same order they were created).

$KNOW_SPELL(actor, spell, add)

Adds a spell to (or deletes a spell from) the actor's spellbook. If 'add' is non-zero then the spell is added. Else the spell is deleted. The return value is '1' if the operation was successful.

$GetHighestLevelBaseclass(index)

'index' is party index outside of combat and combatant index when in combat. The function examines the character's baseclasses and returns the name of the baseclass with the highest level. An empty string indicates some sort of error...no such character, for example.

$GetBaseclassLevel(index, baseclassName)

Return the current of the character's baseclass. A return value of zero indicates some error.

$RollHitPointDice(baseclassName, low, high)

When a character gains a level in a baseclass, he gains Hit Points as defined in the baseclass definition. The number of hitpoints is defined as a dice roll of the form nDm+k. For example: 1D10+0 or 0D0+2. This function performs those dice rolls for each level from low to high and returns the sum of the results.

$DAT_Race_xxxxxx

Get values from the Race Database.

See GPDL$DAT_Race

$DAT_Item_xxxxx

Get values from the Items Database

See GPDL$DAT_Item

$DAT_Class_xxxxx

Get values from the Class Database

See GPDL$DAT_Class

$GET_CONFIG(name)

Get values from “config'txt”.

See GPDL$GET_CONFIG

$GrSet, $GrPrint, etc....

See GraphicsDraqwingFunctions

$SLEEP(milliseconds)

Everything stops for the given amount of time.

$DrawAdventureScreen()

Attempts to redraw the 3D 'adventure' screen. If called from a 'Special Graphics' hook, it will not recursively call the hook. This is to avoid infinite recursion.