Page tree
Skip to end of metadata
Go to start of metadata

Introduced in



Description:Controls a convoy of several land vehicles, led either by a player or an AI unit.


Syntax:[action, vehicles, waypoints, speed, spacing] call fn_vbs_convoy
  • action: String - Action applied to convoy. Can be
    • "INIT": Vehicles are grouped together, and start moving towards the waypoints.
    • "UPDATE": Allows updating the speed and distance of an active convoy.
    • "HALT": Temporarily stops the convoy.
    • "RESUME": Resumes convoy movement after a temporary stop.
    • "ABORT": Permanently stops an active convoy.
  • vehicles: Array of Object - Vehicles that belong to the convoy. The position of a vehicle within the convoy is defined by its position in this array, with the lead vehicle being the first one in the array.
  • waypoints: Array - List of waypoints that the convoy should pass.
    Only passed for "INIT" action (even if the convoy is lead by a player, where these waypoints are ignored, at least one waypoint must be passed).
    Can be either an array of markers or positions:
    • Use markers: ["MARKERS",["marker1", "marker2", ...]]
    • Use positions: ["WAYPOINTS", [[2000, 2000], [2500, 2500], ...]]
  • speed: Array - Maximum speed of the convoy leader (in km/h). Every following vehicle adjusts its speed to keep an appropriate distance (optional).
    Can be either an absolute speed, or a relative offset, based on the slowest vehicle in the convoy (its maxSpeed property).
    • Absolute speed: ["ABS", 50] (maximum speed is 50km/h)
    • Relative speed: ["CLIP", 10] (maximum speed is 10km, less than the top speed of the slowest vehicle).
  • spacing: Number - Minimum spacing between vehicles (in meters) (optional).
Return Value:Nothing


When using functions in VBS versions older than 3.4, certain limitations and requirements should be kept in mind - the main ones being that capitalization of the function name is crucial, and that #include "\vbs2\headers\function_library.hpp" has to be included in every script that utilizes it. More Category VBS Scripting Functions.


// Vehicles that will be part of the convoy (car1 is the leader):
_cars = [car1, tank1, car2, truck1]; 

// Convoy moves to the defined positions:
["INIT",_cars, ["WAYPOINTS", [[1000,1000], [1500,2000], [2000,2000]]] call fn_vbs_convoy;

// Convoy moves to markers "wp1", "wp2", "wp3":
["INIT",_cars, ["MARKERS",["wp1", "wp2", "wp3"]]] call fn_vbs_convoy;

// Convoy moves to the defined markers, at a maximum speed of 20km/h, and a minimum distance of 50m:
["INIT",_cars, ["MARKERS", ["wp1", "wp2", "wp3"]], ["ABS", 20], 50] call fn_vbs_convoy;

// Temporarily stop convoy:
["HALT",_cars] call fn_vbs_convoy; 

// Resume stopped convoy:
["RESUME",_cars] call fn_vbs_convoy;

// Cancels an active convoy:
["ABORT", _cars] call fn_vbs_convoy;

// Updates the speed and distance of an active convoy:
["UPDATE", _cars, 30, 100] call fn_vbs_convoy;

Additional Information

See also: setNewConvoy
Problems:The following issues currently (V3.4) exist:
  • Halting or aborting a player-led convoy has no effect - the AI vehicles continue to follow.
  • When an AI-led convoy is aborted, the convoy continues to the last waypoint.
  • The first waypoint for AI-led convoys is always skipped, and the convoy immediately heads for the second waypoint.
  • The speedmode qualifier "CLIP" is case-sensitive.