Simple Convoy Script [RELEASE]

[Tova 122]

 

Hello Arma truckers !

 

It is now of common knowledge that Arma AI barely got its driving license !
While the driving is "decent enough" for single vehicles, once they hear the word "convoy", they get petrified and/or start ramming each other...

 

While there are great convoy scripts out there (respects to@norrinand@Devastator_cm), I wanted a script who uses the new features of Arma 3 engine and follows the novacula Occami principle : Simpler is safer.

 

So here's to you the Simple Convoy Script !

 

And it's robust !
So robust my AI convoy drove for 2.5 hours on Altis without getting stuck ! They crossed bridges, towns and villages, drove on dirt roads, small roads and highways.
The recording is from the player perspective as a gunner on the tail vehicle.

Convoy was composed of 8 vehicles, a mix of trucks and Humvees, in AWARE behaviour and was setup using MOVE waypoints and the Simple Convoy Script with default parameters (50km/h, 50m spacing).

 

 

And here's an even longer demo with v. 1.2 of the script !

8 hours of AI convoy driving on South Asia, the convoy is 7 vehicles long, with parameters 100km/h and 50m spacing.

Spoiler

 

 

Features :

• Convoys will not get stuck for no reason !
• Robust script
• Easy to use : put your waypoints in the editor, and run the script only giving the convoy's group name as parameter
• Player friendly : you can be driver/gunner/commander/passenger in any vehicle of the convoy without breaking the script
• AI will push through contact (feature can be turned off)
• Adjustable convoy speed
• Adjustable convoy spacing
• Performance and environment friendly 🙂

 

 

How to use :

Here's a video example :

Spoiler

 

 

Put the script code in an sqf file, trigger, init field or whatever you fancy, then call it with :

convoyScript = [convoyGroup] spawn TOV_fnc_SimpleConvoy;

Optional parameters are also available :

convoyScript = [convoyGroup, convoySpeed, convoySeparation, pushThrough] spawn TOV_fnc_SimpleConvoy;

With :

• convoyGroup : the group you want to move as a convoy
• convoySpeed : Maximum speed of the convoy in km/h (default 50 km/h)
• convoySeparation : distance between each vehicle of the convoy (default 50m)
• pushThrough : true/false, force the AI to push through contact, only returning fire on the move (default true)

 

The script doesn't exit himself, so once you reach your final waypoint, you'll have to end it with :

terminate convoyScript;
{(vehicle _x) limitSpeed 5000;(vehicle _x) setUnloadInCombat [true, false]} forEach (units convoyGroup);
convoyGroup enableAttack true;

 

The script :

 

Spoiler

TOV_fnc_SimpleConvoy = { 
	params ["_convoyGroup",["_convoySpeed",50],["_convoySeparation",50],["_pushThrough", true]];
	if (_pushThrough) then {
		_convoyGroup enableAttack !(_pushThrough);
		{(vehicle _x) setUnloadInCombat [false, false];} forEach (units _convoyGroup);
	};
	_convoyGroup setFormation "COLUMN";
	{
    	(vehicle _x) limitSpeed _convoySpeed*1.15;
        (vehicle _x) setConvoySeparation _convoySeparation;
    } forEach (units _convoyGroup);
	(vehicle leader _convoyGroup) limitSpeed _convoySpeed;
	while {sleep 5; !isNull _convoyGroup} do {
		{
			if ((speed vehicle _x < 5) && (_pushThrough || (behaviour _x != "COMBAT"))) then {
				(vehicle _x) doFollow (leader _convoyGroup);
			};	
		} forEach (units _convoyGroup)-(crew (vehicle (leader _convoyGroup)))-allPlayers;
        {(vehicle _x) setConvoySeparation _convoySeparation;} forEach (units _convoyGroup);
	}; 
};

 

 

 

Download links :

Mission example : Armaholic

 

Known limitations :

• Having mixed vehicles in the convoy will cause the fastest vehicles to have a not so smooth driving, as they'll accelerate faster than the other vehicles then brake once they reach target speed. ==> Fixed by v. 1.2
• Due to how setConvoySeparation works, the convoy will stop on tight turns, vehicles crossing one at a time. Rear vehicles will then often cut the corner to catch up faster if possible (doFollow behavior).
• Behavior of the convoy when "pushThrough" parameter is disabled isn't very satisfying : passengers in cargo slots will disembark (but keep formation) to engage, armed vehicles will leave convoy formation to engage, some unarmed vehicles will just stop while others will keep pushing on etc.
  The convoy will eventually recover after the contact is destroyed and the leader calls "Area Clear" (as in they will mount up again and resume convoy route). That however might take up to 20 minutes, as the convoy and dismounts are usually spread over a couple km after the fight.

 

Credits :

The Arma community.
With special thanks to all those who answer scripting questions on the forums.

 

Changelog :

 

Spoiler

v. 1.23

• Handling case where group is delete (thanks to @pierremgi).

 

v. 1.22

• Makes more sense to refresh convoy separation after unsticking units, and not before.
   

v. 1.21

• Even smoother driving with setConvoySeparation inside the main loop, but applied to all convoy vehicles.
• Replace player reference by allPlayers for MP compatibility.

 

v. 1.2

• Fixed the start-and-stop unsatisfying behaviour by moving setConvoySeparation outside the main loop.

 

v. 1.11

• Lowered the cooldown between each "isStuck" check from 10 to 5 seconds.

 

v. 1.1

• Added option to force the AI to push through contact (enabled by default)

 

v. 1.0

• Initial version

 

License :

Share it, edit it, steal it, rip it, call it your own etc.
Arma scripting and modding is about sharing !
If you're having fun, then I'm happy !

 

[Tankbuster 1733]

This looks good. How is the order of vehicles decided?

[wogz187 1085]

@Tova

Can we call a script "eloquent"? I'm just gonna do it anyway,

The script is very eloquent.

[Tova 122]

5 hours ago, Tankbuster said:

This looks good. How is the order of vehicles decided?

@TankbusterVehicle order is the "grouped order" when you placed the vehicles in the editor 🙂
Basically, first placed vehicle will be group leader and is in front vehicle, second placed vehicle is second vehicle and so on...

 

@wogz187 Thank you very much !

I tried to keep it as simple as possible, so it's easy to understand and so there are less things that can go wrong

 

[Maff 246]

Gangsta!

 

Can I use this on my Altis Life server, @Tova?

 

[Devastator_cm 434]

Nice one. Did you also implement reaction to enemy forces?

[Tova 122]

8 hours ago, Maff said:

Gangsta!

 

Can I use this on my Altis Life server, @Tova?

 

@Maff Only if it's one of those heavily monetized servers and I'm getting a 130% share of the profits !

 

7 hours ago, Devastator_cm said:

Nice one. Did you also implement reaction to enemy forces?

@Devastator_cm I didn't implement it per se, but they have the vanilla Arma reaction to contact (the script don't affect their "Combat Behaviour").
I didn't test it extensively but they seem to push on while shooting if there's no vehicle with units in cargo seats, otherwise, passengers dismount and engage.
If a vehicle gets wrecked/badly damaged the group leader will order its passengers to get in other vehicles of the convoy when possible.

EDIT :
@Devastator_cm
After further testing I found the behavior inconsistent, armed vehicles will sometimes stop to engage, or move closer to targets.

I added a parameter to force the convoy to push through ambushes (enabled by default) to make behavior more predictable.

[Tankbuster 1733]

2 hours ago, Tova said:

@TankbusterVehicle order is the "grouped order" when you placed the vehicles in the editor 🙂
Basically, first placed vehicle will be group leader and is in front vehicle, second placed vehicle is second vehicle and so on...

@

Ok thanks. My vehicles are spawned in script not editor, but I can make this work.

[Tova 122]

1 hour ago, Tankbuster said:

Ok thanks. My vehicles are spawned in script not editor, but I can make this work. 

Oh my bad @Tankbuster

To explain my statement better, the vehicle order is defined by "the hierarchy" of the group, as in group leader is 1st vehicle and so on.

I don't know how you're spawning the vehicles of your convoy, but if it's a combination of createVehicle and joinSilent in this fashion :

_convoyGroup=createGroup [west,true];
for "_i" from 0 to 9 do
{
	_newVeh="B_MRAP_01_F" createVehicle getMarkerPos "vehSpawner";
	createVehicleCrew _newVeh;
	[_newVeh] joinSilent _convoyGroup;
	sleep 0.5;
};
convoyScript = [_convoyGroup] spawn TOV_fnc_SimpleConvoy;

the convoy order will be :

<- 1st spawned/joined vehicle <- 2nd spawned/joined vehicle <- 3rd spawned/joined vehicle ... 

 

Note that if you want a different order from the "join order", you should use joinAsSilent, as it allows you to specify the "position id in the group". 🙂

 

[johnnyboy 3741]

Excellent work Tova!  And your How To video was perfect also.  Very clever use of Editor comments to help explain usage.  I'm curious to see them push through enemy contact though.  I'll have to try it!

On 11/20/2019 at 9:39 PM, Tova said:

Behavior of the convoy when "pushThrough" parameter is disabled isn't very satisfying : passengers in cargo slots will disembark (but keep formation) to engage, armed vehicles will leave convoy formation to engage, some unarmed vehicles will just stop while others will keep pushing on etc.
The convoy will eventually recover after the contact is destroyed and the leader calls "Area Clear" (as in they will mount up again and resume convoy route). That however might take up to 20 minutes, as the convoy and dismounts are usually spread over a couple km after the fight.

I wonder if this can be improved by terminating the script when convoy attacked and pushThrough is false.  Then wait X minutes (say 5) or wait until some condition (maybe count near enemies < 4).  Then start script again with "pushThrough" true, and convoy would then start moving again  (rather than waiting 20 minutes for AI to sense "Area Clear".

 

Also would convoy move smoother by reducing speed parameters in towns and increasing speed on open roads?  Or does the normal AI already do that well enough?

 

Finally, anyone who uses this script should be required to watch the 2.5 hour test in its entirety. 😎

[Tova 122]

Thanks you very much @johnnyboy!

 

2 hours ago, johnnyboy said:

 I'm curious to see them push through enemy contact though.  I'll have to try it!

Say no more ! Here are some showcases !
A convoy is trying to traverse a town, with insurgents shooting from roofs/windows.

 

Spoiler

Convoy pushing through ambush w/o casualties :

 

 

Convoy pushing through ambush w casualties :

 

 

Convoy pushing through w casualties & convoy stranded (or as we say, everything goes FUBAR)

 

 

So to explain what happens in the videos :

• First video : No one dies, nothing blocks the street. Perfect scenario and the script works flawlessly.
• Second video : Here the two truck drivers get killed, luckily their vehicles end up not blocking the street. You can then see the AI HMMVW overtaking them and resuming the convoy
• Third video : It illustrates a limitation of the script and AI driving. Here again, the two truck drivers get killed, but this time, their trucks are blocking the street.
  Because of Arma 3 AI path-finding limitations, the HMMVW can't calculate a path to continue past them, and gets stuck.
  Maybe he would have moved eventually, but I didn't run the experiment long enough.

Also as a side note, I have noticed that if it is the lead vehicle that gets killed, the convoy always stalls (stops moving toward the waypoint, with n°2 vehicle not taking lead vehicle's role), maybe you have an idea for a fix ?

 

 

2 hours ago, johnnyboy said:

Also would convoy move smoother by reducing speed parameters in towns and increasing speed on open roads?  Or does the normal AI already do that well enough?

I haven't really tried implementing your suggestion, but I feel normal AI behaviour does that good enough already 🙂

However I noticed a "bug" in limitSpeed behaviour, as only the group leader ends up respecting this limitation, any insight on the matter ?

 

 

2 hours ago, johnnyboy said:

I wonder if this can be improved by terminating the script when convoy attacked and pushThrough is false.  Then wait X minutes (say 5) or wait until some condition (maybe count near enemies < 4).  Then start script again with "pushThrough" true, and convoy would then start moving again  (rather than waiting 20 minutes for AI to sense "Area Clear".

I did some testing with the idea, so here are some on the WIP conclusion :

• Basically the working principle of my script isn't to "enforce a convoy behaviour" but rather to "recover" vanilla COLUMN formation when it detects a vehicle is stuck.

  if ((speed vehicle _x < 5) && (_pushThrough || (behaviour _x != "COMBAT"))) then {
  				(vehicle _x) doFollow (leader _convoyGroup); 
  				//doFollow command name is misleading, but what it basically does, is order a unit to return to formation, hence unsticking it
  			};	

  Also once it detects the group is in COMBAT, and if pushThrough is false that "recovery command" isn't run, in practice making the script inactive.
  Terminating the script properly doesn't changes behaviour in combat.
   
• Using a nearTargets to detect end of engagements faster, and restart the script isn't enough, as the units will not mount back in vehicles.
  I should add an orderGetIn to make them mount back and crack on.

Your idea has potential !

[johnnyboy 3741]

3 hours ago, Tova said:

Say no more ! Here are some showcases !

Thanks for the showcases.  Its great that they push through unless blocked.  Not much you can do about AI pathing.

 

3 hours ago, Tova said:

Also as a side note, I have noticed that if it is the lead vehicle that gets killed, the convoy always stalls (stops moving toward the waypoint, with n°2 vehicle not taking lead vehicle's role), maybe you have an idea for a fix ?

Maybe if your script detects lead vehicle killed, you could terminate script and start fresh with next vehicle as lead vehicle.

 

3 hours ago, Tova said:

I haven't really tried implementing your suggestion, but I feel normal AI behaviour does that good enough already 🙂

Sounds good enough to me also.

3 hours ago, Tova said:

However I noticed a "bug" in limitSpeed behaviour, as only the group leader ends up respecting this limitation, any insight on the matter ?

No insights here.  But they seem to move well enough as is.

3 hours ago, Tova said:

• Also once it detects the group is in COMBAT, and if pushThrough is false that "recovery command" isn't run, in practice making the script inactive.
  Terminating the script properly doesn't changes behaviour in combat.
   
• Using a nearTargets to detect end of engagements faster, and restart the script isn't enough, as the units will not mount back in vehicles.
  I should add an orderGetIn to make them mount back and crack on.

Your idea has potential !

I see your points.  Maybe orderGetIn is worth trying.  Depends how much work you want to put into this, and what the potential benefit is. 

 

I'm guessing the two main usages for this script are: 

 

1) player team attacks convoy,

2) player team defends/escorts convoy. 

 

For 1) Player Attack Convoy, if the convoy wins by killing attackers, then player objective or mission fails, and it doesn't really matter if any convoy vehicles get stuck. 

For 2) Player Defend/Escort Convoy, if lead vehicles are disabled and blocking convoy, then it could be up to the player to clear those vehicles by pushing them with a remaining vehicle, or taking command of convoy, and ordering them to move to other positions to go around.  It would be up to the mission maker to allow player to handle a blocked convoy situation.

 

For those 2 scenarios, the script is probably good enough.

 

Another option is to fudge the outcome, and disable blocked vehicles by setting engine damage to 1.  Player would hopefully be unaware this "cheat" occurred, and mission has  a natural looking outcome (ai abandons damaged vehicles).  This might be a good option for Player Attacks Convoy mission. 

 

Regardless, this is very useful and cool, and I hope to make a convoy mission someday using this!

[accuracythruvolume 547]

So far working good on dedicated server    Thanks much for the script 

[Towndawg 0]

Hi Tova - I'm building a recon mission for my unit which involves a large AO that basically has to move on its own. a part of this is a resupply convoy that drives through 5 of the 6 main defensive points on Pulua. However I have tried to imitate your how to video and don't believe it's working. The rear vic continues to speed up and suddenly stop and doesn't resume driving instead turns his engine off. any ideas? Am i just not doing something right? Help would be awesome - Thanks!

[iZiiuksiCloud 0]

Hi , can i know how did you know your group name in video "group this, 70, 20" im new player here . 

[shi4stone 1]

Convoy works really well, but once one units get destoryed i am getting this spam 

} forEach (units _convoyGroup)-(crew (vehicle (leader _co>

13:45:02 Error position: <_convoyGroup)-(crew (vehicle (leader _co>

13:45:02 Error Undefined variable in expression: _convoygroup

13:45:02 Error in expression <nvoyGroup);

 

Tried to terminiate the script in debug console, but does not seem to work, or maybe i am not putting the right thing there. 

[pierremgi 4738]

You probably delete groups when empty... somewhere.

 

Instead of:  while {sleep 5;true} do {...   just write:  while {sleep 5; !isNull _convoyGroup} do {....

 

 

[Lil Fluff 1]

Awesome script but doesns't wanna work for me :(

[pierremgi 4738]

4 hours ago, Lil Fluff said:

Awesome script but doesns't wanna work for me 😞

Welcome on forum.

Is it just a remark? If you need help, you should explain how do you script. What test did you do?

[Lil Fluff 1]

I followed the tutorial perfectly but the vehicles i used in the convoy just started driving everywhere but to where they were supposed to go to.

[Lil Fluff 1]

I have fixed it a little bit but vehicles now go offroad sometimes.

[pierremgi 4738]

The best way for having help on forum is to clearly explain your issue in which context:

>> which map, which mod(s), which tested code (usually people think they apply a code but make mistakes),

and, cherry on the cake, video or uploaded short mission. Not mandatory if you can bring your codes up.

 

Without any clue of what you're doing, potential issues are: formation omitted, convoy falling into combat or destroyed/damaged vehicle, no path found.

 

[Lil Fluff 1]

1 minute ago, pierremgi said:

The best way for having help on forum is to clearly explain your issue in which context:

>> which map, which mod(s), which tested code (usually people think they apply a code but make mistakes),

and, cherry on the cake, video or uploaded short mission. Not mandatory if you can bring your codes up.

 

Without any clue of what you're doing, potential issues are: formation omitted, convoy falling into combat or destroyed/damaged vehicle, no path found.

 

The mape is Altis, the mod being used is RHS USA and the code used is the same as in the tutorial video. Hope that helps.

[pierremgi 4738]

How could I guess if your code is OK, with your vehicles?

 

My rule of thumb for convoy:

- keep it simple: don't stack plenty of commands by vehicles.

- group them and choose the column formation. At the end, you'll have to verify the good order in preview. Sometimes it's surprising: some vehicles give way to another one then "shuffle" order... So, group them one by one from 2nd to last, on leader. This is also possible in scripted way, as you join the group one vehicle by one but mind for the relative positions!

- For the group, set safe mode, don't mess with other parameters, but driver (each vehicles) disableAI "autocombat"; (gunners can fire)

- limit the speed of the leader: if (isServer) then {yourLeaderVehicleHere limitSpeed 50}; // and leader only!

- adjust the distance between vehicle: if (isServer) then {theSecondVehicleHere setConvoySeparation 20};  // same distance for each following vehicle.

- waypoints "move" as usual. not too many! Don't multiplicate path calculation. Intermediate wpts are useless most of the time.

[Lil Fluff 1]

31 minutes ago, pierremgi said:

How could I guess if your code is OK, with your vehicles?

 

My rule of thumb for convoy:

- keep it simple: don't stack plenty of commands by vehicles.

- group them and choose the column formation. At the end, you'll have to verify the good order in preview. Sometimes it's surprising: some vehicles give way to another one then "shuffle" order... So, group them one by one from 2nd to last, on leader. This is also possible in scripted way, as you join the group one vehicle by one but mind for the relative positions!

- For the group, set safe mode, don't mess with other parameters, but driver (each vehicles) disableAI "autocombat"; (gunners can fire)

- limit the speed of the leader: if (isServer) then {yourLeaderVehicleHere limitSpeed 50}; // and leader only!

- adjust the distance between vehicle: if (isServer) then {theSecondVehicleHere setConvoySeparation 20};  // same distance for each following vehicle.

- waypoints "move" as usual. not too many! Don't multiplicate path calculation. Intermediate wpts are useless most of the time.

Appriciate it