Scripting:TWTrapAIEcology

TWTrapAIEcology is a script that allows a controlled population of AIs to be spawned dynamically during play.

Periodically this script will check whether the number of currently spawned AIs has reached a configurable population limit. If the count is less than the limit, the script will select an AI archetype to spawn, and then choose a spawn point at which the AI should be created. If AIs are killed and despawn, the population drops, and new AIs will be spawned to replace them. Note that this only works if the AI despawns - use the TWTrapAIEcologyDespawn script to make that happen.

At most one AI is spawned each time the script checks the current population. This is a deliberate restriction imposed to prevent AIs being spawned on top of each other.

The AI archetype is chosen based on links from the TWTrapAIEcology host object to archetypes. By default the script will use weighted random selection if multiple AI archetypes are linked, and if only a single AI archetype is linked that is always used.

Example from demo.osm

The spawn point is chosen based on links from the TWTrapAIEcology to concrete objects in the world. If multiple spawn points are linked, one is chosen at random, whereas if only one spawn point is linked that one is always used. The default behaviour is to try and find the first randomly selected spawn point that is not visible on screen. If all spawn points are on screen, spawning is aborted. This behaviour can be disabled if desired - the spawn point is sent a TurnOn message when an AI spawns there, so particle effects can be tiggered.

It is important to note that, while a fnord (a Marker or similar) could be used to mark the location of a spawn point, using a standard fnord is NOT recommended if you want to spawn AIs off screen. fnord objects are not rendered, and this means that the engine can not determine whether the object is on screen: it will always say it is not because, well, you can't see it; it's not rendered! While this is a fine and useful attribute for a normal fnord to have, if you want to make sure that AIs are always spawned off screen, you can't use a fnord unless you give it a transparent, physicsless object and change its Render Type to 'Normal'. An example using this setup can be found in the TWScript Demo mission.

You can attach AIWatchObj links to each spawn point, and whenever an AI is spawned the AIWatchObj links set on the spawn point are copied to the newly spawned AI.

Design Note Parameters

This script supports all the following arguments in the Editor -> Design Note in addition to the arguments given in the TWBaseScript and TWBaseTrap documentation.

TWTrapAIEcologyRate

Type: time

Default: 30s

The frequency at which the AIEcology checks the current population and attempts to spawn new AIs if the number of spawned AIs is less than the target population. You probably don't want to set this to anything less than the default - and even that is probably too fast - unless there's some obvious reason why AIs are spawning so quickly (for example, you have Fire Elementals spawning near lava)

TWTrapAIEcologyPopulation

Type: integer

Default: 1

The target number of AIs to have spawned at the same time. If less than this number of AIs have been spawned, the script will try to spawn a new one at the specified rate.

TWTrapAIEcologyLives

Type: integer

Default: 0 (unlimited)

Limit the overall number of times that AIs can be spawned. If this has been set, every time an AI is spawned the number of 'lives' the AIEcology has is decreased by 1. When the lives have all been used up, the AIEcology stops spawning new AIs until it receives a ResetSpawned message.

TWTrapAIEcologyStartOn

Type: boolean

Default: false

If this is set to true the AIEcology starts working as soon as the mission starts, otherwise it must be turned on before it will start spawning AIs

TWTrapAIEcologyVisibleSpawn

Type: boolean

Default: false

If set to true, no visibility checks are done on spawn points and AIs can be spawned at them even when they are on screen - you may want to add particle effects or the like to the spawn point in this case.

TWTrapAIEcologySpawnQVar

Type: string

Default: not set

If set to a quest variable name, the number of currently spawned AIs is stored in the quest variable.

TWTrapAIEcologyAILink

Type: target

Default: &%Weighted

The AIEcology uses this to determine which AI to spawn. If you're only spawning one kind of AI in the ecology, this can be the archetype name or archetype ID. If you want to select between different AIs at random, set ScriptParam links to each of the possible archetypes to spawn and the default value will allow one to be chosen at random each time an AI is spawned.

TWTrapAIEcologySpawnLink

Type: target

Default: &#Weighted

The AIEcology uses this to work out where to spawn AIs. If you only have one spawn point, this can be the ID or name of the spawn point, otherwise you will want to link the host object to the spawn points (typically using ScriptParam links) and the ecology will select one at random - subject to possible visibility checks - to spawn the AI at that location.