Skip to content

5. Vehicle Spawning System

cjcarw edited this page Jul 15, 2026 · 5 revisions

🚗 5. Vehicle Spawning System

BS KeyRoom can spawn vehicles as rewards when a keycard door is activated. Vehicles can have pre-filled fuel, custom attachments, and weighted spawn chances — making them ideal for high-tier keycard events.


📖 Table of Contents


5.1. How Vehicle Spawning Works

When a player successfully uses a keycard and the door opens:

  1. The system reads the door's vehiclesToSpawn list together with min_vehicles_to_spawn / max_vehicles_to_spawn.
  2. If min_vehicles_to_spawn or max_vehicles_to_spawn is -1, every vehicle in the list spawns.
  3. Otherwise, a random count between min and max is rolled, and that many vehicles are picked by weighted random selection based on each vehicle's spawnChance — without repeats, so each entry can spawn at most once per event. Entries with spawnChance of 0 are never picked.
  4. The selected vehicles are spawned at their defined world positions, with fuel and attachments applied.
  5. When the door's restock timer ends and it closes again, all spawned vehicles are automatically despawned (deleted).

⚠️ Vehicles are tied to the door event. Do not use this system if you want permanent vehicle spawns — use a dedicated vehicle spawn mod for that.


5.2. Vehicle Entry Parameters

Each object inside vehiclesToSpawn supports these fields:

Parameter Type Default Description
referenceName String "NewVehicle" Unique name for this vehicle entry, used in logs and the Admin Menu list.
className String "OffroadHatchback" The vehicle entity classname (e.g. OffroadHatchback, ExpansionMh6).
position Array [0, 0, 0] World coordinates [X, Y, Z].
orientation Array [0, 0, 0] Rotation [Yaw, Pitch, Roll].
spawnChance Float 1.0 Weighted probability of this vehicle being selected when min/max limits the count. Higher = more likely relative to the other entries. 0 = never selected.
useDebugAttachments 0 or 1 1 1 = Calls OnDebugSpawn() on the vehicle, letting the game attach its full default part set automatically — quick setup with no manual part list. 0 = Uses the manual fuel value and attachments array below.
fuel Float 1.0 Fuel level as a fraction of tank capacity: 0.0 = empty, 0.5 = 50%, 1.0 = full. Values outside 0–1 are clamped. Set to -1 to skip fuel filling entirely (tank spawns empty). Only applied when useDebugAttachments is 0; when fuel is applied, oil, brake fluid, and coolant are also topped up automatically.
attachments Array [] List of parts to attach. Each entry has a name (classname) and a quantity. Only used when useDebugAttachments is 0. See 5.4.

Door-Level Vehicle Parameters

These live at the top level of the door config, next to vehiclesToSpawn:

Parameter Type Default Description
min_vehicles_to_spawn Int -1 Minimum number of vehicles to spawn per door event. -1 = always spawn all defined vehicles.
max_vehicles_to_spawn Int -1 Maximum number of vehicles to spawn per door event. -1 = always spawn all defined vehicles.

💡 If the rolled count exceeds the number of defined vehicles, it is clamped automatically.


5.3. JSON Configuration

Vehicle settings are defined inside your door's JSON file (see 2. Door Configuration).

Minimal Example

"vehiclesToSpawn": [
    {
        "referenceName": "Reward_Heli",
        "className": "ExpansionMh6",
        "position": [
            3670.0,
            402.5,
            5990.0
        ],
        "orientation": [
            0.0,
            0.0,
            0.0
        ],
        "spawnChance": 1.0,
        "fuel": 1.0,
        "useDebugAttachments": 1,
        "attachments": []
    }
],
"min_vehicles_to_spawn": -1,
"max_vehicles_to_spawn": -1

Example with Multiple Vehicles and Random Count

"vehiclesToSpawn": [
    {
        "referenceName": "Common_Car",
        "className": "OffroadHatchback",
        "position": [
            3672.0,
            402.0,
            5992.0
        ],
        "orientation": [
            90.0,
            0.0,
            0.0
        ],
        "spawnChance": 1.0,
        "fuel": 0.5,
        "useDebugAttachments": 0,
        "attachments": [
            {
                "name": "HatchbackWheel",
                "quantity": 4
            },
            {
                "name": "HatchbackHood_Black",
                "quantity": 1
            },
            {
                "name": "HatchbackTrunk",
                "quantity": 1
            },
            {
                "name": "CarBattery",
                "quantity": 1
            },
            {
                "name": "SparkPlug",
                "quantity": 1
            }
        ]
    },
    {
        "referenceName": "Rare_Sedan",
        "className": "CivilianSedan",
        "position": [
            3680.0,
            402.0,
            5995.0
        ],
        "orientation": [
            0.0,
            0.0,
            0.0
        ],
        "spawnChance": 0.3,
        "fuel": 0.8,
        "useDebugAttachments": 1,
        "attachments": []
    }
],
"min_vehicles_to_spawn": 1,
"max_vehicles_to_spawn": 1

Each door opening spawns exactly 1 vehicle: the hatchback (weight 1.0, most likely) or the sedan (weight 0.3).


5.4. Vehicle Attachments

When useDebugAttachments is 0, you manually define which parts the vehicle spawns with. This gives you full control over the vehicle's components — spawn a fully drivable car, or one deliberately missing its spark plug so players have to bring their own.

"attachments": [
    {
        "name": "HatchbackWheel",
        "quantity": 4
    },
    {
        "name": "HatchbackDoors_Driver",
        "quantity": 1
    },
    {
        "name": "HatchbackDoors_CoDriver",
        "quantity": 1
    },
    {
        "name": "HatchbackHood_Black",
        "quantity": 1
    },
    {
        "name": "HatchbackTrunk",
        "quantity": 1
    },
    {
        "name": "CarBattery",
        "quantity": 1
    },
    {
        "name": "SparkPlug",
        "quantity": 1
    },
    {
        "name": "CarRadiator",
        "quantity": 1
    }
]
  • quantity repeats the attachment that many times — perfect for wheels ("quantity": 4 fills all four wheel slots one by one).
  • If an item cannot be attached (no free slot), the system falls back to placing it in the vehicle's cargo instead — handy for spare parts or bonus loot inside the trunk.
  • Failed attachments are logged with a warning so you can spot classname typos.

💡 Tip: Use useDebugAttachments: 1 first to verify the vehicle spawns and drives correctly, then switch to 0 with a manual list if you need specific parts, colors, or missing components.

⚠️ Attachment classnames are vehicle-specific (HatchbackWheel vs CivSedanWheel vs Sarka120Wheel …). Using the wrong family of parts results in "Failed to attach" warnings in the log.


5.5. Placing Vehicles — Hologram & Coordinates

Admin Menu (Recommended)

The Admin Menu's vehicle section supports the same placement hologram workflow as containers and AI: select a vehicle entry, click Set Position, and a ghost preview follows your aim so you can drop the vehicle exactly where you want it, at the right rotation. Confirm to write position and orientation into the entry. See 8. Admin Menu Guide.

Manual Coordinates

If you prefer editing JSON, use the same method as for loot containers (see 3. Advanced Loot System):

  1. Load the map in Offline Mode or with admin tools.
  2. Go to the spot outside the keycard room where you want the vehicle.
  3. Spawn a placeholder object and read its coordinates (getpos, DayZ Editor, etc.).
  4. Copy the coordinates into your JSON.

⚠️ Make sure the spawn point is on solid, reasonably flat ground with enough clearance — vehicles spawning at bad angles can clip into terrain or objects and take damage (or launch into orbit).


5.6. Full Example — High-Tier Door with Vehicle Reward

"vehiclesToSpawn": [
    {
        "referenceName": "Jackpot_Helicopter",
        "className": "ExpansionMh6",
        "position": [
            3670.0,
            402.5,
            5990.0
        ],
        "orientation": [
            0.0,
            0.0,
            0.0
        ],
        "spawnChance": 0.15,
        "fuel": 1.0,
        "useDebugAttachments": 1,
        "attachments": []
    },
    {
        "referenceName": "Standard_Car",
        "className": "OffroadHatchback",
        "position": [
            3672.0,
            402.0,
            5994.0
        ],
        "orientation": [
            90.0,
            0.0,
            0.0
        ],
        "spawnChance": 1.0,
        "fuel": 0.6,
        "useDebugAttachments": 0,
        "attachments": [
            {
                "name": "HatchbackWheel",
                "quantity": 4
            },
            {
                "name": "HatchbackDoors_Driver",
                "quantity": 1
            },
            {
                "name": "HatchbackDoors_CoDriver",
                "quantity": 1
            },
            {
                "name": "HatchbackHood_Black",
                "quantity": 1
            },
            {
                "name": "HatchbackTrunk",
                "quantity": 1
            },
            {
                "name": "CarBattery",
                "quantity": 1
            },
            {
                "name": "SparkPlug",
                "quantity": 1
            }
        ]
    }
],
"min_vehicles_to_spawn": 1,
"max_vehicles_to_spawn": 1
  • ~87% chance → A drivable hatchback with 60% fuel, all four wheels, doors, battery, and spark plug installed.
  • ~13% chance → A fully fueled helicopter (requires DayZ Expansion — see 10. Expansion Integration).

ℹ️ The weights 1.0 vs 0.15 translate to 1.0 / 1.15 ≈ 87% and 0.15 / 1.15 ≈ 13% — weights are relative to each other, not absolute percentages.


Next Steps

Configure keycard names and uses → 6. Keys and Keycards Configuration

Related pages: 2. Door Configuration · 8. Admin Menu Guide · 11. FAQ & Troubleshooting

Clone this wiki locally