spawning waves

Dependencies
(order dependant, as in it has to be included before the global_spawnWave.scr):

#include "maps/global_scripts/global_common.scr"
#include "maps/global_scripts/global_array.scr"

Actual script file:

#include "maps/global_scripts/global_spawnWave.scr"

The way it works is that you place a bunch of spawners where you want a group of guys to spawn in waves (you can have as many groups of spawners as you like per level). You then run the setup function that defines the behavior of how the waves of guys need to spawn for a single group. The parameters you can setup are number or waves to spawn, the minimum number of guys in a wave, the maximum number of guys in a wave, and the group id that all the spawned guys will have when they spawn. When you're ready to start the spawn group, call the function referencing that group and voila.

Here's the breakdown on the specifics:

Placing Spawners

First thing you need to do is place a bunch of spawners for a group. Think about the maximum number of guys you want to be able to spawn in a single wave of the group, and make sure that you have at LEAST that many spawners available. The reason for this is when a wave spawns, it will never use the same spawner twice for that particular wave to prevent AI from spawning on top of themselves. So if you want a maximum of 5 AI to spawn in a wave, and you only have 4 spawners, it won't work and the script will report an error.

Naming spawners

You can have as many spawning groups in your level as you like, but each group has to have a unique name identifier. So for example, let's say I'm creating a fight in engineering on the enterprise and I want a group to spawn there. I'll name this group 'spawnEngineeringGroup' (without the quotes of course :). This is what I'm going to reference the group as from here on out. So, when I name my spawners, ALL of the spawners have to start with this reference, followed by a number.

The spawners should be numbered in sequence starting with 1. So, in my example, let's say I want a maximum of 5 guys to spawn in a wave, so I place 10 spawners around the room to give some variety in location. The spawners would be named:

$spawnEngineeringGroup1
$spawnEngineeringGroup2
$spawnEngineeringGroup3
$spawnEngineeringGroup4
$spawnEngineeringGroup5
$spawnEngineeringGroup6
$spawnEngineeringGroup7
$spawnEngineeringGroup8
$spawnEngineeringGroup9
$spawnEngineeringGroup10

Setting up the Spawners

This global script will NOT setup the spawners for you. You still have to set what model you want to spawn, if you want it to play beam in effects or whatever. So you need to setup your spawners.

Running the Setup Function

After you've setup your spawners, at the start of your level, you need to run this setup function:

globalSpawnWave_Setup( strGroupName, intNumberOfSpawners, intNumberOfWaves, intMinPerWave, intMaxPerWave, intWaveId )

Now here are the parameters and what they mean:

• strGroupName (string)
  This is the unique name identifier you gave the group. In my example case, this would be 'spawnEngineeringGroup' (of course minus the quotes :). You HAVE TO HAVE a group name or the script will not work at all because it has to know which group you are referencing!
  
  
• intNumberOfSpawners (float)
  This is the number of spawners you placed for this group. In my example case, this would be set to 10. This parameter has to be set to at LEAST 1.
  
  
• intNumberOfWaves (float)
  T his is the number of waves you want spawned for this group. Meaning, when the number of spawned AI that are alive falls below the minimum allowed per wave that you set (which will be discussed next), then it will spawn in another wave of AI in the group. This parameter has to be set to at LEAST 1.
  
  
• intMinPerWave (float)
  This is the minimum number of guys that will spawn in a wave. When a wave spawns, it randomly picks a value between the set minimum number of guys and the set maximum number of guys. That value is how many AI will spawn that wave. So if I have a minimum number of guys set to 3, and a maximum number of guys set to 5, then for every wave that spawns in that group, between 3 and 5 guys will spawn.
  
  The minimum number of guys value also serves as the defining point on when to spawn in the next wave (if there are waves left to spawn). So in this case, if the number of spawned AI that are alive falls from 3 guys, to 2 guys, it has now fallen below the set minimum number of guys allowed and will attempt to spawn another wave in this group. This parameter has to be set to at LEAST 1.
  
  
• intMaxPerWave (float)
  This is the maximum number of guys that will spawn in a wave. You also have to make sure that the number of spawners placed is equal to, or greater than this value. For example, if I set a maximum number of AI to 5, and I only have 4 spawners placed, this would cause a major problem, and therefore the script will catch this and print an error message to the console. This value also works in tandum with the intMinPerWave value in determining how many AI to spawn in a wave.
  
  
• intWaveId (float)
  This is the group ID number that all the spawned AI will have. This is primarily for use with the optional group death thread, but it MUST be set regardless. Make sure that each spawn wave group has it's own unique ID.

Setting up an Optional Group Death Thread

If you have a situation where when all of your spawned AI from a group are dead, and you need a thread to be called due to this, you can set this optional goup death thread. This will ONLY run when all the AI are dead, meaning it has gone through ALL of the waves of AI for that group. Here is the function you run in your level script:

globalSpawnWave_SetupDeathThread( strGroupName, strDeathThread )

You MUST run this after the setup function has been fully run else it won't set the death thread properly. Here are the parameters for this function:

• strGroupName (string)
  This is the unique name identifier you gave the group. In my example case, this would be 'spawnEngineeringGroup' (of course minus the quotes :). You HAVE TO HAVE a group name or the script will not work at all because it has to know which group you are referencing!
  
  
• strDeathThread (string)
  This is the thread to call when all the spawned AI in the group are dead

Calling the Start function

When it's time to activate this group and get them spawning, call this function:

globalSpawnWave_Start( strGroupName )

Here are the parameters for this function:

• strGroupName (string)
  This is the unique name identifier you gave the group. In my example case, this would be 'spawnEngineeringGroup' (of course minus the quotes :). You HAVE TO HAVE a group name or the script will not work at all because it has to know which group you are referencing!!

That's it, the rest works on it's own. You do not have to worry about AI being on top of spawners and spawning ontop of each other, that is taken care of by the script and the func spawn.