Warfare Patterns

* The person who created or recently edited this article is still making changes to this page.
* Unlike a stub, contributors intend to complete this article soon.
* This page is automatically sorted into the category Under Construction, until this box is removed.

TODO: create Explanation of Parameters (maybe in Script-Reference)

TODO: maybe move Example to Script-Reference

Warefare-Patterns are considered to be a State.

# WP\_SpawnWave

Spawns or respawns waves of Squads as defined in \_spawngroups.lua

## Prerequisites

**`_spawngroups.lua`**
containing the `SpawnWaveTemplate` and `SpawnWaveEmitter`

this script deals with defining the squads in the waves, and spawning the waves

HOWEVER, the conditions for spawning are found in the `sp_*wave.lua` scripts themselves

**`sp_*wave.lua`**
containing the `WP_SpawnWave` command. This filename must be equal to the `GroupName` defined in `SpawnWaveEmitter`

*sp\_ in the name of the script seems optional, it might only serve to differentiate these types of scripts from the rest*

Each wave runs this script.

Enemies are being spawned until the wave is complete.

Then the script (for that wave) switches it's state to the `FinishState` (in our case: `WaitForDeath`).

When finished spawning, it waits in that state until all Squads (of that wave) are dead (again - that mechanism runs in parallel for every wave) and switches back to the `SpawnSate`

## Example

`_spawngroups.lua`

```
-- this defines the squads that will get spawned in the wave
-- copy this template to create different spawn waves
SpawnWaveTemplate {
    Name = "human\_group",

    [DifficultyEasy] = {
        [684] = 2, --wardens
        [955] = 0, --priest
    },

    -- number of squads in this difficulty gets ADDED to the previous difficulty
    -- -> so 3 wardens will spawn on Advanced diff
    [DifficultyNormal] = {
        [684] = 1, --wardens
        [955] = 0, --priest
    },

    -- number of squads in this difficulty gets ADDED to the previous difficulties
    -- you can also use negative values.
    -- -> so 2 wardens and 1 priest will spawn on Expert diff
    [DifficultyHard] = {
        [684] = -1, --wardens
        [955] = 1, --priest
    },
};

SpawnWaveTemplate {
    Name = "bug\_group",

    [DifficultyEasy] = {
        [706] = 1, --bugs
    },
    [DifficultyNormal] = {
        [706] = 1, --bugs
    },
    [DifficultyHard] = {
        [706] = 1, --bugs
    },
};

-- this will spawn the waves defined below with set time delay
-- copy SpawnWaveEmitter for different WP\_SpawnWave scripts
SpawnWaveEmitter
{
    -- name of the WP\_SpawnWave script you have created (in our case: sp\_examplewave.lua)
    GroupName = "sp\_examplewave",

    -- time when EACH of the Waves bellow will respawn when all it's squads die
    RespawnDelaySeconds = 10,
    RespawnDelayMinutes = 0,

    -- time between individual squads spawning
    -- 0 means the whole wave should spawn instantly
    -- 5 means there is 5sec delay between each squad spawning
    -- InitialSpawnDelay has to be >0 for this parameter to work
    -- (on the first spawn of a wave)
    SpawnInterval = 5,

    -- Wave Setup
    Waves =
    {
        {   -- wave 1 parameters
            -- SpawnWaveTemplate.Name (from above) to spawn
            SpawnWaveTemplate = "human\_group",

            -- Before the wave spawns, wait time..
            InitialSpawnDelaySeconds = 1,
            InitialSpawnDelayMinutes = 0,
        },
        {   -- wave 2 parameters
            SpawnWaveTemplate = "bug\_group",
            InitialSpawnDelaySeconds = 20,
            InitialSpawnDelayMinutes = 0,
        },
    },
}

```

`sp_examplewave.lua`

```
WP\_SpawnWave
{
    -- Warfare Patterns are considered to be a state. this is the name of that state
    StateName = "SpawnState",

    -- Where this Wave will spawn. If this is not a SpawnBuilding, you can set the Parameter: SpawnBuilding
    TargetTag = "enemy\_spawn",

    -- The tag of the SpawnBuilding.
    -- If TargetTag is the SpawnBuilding you don't need this parameter.
    -- But SpawnBuilding is necessary if you spawn to a TargetTag near the SpawnBuilding
    -- but still want the SpawnBuilding to control the spawning
    -- (eg. only spawn if it's alive, don't spawn while building is under attack).
    SpawnBuilding = "enemy\_spawnbuilding",

    -- Direction in degrees (0-360°). 0 means 'south' (down), 90 means 'east' (right), etc.
    Direction = 60,

    -- To which Team the spawned units are assigned to
    Team = "tm\_Enemy1",

    -- To which Player the spawned units are assigned to
    Player = "pl\_Enemy1",

    -- Use this parameter to let the individual spawned squads go to a location right after spawning.
    -- Intended to avoid that the spawn location is blocked by squads and new squads spawn on the outer "ring" of existing squads.
    -- Basically it just looks better when squads move a couple meters after spawn.
    -- don't use with long walkways, it has a limited range -> so more of a meeting place nearby to not block the spawnpoint
    AfterSpawnGotoTargetTag = "A",

    -- Can be used to spawn different SpawnWaveTemplate squads for each WP\_SpawnWave.
    -- Overrides the default Template from the SpawnWaveEmitter.
    -- Makes it possible to, for example, switch the same wave
    -- from spawning infantry to cavalry by using two WP\_SpawnWave with appropriate SpawnWaveTemplates.
    --SpawnWaveTemplate = , --this should override the SpawnWaveTemplate set in \_spawngroups -> UNTESTED

    -- The delay for the very first spawn of the wave.
    -- If 0 wave will begin spawning from the start of the map,
    -- otherwise the first Spawn is delayed appropriately and independently from the regular RespawnDelay
	--InitialSpawnDelaySeconds = , --probably best to use the one in \_spawngroups
	--InitialSpawnDelayMinutes = , --probably best to use the one in \_spawngroups

    -- These conditions must be satisfied to Start the Event/Pattern.
    -- Check here if the Spawn Building is still alive, or similar (re)spawn Conditions. Default: AND
    -- spawn delay is set in \_spawngroups
    -- Careful, your StartConditions will not be checked while eg. the RespawnDelay is running!
    -- That could result in Squads being spawned even if your SpawnConditions are no longer true.
    -- See: ExitConditions
    StartConditions =
    {
        -- BuildingIsAlive{ For = "ALL", Tag = \*TargetTag\* } <-- is automatically added!
        MapFlagIsTrue {Name = "mf\_test"},
    },

    -- these actions will get called once the conditions above are met
    StartActions =
    {
        -- the actions will get called once for every SpawnWaveTemplate instance in \_spawngroups
		-- so if you have 2 waves coming with different delays in \_spawngroups, these actions will get called 2 times
        -- it runs everytime, the StartConditions are checked, so basically everytime the script prepares for spawning a wave
    },

    -- FinishActions will be executed if WP can 'complete' its task and has completed it.
    -- Once all Units (of that wave) are spawned, these Actions are executed.
    -- Eg. you can send your units somewhere with SquadGridGoto
    -- After that, the script will switch to "FinishState"
    FinishActions =
    {
        SquadGridGoto {Tag = default, TargetTag = "player\_monument", Direction = default, IgnoreGridIfAllSquadsFly = default},
    },

    -- Conditions after which the script will go to the ExitState
    --
    -- They are necessary, if you already entered the WP\_SpawnWave-State (StartConditions are true)
    -- and the (Re)spawn-Timer already started.
    -- Exit is only evaluated while waiting for units to be spawned.
    --
    -- They are the only way to check if Spawning Conditions are still true,
    -- right before actually spawning the Squads.
    --
    -- In the background, an ExitCondition for BuildingIsDestroyed will be added!
    -- Keep that in mind, when programming your ExitConditions,
    -- since everything added here AND BuildingIsDestroyed will need to be true (AND!!)
    ExitConditions =
    {
        -- BuildingIsDestroyed{ For = "ALL", Tag = \*TargetTag\* } <-- is automatically added!
    },

    -- actions that are called before the script goes to ExitState
    ExitActions =
    {
    },

    -- Cannot be "self", switches to a state where the script either waits for the wave to die,
    -- or to send the units somewhere else, based on other conditions
    FinishState = "WaitForDeath",

    -- will go to this state after ExitActions are called
    ExitState = "WaitForDeath",

    -- have not found a way to enter this state.
    -- "Change to this State on death. Only use to link with a respawn pattern!"
    DeathState = "self",

    -- Allows ExitConditions to exit WP before it has even started.
    AllowExitBeforeStart = false,
};
State
{
    StateName = "WaitForDeath",

    OnEvent
    {
        EventName = "They wuz all killed!",
        Conditions =
        {
            SquadIsDead {},
        },
        Actions =
        {
        }, GotoState = "SpawnState",
    };
};

```

# WP\_AttackAndPatrolArea

Basically a fancy version of the Action: `SquadPatrol()`.
Seems to be used in conjunction with `WP_Respawn` or `WP_SpawnWave`. But it can be used standalone aswell - your units will not respawn of course.

This works differently than `WP_SpawnWave`.

This Pattern takes units that already exist on the map and works with them.

Sends the ScriptGroup of squads to the `TargetTag` location.
They then wait at the TargetTag for 3 seconds and continue moving between the first and the last point defined in `PatrolPoints`.

It also considers the Goto-Grid.

It works internally with the Action: `SquadPatrol`

`TargetTag` should be a single script tag.
If you want to (initially) send the Group along a path towards the `TargetTag`, rather than the `TargetTag` directly, simply use a `SquadGoto` command in the `StartActions` with the path as TargetTags of the Goto command.

**Be careful** with the placement of your squads. They either need to be completely within 16m of the TargetTag, or be completely outside of the 16m radius of the `TargetTag`. If they are partially inside the 16m radius (one squad is, another not), they will not move initially.

## Prerequisites

**`_scriptgroups.lua`**
In here, you will define what Patrol Points the Squads will go to (`sg_PatrolPoints`) and what Squads will move along those points (`sg_patrol`)

**`sg_*.lua`**
This is the file, where the `WP_AttackAndPatrolArea` function will live.

## Example

`_scriptgroups.lua`

```
return {
    -- Points where the Patrol will move between
    -- (it seems, Squads only go between Goto1 and Goto3, also considering the Goto-Grid)
    sg\_PatrolPoints = {"Goto1", "Goto2", "Goto3" },

    -- Group of Squads to be patrolling
    -- (must be equal to the filename containing the WP\_AttackAndPatrolArea)
    sg\_Patrol = {"patrol1","patrol2","patrol3"},
}

```

`sg_patrol.lua`

```
WP\_AttackAndPatrolArea
{
    -- initial location for the Squads
    TargetTag = "GotoTarget",

    -- Squads will move between the first and last patrolpoint.
    PatrolPoints = "sg\_PatrolPoints",

    -- I have no idea what that parameter does.
    NumPatrolSquads = 2,

    -- Warfare Patterns are considered to be a state. this is the name of that state
    StateName = "NormalPatrol",

    -- These conditions must be satisfied to Start the Event/Pattern. Default: AND
    StartConditions =
    {
        MapTimerIsElapsed {Name="mt\_berger", Minutes = default, Seconds = 10}
    },

    -- these actions will get called once the conditions above are met
    StartActions = {},

    -- to be documented
    FinishActions = {},
    ExitConditions = {},
    ExitActions = {},
    FinishState = "NormalPatrol",
    ExitState = "NormalPatrol",
    -- /to be documented

    -- This is the usual way to exit this pattern, once the units are dead, switch to another state.
    -- in this case, we switch to the Respawn-State
    DeathState = "RespawnPatternNormal",

    -- Allows ExitConditions to exit WP before it has even started.
    AllowExitBeforeStart = false,
}

-- WP\_Respawn below here (if you want your units to respawn)

```

# WP\_Respawn

Respawns the SquadGroup (all at once) after a specified delay. (If all are dead)

This works differently than `WP_SpawnWave`.

This Pattern takes units that already exist on the map and works with them.

You want the units to be dead when entering this state. Otherwise they will respawn instantly without considering the RespawnDelay.

## Prerequisites

**`_scriptgroups.lua`**
In here, you will define what what Squads will be respawned (`sg_patrol`)

**`sg_*.lua`**
This is the file, where the `WP_Respawn` function will live.

## Example

`_scriptgroups.lua`

```
return {
    -- optional, if you don't want your squads to patrol
    sg\_PatrolPoints = {"Goto1", "Goto2", "Goto3" },

    -- Group of Squads to be respawned
    -- (must be equal to the filename containing the WP\_Respawn)
    sg\_Patrol = {"patrol1","patrol2","patrol3"},
}

```

`sg_patrol.lua`

```
-- This WaitForDeath-State is only necessary, if you don't want to use WP\_AttackAndPatrolArea
State
{
	StateName = "WaitForDeath",

	OnEvent
	{
		EventName = "They wuz all killed!",
		Conditions =
		{
			SquadIsDead	{},
		},
		Actions =
		{
		}, GotoState = "RespawnPatternNormal",
	};
};

-- Keep this after the WaitForDeath/WP\_AttackAndPatrolArea-State
WP\_Respawn
{
    -- Where the Squads will respawn
    TargetTag = "enemy\_spawn2",

    -- How long it takes until they will respawn
    RespawnDelayMinutes = 0,
    RespawnDelaySeconds = 30,

    -- Warfare Patterns are considered to be a state. this is the name of that state
    StateName = "RespawnPatternNormal",

    -- These conditions must be satisfied to Start the Event/Pattern. Default: AND
    StartConditions =
    {
        BuildingIsAlive {For = "any", Tag = "enemy\_spawn2"},
    },

    -- these actions will get called once the conditions above are met
    StartActions = {},

    -- to be documented
    FinishActions = {},
    ExitConditions = {},
    ExitActions = {},
    -- /to be documented

    -- This is the usual way to exit this pattern.
    -- Once everything is respawned, we go to State WaitForDeath.
    -- If you are using WP\_AttackAndPatrolArea instead of the WaitForDeath-State,
    -- enter the StateName of that: eg. "NormalPatrol"
    FinishState = "WaitForDeath",

    -- to be documented
    ExitState = "RespawnPatternNormal",
    DeathState = "self",
    -- /to be documented

    -- Allows ExitConditions to exit WP before it has even started.
    AllowExitBeforeStart = false,
}

```