Scripting:AIEcologyTutorial

Setting up an AI Ecology has several levels of complexity, depending on which AIs you are going to spawn and how adventurous you want to get. The instructions here should considered to be an introduction to the capabilities of the various AIEcology scripts, and far more complex setups can be created - experiment, and see what you can make!

Obviously before you begin you should make sure that TWScript is loaded in your FM, otherwise no AIs will spawn.

A Schrödin-fnord

As noted in the documentation for TWTrapAIEcology, the locations at which the TWTrapAIEcology script will create AIs are marked with 'spawn point' markers. If you don't care about AI being spawned on-screen - say you have magic portals they can "enter" through - you can skip this section entirely. However, if you want to ensure that spawns do not happen when the spawn point is visible, there is a problem: normal fnord markers are unrendered, invisible to both the player and the render pipeline, and as such there is no way to determine whether they are on screen!

To address this, you need to create a special kind of fnord that is both invisible and visible at the same time: invisible to the player, but visible to the render pipeline. In the demo mission resources you will find a twvcube.bin object that is completely transparent and is thus suitable for creating a marker that isn't visible to the player, but is rendered as part of the scene. Once you've copied twvcube.bin into your FM's obj directory you can create the special marker:

• Open the Object Hierarchy
• Select Object -> fnord -> Marker
• Click Add and enter the name AIEcologySpawnPoint
• Select AIEcologySpawnPoint and click Edit
• Add Renderer -> Render Type and set the type to Normal
• Add Shape -> Model Name and set the name to twvcube
• Click Done

You can now place these markers at the appropriate spawn points around your level, and they can be used in the same way as normal fnord markers except that they have the special property that TWTrapAIEcology can determine whether they are on screen.

Setting up the AIs

First, set up your patrol points for AIs spawned by the AIEcology. You can include the spawn point as a marker in the patrol point, or just make sure the spawn point is near a patrol point.

In order for there to be a point in even having an AIEcology script, the ecology needs to be told when an AI has been killed so that it can spawn a replacement. Ideally, the corpse of the slain AI should also be removed from the level to prevent object ID waste. This means that you need to do some prep work on the AIs you want to spawn - in this case we're going to assume that you're spawning spiders, but the principles apply to any AI:

• Open the Object Hierarchy
• Select the archetype for the AI you want to spawn, say Object -> physical -> Creature -> Animal -> Spider -> SewerSpider
• Click Add and enter an appropriate name like SpawnableSewerSpider
• Select the new archetype and click Edit
• Add AI -> Ability Settings -> Patrol: Does Patrol and tick the box. The AI needs to have this set, otherwise it'll just stand there at the spawn point being rather pointless. You may also want to set the AI to do a random patrol using AI -> Ability Settings -> Patrol: Random sequence
• Add S -> Scripts and in the Script 0 box add:
  • TWTriggerAIEcologyDespawn if the AI leaves a corpse behind on the map (anything descending from Animal, for example)
  • TWTriggerAIEcologySlain if the AI does not leave a corpse (for example, if you are spawning fire elementals), or if you don't care if the bodies pile up.

Creating the AIEcology

The AIEcology script can be attached to any object in your level, but here we'll use a Marker:

• Add a Marker to your world in an appropriate location.
• Open the marker's properties and change its name to something that lets you identify it more easily - AIEcology or something.
• Add S -> Scripts and in the Script 0 box add TWTrapAIEcology
• Add Editor -> Design Note and in the box set any of the TWTrapAIEcology parameters you want for your level, for example this will have an ecology with a target population of 3 concurrently spawned AIs, 60 seconds between spawn attempts, and start spawning as soon as the level starts:

TWTrapAIEcologyPopulation=3;TWTrapAIEcologyRate=60s;TWTrapAIEcologyStartOn=true;

• Close the properties, and open the Links for the marker.
• Click Add, and add a ScriptParams link from the marker to the AI archetype you want to spawn, SpawnableSewerSpider for example. If you want to spawn different AIs in the same ecology you can create additional links to their archetypes and the ecology will choose between them randomly at spawn time. If you want a given AI to be spawned more often than another, set the data for the ScriptParam link to that AI to be 2 to make it spawn twice as often as the other AIs, 5 to be 5 times more likely to be chosen, and so on.
• Add ScriptParams links from the marker to each of the spawn points you want the AIEcology to choose between when spawning new AIs. As with the AI archetype links, you can influence the selection of spawn points based on the value in the ScriptParams data, with the proviso that visibility may affect the selection of spawn points!

That should be enough to get you going - when you enter game mode, AIs should start being spawned at the spawn points, and then replaced if any of them are killed.

You can, of course, turn the AIEcology spawning behaviour on or off by sending it a TurnOn or TurnOff message (or the equivalent, if you set TWTrapAIEcologyTurnOn/TWTrapAIEcologyTurnOff.