Squad AI - A How to

Company of Heroes/Essence Engine 1.0:
Squad-Ai Guide


Here's the example squad AI file that we'll be looking at. I'll try to explain each entry in detail. You can Use notepad++ to open it.

Download Link

This is overhauled SP plan made for a squad-ai update. This is what a controllable, but still advanced plan generally looks like.

Part 1; Moving Infantry: ACTION_MOVE_POSTURE

This is the line we will be dissecting:
ACTION_MOVE_POSTURE_EXT( DT_MAX_SQUAD_RANGE, 0.85, 5.0, 75.0, "", PACE_VERYFAST, PACE_FAST, POSTURE_CROUCH, POSTURE_CROUCH, 2.0, false, false, false ),
This is part of phase 1, a small jump to cover. This movement is applied to the flank elements (the elements that have the support weapons in SP). The core elements move with different settings.

So, lets start explaining this line, one by one.

1.DT line: What type of movement is used.
The (known) DT's are as follows;

DT_MIN_SQUAD_RANGE - the move point must be within the percentage range set to move/move to.

DT_MAX_SQUAD_RANGE - the inverse of min_squad_range. The move point must be outside of the range specified. If backwards/out of sight move is enabled, the squad will fall-back until out of the range set.

Note; Units using squad_range tend to stick together.

DT_MIN_ELEM_RANGE - mainly used for basic moves. This is different than min squad range in the sense that its based on the formation elements, rather than the relative position of the squad.
This means that, most of the time, units will be much more spread out and disorganized than squad range (min_squad_range).

DT_MIN_ELEM_RANGE_COVER - based on nearby cover objects, rather than the element/formation positions. This seems to be one of the most useful DTs for basic movement. Seems to more effectively prevent units from running around to the other side of cover than the normal elem range, when the search radius is below 5.

DT_AT_TARGET - self-explanatory. The squad will move towards the target until the desired distance is achieved, and then they will search for cover. This should only be used for abilities and specialized plans.

DT_AWAY_FROM_TARGET - mostly used for reaction plans. Your men will move away from the current target, searching for cover once they reach the specified range. For the reaction plan, the target changes to the nearest explosion that triggered it.

DT_LOS - Used in ACTION_MOVE_LOS. Its suggested to use that in most cases, unless you really need posture settings for a LOS move.

2. distance_percentage(0.85), or; how close should I get to that guy over there?
This is the percentage of the weapon range that the unit will move to. The way they go and how they go there depends on the DT used. If you are making a mod that changes vanilla ranges, you will have to tweak this. As a rule of thumb, the bigger the range, the more precise percentages should be used.

For this example plan, we are using max_squad_range with a percent of 0.85. Assuming vanilla range of 35, this means the cover search will start at a range of 30. This means that if the enemy is closer than that range, the squad will not move.

3. cover_search_radius(5.0)
This is the radius your men will search for cover at the target of the distance_percentage.
5 is generally a small cover-search radius. For all the movement types barring elem_range_cover, anything lower than this runs the risk of that running around to the other side of cover bug.
It is recommended to use even numbers. Here's a good table to go by;
0.0 - No search radius. Move to specified range with no cover search.
2.0 - Smallest search radius possible with elem_range_cover before bugs.
4.0 - Smallest search radius possible with most dt's before bugs.
5.0 - Small search radius within jumping distance.
8.0 - Medium search radius - most useful. 1-2 second run distance with pace_veryfast, depending on dt.
10.0 - Medium/large search radius. 1-3 second run with pace_veryfast, depending on dt.


4. cover_search_angle(75.0)
This is the angle, or size of the cone, that the squad will search for cover between themselves and the distance_percentage. This is a very similar system to the LOS cones of units. The standard angle for most movement is (90.0), a search angle that only encompasses the area (more or less) directly in front of the squad/entity. A angle of (180.0) encompasses the entire front and side areas. Increasing it past 180 enables backwards searching. It is recommended to keep the angle at rounded numbers. Here's a good table to go by;
30.0 - Direct front. Use 45.0 in most cases if possible.
45.0 - Front.
60.0 - Front with small left and right potential at longer range.
75.0 - Front with small left and right potential.
90.0 - Front with some left and right potential. Best angle for most movement.
120.0 - Front with full left and right potential at longer range.
150.0 - Front with full left and right potential.
180.0 or higher - complete cone (barring backwards). Recommended not to use, unless absolutely necessary.

5. formation_name("squad_formations/squad_ai.lua")
The formation the squad will attempt to create/stick to when moving. This can be useful for keeping units in shape when searching for cover. Say, if there's a large field full of light cover, instead of getting into the best cover considered by the DT, and possibly breaking formation, the squad will try to form the specified formation in the cover provided. In layman's terms: Imagine the squad staying in a loose wedge in a large field of craters, instead of all jumping into/balling up in single crater. Setting it to empty ("") disables the consideration of formation spots, so units will only consider cover and not formation spots.

6. paces - how fast should I run away?!

There are four paces to choose from. PACE_VERYFAST, PACE_FAST, PACE_MEDIUM, and PACE_SLOW. Medium and slow allows fire on the move.
The first line you specify, in this case VERYFAST, is the desired_pace. This is the pace they will try to use whenever they can.
The next line is minimum_pace. This is the minimum pace they can use in any situation. A pace will be randomly chosen between these two settings.

7. posture - standing in the open is for chums!

Similar to pace, this is the posture they will try to use when moving and shooting (unless something else forces something different, like suppression). There are 3 postures to choose from; STAND, CROUCH, and PRONE.
The first line is destination_posture, the desired posture to be used in most situations.
The second line is destination_min_posture, the minimum posture to be used in any situation. A posture will be randomly chosen between these two settings. Its best to keep this at prone, even if you don't want your men to prone. Cover objects that require a certain posture are not overridden. This means if the plan has both options set to PRONE, soldiers will still stand/crouch behind most walls and cover objects.

8. max_order_delay(2.0), or; how long should I wait to move?

This is the maximum amount of time a soldier will wait before moving. Setting this to a relatively high number (5 or so) will usually prevent squad members from all moving at once, making movement look more dynamic/natural. Remember, the phase will only complete once all movement/waiting is finished. This number is completely random, meaning there's a 50/50 chance the squad will all move at once anyway, or take up the entire time allotted.

9. Flags - no not those flags!

The 3 flags are as follows;
The first option is allow_backwards. If this is set to true, this allows the squad to search and move backwards(The angle must also be set above 180.0 for this to work).
The second option is allow_leave_los. If this is set to true, your men can run for cover that blocks their shot and/or sight from their current target (in FOW). This is a very finicky flag, and should always be set to false unless its a special plan.
The last option is always_move. This makes your men move no matter what, even if they are already in cover and/or in the right formation spot. This is useful for bounds and forcing the squad to spread-out, but should not be used for basic cover searches and/or at the start of any normal plan.


Part 2; Format follows function, or have I got that wrong?

Now, lets take a look at how to actually implement this into a phase. So, lets start at the top and go down.

1. Phase Info
type should always look like this (type = DATA_PHASE,)
name is the name of the phase the system refers to. Its best to keep this simple (not done in the example file, but try to keep the names short anyway), and add information about the phase in a dummy line. To make one just add (--) to a line, and the system will skip over it.

2. Elements
This is how you can control what troops move and when. As you can see, the line of movement in the example file we are looking at is applied to the flank elements. The core element has a more lax min_elem_range cover search, allowing that element to search for cover at almost any range. The possible formations to apply actions to are: {ET_Core, ET_RFlank, ET_LFlank, ET_Scout},

This is all linked to the formation you have made/set in the attributes, so make sure to fix those up first before moving onto this. ET_All can be used to apply the phase to all elements, and is most useful for setting new formations.

Remember to check your commas and spaces, as the system might bug out if they are not set correctly.

One thing to remember is timing. A phase is only completed if all actions are run/completed (units have reached their destination). Actions that cant run are skipped over.

Part 3; Extra, Extra! Get your Extra functions!

1. ACTION_WAIT_RANDOM( min_delay_seconds, max_delay_seconds )
The squad/the elements the phase is applied to will wait a random amount of time before moving onto the next action.

2. ACTION_WAIT_PRECISE( delay_seconds )
The squad/the elements the phase is applied to will wait the set time before moving onto the next action

3. ACTION_MOVE_LOS( max_order_delay )
Units will move to LOS (Line of Sight) if they don't have it. This should be put after large cover searches to make sure your units are firing at the enemy. max order delay is the same as it is in other moves, the delay before units actually move to LOS (note that this uses the default settings of a move (normal pace, standing posture, no cover search).

4. ACTION_DO_ABILITY( ability_name, max_casters )
Units will execute the specified ability (the search starts in the root abilities folder, so its best to put them there when using this). The ability should either be timed (executed on self) or targeted. Target is, unless otherwise set, current target for main weapon. Max_casters is the max amount of men executing the ability, so even if its applied to the whole squad, if max_casters is set to 1 only 1 person will execute it.

5. ACTION_DO_CRITICAL( critical_name, id_name )
The specified critical will be executed on the specified units. Relic mainly used this for attack_plan_modifiers.
ACTION_UNDO_CRITICAL( id_name ) - Undoes a specified critical
ACTION_UNDO_ALL_CRITICALS() - Undoes all criticals (Not known if it only affects ones added with the plan or all criticals)

6. ACTION_SET_POSTURE( posture_name, duration_seconds )
Set the posture to be used and for how long. Will not be used if behind cover objects that prevent specified posture.

7. And the biggest extra of them all...
PHASE_LEAP_FROG_ABILITY( phase_name, distance_type, distance_percentage_start, distance_percentage_end, cover_search_radius, cover_search_angle, formation_name, desired_pace, destination_posture, max_order_delay, ability_name, ability_casters, casters_per_element, num_leap_frogs )

This is a special phase/ability action that can simulate leapfrogging without having to use a bunch of individual phases. While they are doing this, you can execute a ability on them to do whatever you please during/after each bound. The only time relic used this was for the assault ability in COH1. This works differently than other actions, as this one is not put into a phase.

This is how it should roughly look:
-- phase10 -- leapfrogging (if troops have not found any cover by this point, just get them to move)

PHASE_LEAP_FROG_ABILITY( "Leap_Frog_Forced", DT_MAX_SQUAD_RANGE, 0.75, 0.25, 5.0, 90.0, nil, PACE_FAST, POSTURE_CROUCH, 1.0, "abilities\german\throw_assault_grenade_ability.lua", {ET_RFlank, ET_LFlank, ET_Core}, 1, 2 ),

----------------------------------------------------------

This will make the specified elements leapfrog two times each towards the enemy, searching in a small radius for nearby cover, and each time they complete a leap-frog they throw a grenade. Remember, this is its own phase, and it wont end until its complete or cancelled.

Part 4; Vehicle AI

This is mostly a leftover from COH1's beta/alpha days. COH was originally very similar to the Wargame series--units had much higher range and vehicles were also in squads. This is what's leftover for vehicles (there are some plans leftover in coh1's data).

ACTION_MOVE_VEHICLE_EXT( distance_from, distance_percentage, cover_search_radius, cover_search_angle, formation_name, max_order_delay, allow_backwards, allow_leave_los, always_move )

ACTION_MOVE_NO_RANGE_VEHICLE_EXT( cover_search_radius, cover_search_angle, formation_name, max_order_delay, allow_backwards, allow_leave_los, always_move )

I would recommend to ignore the cover_search_radius, as vehicles no longer use cover.

Here is what the original vehicle plan looked like (slightly modified, text changed, but mostly the same from the 2004-5 version).

Note: All the extra squad-ai bits work on vehicles, and most vehicle plans only use wait and LOS moves.

Part 5; Conclusion

Well, I hope you mates enjoyed the basic rundown of squad-ai. There is a good amount of funky stuff that you can do with it, especially with a good amount of cooperation between the ai file and the attrib files (a proper fatigue system and random grenades comes to mind). If you have any ideas or need any help, feel free to contact me.

Thanks a lot for the guide, I am busy in my mod doing a lot of things, but this info is really god and I am going to save it because I will use it in a near future.

Regards
Olhausen

Thanks a lot for the guide, I am busy in my mod doing a lot of things, but this info is really god and I am going to save it because I will use it in a near future.

Regards
Olhausen

Thanks mate, im glad this guide has helped somebody. What do you plan on using it for?

My idea in a future is to give a more realistic formations for squad columns. Your post has some interesting data.

10/14/2017 Updated guide with better example

11/14/2017 Updated guide with more DT info

11/27/2017 Figured out the purpose of always_move, changed info accordingly.

1/15/2018 Updated entries for MIN_ELEM_RANGE and MIN_ELEM_RANGE_COVER.

11/21/2018 Updated guide, polished the spelling and changed a few minor things.

6/10/2019. Overhauled the guide. Completely re-did the opening section, and added a better example.

Great Lugie. Thank you to keep the post up to date