Table Of Contents

Table Of Contents *

Disclaimer: *

Using the Script Compiler: *

Creating Scripts: *

Definitions: *

Creature and Object Identification *

Trigger Descriptions *

Action Descriptions *

Sample Script File *

The "Baldur’s Gate Script Compiler," this document, and any information contained herein, are provided in an "as is" state. No support will be provided for either the use of the compiler or for any script files generated by the compiler. Neither BioWare Corp. or Interplay Productions are responsible for any problems encountered in running the compiler or in creating scripts.

BALDUR'S GATE: Developed and (c)1998 BioWare Corp. All Rights Reserved. Baldur's Gate, Forgotten Realms, the Forgotten Realms logo, Advanced Dungeons & Dragons, the AD&D logo, and the TSR logo are trademarks of TSR, Inc., a subsidiary of Wizards of the Coast, Inc., and are used by Interplay under license. All Rights Reserved. BioWare, the BioWare logo and The BioWare Infinity Engine are the trademarks of Bioware Corp. All Rights Reserved. Interplay, the Interplay logo, Black Isle Studios, the Black Isle Studios logo, and "By Gamers. For Gamers." are trademarks of Interplay Productions. All Rights Reserved. Exclusively licensed and distributed by Interplay Productions. LUA copyright 1994-1998 TeCGraf, PUC-Rio. LUA written by Waldermar Celes, Robert Ierusalimschy and Luiz Henrique de Figueirido. All other trademarks and copyrights are property of their respective owners. All rights reserved.

Before using the script compiler, you must copy the entire ScriptCompiler directory from Baldur’s Gate CD1 to your hard drive. You will be unable to run the script compiler directly from the CD. Once the ScriptCompiler directory has been copied, follow the instructions in the following sections.

Decide what you want the script to do before actually starting one. For example, "When attacked by an XX I want my character to react according to the range of my attacker. If I am within a range of 4 search squares I will run to get some distance between us. If I am further than 4 search squares I will attack with a ranged weapon."

After you have decided what you want the script to do open notepad or whatever else you would like to use and begin entering in the commands you will need. For mine I will need to use the commands, AttackedBy, Range, RunAwayFrom, EquipRanged and Attack.

This is how my script would look:

IF

AttackedBy([ANYONE],DEFAULT)

Range(LastAttackerOf(Myself),4)

THEN

RESPONSE #100

RunAwayFrom(LastAttackerOf(Myself),45)

END

IF

!Range(LastAttackerOf(Myself),4)

THEN

RESPONSE #100

EquipRanged()

Attack(LastAttackerOf(Myself))

END

In the first part of the script I check to see if I was attacked by [ANYONE]. The object type parameter uses any function that returns an object type or objects referenced by ENEMYALLY, RACE, CLASS, etc. Examples of these are: [ANYONE], [ENEMY], [PC], etc. The object type can also be Myself. But in this case it would be useless since you would not attack yourself.

Once I have determined if someone attacked me I check to see if the Range was within 4 search squares. (The screen is about 30 search squares). If the last attack of myself is within range I run away from the target for about 3 seconds. The time is given in 15ths of a second.

If the range of the target is not within 4 search squares the script falls through to the next set of checks. In this next set I just check to see if the target’s range is not (using the ! to reference not) within 4 search squares. If so then I equip my ranged weapon and attack the last attacker of myself.

If I do not have a ranged weapon or ammo the function will equip a melee weapon and then approach the target to get within weapons range.

Once the script is done I save it to the Source directory of the script compiler. The filename must be 1 – 8 characters with the extension .BAF. I then run the compiler by typing COMPILE <FILENAME>. The compiler will notify you of any errors in the script by placing a error file in the ERRORS directory with the script’s filename and extension .ERR. If the file size is 0 then the script compiled successfully. And the final script will be placed in the COMPILED directory with the filename and extension .BS. This will then have to be copied into your SCRIPTS directory of Baldur’s Gate.

Creatures include all objects capable of action. This includes player characters.

A trigger is sent to a creature when a certain event occurs. A trigger includes the knowledge of the cause of the trigger

A combination of triggers joined with ands.

A specified response to a condition. An action requires the knowledge of who (or what) to perform the action upon.

A combination of actions which will be performed sequentially. It is possible for a response to be interrupted.

A combination of Responses, each with a weighting from 1 to 100. This weighting is used to randomly determine which response is actually executed.

Creature and Object Identification is done through the ObjectType Class.

ObjectType is arranged as follows

BYTE EnemyAlly General

BYTE General |

BYTE Race |

BYTE Class |

BYTE specifics V

LONG Instance Specific

BYTE SpecialCase

EnemyAlly is a range between the PC and the evil NPC’s Creatures can fall anywhere along this range.

General specifies the generic characteristics of the creature (Humanoid, animal, object etc.…)

Race is the race of the creature (Elf, Dwarf …)

Class is the class information (Mage, fighter …) Alternatively it can be used for more detailed information (e.g. Drow is more specific then elf)

Specifics holds the identification for special NPC’s

Instance is unique for each creature within the game. It should not generally be specifies in the AI scripting but will be set by the AI code once a target is selected

SpecialCase is used to specify whether or not to use any special case information. Currently this will only be used for LAttacked and LTargetted. Protecting, Protector and Myself must be stored in a different way so that you can do things like Protecting.Lattacked.

To specify all of a subtype, set the more specific variables to 0.

e.g. To specify all Enemy Dwarfs, set Class, specifics and instance to 0.

The following functions return ObjectType variables corresponding to some special cases. They are called using the following syntax:

Function(Source)

For Example: LAttacked(Spud) will return the ObjectType of the last thing to attack Spud.

If One of Leader, Weakest, Strongest, MDamaged, LDamaged is called, the Source will be used ONLY to determine which group to use.

For Example: Leader(Spud) will return the leader of Spud’s Group

These functions can be used as the Source for any other of these functions. HOWEVER, this nesting can only go 5 deep.

For Example: Protector(LAttacked(LTargeted(Protecting(Myself)))) is valid and will return the protector of the person last attacked by the person last targeted by the person protecting myself. Any more then this depth of nesting is NOT allowed, however.

Note: If you ever use this level of nesting, please seek professional help.

-Returns ObjectType with the instance field filled out if the object currently exists.

-Returns ObjectType

- The Creature that last did Caller damage

-Returns ObjectType

-Returns the last person who issued Caller an order

-Returns ObjectType

-last heard by type

-Returns ObjectType

-Last person type heard call for help

-Returns ObjectType

-Last person who hit type

-Returns ObjectType

-Last seen by type

-Returns ObjectType

-Last talked to by type

-Returns ObjectType

- The Creature that Caller last targeted for attack

-Returns ObjectType

-Last triggerer of type

-Returns ObjectType

-Current leader of Player group

-Returns ObjectType

- Group member with highest percentage of remaining hit points

-Returns ObjectType

- Use Source to specify Enemy / Ally status of group

- Group member with the lowest percentage of remaining hit points

-Returns ObjectType

-Yourself

-Returns ObjectType

-Returns the instance of the nearest ObjectType of the given Type.

-Returns ObjectType

-Returns the nearest creature with Enemy / Ally flag opposite to the Caller.

-Returns ObjectType

-Character in portrait slot 1

-Returns ObjectType

-Character in portrait slot 2

-Returns ObjectType

-Character in portrait slot 3

-Returns ObjectType

-Character in portrait slot 4

-Returns ObjectType

-Character in portrait slot 5

-Returns ObjectType

-Character in portrait slot 6

- The Protagonist

- Returns ObjectType

- The Creature currently protected by Caller

- Returns ObjectType

- The Creature Caller is currently being protected by

-Returns ObjectType

- Group member with the highest threat rating

- Returns ObjectType

- Male group member with the highest threat rating

-Returns ObjectType

- Group member with lowest threat rating

Event Triggers only last until the next AI cycle. At that point they are examined and processed. At the end of the AI cycle all of the triggers are removed from the pending list.

Returns: Boolean (True or False)

Description: I was just attacked by creature X using style Y.

Information required:

Attack type: DEFAULT

X is an ObjectType variable.

Returns: Boolean (True of False)

Returns: Boolean (True or False)

Description: X just died in my hearing range.

Returns: Boolean (True or False)

Description: I heard X shout Y

Returns: Boolean (True or False)

Description: a call for help is heard from X

Information required: X is an ObjectType

Returns: Boolean (True or False)

Description: I have just been hit by X the style is Y

Returns: Boolean(True or False)

Description: key X has just been pressed when I was the selected creature

Currently hotkeys are restricted to letters A through Z.

Returns: Boolean (True or False)

Description: Just received order Y from X

Information Required: X specifies the creature that sent the order. OrderID specifies type of the order.

Returns: Boolean (True or False)

Description: X said something to me

Returns: Boolean (True or False)

Description: I have just been sent the trigger TriggerId

Status triggers are checked every time through the AI cycle. As a result they always apply if they are true.

Returns: Boolean (True or False)

Description: I have no actions on my queue

Returns: Boolean (True or False)

Description: Is the Class of X equal to CLASS?

Information Needed: X is an ObjectType CLASS is the class

ANKHEG

BARD

BASILISK

BASILISK_GREATER

BEAR_BLACK

BEAR_BROWN

BEAR_CAVE

BEAR_POLAR

CARRIONCRAWLER

CLERIC

CLERIC_MAGE

CLERIC_RANGER

CLERIC_THIEF

DOG_WAR

DOG_WILD

DOPPLEGANGER

DOPPLEGANGER_GREATER

DRIZZT

DRUID

ELMINSTER

ETTERCAP

FAIRY_DRYAD

FAIRY_NEREID

FAIRY_NYMPH

FAIRY_SIRINE

FIGHTER

FIGHTER_CLERIC

FIGHTER_DRUID

FIGHTER_MAGE

FIGHTER_MAGE_CLERIC

FIGHTER_MAGE_THIEF

FIGHTER_THIEF

GHOUL

GHOUL_GHAST

GHOUL_REVEANT

GIBBERLING

GNOLL

GREEN_SLIME

GREY_OOZE

HOBGOBLIN

KOBOLD

KOBOLD_TASLOI

KOBOLD_XVART

MAGE

MAGE_THIEF

MUSTARD_JELLY

NO_CLASS

OCRE_JELLY

OGRE

OGRE_HALFOGRE

OGRE_MAGE

OGRE_OGRILLON

OLIVE_SLIME

PALADIN

RANGER

SAREVOK

SKELETON

SKELETON_BANEGUARD

SKELETON_WARRIOR

SPIDER_GIANT

SPIDER_HUGE

SPIDER_PHASE

SPIDER_SWORD

SPIDER_WRAITH

THIEF

VOLO

WOLF

WOLF_DIRE

WOLF_DREAD

WOLF_VAMPIRIC

WOLF_WINTER

WOLF_WORG

WYVERN

Returns: Boolean (True or False)

Description: returns False except every X seconds

Use: Use to avoid excessive calling of slow triggers

Returns: Boolean (True or False)

Description: Is X a valid ObjectType?

Information Needed: X is an ObjectType variable.

Description: Always return FALSE

Returns: Boolean (True or False)

Description: Is the X’s gender equal to GENDER?

Returns: Boolean (True or False)

Description: Is the General type of X equal to GENERAL?

Information Needed: X is an ObjectType GENERAL is the general type.

HUMANOID

ANIMAL

DEAD

UNDEAD

GIANTHUMANOID

FROZEN

MONSTER

Description: Does the Object have a weapon equiped?

Returns: Boolean (True or False)

Description: Do I have any Spells?

Returns: Boolean (True or False)

Description: Do I have spell X

Returns: Boolean (True or False)

Description: X’s current hit points are EXACTLY Y

Information needed: the value of Y (as a percentage). X is an ObjectType.

Development Notes: the specificID flag can be used to store the percentage

Returns: Boolean (True or False)

Description: X’s current hit points are GREATER THEN Y

Information needed: the value of Y (as a percentage) . X is an ObjectType.

Development Notes: the specificID flag can be used to store the percentage

Returns: Boolean (True or False)

Description: X’s current hit points are LESS THEN Y

Information needed: the value of Y (as a percentage) . X is an ObjectType.

Development Notes: the specificID flag can be used to store the percentage

Returns: Boolean (True or False)

Description: Is the HP percent of X equal to Y?

Returns: Boolean (True or False)

Description: Is X in the Party

Description: Is object in Weapon range?

Returns: Boolean (True or False)

Description: Is Object X within RANGE search map blocks? Also, is there a clear line of sight to X?

Information Needed: X is an ObjectType variable. RANGE is an integer count of intervening blocks.

Returns: Boolean (True or False)

Description: Is X in state Y

Returns: Boolean (True or False)

Description: Is the number of X’s visible Equal to Y

Returns: Boolean (True or False)

Description: Have I interacted with NPC num times?

Returns: Boolean (True or False)

Description: Is my current weapon out of ammo. Melee always returns false.

Returns: Boolean (True or False)

Description: Is the Race of X equal to RACE?

Information Needed: X is an ObjectType RACE is the race to be compared to.

Development Notes: Simply compare X.m_type.Race to RACE.

ANKHEG

BASILISK

BEAR

CARRIONCRAWLER

DOG

DOPPLEGANGER

DWARF

ELF

ETTERCAP

FAIRY

GHOUL

GIBBERLING

GNOLL

GNOME

HALF_ELF

HALFLING

HOBGOBLIN

HUMAN

KOBOLD

NO_RACE

OGRE

SKELETON

SLIME

SPIDER

WOLF

WYVERN

Returns: Boolean (True or False)

Description: Generate a number from 0 to Range and check against Value.

Returns: Boolean (True or False)

Description: Is Object X within RANGE search map blocks?

Information Needed: X is an ObjectType variable.

Development Notes: Pure distance, no line of sight. Use SpecificID for Range.

Returns: Boolean (True or False)

Description: Object X is in visual range

Information Needed: Several options for specifying X

1. The ObjectType class must be specified for X (this allows a general description)
2. Foe / friend

Returns: Boolean (True or False)

Description: Is the Specific information of X equal to SPECIFICS?

Information Needed: X is an ObjectType SPECIFICS is the specific information flag.

Description: Check if X is in State Y

Returns: Boolean (True or False)

Description: The game time is TIME. Game time is the time that has passed in the game world.

Information needed: TIME specifies the time (in seconds) since the beginning of the game

Returns: Boolean (True or False)

Description: Is the time of day TOD?

Information needed: Time of day (TOD) is a reference to the current world time in hours. Constants are:

MIDNIGHT

NOON

DAWN_START

DAWN_END

DUSK_START

DUSK_END

Description: Always returns True

Overall Development Note:

For any action that requires movement before the action, set the current action to move (with the correct target) and set the next action as the desired action. In general, when a movement is taking place, it will continue as long as the next action is No Action or the target of the next action is the same as the target of the movement and the next action is one that would require movement to the target.

Description: Attack creature X using Style Y. If no X then attack Z by default.

Information Required: Y specifies the style of attack desired

DEFAULT

RANGED

MELEE

X is used to specify the target. Unless X includes an Instance, then X will be used to indicate the preferred target. Once a target is selected, an Instance will be obtained so that target don’t constantly change. A second ObjectType Z is used to specify general targets.

Development Notes: To do this, place all of type X or Z on the search map. Add Threat radii. However, give the creatures of type X a much lower threat radius penalty.

Description: Use the actions currently selected, but continue looking for more.

Information Required: none

Description: Equip melee weapon which does the most damage

Description: Equip a ranged weapon.

Description: follow the leader with offset of Offset.

Description: Get Item X and add it to inventory. Walk to the item if necessary.

Information Required: X is a ResRef

Description: Give order Y to X. X must have a trigger to respond to the order or nothing will happen

Information Required: X specifies the creature(s) to send the order to. OrderID specifies type of the order.

Development Notes: Send a ReceivedOrder trigger to X. Limit range to hearing range of Targets

Description: Call for help

Information Required: None

Development Notes: Send a Call for help Heard trigger to ALL creatures in hearing range (regardless of which side they are on)

Description: Hide in shadows / Move silently

Information required: None

Development Notes: This action should continue until an action that would counter this occurs. That is you should be able to simultaneously move silently and move. Perhaps a flag in the thief character should indicate that the character is moving silently.

ClickLButtonPoint(Point X, SCROLLSPEED)

ClickRButtonPoint(Point X, SCROLLSPEED)

DoubleClickLButtonPoint(Point X, SCROLLSPEED)

DoubleClickRButtonPoint(Point X, SCROLLSPEED)

MoveCursorPoint(Point X, SCROLLSPEED)

ClickLButtonObject(ObjectType X, SCROLLSPEED)

ClickRButtonObject (ObjectType X, SCROLLSPEED)

DoubleClickLButtonObject (ObjectType X, SCROLLSPEED)

DoubleClickRButtonObject (ObjectType X, SCROLLSPEED)

Description: Click or move cursor to designated spot

Description: Plot a path to X and begin moving

Information requires: X is an ObjectType

Development Notes: Once a path is obtained, it should be followed as long as no other action is chosen. Further, if the Move To X action reoccurs then, if the two destinations are equal, the existing path should be used.

Description: Move to P offset from current location

Description: Protect Object X. Stay within a certain distance of X. Attack enemies in range.

Information required: X is an ObjectType.

Development Notes: Center the In Range check around X. If outside range, move back.

Description: Protect X. Stay within a certain distance of X. Attack enemies in range.

Information required: X is an ObjectType.

Development Notes: Center the In Range check around X. If outside range, move back.

Description: Wander around randomly

Description: Run away from X for Time seconds.

Information required: X is an ObjectType, Time is in seconds

Development Notes:

Description: Send trigger number ID to X.

Description: Turn interrupt on or off

Description: Send all in range Heard trigger

Description: Cast the spell Y on target X.

Information Required:

The desired spell can be specified as follows:

Target X is specified using an ObjectType variable.

Description: Cast the spell Y on target X.

Description: Enter ready state for X seconds

IF

Condition1

THEN

RESPONSE #weight

Response1

RESPONSE #weight

Response2

END

IF

Condition2

THEN

RESPONSE #weight

Response3

RESPONSE #weight

Response4

END

weight is a number between 1 and 100.

Trigger1

Trigger2

Action1

Action2

Action3

Trigger(Parameter1, Parameter2, …)

Action(Parameter1,Parameter2, …)

SpecialCase1( SpecialCase2( SpecialCase3( SpecialCase4(…)))))

"NAME"

[Allegiance . General . Race . Class . Specifics]

IF

Class(LastAttackerOf(Myself), MAGE)

HPGT(Myself,50)

THEN

RESPONSE #80

Attack(LastAttackerOf(Myself),MELEE)

RESPONSE #40

Help()

RunAway()

END

IF

Exists(LastAttackerOf(ProtectedBy(Myself))

THEN

RESPONSE #100

Attack(LastAttackerOf(ProtectedBy(Myself)), RANGED)

END

IF

HPLT(MostDamagedOf(GroupOf(Myself)),25)

THEN

RESPONSE #76

Spell(MostDamagedOf(GroupOf(Myself)),MOST_HEALING)

Protect(MostDamagedOf(GroupOf(Myself)))

RESPONSE #76

Attack(LastAttackerOf(MostDamagedOf(GroupOf(Myself))),RANGED)

END

IF

See(NearestEnemyOf(Myself))

THEN

RESPONSE #54

Attack(NerestEnemyOf(Myself), DEFAULT)

END

1. If I’m attacked by a mage and my hit points are more then 50%, either attack the mage using melee (66.7%) OR yell for help and run away (33.3%)
2. If the person I’m protecting is attacked, attack their attacker using a ranged attack (100%)
3. If the most damaged person in my group has less then 25% of his hit points, then either cast the most powerful healing spell on him and start protecting them (50%) OR attack the last person who attacked them (50%).
4. Attack the nearest enemy using my default attack. (100%)

Define ANYONE as the ObjectType with all 0’s. Define ENEMY as the ObjectType with all 0’s except EnemyAlly set to enemy.