INI file format: Creature Spawning

Applies to:
PST, IWD, IWD:HoW, IWD:TotL, IWD2, BGEE

General Description

Detailed Description
Each INI file is attached to an area, based on the filename of the referenced WED resource, e.g. AR0513.INI is attached to AR0513.ARE if the area file references AR0513.WED. However, AR0014.INI is attached to AR0083.ARE if the area file references AR0014.WED instead. It is possible to associate a single INI file with multiple areas that way.

Example from IWD (AR6006.INI):

[locals]

[spawn_main]
enter=ENTERSPAWN
events=2_MIN

[ENTERSPAWN]
critters=TheLilznich
interval=1

[2_MIN]
critters=TheLilznich
interval=1800

[TheLilznich]
spec              = [255.0.0.0.101]
spec_var          = 6006_LICH_SPAWN
cre_file          = LICH
script_general    = udNewLch
script_default    = udLich1
ignore_can_see    = 1
check_view_port   = 0
ai_specifics      = 101
point_select      = R
spawn_point       = [595.583:14],[787.562:14],[859.757:14],[1204.924:14],[1353.1135:14],[1638.1260:14],[1573.1349:14],[537.492:14]

There are the following sections in these files:

[nameless]
This section handles various peculiarities stemming from the Nameless One's immortality. This section is only available in PST and PSTEE.

destare = resref
This value changes the area where the Nameless One will be resurrected after his death. The party members are teleported there as well.

point = [x.y]
These are the alternative map coordinates where the Nameless One will be resurrected after his death. The default is the same slab in the Mortuary where you started the game.

state = number
This value indicates the animation sequence (see ANIMSTAT.IDS) used by the Nameless One after being resurrected. It's mostly used to change whether he starts standing or with his special getting-up animation sequence.

partypoint = [x.y]
These are the map coordinates where the rest of the party (without TNO) is moved when entering the area specified by partyarea. Used in ar1800, to force only the namesake to be able to enter the Nameless One's Tomb.

partyarea = resref
Replacement map for the party, see description above of partypoint.


[namelessvar]
This section appears to be used to initialize global variables when the Nameless One dies. This section is only available in PST and PSTEE.

name_of_variable = value
The specified value is assigned to the global variable "name_of_variable".


[locals]
This section appears to be used to initialize local variables (LOCALS scope).


[spawn_main]
This section is responsible for spawning creatures. It supports the following attributes:

enter = name_of_group_section
This attribute expects the name of a single group section. It is executed by the engine whenever the player enters the area.

exit = name_of_group_section
This attribute expects the name of a single group section. It is executed by the engine whenever the player leaves the area. It is only supported by PST, IWD and IWD2.

events = name_of_group_section
This attribute expects one or more comma-separated names of group sections. It is executed by the engine whenever the conditions defined by the assigned sections are met. Note: Because of a buggy implementation only the last listed group section will be considered in EE games.


[name_of_group_section]
This section controls a group of individual spawn sections. It supports the following attributes:

critters = name_of_creature_section1,name_of_creature_section2,...
This attribute expects a comma-separated sequence of creature section names. These sections define individual creatures with their spawn conditions, attributes and behavior. Each listed creature section is evaluated and executed when their spawn conditions are met.

interval = number
Time interval, measured in AI ticks (15 ticks = 1 second), before creature sections defined by the "critters" attribute are evaluated. This attribute is only relevant if the section is linked to the "events" attribute of the [spawn_main] section. The smallest supported interval value appears to be 15 AI ticks. Smaller values are adjusted accordingly by the engine.

detail_level = name
This was possibly a memory saving option, but eventually got excluded - it is controlled by the "Detail level" key not present by default in torment.ini. Known attribute values: High, Medium, Low. However the engine has a bug and treats Medium entries as High. It is only supported by PST.

control_var = scope::variable_name
This attribute was supposed to control whether enter and exit spawn groups are executed by checking a boolean value defined by the specified variable. Note: Specifying this attribute causes the game to crash because of a buggy implementation.

spawn_time_of_day = string
This attribute was supposed to be a bit-string with allowed times for enter and exit spawn groups to execute. It appears to be unused by the engine.


[name_of_creature_section]
This section defines the spawn conditions, attributes and behavior of a single creature type. It can be referenced by the "critters" attribute of group sections. Notes: Attributes that expect a variable name require the variable to exist in the game, even if it contains the value 0. Many attributes that expect a boolean value are merely checked for existence by the engine. The actual value doesn't matter. The whole attribute definition has to be removed to disable it.

It supports the following attributes:

spec_var = scope::variable_name
This attribute expects the name of a variable which is used to control whether the creature section is eligible for spawning. It uses GLOBAL scope by default, but can be optionally preceded by a user-defined scope and two consecutive colons (e.g. AR0500::MY_VAR). Only a single variable can be evaluated per creature section.

spec = filter_value
This attribute expects either a script name or a target specification between square brackets in the order [EA.FACTION.TEAM.GENERAL.RACE.CLASS.SPECIFIC.GENDER.ALIGN]. These specification values are checked by the engine whenever the spawning process is triggered to determine whether a new instance of the creature can be spawned.
A specified script name is checked against the script name of the spawned creature. A target specification in square brackets is checked against the respective numeric attributes of the spawned creature. A value of 0 is considered a wildcard. Faction and Team may not be available for all games. Just like the target notation in scripts it is not necessary to specify all fields. Unlisted fields are treated as 0.

spec_area = [centerX,centerY,range,unknown?]
This attribute is supposed to alter where on the map the engine looks for existing creatures to determine the spawn cap. Note: Because of a buggy implementation this attribute is mostly inoperable. Don't use it!

spec_qty = number
This attribute specifies the total amount of creatures matching the given "spec" attribute that can be spawned on the map. Number of spawns is limited to the value defined by the "create_qty" attribute. Default value: same as "create_qty", 1 otherwise.

spec_var_inc = number
This attribute specifies the amount to increment the variable defined by the "spec_var" attribute per spawn operation. It is only supported by IWD2.

spec_var_value = number
This attribute expects a numeric reference value which is compared according to the "spec_var_operation" attribute. It is only supported by IWD2.

spec_var_operation = operation
This attribute expects an operation mode. It is used to compare the content of the variable specified by the "spec_var" attribute with the value defined by the "spec_var_value" attribute.
Known operations:
  • greater_than: spec_var > spec_var_value
  • less_than: spec_var < spec_var_value
  • equal_to: spec_var == spec_var_value
  • not_equal_to: spec_var != spec_var_value
It is only supported by IWD2.

area_diff_1 = boolean_value
area_diff_2 = boolean_value
area_diff_3 = boolean_value
Indicates the area difficulty where an instance of this creature should be spawned. It mirrors the area difficulty mask defined in ARE V9.1 actor structures. It is only supported by IWD2.

cre_file = resref
This attribute expects the resref of the CRE file to spawn when all conditions are met.

create_qty = number
This attribute controls how many instances of the current creature are spawned at once. Number is limited by the value specified by the "spec_qty" attribute. Default value: same as "spec_qty", 1 otherwise.

script_name = string
This attribute expects the script name for the spawned creature. It should not exceed 32 characters. The string can be used for targeting in scripts. It is functionally identical to the name of ARE actor structures.

ai_ea = number
This attribute defines the numeric EA value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_general = number
This attribute defines the numeric GENERAL value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_race = number
This attribute defines the numeric RACE value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_class = number
This attribute defines the numeric CLASS value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_gender = number
This attribute defines the numeric GENDER value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_specifics = number
This attribute defines the numeric SPECIFIC value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_alignment = number
This attribute defines the numeric ALIGN value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource.

ai_faction = number
This attribute defines the numeric FACTION value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource. Not all games support factions. Note: It doesn't appear to be supported by PSTEE as well.

ai_team = number
This attribute defines the numeric TEAM value which is assigned to the creature when it is spawned. Omit this attribute to use the value defined by the CRE resource. Not all games support teams. Note: It doesn't appear to be supported by PSTEE as well.

script_override = resref
This attribute defines the override script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_class = resref
This attribute defines the class script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_race = resref
This attribute defines the race script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_general = resref
This attribute defines the general script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_default = resref
This attribute defines the default script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_area = resref
This attribute defines the area script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_specifics = resref
This attribute defines the specifics script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource.

script_special_1 = resref
This attribute defines the special 1 script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

script_team = resref
This attribute defines the team script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

script_special_2 = resref
This attribute defines the special 2 script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

script_combat = resref
This attribute defines the combat script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

script_special_3 = resref
This attribute defines the special 3 script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

script_movement = resref
This attribute defines the movement script assigned to the creature when it is spawned. Omit this attribute to use the script defined by the CRE resource. This script slot is only available in IWD2.

dialog = resref
This attribute defines the dialog assigned to the creature when it is spawned. Omit this attribute to use the dialog defined by the CRE resource.

good_mod = number
This attribute defines the value that is added to the GOOD variable when the spawned creature is killed. It is only supported by PST and PSTEE.

law_mod = number
This attribute defines the value that is added to the LAW variable when the spawned creature is killed. It is only supported by PST and PSTEE.

lady_mod = number
This attribute defines the value that is added to the LADY variable when the spawned creature is killed. It is only supported by PST and PSTEE.

murder_mod = number
This attribute defines the value that is added to the MURDER variable when the spawned creature is killed. It is only supported by PST and PSTEE.

death_scriptname = boolean_value
This attribute indicates whether the script name defined by the "script_name" attribute is also used for the death variable.

death_faction = boolean_value
This value controls whether the faction death counter is incremented when the spawned creature is killed. It appears to be supported only by PST.

death_team = boolean_value
This value controls whether the team death counter is incremented when the spawned creature is killed. It appears to be supported only by PST.

spawn_point = [x.y:dir],[x.y:dir],...
This attribute expects one or more map coordinates for the creature. Values can be separated by comma or directly appended without a separator. The engine uses a point randomly if multiple locations are defined. The behavior can be further refined by additional attributes described below. In PST orientation is sometimes omitted and defined by the "facing" attribute instead.

point_select = letter
This attribute expects a single letter which determines how the engine chooses the next spawn point.
Known attribute values are:
  • e: (POINT_SELECT_EXPLICIT) The spawn location and orientation are retrieved from predefined game variables defined by "spawn_point_global" and "spawn_facing_global" respectively. Note: Due to a bug in the implementation the orientation is read from "point_select_var" instead of "spawn_facing_global".
  • i: (POINT_SELECT_INDEXED_SEQUENTIAL) Uses the value of the variable defined by "point_select_var" as starting index into the array of map coordinates defined by the "spawn_point" attribute.
  • r: (POINT_SELECT_RANDOM_SEQUENTIAL) Default mode if unspecified. The spawn location is chosen at random from the array of map coordinates defined by the "spawn_point" attribute.
  • s: (POINT_SELECT_SEQUENTIAL) The engine uses the first spawn location defined by the "spawn_point" attribute and increments the index by one after each spawn. Note: Due to a buggy implementation the spawn index is reset to 0 AFTER selecting the first spawn location, so the first spawn will always continue the progression of the PREVIOUS spawn execution. Additionally, the only way a spawn location other than the first or second is used is if 1) Every spawn location index before the selected one was unsuitable for spawning, or 2) "create_qty" is defined to spawn more than one creature at once. Spawning multiple creatures at once (by setting create_qty > 1) will increment the spawn location index for each individual creature correctly, however.
point_select_var = scope::variable_name
This attribute is only used if "point_select" is set to i (POINT_SELECT_INDEXED_SEQUENTIAL). It expects a variable name that determines the first spawn location index the engine considers when selecting for a spawn. It uses the following index calculation: index = [point_select_var] % [spawn_point].size. Notes: Specifying the scope is mandatory for this attribute to work. Due to a bug in the implementation this attribute is also used to determine the creature orientation if "point_select" is set to e (POINT_SELECT_EXPLICIT).

facing = number
This attribute expects a numeric value in the range 0..15 for the creature's orientation where 0=south, 4=west, 8=north and 12=east. It is used by PST if the orientation is omitted by the "spawn_point" attribute.

ignore_can_see = boolean_value
This attribute indicates whether a creature can be spawned even if the spawn point is not obscured by the fog of war and is currently in the viewport. By default creatures are only spawned off-screen.

check_crowd = boolean_value
This attribute appears to be unimplemented.

find_safest_point = boolean_value
When this attribute is defined the engine iterates over all eligible spawn locations and selects the first entry that is considered "safe". A "safe" spawn location is defined as being currently obscured by the fog of war and is not currently in the viewport. This behavior can be overridden by the "ignore_can_see" attribute.

save_selected_point = scope::variable_name
This attribute instructs the engine to store the map coordinates of the spawned creature in the specified variable. Note: The map coordinates of the first spawned creature are stored if create_qty > 1.

save_selected_facing = scope::variable_name
This attribute is supposed to instruct the engine to store the orientation of the spawned creature in the specified variable. Note: This attribute appears to be unimplemented.

spawn_point_global = scope::variable_name
This attribute is only used if "point_select" is set to e (POINT_SELECT_EXPLICIT). It expects a variable name that is used to retrieve the map coordinates for the spawned creature.

spawn_facing_global = scope::variable_name
This attribute is only used if "point_select" is set to e (POINT_SELECT_EXPLICIT). It expects a variable name that is used to retrieve the orientation for the spawned creature. Notes: Specifying the scope is mandatory for this attribute to work. Due to a bug in the implementation the orientation is read from "point_select_var" instead of this attribute. However, both attributes must be specified to work and require an explicit scope definition.

inc_spawn_point_index = boolean_value
This attribute is only used if "point_select" is set to i (POINT_SELECT_INDEXED_SEQUENTIAL). It indicates that the variable defined by "point_select_var" is incremented on spawn location selection. If "create_qty" is greater than 1 then spawn point index is incremented after each creature is spawned. Note: The spawn operation applies a pre-selection and post-selection pass when executing a creature spawn section which results in the index being incremented twice if the same section is executed multiple times. Pre-selection is applied before the whole spawn operation is executed. Post-selection is applied after individual creature spawns which is important to note if "create_qty" is set to spawn multiple creatures at once.

hold_selected_point_key = boolean_value
This attribute prevents the engine from updating the currently selected spawn location index directly after the spawn operation (post-selection). If "create_qty" is greater than 1 then this attribute forces the engine to reuse the initially selected spawn location for all spawns created during the current spawn operation. This attribute affects only sequential "point_select" modes which includes i, r and s.

check_by_view_port = boolean_value
This attribute appears to be unimplemented. Note: There are plenty of uses of the "check_view_port" attribute. That attribute is not supported by the engine.

do_not_spawn = boolean_value
This attribute indicates that the creature should not be spawned at all.

auto_buddy = boolean_value
It is likely that this attribute controls whether all nearby creatures turn party-hostile when the spawned creature calls for help. It is only supported by PST.

time_of_day = string
This attribute is supposed to be a bit-string defining the spawned creature's "Present at" field (see offset 0x40 in ARE actor structure). Note: Specifying this attribute causes the game to crash because of a buggy implementation of the bit-string parser.

disable_renderer = boolean_value
This attribute indicates whether the animation of the spawned creature should be rendered on the game screen. The state is not stored in saved games. Regardless of their rendering state the spawned creature takes up personal space, and the mouse cursor will react appropriately when placed over their current location. The script action SetRenderable(O:Target*,I:Renderable*Boolean) can be used to further control the rendering state of the creature. This attribute is only supported by PSTEE.