The spawn system uses waypoints as spawn points. These waypoints have a great deal of options on them in the form of local variables which the builder can change to suit his needs. A spawn point works if its local string variable ACR_SPAWN_RESNAME_1 is given a valid creature Resource Name. By default, spawn points are always active, always spawn what you tell them to, and will not respawn when their children are killed.
In computer lingo, an "array" is simply a list of some sort of data of the same time. The spawn system uses arrays to list the "resource names" of creatures or objects you want to spawn, and the scripts you may wish to attach to these creatures. Since the spawn system depends on local variables for configuration, the arrays are lists of local variables. For example, ACR_SPAWN_RESNAME_ is a local string which lists the resrefs of the creatures spawned. So ACR_SPAWN_RESNAME_1 would be the name of the local variable for the first resref, ACR_SPAWN_RESNAME_2 the second, ACR_SPAWN_RESNAME_3 the third, and so on. Never skip a entry in an array. If you do, the spawn system will think the array has stopped at the missing entry. Also, always start at 1, not 0.
ACR_SPAWN_TYPE (Local integer) This indicates the type of object which is being spawned. The default is 0, for a creature, but other types are available, as listed below:
Store: 3 (not tested, but should work)
ACR_SPAWN_RESNAME_ (Local string array) This array lists Resource Names of objects which are always spawned by the spawn point. If the spawn point is activated, all the Resource Names in this array will be spawned. Resource Names listed more than once are spawned more than once. ex, leading to 2 badgers and a chicken each time: ACR_SPAWN_RESNAME_1 = "c_badger" ACR_SPAWN_RESNAME_2 = "c_badger" ACR_SPAWN_RESNAME_3 = "c_chicken"
ACR_SPAWN_RANDOM_RESNAME_ (Local string array) This array lists Resource Names of objects which are chosen at random to be spawned. The number of chosen Resource Names depends on the ACR_SPAWN_RESNAMES_MIN/MAX settings, see below. This array can have no more than 31 entries. Each time the spawns are chosen randomly from this list, ex, leading to 67% chicken and 33% badger: ACR_SPAWN_RANDOM_RESNAME_1 = "c_badger" ACR_SPAWN_RANDOM_RESNAME_2 = "c_chicken" ACR_SPAWN_RANDOM_RESNAME_3 = "c_chicken"
ACR_SPAWN_RESNAMES_MIN (Local integer) ACR_SPAWN_RESNAMES_MAX (Local integer) These are the maximum and minimum numbers of Resource Names spawned from the ACR_SPAWN_RANDOM_RESNAME_ array. The actual number spawned is determined randomly between these values. They can range between 0 and 31. To keep this value from being random, set both the min and max equal. Each one will be an independent pull from the RANDOM_RESNAME array described above, so if these are >1, you may end up with multiples of Resource Names from the RANDOM_RESNAME array: best to leave uniques like bosses to their own waypoint, or use the ACR_SPAWN_RESNAME_# option above for them.
ACR_SPAWN_RESPAWN_COUNT (Local integer) This local integer defines the number of times a spawn point will spawn, if all its children have been killed. The default is 1, which indicates a "single-life" spawn. Mod reset or scripts can bring the spawn back, and normal despawning due to time or inactivity will not permanently deactivate the spawn point, only death of all of it's spawned "children". Note that this relies on the spawned objects having the correct acf_ondeath() scripts in their OnDeath events. A setting of "-1" will lead to an infinitely respawning waypoint, which will always repopulate after being "cleared out". Similarly, setting this value to "5", would mean the spawn point would have to be killed off 5 separate times to deactivate "for good". Note that currently a mod reset still sets this counter back to it's original state, though we may tie this into persistent variables once they become available to us again.
ACR_RESPAWN_DELAY_MIN (Local float) ACR_RESPAWN_DELAY_MAX (Local float) This is the random period of time a spawn spends "recharging" after its children have all been killed (see above). This value is in game hours, and is chosen randomly between the mininum and maximum. To keep this value from being random, set both the min and max equal. In practical terms, the respawn will happen at the next spawn pseudoheartbest after the timer expires, so the "accuracy" of the respawn delay will be somewhat dependent on the refresh rate of the system. Also note that setting respawn delay to "0.0" means the respawn will still be delayed until the next pseudoheartbeat, so respawns are never instantaneous (though if a spawn is killed just before a heartbeat, it may appear so).
ACR_SPAWN_CHANCE (Local float) This value, from 0 to 100, represents the chance a spawn has of spawning. This chance is computed once every game day. The % chance applies per day for the waypoint collectively, so it is an all-or-nothing situation.
ACR_SPAWN_RANDOM_RADIUS (Local float) This, if nonzero, specifies a maximum distance from the chosen spawn point location at which the spawn child may appear, in a random direction. This is calculated separately (distance and direction) for each spawned child, so for a multiple spawn, you can imagine it to describe the tightness of the "scatter" of the spawned children around the spawn point target. A small value will give a closely-spaced group, while a large one will give the illusion of entirely separate spawns, even though they are all children of the same waypoint.
ACR_SPAWN_RANDOM_RANGE (Local float) This, if nonzero, specifies a range (in a random direction) from the actual location of the waypoint to the target/centerpoint of the spawning- 0.0 will always center the spawn right on top of the waypoint, while an arbitrarily large value could place the spawn anywhere in the area. Note that when spawning a single child, this parameter is functionally equivalent to ACR_SPAWN_RANDOM_RADIUS, but when used with multiple children, it can place a mob of creatures, placeables, or items in a less predictable position, either in a closely knit group, or a broad spread.
ACR_SPAWN_IN_VFX (Local int) This integer indicates the visual effect number of a visual effect which is played on every object this spawn point spawns. It is commonly used to represent teleporting or summoned monsters.
ACR_SPAWN_VFX (Local int) This integer indicates the visual effect number of a visual effect which is played on the spawn point itself as it activates. It is commonly used to represent groups of teleporting or summoned monsters.
ACR_SPAWN_IN_SFX (Local string) This is the sound effect file which is played on each object spawned at this spawn point. (not yet tested, but should work)
ACR_SPAWN_SFX (Local string) This is the sound effect file which is played on the spawn point itself as it activates. (not yet tested, but should work)
ACR_SPAWN_ANIMATION (Local string) This is the animation performed by all creatures spawned from this spawn point, as they spawn. (not yet tested, but should work)
ACR_SPAWN_IN_HOUR (Local int) ACR_SPAWN_OUT_HOUR (Local int) This is the hour of the day the spawn starts to spawn in and spawns out at. If the current hour is between these values, the spawn can be active. If the two values are equal (such as zero, the default), the hour of the day has no effect on whether or not the spawn activates. Valid values are between 0 and 23. This also works for "circular" cases, such as Night-only spaws, ex here for spawning in at 18:00, and spawning back out every 06:00: ACR_SPAWN_IN_HOUR = "18" ACR_SPAWN_OUT_HOUR = "6"
ACR_SPAWN_IN_DAY (Local int) ACR_SPAWN_OUT_DAY (Local int) This is the day of the month (28 days in the Fearunian month) in which the spawn will spawn in and spawn out. These should also work in a circular fashion similar to the hours above, though that behaviour has not been stringently tested.
ACR_SPAWN_IN_MONTH (Local int) ACR_SPAWN_OUT_MONTH (Local int) This is the month of the year (12 months in the Faerunian year) the spawn starts to spawn in and spawns out at. If the current month is between these values, the spawn can be active. If the two values are equal (such as zero, the default), the month of the year has no effect on whether or not the spawn activates. Valid values are between 1 and 12.
ACR_SPAWN_IN_PC_SIGHT (Local int) If nonzero, the spawn will spawn with a PC in sight of it. This is disabled to keep spawns from suddenly appearing in front of a PC in an OOC fashion. (not tested, should work)
ACR_SPAWN_ONLY_WHEN_NO_PC_IN_AREA (Local int) If nonzero, this spawn will not respawn or activate at all if a PC is already in the area when it tries to do so. This is used to prevent creatures from re-appearing where they were after a PC just killed them, or something similar. (not tested, should work)
ACR_SPAWN_WITH_ANIMATION (Local int) If nonzero, this setting makes the spawn appear with its default spawn-in animation. This is usually a "fly-down" effect for most creatures, and a "climb down" effect for spiders. (not tested, should work)
ACR_SPAWN_IS_DISABLED (Local int) If nonzero, this spawn is disabled and will not spawn unless enabled by some other script or DM tool.
ACR_SPAWN_RANDOM_FACING (Local int) If nonzero, the spawn's facing is random, instead of facing the direction of the spawn waypoint.
ACR_SPAWN_IN_STEALTH (Local int) If nonzero, the spawn spawns in stealth mode.
ACR_SPAWN_IN_DETECT (Local int) If nonzero, the spawn spawns in detect mode.
ACR_SPAWN_BUFFED (Local int) If nonzero, spawned creatures spawn with all hour per level (or longer) buffs cast on itself in a semi-intelligent fashion (evil creatures cast protection from good, multiple magic vestimates or magic weapons are distributed over different items, etc). (not tested, should work)
Custom Script Parameters
The spawn system allows custom scripts to be run when a spawn activates, for scripters to use how they wish. In order to use the functions listed here, be sure and include the spawn system's source file with the line: #include "acr_spawn_i" at the top of your script.
ACR_SPAWN_IN_SCRIPT_ (Local string array) This array defines custom scripts which are run on each object spawned by the spawn point. Each script is executed on each spawned object once, with OBJECT_SELF pointing to the spawned object. These scripts can have any name.
ACR_SPAWN_SCRIPT_ (Local string array) This array defines custom scripts which are run on the spawn point after it activates and spawns children. Each script is executed once, with OBJECT_SELF pointing to the spawn waypoint itself. If you wish to spawn additional objects from this script, use the function ACR_SpawnObject(). These scripts can have any name.
ACR_SPAWN_IS_ACTIVE_SCRIPT (Local string) This variable defines a single custom which is run whenever the spawn system looks at the spawn point and tries to decide whether or not to spawn it. It allows custom logic to be used to decide whether or not the point should spawn, overriding the spawn point's normal behavior. In this script, OBJECT_SELF points to the spawn waypoint itself. If you wish the point to spawn, call ACR_ForceSpawn(). If you wish to keep it from spawning, call ACR_DisallowSpawn(). If you don't call either of these functions, the spawn point behaves as it normally would. If for some reason you call both, ACR_ForceSpawn() takes precedence and the spawn activates. (not yet tested)
In addition to the options of each spawn point, there are a few settings which you can use to globally configure the spawn system. These are constants located in the script acf_spawn_i.
_SPAWN_AREA_DESPAWN_DELAY This is the delay between when an area becomes empty of PCs, and when the spawn system despawns its children within it. Larger values here may lead to increased CPU usage as more creatures stay spawned at once.
_SPAWN_REFRESH_DELAY This is the "heartbeat" of the spawn system. Larger values here reduce CPU usage, but make the spawn system react slower.
_SPAWN_PRESPAWN_SEAMLESS This controls whether the spawn system will take cues from PCs entering seamless ATs in adjacent areas. If active, it should ensure all spawns are in place before the PC actually ATs. It may be disabled to keep memory use down, as it may lead to areas being population without PCs actually entering them (if the PC backs out of the AT trigger instead of continuing)
_SPAWN_PRESPAWN_PREDICTION This controls whether the spawn system will take into account the predicted arrival point of an ATing PC, when deciding whether to spawn a group intended to be out of sight.
These parameters do not currently function, but are included for builders to use as an interface until they are completed.
ACR_SPAWN_IN_WAYPOINT (Local string) ACR_SPAWN_OUT_WAYPOINT (Local string) These strings represent tags of waypoints where the creature spawns in at, and despawns at. Once spawned, the creature will move towards the spawn point's location. For example, a peasant could spawn at his house door at 8:00 in the morning, move to the location of the spawn point in a field of oats, then despawn at a tavern door at 17:00. All waypoints must be in the same area as the spawn point. If more than one waypoint with the same tag is placed, the closest one to the spawn point is used.
ACR_SPAWN_WHEN_PC_NEARS (Local float) This parameter keeps the spawn point from activating unless a PC nears it within a certain range. Distances are in meters.
ACR_MIN_SPAWN_DURATION (Local float) ACR_MAX_SPAWN_DURATION (Local float) A random value is chosen between these two values to determine how long a spawn remains spawned in game hours. After this time is up, the spawn despawns noramally, and can respawn again when the respawn delay is up (see below). To keep this value from being random, set both the min and max equal. If you want the spawn to remain spawned indefinitely, just leave these set to zero. After this counter is up, the spawn will despawn itself, and it will try to respawn itself as soon as its respawn delay counter is up (see below).
ACR_SPAWN_RANDOM_POSITION_BORDER (Local int) If nonzero, this setting prevents any spawn from spawning in within visible range of the map edge. This is used to prevent PCs from ATing into monsters, who prompty eat them before the player can react.
These are parameters we hope to have working in NWN2, but we aren't entirely sure if we will be able to.
ACR_SPAWN_FACTION (Local string) This parameter sets the spawned object's faction. If the name of the faction is invalid, it does nothing.
Disabled until future NWN2 updates: Until some of the base functions in NWN2 are fixed by Obsidian patches, we won't be able to dynamically rename spawns on the fly.
ACR_SPAWN_NAME_PREFIX (Local string) This is the string added to the beginning of the spawned object's name. Spaces are not included, so be sure to add one if you need it. For example, setting this to "Black Lance " (without quotes) would cause all creatures spawned from the point to take that prefix, ie "Black Lance Orc" would be spawned.
ACR_SPAWN_NAME_SUFFIX (Local string) This is the string added to the end of the spawned object's name. Spaces are not included, so be sure to add one if you need it. For example, setting this to " Archer" (without quotes) would cause all creatures spawned from the point to take that prefix, ie "Orc Archer" would be spawned.
ACR_SPAWN_NAME_FIRST (Local string) This string, if set, completely replaces the first name of the spawn. If for some reason you have prefixes and suffixes set as well, they will also be included.
ACR_SPAWN_NAME_LAST (Local string) This string, if set, completely replaces the last name of the spawn. If for some reason you have prefixes and suffixes set as well, they will also be included.
ACR_SPAWN_RANDOM_NAME (Local integer) If nonzero, this setting will assign a randomly-generated name to each spawned creature, based on the creature's gender and racial type.
ACR_SPAWN_WEATHER_CLEAR (Local int) ACR_SPAWN_WEATHER_RAIN_WEAK (Local int) ACR_SPAWN_WEATHER_RAIN_LIGHT (Local int) ACR_SPAWN_WEATHER_RAIN_MEDIUM (Local int) ACR_SPAWN_WEATHER_RAIN_HEAVY (Local int) ACR_SPAWN_WEATHER_RAIN_STORMY (Local int) ACR_SPAWN_WEATHER_SNOWN_WEAK (Local int) ACR_SPAWN_WEATHER_SNOW_LIGHT (Local int) ACR_SPAWN_WEATHER_SNOW_MEDIUM (Local int) ACR_SPAWN_WEATHER_SNOW_HEAVY (Local int) ACR_SPAWN_WEATHER_SNOW_STORMY (Local int) ACR_SPAWN_WEATHER_LIGHTNING_WEAK (Local int) ACR_SPAWN_WEATHER_LIGHTNING_LIGHT (Local int) ACR_SPAWN_WEATHER_LIGHTNING_MEDIUM (Local int) ACR_SPAWN_WEATHER_LIGHTNING_HEAVY (Local int) ACR_SPAWN_WEATHER_LIGHTNING_STORMY (Local int) If set to 1, each of these integers allow the spawn to spawn in under the indicated conditions. If set to 0, the spawn does not spawn under those weather conditions. Disabled until we have a working weather system.
ACR_SPAWN_IN_COLD_DAMAGING_WEATHER (Local int) ACR_SPAWN_IN_HEAT_DAMAGING_WEATHER (Local int) If nonzero, this spawn will activate in dangerous weather which causes heat or cold damage. Disabled until we have a working weather system.