Skip to content

Helicopter settings

cjcarw edited this page Feb 27, 2026 · 6 revisions

Helicopter Settings

The HelicopterSettings block controls the helicopter's identity, durability, aggression behavior, and the patrol routes it follows across the map.


Full Reference

"HelicopterSettings": {
    "HelicopterClassName": "BS_AH64D_Apache",
    "HelicopterHealth": 0,
    "AggroWhilePatrolling": 0,
    "PatrolAggroRange": 300.0,
    "PatrolAggroPursue": 0,
    "PatrolRoutes": [
        {
            "RouteName": "Airfield Route",
            "SpawnPosition": "5213.19 390.0 9080.21",
            "Waypoints": [
                "4205.63 390.2 10859.44",
                "3953.76 390.0 10735.22",
                "4550.12 390.0 10520.33",
                "4246.88 390.0 10177.47"
            ]
        }
    ]
}

Option Details


HelicopterClassName

Type String
Default "BS_AH64D_Apache"
Description The class name of the helicopter object to spawn. Unless you have created a custom helicopter model that extends BS_AH64D_Apache_Base, you should leave this as the default.

HelicopterHealth

Type Integer
Default 0 (use model default)
Description Custom maximum HP for the helicopter. When set to 0, the helicopter uses its model's default health value from the config(20000 HP). When set to any positive value, the mod overrides the default health with this custom value and manages a separate health tracking system internally.

How custom health works: When HelicopterHealth is greater than 0, the mod creates its own health pool (m_CustomMaxHealth) separate from DayZ's built-in entity health. All incoming damage is subtracted from this custom pool. The helicopter's visual damage states (smoke, fire, sparks) are calculated as a percentage of this custom health. At 0 custom HP, the crash sequence begins.

Tip: The default Apache model health is relatively low. If you want the helicopter to be a long, challenging fight for a group of players, set this to a high value like 2000–5000. For solo-friendly servers, keep it at 0 or use a low value like 500.

Example — Very tanky helicopter (squad fight):

"HelicopterHealth": 25000

Example — Moderate custom health:

"HelicopterHealth": 10500

Example — Use model default (easiest to destroy):

"HelicopterHealth": 0

AggroWhilePatrolling

Type Boolean (1 / 0)
Default 0
Description When enabled, the helicopter actively scans for nearby players during its patrol route (not just when shot at). It checks for targets every 0.5 seconds. If a player is found within PatrolAggroRange, the helicopter locks onto them as a target.

Without this enabled (default): The helicopter only enters combat when a player damages it. It peacefully flies its route and ignores players even if they stand directly below it.

With this enabled: The helicopter is a proactive hunter. It detects players and can engage them unprovoked. This dramatically changes the gameplay — the helicopter becomes a real threat just by being in the area, not just a loot piñata waiting to be shot down.

Example — Aggressive helicopter that hunts players:

"AggroWhilePatrolling": 1,
"PatrolAggroRange": 300.0,
"PatrolAggroPursue": 1

Example — Passive patrol (default):

"AggroWhilePatrolling": 0

PatrolAggroRange

Type Float (meters)
Default 300.0
Description The detection radius for patrol aggro scanning. Only used when AggroWhilePatrolling is enabled. Players within this distance of the helicopter can be detected and targeted. If a player moves beyond 120% of this range (e.g., 360m for a 300m range), the helicopter loses interest and clears the patrol target.

How the disengage works: The helicopter uses PatrolAggroRange * 1.2 as the "lose interest" distance. This hysteresis prevents the helicopter from constantly locking/unlocking on targets at the edge of its range. It also clears patrol targets that are dead or unconscious.

Example — Long detection range (helicopter spots players from far away):

"PatrolAggroRange": 500.0

Example — Short detection range (only reacts to very close players):

"PatrolAggroRange": 150.0

Example — Default range:

"PatrolAggroRange": 300.0

PatrolAggroPursue

Type Boolean (1 / 0)
Default 0
Description When enabled (along with AggroWhilePatrolling), the helicopter breaks from its patrol route to actively pursue and engage detected players. It enters full combat mode (Orbit → Pull Back → U-Turn → Attack Run) against the patrol target. When disabled, the helicopter detects and locks onto the player but continues following its route — it fires at the target opportunistically but doesn't deviate from its path.

The difference is significant:

  • PatrolAggroPursue: 0 — The helicopter notices you and might shoot at you if it has a clear shot, but it keeps flying its route. You can wait for it to fly away.
  • PatrolAggroPursue: 1 — The helicopter breaks formation and comes after you. It enters the full combat state machine (Orbit, Attack Run, etc.) and won't stop until you're dead, it loses sight for LostSightTimeout seconds, or you leave its range.

Example — Full hunter mode (detects + pursues):

"AggroWhilePatrolling": 1,
"PatrolAggroRange": 400.0,
"PatrolAggroPursue": 1

Example — Aware but passive (detects but keeps flying):

"AggroWhilePatrolling": 1,
"PatrolAggroRange": 300.0,
"PatrolAggroPursue": 0

Patrol Routes

The PatrolRoutes array defines one or more flight paths for the helicopter. Each route has a name, a spawn position, and a sequence of waypoints.

Route Structure

{
    "RouteName": "Airfield Route",
    "SpawnPosition": "5213.19 390.0 9080.21",
    "Waypoints": [
        "4205.63 390.2 10859.44",
        "3953.76 390.0 10735.22",
        "4550.12 390.0 10520.33",
        "4246.88 390.0 10177.47"
    ]
}
Field Type Description
RouteName String A label for this route. Used in server logs for debugging. Has no gameplay effect.
SpawnPosition String ("X Y Z") The 3D world position where the helicopter initially spawns. This is where it physically appears before flying to its first waypoint.
Waypoints Array of Strings Ordered list of positions the helicopter flies through, one after another. After reaching the last waypoint, the helicopter loops back to the first.

Coordinate Format

Coordinates are strings in the format "X Y Z" where:

  • X = East/West position
  • Y = Altitude (height above sea level)
  • Z = North/South position

⚠️ Common Mistake: Coordinates must be separated by spaces, not commas. The format is "X Y Z" not "X, Y, Z". Using commas will cause the position to be read as 0 0 0.

About the Y value: The Y value in SpawnPosition determines where the helicopter initially appears vertically. A good altitude is 300–500 to keep it high enough to fly in from the distance realistically. For waypoints, the Y value is less important because the helicopter's actual flight altitude during patrol is controlled by Difficulty.PatrolAltitude (height above ground) — the helicopter smoothly adjusts to terrain using its lookahead system.


Getting Coordinates

You can get coordinates in DayZ using:

  • In-game admin tools COT-VPP (press HOME-INSERT-P in many admin mods to show current position)
  • iZurvive map (right-click → copy coordinates)
  • DayZ Editor (place objects and read their coordinates)
  • Server logs (player positions are logged periodically)

How Route Selection Works

When the helicopter spawns, the mod selects a route from the PatrolRoutes array. It cycles through routes sequentially: first spawn uses route 0, second spawn uses route 1, and so on. After the last route, it loops back to route 0. The active route index persists in the config's internal state (m_ActiveRouteIndex).

Within a route, the helicopter flies to each waypoint in order. When it reaches the last waypoint, it loops back to the first waypoint and continues the circuit indefinitely until it's shot down or the event ends.


Example: Multi-Route Setup (Chernarus)

"PatrolRoutes": [
    {
        "RouteName": "South Coast",
        "SpawnPosition": "14000.0 400.0 2500.0",
        "Waypoints": [
            "12800.0 400.0 3200.0",
            "10500.0 400.0 2200.0",
            "8200.0 400.0 3000.0",
            "6000.0 400.0 2500.0"
        ]
    },
    {
        "RouteName": "NWAF Circuit",
        "SpawnPosition": "5213.19 400.0 9080.21",
        "Waypoints": [
            "4205.63 400.0 10859.44",
            "3953.76 400.0 10735.22",
            "4550.12 400.0 10520.33",
            "4246.88 400.0 10177.47"
        ]
    },
    {
        "RouteName": "Tisy Military",
        "SpawnPosition": "1500.0 500.0 14000.0",
        "Waypoints": [
            "1867.30 500.0 13845.36",
            "1376.84 500.0 13662.82",
            "1677.32 500.0 14350.05"
        ]
    }
]

This setup creates three patrol zones. The helicopter cycles through them: first spawn → South Coast, second spawn → NWAF, third spawn → Tisy, fourth spawn → back to South Coast, etc.


Example: Single Route (Simple)

"PatrolRoutes": [
    {
        "RouteName": "Main Route",
        "SpawnPosition": "14000.0 400.0 8000.0",
        "Waypoints": [
            "12000.0 400.0 9000.0",
            "10000.0 400.0 7000.0",
            "8000.0 400.0 8500.0",
            "6000.0 400.0 6000.0",
            "4000.0 400.0 9000.0",
            "2000.0 400.0 12000.0"
        ]
    }
]

A single route that traverses the map from east to west.


Example: Short Route for Testing

"PatrolRoutes": [
    {
        "RouteName": "Test Loop",
        "SpawnPosition": "7500.0 300.0 7500.0",
        "Waypoints": [
            "7700.0 300.0 7700.0",
            "7300.0 300.0 7700.0",
            "7300.0 300.0 7300.0",
            "7700.0 300.0 7300.0"
        ]
    }
]

A small square loop in the center of the map. Useful for testing the helicopter's behavior without waiting for it to fly across the entire map.


Complete Examples

Aggressive Hunter Configuration

The helicopter actively hunts players with high health and long routes:

"HelicopterSettings": {
    "HelicopterClassName": "BS_AH64D_Apache",
    "HelicopterHealth": 25000,
    "AggroWhilePatrolling": 1,
    "PatrolAggroRange": 400.0,
    "PatrolAggroPursue": 1,
    "PatrolRoutes": [
        {
            "RouteName": "Hunter Route",
            "SpawnPosition": "14000.0 450.0 7500.0",
            "Waypoints": [
                "12000.0 450.0 9000.0",
                "10000.0 450.0 7000.0",
                "8000.0 450.0 8500.0",
                "6000.0 450.0 6000.0",
                "4000.0 450.0 9000.0",
                "2000.0 450.0 12000.0"
            ]
        }
    ]
}

Passive Patrol Configuration (Default Feel)

The helicopter flies peacefully and only fights back when attacked:

"HelicopterSettings": {
    "HelicopterClassName": "BS_AH64D_Apache",
    "HelicopterHealth": 0,
    "AggroWhilePatrolling": 0,
    "PatrolAggroRange": 300.0,
    "PatrolAggroPursue": 0,
    "PatrolRoutes": [
        {
            "RouteName": "Scenic Route",
            "SpawnPosition": "14000.0 400.0 2500.0",
            "Waypoints": [
                "12800.0 400.0 3200.0",
                "10500.0 400.0 2200.0",
                "8200.0 400.0 3000.0",
                "6000.0 400.0 2500.0"
            ]
        }
    ]
}

Tips for Route Design

  1. Start outside the action. Place SpawnPosition at the edge of the map or high in the air so the helicopter "arrives" rather than appearing suddenly over players.
  2. Space waypoints 1–3 km apart. Too close and the helicopter just wiggles in place. Too far and it takes ages between patrol areas.
  3. Cover high-traffic areas. Route the helicopter over military bases, high-tier loot zones, or known PvP hotspots for maximum engagement.
  4. Use 3+ routes for variety. With multiple routes, each helicopter feels different. Players can't predict exactly where it will go.
  5. Test on an empty server first. Watch the helicopter fly a full cycle to make sure it doesn't clip through terrain or fly over boring areas.
  6. Consider aggro + routes together. If AggroWhilePatrolling is enabled, routing the helicopter over player bases or spawn areas makes it a genuine hazard. Route it over low-traffic areas if you want aggro to be a rare surprise.