Complete Scripting Guide

The script:

IF
    // Triggers
THEN
    RESPONSE #100
        SetToken("TOKEN1",#####) // string2
        SetToken("TOKEN2",#####) // string3
        DisplayString(Myself,#####) // string1
END

Will display the string "test1 and test2".
In this example, the first action sets to string1. The second action sets to string2. The third action displays string 3. If string 3 is " and ", then whatever tokens 1 and 2 have been set to will be displayed: "string1 and string2". The strings must be present in the TLK file, and you specify a strref with the action.

Note that you cannot assign different value to the same token for different creatures. SetToken is a 'global' action.

However, tokens also have further use. You can use SetTokenGlobal to set the value of a token to that of a global, which can be useful in some situations.
One use of SetTokenGlobal might be for debugging: you can use it to check the value of globals with a hotkey via a script, which might be more convenient than the console. Simply create a string in the TLK with the token to be used, and have a hotkey triggered script assign the value of the variable you are checking to this token. Of course, you can use multiple tokens and variables.

You can also use tokens for targetting, with SetTokenObject.
If you use the action SetTokenObject("TARGET",Myself), you can then use [TARGET] as an object in subsequent blocks/scripts.

Bear in mind that tokens are not stored in the savegame; therefore, for them to be used, they must be reinitialized every time the game is loaded.

14) Default scripts

Upon first inspection, the ACTION.IDS and TRIGGER.IDS files often appear somewhat incomprehensible. However, when used properly, they can tell you the syntax used with each action or trigger.

0x400F Global(S:Name*,S:Area*,I:Value*)

This is an example of an entry in TRIGGER.IDS.
The 0x400F part is the trigger ID, and is not important in writing scripts. However, it is worth understanding that when the script is compiled, this is the number to which the compiler converts the action or trigger you used.

Inside the brackets, the parameters for the trigger are given. These are separated by commas, and always take the form X:Something* or X:Something*Something.

In the first case, the X indicates the type of argument.
This can be:

O - object
This can be:

• 1) A death variable or object name (such as door name/trap name). Its length is maximum 32 characters
• 2) An object type in the form of [EA.GENERAL.RACE.CLASS.SPECIFIC.GENDER.ALIGN]. In this form the values are integer types (decimal, hexadecimal or IDS lookup). It is not necessary to specify all values, and any omitted values will be counted as zero.
• 3) An object from OBJECT.IDS, possibly nested. An omitted parameter in an object defaults to 'Myself'.

P - point
In the form of [X.Y] where X and Y are numbers. A point of [-1,-1] used to mean the actual position of the actor

A - action
Used only with ActionOverride, this is an action to perform

S - string
This may be an area name (strictly 6 characters), death variable (theoretically up to 32 characters, but in practice, should not be over 18, to allow for 'sprite_is_dead'), a resref (filename, up to 8 characters long) or in IWD2 a spell string (which consists of a string of spell numbers, each made up from 3 letters).

I - integer
Either a decimal, hexadecimal or IDS lookup value. TLK strrefs are integers.

In the above example, the something is a brief explanation of the purpose of this argument; this is meaningless to the compiler, but can give an indication of what the argument should be.
In the second case, it is the same, but the something after the asterisk indicates that entries from an IDS file are used. So, in the above example, the first parameter is the global name (a name), the second is the area (a name), and the third is a value (integer).

It is also worth noting that strings are always written in quotes.

Other IDS files simply provide identifiers for use in scripts.

IDS files can be changed, and the script compiler and game will respond to this; however, it is important to fully understand them before attempting any changes. ACTION.IDS and TRIGGER.IDS in particular require understanding, and the main use for changes to point an action or trigger to another custom IDS file.
For exmaple, changing the range trigger to:

0x4018 Range(O:Object*,I:Range*Range)

Will allow identifier values from a RANGE.IDS file to be used with this trigger.

1) 'Header' - sets any initial variables once only, and handles the turning hostile of neutral creatures.
2) Weapon handling - sets globals to indicate later on what types of weapon are available: this only occurs once normally (although setting globals should allow for it to cope with running out of ammo); good weapon handling is crucial, and this is done early on
3) Priority actions - includes all manner of behavior which is important to perform; this includes hiding in shadows, moving to the player if they are unseen, running from area spells, and coping with low hit points
4) Item usage - items are placed in order, with the most preferable to use at the top
5) Target acquisition - selects the target as appropriate for later attacking blocks; the See or Detect triggers are not used beyond here, to avoid disrupting the targetting process
6) Movement - maneuvering as a result of the presence of a target or other enemy nearby, or in preparation for an attack
7) Further item usage - semi-random usage of offensive items such as wands on the selected target
8) Spellcasting - casts spells semi-randomly on the selected target, with appropriate checks performed
9) Physical attacks - attack the target physically, taking into account distance and the weapons available (which are stored in globals); also includes support for later randomwalking
10) Randomwalking - a last resort block, which helps in target selection and makes combat more interesting

This is simply an outline, and can obviously be adapted to suit personal preference. However, the crucial thing to bear in mind is that the most important blocks should always be placed towards the top of the script; so long as this is done, the rest is optional.
For more information on what some of these sections I have listed actually consist of, see the Useful Scripting Techniques section.

It is often best to plan out what a script needs to do, and how this should be organised within it before starting. When you begin writing a script, stick rigidly to the structure and use comments to organise it; section headings, block headings, and contents are all useful.
Remember that a well structured script is more fluent, and will prevent slowdown due to size.

A cutscene can be called either from another script, or from dialog. A block to call a cutscene might look like:

IF
	// Triggers
THEN
	RESPONSE #100
		ClearAllActions() // This ensures that all action lists are cancelled before beginning the cutscene
		StartCutSceneMode() // This action removes the player interaction from the game
		StartCutScene("cutscene") // Starts the cutscene 'cutscene.bcs'
END

Then, cutscene.bcs might contain:

IF
	True() // Cutscene conditions are always read as true anyway
THEN
	RESPONSE #100
		CutSceneID(Player1) // This must be specified in every cutscene block, and specified who 'performs' the actions
		// Actions
		EndCutSceneMode() // This reverses the StartCutSceneMode() action
END

CutSceneID sets who performs the actions in the cutscene. Therefore, anything intended to affect characters other than the CutSceneID must be performed via ActionOverride.
However, each ActionOverride must be completed before the next action is executed. Therefore, ActionOverride(Object,PlayDead(180)) would also cause a delay in the CutSceneID's actions. To solve this, multiple blocks, and hence multiple CutSceneIDs are possible. All blocks will be executed simultaneously, but the problem with actions delaying one another is removed.

Another action commonly used in cutscenes is MultiplayerSync(). This will wait for all participants in a game to reach the same point before the script continues.

There is an additional action, SetCutSceneLite(TRUE), which functions similarly to StartCutSceneMode(). However, crucially, it allows other scripts besides the cutscene script to remain running. This opens up a number of possibilities, allowing for conditions to be checked during cutscenes. SetCutSceneLite(FALSE) functions for this as EndCutSceneMode() would.

1) Using Custom Spells in Scripts

Method 1
This method should apply to all IE games.
To allow you to use spells with this method, they must be in the standard naming convention:
SPPR### for priest spells
SPWI### for wizard spells
SPIN### for innate spells
SPCL### for class spells
The first number should be the level of the spell. The other two can be anything, but be sure not to overwrite an existing spell.

Having ensured that your spells are in this format, you then need to determine the number of the spell. This is a four digit number.
The number is dependant on the filename of the spell.
- The first number denotes the type of spell: 1 for priest, 2 for wizard, 3 for innate, 4 for class
- The last 3 numbers correspond to the numeric suffix of the SPL file.

You can then use this number in the scripting action (or trigger) for your spell.

For example, if we have a spell called SPWI999.SPL, and we want to use it with ApplySpell() on whoever is running the script, in a script, we could write:
ApplySpell(Myself,2999)

Since 2999 in the number that would be associated with SPWI999.SPL.

Method 2
This method should also apply to all IE games. It works the same as the above method, but can be easier to use, as it allows you to assign a name to your spell which can be referred to in scripts.

Using the standard spell scripting actions, such as ApplySpell(), you can add your spell to SPELL.IDS. To be able to add the spell to SPELL.IDS, it must be in the standard naming convention, as explained above.

If you look at SPELL.IDS, you will notice that the spells are listed with first a number, then a name. When you add your own spell, you can choose any name you like; this name will be what you use to refer to the spell in your scripts if you choose to use this method. The number, however, does matter, and cannot be chosen. It must be the number of your spell, according to the filename, as explained above.

For example, using the example of SPWI999.SPL, first we would add the following line to SPELL.IDS:
2999 Example_Custom_Spell

Then, in a script, we could write:
ApplySpell(Myself,Example_Custom_Spell)

This performs exactly the same function as the action in Method 1, but can make spells easier to remember, since they are assigned a name of your choice, rather than a fixed number.

Method 3
The method definitely applies to BG2: SoA and ToB; it may work with other IE games, but has not been tested. It has, however, been confirmed that does not work with BG1.
In BG2:ToB, there are a number of RES actions that can be used in scripts:

31 SpellRES(S:RES*,O:Target*) 
95 SpellPointRES(S:RES*,P:Target*)
113 ForceSpellRES(S:RES*,O:Target) 
114 ForceSpellPointRES(S:RES*,P:Target) 
160 ApplySpellRES(S:RES*,O:Target) 
181 ReallyForceSpellRES(S:RES*,O:Target) 
191 SpellNoDecRES(S:RES*,O:Target*) 
192 SpellPointNoDecRES(S:RES*,P:Target*) 
240 ReallyForceSpellDeadRES(S:RES*,O:Target) 
318 ForceSpellRangeRES(S:RES*,O:Target) 
319 ForceSpellPointRangeRES(S:RES*,P:Target)
337 ReallyForceSpellPointRES(S:RES*,P:Target*)

To be usable in scripts, these must be present in ACTION.IDS. They will only be present if you have ToB installed. However, they also work with just SoA; simply copy and paste the above list into ACTION.IDS, and save it.

In addition to these actions, HaveSpellRES(S:Spell*) is also a valid trigger which can be used in the same way.

With the RES actions, the spell does not have to be added to SPELL.IDS; the filename of the spell can be used instead. Note, however, that with these actions, the order of spell and target is reversed from what it is normally in the spell actions.

Based on this, with the now infamous example spell, SPWI999, we would simply use the following action to do the same as the example in the method above:
ApplySpellRES("SPWI999",Myself)

The RES actions are a far more efficient way of using spells in scripts than to add each one to SPELL.IDS.

It is up to you which method you use, but I would strongly recommend the RES actions if you have BG2.

---

BG2 has, in addition to those mentionned above, several other spell prefixes:

SPWM### - Wild Mage
SPDR### - Druid
SPRA### - Ranger

The last two are used by non-mage kits which are able to cast mage spells.

Spells named in this way cannot be added to SPELL.IDS, and hence cannot be used without the RES actions. There is no number for use in either the IDS of actions/triggers associated with either SPWM, SPDR or SPRA.
The RES actions and triggers, however, can be used with these spells.

It is also worth noting that the RES actions are not case sensitive, so either SPDR### or spdr### is fine.

2) Detectable Spells

In the STATS.IDS, there are a number of SCRIPTINGSTATES. The value of these can be read, like anything else in STATS.IDS, with the CheckStat trigger. Detectable Spells work by assigning each spell a scripting state, and modifying the scripting state for the duration of the spell.

To begin making a spell detectable, it is necessary to add an extra effect to the spell. You need to use the 'Scripting State Modify' effect. The parameters of this effect are listed as unknown. The first unknown is the value to set the specified scripting state to. The second is the scripting state to modify; this starts (confusingly) with 0 corresponding to SCRIPTINGSTATE1, 1 to SCRIPTINGSTATE2, and so on.
The duration of the effect should be the same as that of the spell.

Having done this, you can then use CheckStat(O:Object*,I:Value*,SCRIPTINGSTATE) to determine the value of a scripting state, and hence the spell that is in effect.

STATS.IDS can be extended, adding further scripting states, up to a limit of 31. This limit makes it necessary, if many spells need to be detectable, to assign multiple spells to one scripting state (hence each spell setting the scripting state to a different value). In choosing which spells go together, it is best to choose spells that will not be cast at the same time.

Based on this, you can make enemies react more effectively to any spells in effect on the party in your mod or TC.

3) Priority Targetting

Method 1: A Large OR() Block
The first stage in any priority targetting system is to set the target as LastSeenBy() in one or more blocks.
As the name suggests, in this first method, the target is set in a single large OR() block. Something like:

IF
    OR(4)
      See(NearestEnemyOfType([GOODCUTOFF])) // Lowest priority (any enemy)
      See(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
      See(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
      See(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER])) // Highest priority (sorcerer)
    False()
THEN
    RESPONSE #100
END

While this block looks unusual, after it has been assessed, LastSeenBy() will be left as the highest priority target found, since the block is assessed line by line, and LastSeenBy() will be changed every time a valid target is encountered. The False() trigger ensures that the block is never actually executed, so that the script can continue to the attacking blocks when LastSeenBy() has been set appropriately.

A basic attacking block might look something like:

IF
    Range(LastSeenBy(Myself),10)
THEN
    RESPONSE #100
        EquipMostDamagingMelee()
        Attack(LastSeenBy(Myself))
END

However, spellcasting can also be done using LastSeenBy(). Spellcasting blocks are always best placed above basic attacking blocks, simply because they are usually preferable to attacking. It is also often good to use a RandomNum trigger with spellcasting blocks to randomise the use of spells somewhat (although this can also apply to other attacks).

The main disadvantage of this method is that extra conditions for each target are not possible. In this method, extra checks on LastSeenBy() should not be added to the targetting block, as LastSeenBy() will be set regardless of whether they are true or not.

Method 2: Multiple Blocks
This second method, as above, relies on setting LastSeenBy(). However, it is done in multiple blocks, rather than a single OR block. This addresses the main shortcoming of this first block, as better control is available over the conditions for targetting.
The initial blocks, for setting LastSeenBy(), with this method, would appear similar to:

IF
    !StateCheck(ThirdNearestEnemyOf(Myself),STATE_STUNNED)
    See(ThirdNearestEnemyOf(Myself))
    False()
THEN
    RESPONSE #100
END

IF
    !StateCheck(FourthNearestEnemyOf(Myself),STATE_STUNNED)
    See(SecondNearestEnemyOf(Myself))
    False()
THEN
    RESPONSE #100
END

IF
    !StateCheck(NearestEnemyOf(Myself),STATE_STUNNED)
    See(NearestEnemyOf(Myself))
    False()
THEN
    RESPONSE #100
END

IF
    !StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_STUNNED)
    See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
    False()
THEN
    RESPONSE #100
END

IF
    !StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_STUNNED)
    See(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
    False()
THEN
    RESPONSE #100
END

IF
    See(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
    False()
THEN
    RESPONSE #100
END

IF
    See(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]))
    False()
THEN
    RESPONSE #100
END

Again, the lowest priority target is at the top, while the highest is at the bottom. False() plays the same role as previously.
However, conditions (which in this case vary for different target types) are present for targetting. So, for example, in:

IF
    !StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_STUNNED)
    See(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
    False()
THEN
    RESPONSE #100
END

LastSeenBy() will only be assigned to the target if it is not STATE_STUNNED.
In all blocks, the extra conditions should always be above the See() trigger. If they are not, LastSeenBy() will be set regardless, since the See() trigger has already returned true.

Attacking blocks can then be used in the same way as the previous method.

Method 3: 'False Conditions'
While the name I have invented for it gives away little about this targetting method, it is superior in terms of efficiency to the previous two mentionned. This method uses a single targetting block, and cuts off the remaining targets once a valid one has been found, hence the improved efficiency.
A basic block using this method might appear as follows:

IF
    !See([GOODCUTOFF.0.0.SORCERER]) // Highest priority
    !See([GOODCUTOFF.0.0.MAGE_ALL])
    !See([GOODCUTOFF.0.0.CLERIC_ALL])
    !See([GOODCUTOFF.0.0.DRUID_ALL])
    !See([GOODCUTOFF.0.0.BARD_ALL]) // Default target
    !See([GOODCUTOFF])
THEN
    RESPONSE #100
END

This time, the highest priority target is at the top. The logic of this block can be quite hard to follow at first, but basically, the block first checks for a sorceror. If one is seen, LastSeenBy is set due to the See() trigger (in spite of the !), and the block returns false, so it moves on to the next one. If no sorceror is seen, the trigger returns true, so the second one is evaluated, looking for a mage. In the same way, all of the triggers are evaluated until one is found false, indicating a valid target.
In this particular case, the block is also acting as a cutoff; the final condition evaluated is !See([GOODCUTOFF]). If this returns true (meaning no GOODCUTOFFs are in sight), the entire block returns true, and the lack of actions causes the script to restart. However, if this is not wanted, a False() condition can also be added at the bottom.

This can be extended slightly to allow OR blocks to be used to perform other checks on the validity of the target. An OR() block with all the possible triggers to make a target invalid in can be used, as follows:

IF
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]))
      RandomNumGT(20,5)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]))
      RandomNumGT(20,7)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
      RandomNumGT(20,9)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
      RandomNumGT(20,11)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
      RandomNumGT(20,13)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
      RandomNumGT(20,14)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.DRUID_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.DRUID_ALL]))
      RandomNumGT(20,15)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.BARD_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.BARD_ALL]))
      RandomNumGT(20,16)
    !See(NearestEnemyOf(Myself))
THEN
    RESPONSE #100
END

This block is rather more complex. However, the basic principle is the same. When the block is parsed, the first OR block is assessed. If any of the conditions are true, making the target invalid, then this OR block returns true, and the next one is assessed. If none of the triggers in the OR block are true, then the target is valid, LastSeenBy() is set, and the next script block will be evaluated.

When using this method of targetting, it is important to consider not only the use of NearestEnemyOfType() targets, but also NearestEnemy() objects too. These must be treated slightly differently, since placing !See(NearestEnemyOf(Myself)) at the top of a block will cause it to be assessed only if no enemies are present (therefore, no other targets will be considered).
To avoid this problem, See() checks can be performed outside OR blocks. For example:

IF
    See(NearestEnemyOf(Myself))
    OR(2)
      StateCheck(NearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(SecondNearestEnemyOf(Myself))
    OR(2)
      StateCheck(SecondNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,4)
    See(ThirdNearestEnemyOf(Myself))
    OR(2)
      StateCheck(ThirdNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,5)
    See(FourthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(FourthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(FifthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(FifthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(SixthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(SixthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(TenthNearestEnemyOf(Myself))
THEN
    RESPONSE #100
END

When this block is evaluated, it will return false immediately unless an enemy is seen (possibly meaning another cutoff is required). If an enemy is seen, however, LastSeenBy() is set, and unless one of the conditions in the first OR block is true (invalidating the target), the block returns false. All other conditions are assessed in the same way.
This type of block cannot be used with NearestEnemyOfType type objects, as See(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER])) will return true only if a sorcerer is seen, meaning that a sorcerer must be seen for the other targets to be evaluated at all.

This means that there are two basic logics here for NearestEnemyOf and NearestEnemyOfType. These can of course be combined into a single block. For example:

IF
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]))
      RandomNumGT(20,5)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.SORCERER]))
      RandomNumGT(20,7)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
      RandomNumGT(20,9)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.MAGE_ALL]))
      RandomNumGT(20,11)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
      RandomNumGT(20,13)
    OR(3)
      StateCheck(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]),STATE_HELPLESS)
      !See(SecondNearestEnemyOfType([GOODCUTOFF.0.0.CLERIC_ALL]))
      RandomNumGT(20,14)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.DRUID_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.DRUID_ALL]))
      RandomNumGT(20,15)
    OR(3)
      StateCheck(NearestEnemyOfType([GOODCUTOFF.0.0.BARD_ALL]),STATE_HELPLESS)
      !See(NearestEnemyOfType([GOODCUTOFF.0.0.BARD_ALL]))
      RandomNumGT(20,16)
    See(NearestEnemyOf(Myself))
    OR(2)
      StateCheck(NearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(SecondNearestEnemyOf(Myself))
    OR(2)
      StateCheck(SecondNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,4)
    See(ThirdNearestEnemyOf(Myself))
    OR(2)
      StateCheck(ThirdNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,5)
    See(FourthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(FourthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(FifthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(FifthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(SixthNearestEnemyOf(Myself))
    OR(2)
      StateCheck(SixthNearestEnemyOf(Myself),STATE_HELPLESS)
      RandomNumGT(10,3)
    See(TenthNearestEnemyOf(Myself))
THEN
    RESPONSE #100
END

4) Randomwalking

So, you might have:

IF
	!Range(LastSeenBy(Myself),10)
	Global("d0hasranged","LOCALS",1)
THEN
	RESPONSE #100
		EquipRanged()
		Attack(LastSeenBy(Myself))
	RESPONSE #10
		Continue()
END

You would then have a block:

IF
	True()
THEN
	RESPONSE #100
		RandomWalkContinuous()
END

In this case, the RESPONSE #10 leads on to the randomwalking block occasionally, so the creature randomwalks instead of attacking.
It is worth bearing in mind that randomwalking can be dangerous, as creatures can potentially become 'stuck' on such actions, preventing it running any scripts at all.

5) Cast 'n' Attack

So, you might have the following block:

IF
    !GlobalTimerNotExpired("castnattack","LOCALS")
    HaveSpellRES("spwi999",Myself)
THEN
    RESPONSE #100
        SetGlobalTimer("castnattack","LOCALS",6) // Timer always set to 6, as that is the duration of the pause
        SpellRES("spwi999",LastSeenBy(Myself))
END

If similar lines are added to each spellcasting block to check for expiration of the timer, and set it when the spell is cast, then no spellcasting will be attempted when it is not possible, and this will allow other attacking blocks to be executed, such as:

IF
    True() // Note that this requires this block to be placed below all others
THEN
    RESPONSE #100
        AttackOneRound(LastSeenBy(Myself))
END

In addition to this, you can also account for aura cleansing (alacrity) in cast 'n' attack routines. This is done simply with an OR block, in which the timer and another condition is used. You can either CheckStat(Myself,1,AURACLEANSING), or implement aura cleansing as a detectable spell and check for it.
So your triggers would be:

OR(2)
  CheckStat(Myself,1,AURACLEANSING)
  !GlobalTimerNotExpired("castnattack","LOCALS")

6) Item usage and handling

IF
    !GlobalTimerNotExpired("castnattack","LOCALS")
    HPPercentLT(Myself,75)
    HasItem("potn08",Myself) // Minor healing potion
THEN
    RESPONSE #100
        SetGlobalTimer("castnattack","LOCALS",6)
        UseItem("potn08",Myself)
END

This block will use a minor healing potion when hit points have dropped below 75%.
Remember at this point that higher priority actions should come earlier in the script. Therefore, shouting for a cleric to cast a healing spell might be preferable to using a potion, in which case the block would appear earlier on.

IF
    !GlobalTimerNotExpired("castnattack","LOCALS")
    HasItem("potn10",Myself) // Potion of invisibility
    See([GOODCUTOFF])
    !StateCheck(Myself,STATE_INVISIBLE)
    !StateCheck(Myself,STATE_IMPROVEDINVISIBILITY)
THEN
    RESPONSE #100
        SetGlobalTimer("castnattack","LOCALS",6)
        UseItem("potn10",Myself)
END

This block will use a potion of invisibility when the party is in sight and the creature is not invisible. Notice the two statechecks, which account for both forms of invisibility.

Passing items between creatures is also possible.
Shouts are useful to achieve a realistic result here; however, specifics (or internals in IWD) can also be used if this is not wanted.

IF
    !HasItem("potn08",Myself)
    HPPercentLT(Myself,50)
    !GlobalTimerNotExpired("shouted","LOCALS") // Only shout so often
THEN
    RESPONSE #100
        SetGlobalTimer("shouted","LOCALS",10)
        Shout(NEED_POTION) // Shout for help
END

IF
    Heard([EVILCUTOFF],NEED_POTION) // If someone shouted for help
    !HasItem("potn08",LastHeardBy(Myself)) // Ensures they have not already been given an item
    HasItem("potn08",Myself)
    HPPercentGT(Myself,50)
THEN
    RESPONSE #100
        GiveItem("potn08",LastHeardBy(Myself)) // Pass them the item
END

7) The Invisible Creature Trick

IF
	LevelGT(LastSummonerOf(Myself),10)
THEN
	RESPONSE #100
		ApplySpellRES("spell",LastSummonnerOf(Myself))
		DestroySelf()
END

1) How can I have an item level up with the wielder?
Firstly, you would need to create several items, one for each evolutionary stage.
Next, several blocks need to be added to DPLAYER2.BCS and DPLAYER3.BCS, one for each level-up of the weapon.
For example:

IF
	HasItem("weapon1",Myself)
	CheckStatGT(Myself,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Myself)
END

This will swap the item for the newer one when the specified level is reached.
Note that TakeItemReplace does not exist in earlier games; therefore, two actions are needed: one to remove the old item, and one to create the new one.

The problem with this is that the DPLAYER scripts are deactivated with the party AI. Therefore, it is usually better to use BALDUR.BCS.
Since this is a global script, each player must be accounted for individually in a separate block.
For example:

IF
	HasItem("weapon1",Player1)
	CheckStatGT(Player1,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player1)
END

IF
	HasItem("weapon1",Player2)
	CheckStatGT(Player2,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player2)
END

IF
	HasItem("weapon1",Player3)
	CheckStatGT(Player3,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player3)
END

IF
	HasItem("weapon1",Player4)
	CheckStatGT(Player4,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player4)
END

IF
	HasItem("weapon1",Player5)
	CheckStatGT(Player5,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player5)
END

IF
	HasItem("weapon1",Player6)
	CheckStatGT(Player6,3,LEVEL)
THEN
	RESPONSE #100
		TakeItemReplace("weapon2","weapon1",Player6)
END

2) How can I use strings in scripts?
Strings are not actually stored in the BS or BCS files, but are instead found in the DIALOG.TLK file. Therefore, you will need to use a TLK editor to add or find the desired string, and note its 'strref' number, which is what you will refer to in scripts.

3) How can I cause random item placement via scripts?
For placement in areas, you would need to modify the area scripts, and add a block to randomly spawn the items.
For example:

IF
    Global("addtreasure","AR9999",0)
THEN
    RESPONSE #100
        SetGlobal("addtreasure","AR9999",1)
        ActionOverride("container",CreateItem("item1",1,0,0))
    RESPONSE #100
        SetGlobal("addtreasure","AR9999",1)
        ActionOverride("container",CreateItem("item2",1,0,0))
    RESPONSE #100
        SetGlobal("addtreasure","AR9999",1)
        ActionOverride("container",CreateItem("item3",1,0,0))
END

Alternatively, to randomly spawn items on creatures, you could add something similar to a creature script, using a local variable.

4) Can a STATE be changed in a script?
No, you cannot change a state directly from a script. You must deal with the effect that is causing that state.

5) Can I create a random maze or randomly link areas? Yes. Firstly, you would use an initial script, which would run when the game was started.

IF
	Global("link1","GLOBAL",0)
THEN
	RESPONSE #100
		SetGlobal("link1","GLOBAL",1)
	RESPONSE #100
		SetGlobal("link1","GLOBAL",2)
	RESPONSE #100
		SetGlobal("link1","GLOBAL",3)
END

You would then have a trigger region in an area, which would run a script similar to the following:

IF
	Global("link1","GLOBAL",1)
THEN
	RESPONSE #100
		ActionOverride(Player1,LeaveAreaLUA("area1","",[100.100],1))
		ActionOverride(Player2,LeaveAreaLUA("area1","",[100.100],1))
		ActionOverride(Player3,LeaveAreaLUA("area1","",[100.100],1))
		ActionOverride(Player4,LeaveAreaLUA("area1","",[100.100],1))
		ActionOverride(Player5,LeaveAreaLUA("area1","",[100.100],1))
		ActionOverride(Player6,LeaveAreaLUA("area1","",[100.100],1))
END

IF
	Global("link1","GLOBAL",2)
THEN
	RESPONSE #100
		ActionOverride(Player1,LeaveAreaLUA("area2","",[100.100],1))
		ActionOverride(Player2,LeaveAreaLUA("area2","",[100.100],1))
		ActionOverride(Player3,LeaveAreaLUA("area2","",[100.100],1))
		ActionOverride(Player4,LeaveAreaLUA("area2","",[100.100],1))
		ActionOverride(Player5,LeaveAreaLUA("area2","",[100.100],1))
		ActionOverride(Player6,LeaveAreaLUA("area2","",[100.100],1))
END

IF
	Global("link1","GLOBAL",3)
THEN
	RESPONSE #100
		ActionOverride(Player1,LeaveAreaLUA("area3","",[100.100],1))
		ActionOverride(Player2,LeaveAreaLUA("area3","",[100.100],1))
		ActionOverride(Player3,LeaveAreaLUA("area3","",[100.100],1))
		ActionOverride(Player4,LeaveAreaLUA("area3","",[100.100],1))
		ActionOverride(Player5,LeaveAreaLUA("area3","",[100.100],1))
		ActionOverride(Player6,LeaveAreaLUA("area3","",[100.100],1))
END

6) What are some common scripting pitfalls?
As suggested by a number of people in chat, here are some of the most common:

• Using RESPONCE #100 instead of RESPONSE #100, or not using it at all
• Forgetting to use a creature's death variable when it is needed
• Placing the terms in the wrong order
• Forgetting to use quotes when required, or using them incorrectly
• Using the wrong number of brackets (particularly closing brackets)
• Using "LOCAL" instead of "LOCALS"

7) How can I link a script with an item?
There are several ways you can run a script from an item or spell, and the most appropriate one will depend on what you want to do.

The first method it to use the 'change AI script' effect on the user to have them run an appropriate script on themselves. You can then change the script back when required via the script itself. The problems with this are that having a character run the script on himself can potentially cause stuttering, and also that it can interfere with other modifications which assign scripts to characters.

The second way is to summon an invisible creature. For more information on this, see the Invisible Creature section. The only disadvantage of this is that creating large numbers of creatures can be problematic, so it may be inappropriate in some situations.

The final way is to use either DPLAYER2/3.BCS or BALDUR.BCS. The latter is usually preferable, since the DPLAYERs are deactivated with party AI; however, in some circumstances, it cannot be used. The appropriate blocks in the script can be activated from the item by setting a variable.

8) Why does the game crash when I cast some of the class spells like SET_SNARE_TRAP through scripting?
Class spells (SPCL###) should have their level set to 1. If it isn't and you check to see if you have the spell via the trigger HaveSpell() before casting it, the game will crash. There are ways to script around this problem, but the most effective solution is to edit the spell using Spell Maker in IEEP or Near Infinity to set the spell level to one and then place the fixed spell file in your override directory. Fixed SPL files can also be found at Cirerrek's page.

More will be added as they become apparant or are asked.

• Me, for writing this rubbish :)
• Max and Kensai Ryu, for pointing out mistakes and providing helpful input
• Cirerrek, for additional information in several areas
• Xyx, for general suggestions, and an additional targetting method
• Dyara, for the debugging application of tokens
• Avenger, for much input on the structure of IDS files
• Japheth, for feedback, I think
• Gimble, for his helpful and interesting posts on the Interplay boards
• Daxziz, Goran and Max, for their tutorials
• Deano, for webpage-related advice