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

Introduced in




Marks a unit as captive. If the unit is a vehicle, the commander is marked.

A captive is neutral to everyone, and does not trigger Detected By conditions for its original side. Enemies do not fire on a captive unit, but the captive unit itself still attacks (unless its behavior or combat mode have been adjusted with setBehaviour or setCombatMode, respectively).

Using a number instead of a Boolean has no further effect on the engine behavior, but can be used by scripting commands to keep track of the captivity status at a finer resolution (for example, when handcuffed, grouped, and so on).

In V1.50+, more captive numbers have become available:

  • 2 (Capture): A user-action is attached to the unit, that allows it to be "captured". Once that action is executed, the unit becomes part of the player group, and its side changes to that of the player.
  • 4 (Release): A user-action is attached to the unit, that allows it to be "released". Upon release, the unit leaves the player group, and assumes its original side. If the AI was part of a different group before the capture, they do not rejoin that group.
  • 8 (Cuff): A user-action is attached to the unit, that allows it to be handcuffed. Adults display an animation that shows their hands on their backs, children do not display any special animation.
  • 16 (Uncuff): A user-action is attached to the unit, that allows it to be uncuffed.

Combinations of these modes are possible, by adding the base numbers:

  • 3 - Set captive and capture actions available (mode 1 + 2).
  • 10 - Capture and cuff actions available (mode 2 + 8).
  • 12 - Release and cuff actions available (mode 4 + 8).
  • 18 - Capture and uncuff actions available (mode 2 + 16).
  • 20 - Release and uncuff actions available (mode 4 + 16).

Once an action is activated, the captive value may change automatically (after the capture action is executed, the captiveNum value for that unit changes to 4, to indicate that they can now be released).


Syntax:unit setCaptive captiveBool
  • unit: Object - Affected unit.
  • captiveBool: Boolean - If set to true, if you make a unit captive, that unit still fires at the enemy, but the enemy does not fire back.
Return Value:Nothing

Alternative Syntax

Syntax:unit setCaptive captiveNum (V1.19+)
  • unit: Object - Affected unit.
  • captiveNum: Number - When using a number parameter, any value that is bigger than 0 is considered to be the same as true.
Return Value:Nothing


Examples:_soldier1 setCaptive true_soldier1 setCaptive 2

Additional Information

See also: captiveNum, setBehaviour, setCombatMode

If using captive numbers on units that are not (yet) known to the player, it may be necessary in some versions of VBS to reveal the captive unit to the player, in order for the user actions to become visible right away (without the reveal it may take several minutes for them to show up).

In V1.70, the capture action does not work (handcuffing does), so units have to be join manually, in order to become part of the player group.