The AI scripting system implemented here is very similar to the scripting system used by RTCW. Each map has a script file of the same name associated with it that contains scripting for the player, NPCs and special entities. This file, which has an .aiq extension and is placed in the baseq3/maps folder along with the map's bsp file, is a text file that can be created and edited using any text editor. An excellent editor for AI script files is the Crimson Editor, a full featured text editor that will highlight script commands and events when used with the AIQ syntax package avalible on the Downloads page.
If we are making the script for a map called hangars_1.bsp then it would be named hangars_1.aiq and be placed in the baseq3/maps folder. This script file is only loaded and used when we are running this particular map. If there is no script file associated with a map, then none is used. There is no default AI script file. A map does not need an AI script file in order to be run, as the NPCs will operate without any scripting.
Basic Script Block
Each entity with an ainame can have a script block associated with it. The player is given the ainame of player by the program so he also can have a script block associated with him. A script block is defined by :
<ainame>
{
... some scripting ...
}
where <ainame> matches the ainame of an entity. For example, the script block for an NPC with whose ainame key value is ogre1 would have a script block like :
ogre1
{
... some scripting ...
}
while the player's script block would be :
player
{
... some scripting ...
}
All scripting for the entity will reside between the curly brackets of the script block.
Script Events
An AI script is further broken down into blocks based on script events. These events are defined by the following :
<event>
{
... script commands ...
}
where <event> is the name of a predefined scripting event. A scripting event occurs when something happens to the entity (or player). This could be when they spawn into the level, when they die, when they see an enemy, etc. When one of these events happens then the script for that event is run. If no script event block is defined for that event then nothing happens. For example, when an entity or the player spawns into the level the following script event block is run :
spawn
{
... script commands ...
}
While some predefined scripting events can happen to all entities and the player, some are specific to either the player or the NPC entities. See AI Script Events for more details.
Script Commands
Once the script event occurs for the entity or player then the script commands contained in the script event block are run. Depending on the command these may be executed immediately or they may extend over a certain amount of time. For example, the giveweapon command is executed immediately while the gotomarker command will be run until the NPC reaches the specified location. The script event will not terminate until the last script command in it completes it's execution. When a script event has more than one script command in the script block, the commands are executed one after the other but only after the previous command is finished. This means that the command following a gotomarker command will not be executed until the NPC reaches the correct position.
As with script events, script commands can apply to all entities, just the player and NPCs, just the player or just NPCs. If you try to execute a script command for an entity it doesn't apply to, nothing will happen and the command will be ignored. See AI Script Commands for more details.
Example Script
We will look at a sample script here to show some examples of the makeup of an AI script.
player
{
spawn
{
giveweapon machinegun
selectweapon machinegun
}
playerstart
{
alertentity ogre1
}
}
ogre1
{
attributes
{
health 200
}
death
{
dropitem bullets 45
}
}
There are two script blocks in this script, one for the player and the other for an entity with the ainame of ogre1. Lets look at the player script block first.
In this script block there are two script event blocks, one for when the player spawns into the world (spawn) and the other when he actually starts the game (playerstart), which occurs 0.5 seconds later. In the spawn event block we give the player the machinegun and then make him select it so he is armed when the level begins. In the playerstart event block we cause the entity with the ainame of ogre1 to be alerted (or used) so it will spawn into the level.
In the ogre1 script block there are also two script event blocks, attributes and death. The attributes event block is run when a NPC entity is spawned and is used to override the standard defined attributes of that NPC. Here we change the entity's health so he starts with 200. The death script event is run when the entity dies and we make him drop an item, bullets, beside his corpse.
This script is extremely simple but it does show the customization you can perform in a level. It is possible to change the behaviour of entities without having to rewrite the source code and to individually changes features of each entity in the level.
