Conditions

An extensive list of all DLSv2 conditions available.

All conditions have the following four optional attributes available, each defined in milliseconds:

• delay_time: Delays returning true until the condition has been true for at least this many ms. For example, if you added delay_time="1000" to a speed condition, it would not return true until the vehicle was at the specified speed for at least one second.

• max_on_time: Maximum amount of time the condition will return true for (regardless of the actual value of the underlying condition). This resets after the underlying condition returns false again. For example, if you added max_on_time="500" to a braking condition, it would only return true for the first half second that the vehicle was braking. If the vehicle stopped braking (after any amount of time) and started braking again, the timer would reset and it would return true for another 500ms.

• min_on_time: Minimum amount of time the condition will return true for (regardless of the underlying condition). When a condition first becomes true, it will remain true for at least the amount of time specified, even if the underlying value is no longer true. For example, if you added min_on_time="2000" to a braking condition, the condition would return true for at least 2 seconds after the vehicle starts braking, or longer if it continues braking for more than 2 seconds.

• stay_on_time: Specified amount of time for the condition to continue returning true after the underlying condition has changed to false. For example, if you added stay_on_time="1500" to a door open condition, it would return true until 1.5 seconds after the door was closed again.

These attributes can be used together to achieve advanced control of the timing and duration of various functionality, and can be added to any of the conditions listed below.

Grouping Conditions

These special conditions can be used to group together multiple other conditions for advanced control. Any condition - including additional grouping conditions - can be nested inside these conditions.

Any will return true if at least one condition within it is currently returning true. For example, in the configuration below, the condition will return true if either light mode "Stage 2" or "Stage 3" is active. You can think of this like a boolean "OR".

<Any>
    <LightMode name="Stage 3" active="true" />
    <LightMode name="Stage 2" active="true" />
</Any>

All will return true only if every condition within it is currently returning true. For example, in the configuration below, the condition will only return true if the vehicle is not moving and the front left door is open. You can think of this like a boolean "AND".

<All>
    <Speed max="0" />
    <Doors door="FrontLeft" state="FullyOpen" />
</All>

These can be nested as deep as necessary to provide the control you need. For example, if you want to trigger a mode when either both front doors are open or both rear doors are open, you can do so:

<Any>
    <All>
        <Doors door="FrontLeft" state="Open" />
        <Doors door="FrontRight" state="Open" />
    </All>
    <All>
        <Doors door="RearLeft" state="Open" />
        <Doors door="RearRight" state="Open" />
    </All>
</Any>

By default, Requirements in a mode are treated as an "all", and Triggers are treated as an "any".

Global Conditions

Time

Based on in-game time. Specify a start and end time in hh:mm format (24-hour time). Darkness is approximately from 21:00 - 05:00. If the end time is earlier in the day than the start time, then it will include anytime from start to midnight, and anytime from midnight to end.

<Time Start="20:45" End="05:15" />
<Time Start="15:00" End="17:00" />

Weather

<Weather>
  <!-- Weather types can be any of CLEAR, EXTRASUNNY, CLOUDS, OVERCAST, RAIN, CLEARING, THUNDER, SMOG, FOGGY, XMAS, SNOW, SNOWLIGHT, BLIZZARD, HALLOWEEN, NEUTRAL -->

  <!-- You only need to have one of either AllowedConditions OR ProhibitedConditions, but you can have both if you want to -->
  <AllowedConditions>
    <!-- Condition is true if the current weather is ANY of those listed -->
    <Type>Rain</Type>
    <Type>Clouds</Type>
  </AllowedConditions>
  <ProhibitedConditions>
    <!-- Condition is true if the current weather is NONE of those listed -->
    <Type>EXTRASUNNY</Type>
    <Type>NEUTRAL</Type>
  </ProhibitedConditions>
</Weather>

Random

<!-- Chance: integer (0-100) -->
<Random chance="50" />

Random chance conditions are evaluated independently once per occurrence per vehicle instance. Once an individual vehicle is spawned, all random chances in its config will be evaluated, and will not change again for that vehicle instance. If another vehicle of the same model is spawned, the random chances will be independently evaluated for that instance.

Vehicle Conditions

Control Group and Mode

<!-- Triggers if Audio mode/CG is active -->
<AudioControlGroup name="Stages" active="true" />
<AudioMode name="Stage3" active="true" />

<!-- Triggers if Audio mode/CG is **not** active -->
<LightControlGroup name="Stages" active="true" />
<LightMode name="Stage 3" active="true" />

Engine State

<!-- engine_on (Optional): true (default), false --> 
<EngineState engine_on="true" />

Indicator Lights

<!-- Status can be Off, LeftOnly, RightOnly, or Both -->
<IndicatorLights status="LeftOnly" />

Note this is based on whether the indicator lights are currently enabled, not whether the lights are currently illuminated. This condition will return true continuously as long as the turn signal or hazard lights are activated. For a condition which is based on when the relevant lights are actually illuminated, see the Light Emissive condition.

Doors

<!-- Doors: FrontLeft, FrontRight, RearLeft, RearRight, Hood, Trunk, Bonnet, Boot -->
<!-- States (optional): Open (default), FullyOpen, Closed, Damaged -->
<Doors door="FrontLeft" state="FullyOpen" />

Speed

<!-- Units (optional): mps, mph (default), kmh, ftps -->
<!-- Inclusive (optional): true, false -->
<!-- Absolute (optional): true, false -->
<!--      Set to true if you want 1mph forward and 1mph backwards to be treated the same. -->
<!--      Set to false if you want backwards movement to be treated as negative values. -->
<!-- Round (optional): integer (default: 2) -->
<!--      Rounds the speed to that many decimal points before comparing. -->
<!-- Min: Minimum speed -->
<!-- Max: Maximum speed -->
<Speed units="mph" inclusive="true" abs="true" round="2" min="10" max="15" />

Acceleration

<!-- Min: Minimum acceleration (in m/s) -->
<!-- Max: Maximum acceleration (in m/s) -->
<!-- Negative if slowing down, positive if speeding up -->
<Acceleration min="2" max="8" />
<Acceleration min="-2" />

Livery

<!-- id: integer -->
<Livery id="1" />

Towing

<!-- Attached: true, false -->
<Towing attached="true" />

Specifies if the vehicle is currently towing another vehicle (as a towtruck - see the trailer section below for towing a trailer).

Trailer

<!-- Attached: true, false -->
<!-- Model: string -->
<Trailer attached="true" model="[trailer model]"/>

Specifies if the vehicle currently has a trailer attached (true or false). attached must always be specified. If attached is set to true, you can optionally specify a particular trailer model that must be attached for the condition to be true, or you can omit the model to return true for any trailer.

Extra

<!-- Id: integer -->
<!-- Enabled: true, false -->
<Extra id="1" enabled="" />

Light Emissive

<!-- Id: defaultlight, headlight_l, headlight_r,
         taillight_l, taillight_r, indicator_lf,
         indicator_rf, indicator_lr, indicator_rr,
         brakelight_l, brakelight_r, brakelight_m,
         reversinglight_l, reversinglight_r, extralight_1,
         extralight_2, extralight_3, extralight_4 -->
<!-- Status: true, false -->
<LightEmissive id="indicator_lf" status="true" />

Braking

<!-- Status: true, false -->
<Braking status="true" />

Base Health

<!-- Min: Minimum health -->
<!-- Max: Maximum health -->
<BaseHealth min="100" max="" />

Body Health

<!-- Min: Minimum health -->
<!-- Max: Maximum health -->
<BodyHealth min="100" max="" />

Engine Health

<!-- Min: Minimum health -->
<!-- Max: Maximum health -->
<EngineHealth min="100" max="" />

Gas Tank Health

<!-- Min: Minimum health -->
<!-- Max: Maximum health -->
<GasTankHealth min="100" max="" />

Headlight Damage

<!-- Side: left, right, both, either -->
<!-- Damaged: true, false -->
<HeadlightDamage side="either" damaged="true" />

Bumper Damage

<!-- Bumper: front, rear, both, either -->
<!-- Condition: ok, loose, broken -->
<BumperDamage bumper="front" condition="broken" />

Animation Event

<!-- Event: string (event name) -->
<!-- Active (optional): true (default), false -->
<AnimEvent event="front" active="true" />

Custom animation event tags can be defined when creating animations. Use the VisibleToScript:Event tag channel. Put the custom event name in the configuration. Condition returns true while custom event is active within the animation.

Driver

<!-- Has Driver (optional): true (default), false -->
<Driver has_driver="false" />

Seats

<!-- Occupied (optional): true (default), false -->
<!--     If Occupied is false, then the seats must be *empty* for the condition to match. -->
<!--     If Occupied is true, the seats must have a ped in them for the condition to match. --> 
<!-- All (optional): true (default), false -->
<!--     If All is true, then all specified seats must be [un]occupied. -->
<!--     If All is false, then only one of the seats must be [un]occupied. --> 
<Seats occupied="true" all="true">1,2</Seats>

Occupants and Passengers

Occupants and Passengers conditions are identical, except that "Occupants" includes the driver, and "Passengers" does not. You can mix/match "Min" and "Max", or use "IsFull" or "Any" by themselves.

<Occupants any="true" /> <!-- Vehicle must have any occupant -->
<Passengers any="false" /> <!-- Vehicle must have no passengers -->
<Passengers full="false" /> <!-- There must be at least one free passenger seat -->
<Occupants full="true" /> <!-- All seats in the vehicle must be occupied -->
<Passengers min="2" /> <!-- There msut be at least 2 passengers -->
<Occupants max="3" /> <!-- There must be at most 3 occupants, including driver -->

Vehicle Owner

<!-- IsPlayerVehicle: true, false -->
<!--    Triggers if player was the last ped to drive vehicle -->
<VehicleOwner is_player_vehicle="false" />

At Traffic Light

<!-- Stopped at Light: true, false -->
<AtTrafficLight stopped_at_light="true" />

Road Conditions

These conditions are vehicle-specific but depend on where the vehicle is positioned on the road. This can be used to detect if the vehicle is currently facing the same or opposite direction as traffic, which lane the vehicle is in, whether it is on a median or shoulder, and how many adjacent lanes of traffic there are. This is very useful for setting automatic TA modes.

These conditions are complex. See a fully functional example at the bottom of this section.

Node Flags

This condition checks the flags of nearby road path nodes. This can be used to detect highways, nearby intersections, etc.

<NodeFlags all="true" nearest_n="5" max_dist_to_node="25" 
    no_node_status="false" include_disabled_nodes="true">
    <Flags>
        <Item has_flag="true">highway</Item>
        <Item has_flag="true">junction</Item>
    </Flags>
</NodeFlags>

The following attributes are available on the <NodeFlags> condition:

• all: defaults to true. If true, all specified flags must be present amongst the specified nodes. If false, at least one of the specified flags must be present amongst the specified nodes.

• nearest_n: defaults to 1. Specifies how many nodes to check for the specified flags. Nodes will be checked in order of direct distance from the vehicle's position. The nth nearest node may not necessarily be on the same road as the vehicle or be the nearest by driving distance.

• max_dist_to_node: defaults to 50m. Specifies the maximum distance (in meters) away from the vehicle position for a node to be considered.

• no_node_status: defaults to false. Specifies whether the condition should return true or false if no nodes are found within the specified distance.

• include_disabled_nodes: defaults to false. Specifies whether to include nodes that are currently disabled. Ambient AI vehicles will not spawn/drive on disabled nodes, but vehicles with a driving task may sometimes. Most parking lots, small dirt paths, private areas, and many other roads have disabled nodes.

Within the NodeFlags element there must be a <Flags> element with no attributes, and within the Flags element there must be one or more <Item> elements each specifying a node flag to check for. If nearest_n is greater than 1 and all is true, the condition will return true if all of the flags being checked for are present at least once across the n nodes, even if they don't all appear on the same single node. The <Item> has an optional attribute has_flag which defaults to true. If set to false then the code will ensure that none of the n nodes checked has this flag.

The available <Item> flags include:

offroad, player_road, no_trucks, disabled, inside, dead_end, highway, 
junction, traffic_light, stop_sign, water

Some of these flags can be visualized in CodeWalker paths view for reference. A junction flag typically occurs once per intersection at the node in the middle of the intersection. traffic_light and stop_sign will typically appear at the stop bar when approaching the intersection.

Road Direction

<RoadDirection is_one_way="true" />

Checks if the current road segment is flagged for one-way traffic. Typically occurs on divided highways where the opposite direction is technically a separate road. Also occurs occasionally with actual one-way streets.

On Road

Checks if the vehicle position is on the road within the bounds of the drive lanes, not including shoulders/medians. on_road defaults to true.

<!-- True if the vehicle is between the lanes of the road -->
<OnRoad on_road="true" />

<!-- True if the vehicle is not between the lanes of the road -->
<OnRoad on_road="false" />

Shoulder and Median

These conditions check if the vehicle position is within a median (to the left side of the leftmost lane, typically in the buffer zone between oncoming traffic) or on the shoulder (right of the rightmost lane). Note that "median" returns true when the vehicle is left of the edge of the road on a one-way road even if there is no opposite divided road.

<RoadShoulder on_shoulder="true" min="2" max="10" />
<RoadMedian on_median="false" min="1" max="5" />

All attributes are optional. on_shoulder or on_median defaults to true, in which case the condition will return true when the vehicle is on the shoulder/median. If set to false, it will return false when the vehicle is not on the shoulder/median. Min and max optionally specify the distance range in meters from the edge of the nearest lane. For example, if you set max="10" then the condition will only return true if the vehicle is within 10 meters of the edge of the lane.

Road Lanes

There are several conditions relating to the number of lanes and the vehicle's position within them.

These conditions are all calculated based on the direction of traffic in the lane that the vehicle is currently in or closest to, regardless of which direction the vehicle itself is facing.

Total Lane Count

The basic RoadLanes condition just checks the total number of road lanes on the current road.

<RoadLanes both_directions="false" min="2" max="5" />

The optional attribute both_directions defaults to true. When set to true, it counts the total number of lanes in both directions on two-lane roads. When set to false, it only counts the number of lanes in the direction of traffic for the lane the vehicle is currently in/closest to. You must specify min and/or max for the number of lanes to check for.

Relative Lane Count

There are two relative road lanes conditions, RoadLanesLeft and RoadLanesRight, each behaving in the same way. Left specifies the number of additional vehicle lanes to the left of the current lane, and right specifies the number of additional lanes to the right. If it is a single lane road, both will return 0. The lane the vehicle in is not counted. This condition will change depending on which lane the vehicle is currently in.

Both conditions support specifying attributes min and/or max. At least one of the two must be specified. The condition returns true when the number of lanes to the left or right is greater than min and/or less than max.

<RoadLanesLeft min="1" />
<RoadLanesLeft max="2" />

Road Lane Position

The RoadLanePosition condition checks the vehicle's position within the lane, from -1 being at the far left side of the lane to +1 being the far right side of the lane.

<!-- Checks that the vehicle is no more than 20% of the distance from the center 
     of the lane towards the left side of the lane, and no more than 70% of the 
     distance from the center of the lane towards the right side of the lane -->
<RoadLanePosition abs="false" min="-0.2" max="0.7" />

<!-- Checks that the vehicle is no more than 50% of the distance from the center 
     of the lane towards either edge of the lane -->
<RoadLanePosition abs="true" max="0.5" />

You must specify min and/or max as a decimal value between -1 and 1. The optional abs attribute defaults to false and specifies whether the min/max should be applied to the absolute value of the position.

Road Lane Index

The RoadLaneIndex condition checks which specific lane number the vehicle is in, starting from the leftmost lane as #1. If optional attribute from_left is set to false, it will count from the rightmost lane starting with 1. You must specify min and/or max with the range of lane indexes the vehicle may be in.

<RoadLaneIndex from_left="true" min="2" max="3" />

Vehicle Offset from Road Direction

This condition checks the relative angle between the direction traffic flows in the current lane and the direction the vehicle is facing. The number is returned in degrees between -180 (left) and +180 (right). If the vehicle is facing the direction of traffic the offset is 0°. If the vehicle is facing exactly towards oncoming traffic the offset is 180°. Specify a min and/or max offset, and optionally set abs to true if you want to compare the absolute value of the difference. abs defaults to false, but in most cases it makes sense to set it to true unless you really want to ensure the vehicle is angled in a specific direction (which may be relevant for a TA or traffic stop setting).

<!-- Ensures the vehicle is facing forward within +/- 15 degrees -->
<RoadHeadingOffset abs="true" max="15" />

<!-- Checks if the vehicle is facing backwards within +/- 60 degrees -->
<RoadHeadingOffset abs="true" min="120" />

<!-- Checks if the vehicle is turned approximately 90 degrees to the left -->
<RoadHeadingOffset abs="false" min="80" max="100" />

Full Example

The following configuration adds an automatic traffic advisor function when the vehicle is owned by an NPC. The vehicle must be occupied by a non-player, not waiting at a traffic light, be stopped or moving under 15 mph, or be on a highway moving under 25 mph.

The left TA is triggered when the vehicle is facing forward (within +/- 45 degrees) with zero lanes to the right and at least one lane to the left, or when on the shoulder within 4 meters of the side of the lane. The right TA is triggered under the same conditions from the opposite side. The split TA is triggered when there is at least one lane on each side of the vehicle. All three modes will only trigger if the condition has been true for at least 2 seconds.

Auto TA Modes Example

<Mode name="TA Left">
	<Triggers>
		<All delay_time="2000">
			<VehicleOwner is_player_vehicle="false" />
			<AtTrafficLight stopped_at_light="false" />
			<Any>
				<Speed max="15" units="mph" />
				<All>
					<Speed max="25" units="mph" />
					<NodeFlags all="false"><Flags><Item has_flag="true">highway</Item></Flags></NodeFlags>
				</All>
			</Any>
			<RoadHeadingOffset abs="true" max="45" />
			<RoadLanesRight max="0" />
			<Any>
				<All>
					<RoadLanesLeft min="1" />
					<OnRoad on_road="true" />
				</All>
				<RoadShoulder on_shoulder="true" max="4" />
			</Any>
		</All>
	</Triggers>
	<Sequences>
		<Item id="16" sequence="11111111111111110000000000000000"/>
		<Item id="17" sequence="01111111111111111000000000000000"/>
		<Item id="20" sequence="00111111111111111100000000000000"/>
		<Item id="21" sequence="00011111111111111110000000000000"/>
		<Item id="22" sequence="00001111111111111111000000000000"/>
		<Item id="19" sequence="00000111111111111111100000000000"/>
		<Item id="18" sequence="00000011111111111111110000000000"/>
		<Item id="15" sequence="00000001111111111111111000000000"/>
	</Sequences>
</Mode>
<Mode name="TA Right">
	<Triggers>
		<All delay_time="2000">
			<VehicleOwner is_player_vehicle="false" />
			<AtTrafficLight stopped_at_light="false" />
			<Any>
				<Speed max="15" units="mph" />
				<All>
					<Speed max="25" units="mph" />
					<NodeFlags all="false"><Flags><Item has_flag="true">highway</Item></Flags></NodeFlags>
				</All>
			</Any>
			<RoadHeadingOffset abs="true" max="45" />
			<RoadLanesLeft max="0" />
			<Any>
				<All>
					<RoadLanesRight min="1" />
					<OnRoad on_road="true" />
				</All>
				<RoadMedian in_median="true" max="4" />
			</Any>
		</All>
	</Triggers>
	<Sequences>
		<Item id="16" sequence="00000001111111111111111000000000"/>
		<Item id="17" sequence="00000011111111111111110000000000"/>
		<Item id="20" sequence="00000111111111111111100000000000"/>
		<Item id="21" sequence="00001111111111111111000000000000"/>
		<Item id="22" sequence="00011111111111111110000000000000"/>
		<Item id="19" sequence="00111111111111111100000000000000"/>
		<Item id="18" sequence="01111111111111111000000000000000"/>
		<Item id="15" sequence="11111111111111110000000000000000"/>
	</Sequences>
</Mode>
<Mode name="TA Diverge">
	<Triggers>
		<All delay_time="2000">
			<VehicleOwner is_player_vehicle="false" />
			<AtTrafficLight stopped_at_light="false" />
			<Any>
				<Speed max="15" units="mph" />
				<All>
					<Speed max="25" units="mph" />
					<NodeFlags all="false"><Flags><Item has_flag="true">highway</Item></Flags></NodeFlags>
				</All>
			</Any>
			<RoadHeadingOffset abs="true" max="45" />
			<RoadLanesLeft min="1" />
			<RoadLanesRight min="1" />
			<OnRoad on_road="true" />
		</All>
	</Triggers>
	<Sequences>
		<Item id="16" sequence="00000001111111111111111000000000"/>
		<Item id="17" sequence="00000111111111111111100000000000"/>
		<Item id="20" sequence="00011111111111111110000000000000"/>
		<Item id="21" sequence="11111111111111110000000000000000"/>
		<Item id="22" sequence="11111111111111110000000000000000"/>
		<Item id="19" sequence="00011111111111111110000000000000"/>
		<Item id="18" sequence="00000111111111111111100000000000"/>
		<Item id="15" sequence="00000001111111111111111000000000"/>
	</Sequences>
</Mode>

Here is an example of a similar config in action, including additional debug information showing some of the calculated values that are used in the underlying logic for these conditions: