Skip to content

2. Door Configuration

cjcarw edited this page Jul 15, 2026 · 10 revisions

πŸšͺ 2. Door Configuration

Every door controlled by BS KeyRoom has its own .json file inside the BS_KeyRoom/DoorConfigs/ folder. Each file represents one door event with all of its settings: the key(s) required, loot, timers, alarms, announcements, AI, vehicles, teleport safety, and mod integrations.

This page documents every parameter of the door config (the KeyCardLocations data class), a fully annotated example, and three ready-to-use recipes.


πŸ“ Coordinate System β€” Read This First

In the door JSON, the x/y/z and building_x/building_y/building_z fields do not follow the in-game vector order:

JSON field Meaning
x Map easting (same as in-game X)
y Map northing (the in-game Z)
z Altitude / height (the in-game Y)

⚠️ Warning: y and z are swapped compared to in-game vectors. A position that reads <3689.4, 403.7, 5985.5> in-game is stored as "x": 3689.4, "y": 5985.5, "z": 403.7 in the JSON. Getting this wrong places the door event underground or in the sky.

πŸ’‘ Tip: You should never need to type these by hand. Use the in-game admin menu or the DoorLocker tool (see below) β€” both write the coordinates for you in the correct order. The custom_teleport_points and hacked_crate_position fields, by contrast, are regular engine vectors in "X Altitude Z" order.


πŸ› οΈ Creating a Door β€” Three Ways

Way 1: The Admin Menu

Open the in-game admin menu and create/edit door configs entirely from the UI β€” positions, indices and building classnames are captured automatically. Full walkthrough: 8. Admin Menu Guide.

Way 2: DoorLocker Auto-Configuration

The fastest way to generate a config file in the field:

  1. Enable Debug Mode β€” In BS_KeyRoom_Settings.json, set debug_build to 1.
  2. Get the tool β€” Spawn the item BS_DoorLocker as an admin.
  3. Aim and hold β€” Point at the target door and hold the Left Mouse Button. The action is called "Setup Keycard Door".
  4. Check your files β€” A new .json is generated in DoorConfigs/ with the building coordinates, door position, and door index pre-filled.

ℹ️ Note: After generating the file, stop the server, edit it with your loot/timers/etc., then restart.

Way 3: Manual JSON

Copy an existing config, change Location_Name (it must be unique), and adjust the fields using the reference below. Only recommended for tweaking values β€” let the tools write the coordinates and door indices.


πŸ”’ Door Indices and the Door Scanner

Buildings number their doors 0, 1, 2, ... internally. The door_indices array tells BS KeyRoom which of a building's doors this config controls β€” a single keycard can operate several doors of the same building at once.

πŸ’‘ Tip β€” Finding door indices: enable Debug Build and hold the DoorLocker β€” the Door Scanner shows every door's index, state and the building classname as floating tags, right on the doors. See 8. Admin Menu Guide.


πŸ“„ Complete Annotated JSON Example

Below is a full example showing all available parameters (valid JSON β€” copy and trim what you don't need):

{
    "x": 3689.39, "y": 5985.54, "z": 403.74,
    "building_x": 3686.41, "building_y": 5982.14, "building_z": 407.67,
    "door_indices": [
        0,
        1
    ],
    "linked_doors": [ "AnotherLocation_Name" ],
    "Location_Name": "GreenMountain_Barracks_Main",
    "BuildingClassName": "Land_Mil_Barracks5",

    "keycard_class_name": "",
    "keycard_class_names": [
        "BS_keycard_lab_red",
        "BS_keycard_master"
    ],
    "showRequiredKeys": 1,
    "sound_accept": "Sound_Door_Accepted",
    "sound_deny": "",

    "unlockOnly": 0,
    "use_continuous_action": 0,
    "continuous_action_time": 5.0,
    "reputationReward": 0,

    "use_announcement": 1,
    "announcement_title": "ALERT",
    "announcement_text": "A red keycard has been activated at Green Mountain.",
    "announcement_color_rgba": "255,220,53,69",
    "announcement_duration_seconds": 7,

    "use_alarm": 1,
    "alarm_sound": "Alarm_Military",
    "alarm_duration": 45,
    "alarm_loop_delay": 1.8,

    "min_unlock_time": 5,
    "max_unlock_time": 10,
    "min_restock_time": 300,
    "max_restock_time": 600,

    "countdown_notifications": [
        {
            "timeRemainingSeconds": 60,
            "title": "KeyRoom",
            "message": "Door closes in 1 minute!",
            "color": "255,255,165,0"
        },
        {
            "timeRemainingSeconds": 10,
            "title": "KeyRoom",
            "message": "Door closing NOW β€” get out!",
            "color": "255,220,53,69"
        }
    ],

    "containers_only": 0,
    "min_containers_to_spawn": 1,
    "max_containers_to_spawn": 2,
    "containers": [],
    "doorSpecificLootPools": [],

    "persistCooldownOnRestart": 1,
    "delay_close_if_player_nearby": 1,
    "use_safety_teleport": 1,
    "safety_teleport_radius": 50.0,
    "use_custom_teleport_points": 1,
    "custom_teleport_points": [ "3670.0 402.0 5995.0" ],

    "aiToSpawnOnOpen": [],
    "min_ai_to_spawn": -1,
    "max_ai_to_spawn": -1,

    "vehiclesToSpawn": [],
    "min_vehicles_to_spawn": -1,
    "max_vehicles_to_spawn": -1,

    "spawn_hacked_crate": 0,
    "hacked_crate_classname": "",
    "hacked_crate_position": "0 0 0",
    "hacked_crate_orientation": "0 0 0",
    "hacked_crate_config_id": ""
}

ℹ️ Note: Booleans may be written as 0/1 or false/true β€” the loader accepts both. Any parameter you omit falls back to the default listed in the tables below.


πŸ“‹ Parameter Reference

πŸ“ Core Identification

Parameter Type Default Description
x, y, z Float 0.0 World coordinates of the door itself. y = map northing, z = altitude (see coordinate note). Generated by the admin tools β€” do not edit manually.
building_x, building_y, building_z Float 0.0 World coordinates of the building, same swapped axis order. Generated by the admin tools β€” do not edit manually.
door_indices Array<Int> [] List of door indexes on the building that this config controls. Buildings number their doors 0, 1, 2...; one config can open several at once. Use the Door Scanner to read them.
Location_Name String "" A unique identifier for this door, used in logs, cooldown tracking and linked_doors references. Must be unique across all your door JSON files.
BuildingClassName String "" The classname of the building. Retrieved automatically by the admin tools.
linked_doors Array<String> [] Location_Name values of other door configs. When this door opens, all linked doors open simultaneously β€” ideal for double-door entrances or multi-entrance bunkers.

πŸ”‘ Keys & Keycards

Parameter Type Default Description
keycard_class_names Array<String> [] The current field. List of item classnames that can open this door β€” if the player holds any of them, access is granted. Example: ["BS_keycard_lab_red", "BS_keycard_master"].
keycard_class_name String "" Legacy single-key field. Still honored for backward compatibility, but prefer keycard_class_names. If both are set, the array takes priority.
showRequiredKeys Bool 1 1 = shows the required key name to players (e.g. "Requires Red Keycard"). 0 = shows a generic message ("Requires a key/keycard") β€” ideal for mystery/hardcore servers.
sound_accept String "Sound_Door_Accepted" SoundSet name played on successful unlock. Leave "" for silent.
sound_deny String "" SoundSet name played when a player without a valid key tries the door. Left empty (the default), the native vanilla locked-door sound of that exact door type plays β€” a wooden door creaks, a metal vault clanks. Set a SoundSet name for a custom sound instead. See 9. Sounds and Alarms.

πŸšͺ Door Behavior

Parameter Type Default Description
unlockOnly Bool 0 1 = the keycard only unlocks the door; the player must open it manually afterwards. 0 = door opens automatically.
use_continuous_action Bool 0 1 = uses a hold-to-open action instead of a single press β€” great for high-tier or dramatic doors. The action classname is ActionOpenKeyCardDoorContinuous, which you can target from Expansion Quest objectives β€” see 10. Expansion Integration.
continuous_action_time Float 5.0 How many seconds the player must hold the continuous action before the door opens. Only used when use_continuous_action is 1.
containers_only Bool 0 1 = containers spawn permanently on server start and the door itself is never opened by keycard. Used for persistent loot rooms.

⏱️ Timers

Parameter Type Default Description
min_unlock_time Int 0 Minimum seconds between keycard use and the door actually opening.
max_unlock_time Int 0 Maximum seconds. A random value between min and max is chosen.
min_restock_time Int 0 Minimum seconds the door stays open before auto-closing and despawning loot.
max_restock_time Int 0 Maximum seconds. A random value between min and max is chosen.

πŸ“’ Announcements & Alarms

Parameter Type Default Description
use_announcement Bool 0 1 = sends a global message to all players when the keycard is used. Automatically uses Expansion Notifications format if that mod is loaded.
announcement_title String "" Title of the announcement (e.g. "ALERT").
announcement_text String "" Body of the announcement message.
announcement_color_rgba String "255,255,165,0" Notification color as "Alpha,Red,Green,Blue" (0–255 each). Used with Expansion notifications.
announcement_duration_seconds Int 7 How long the announcement stays on screen, in seconds.
use_alarm Bool 0 1 = plays a looping alarm sound at the door's location while the event runs.
alarm_sound String "Alarm_Military" SoundSet classname used as the alarm. See 9. Sounds and Alarms for the built-in list and how to add your own.
alarm_duration Int 15 Total duration in seconds the alarm plays.
alarm_loop_delay Float 1.1 Seconds between each loop of the alarm sound. Lower = more frequent.

πŸ”” Countdown Notifications

Parameter Type Default Description
countdown_notifications Array<Object> [] List of warnings sent to nearby players as the door's closing time approaches. Each entry is a BS_NotificationConfig object (fields below).

Each entry of countdown_notifications:

Field Type Description
timeRemainingSeconds Int Fires when this many seconds remain before the door closes.
title String Notification title.
message String Notification body text.
color String Color as "Alpha,Red,Green,Blue" (0–255 each).
"countdown_notifications": [
    {
        "timeRemainingSeconds": 120,
        "title": "KeyRoom",
        "message": "Door closes in 2 minutes.",
        "color": "255,255,165,0"
    },
    {
        "timeRemainingSeconds": 30,
        "title": "KeyRoom",
        "message": "30 seconds! Leave now!",
        "color": "255,220,53,69"
    }
]

πŸ“¦ Loot & Containers

Parameter Type Default Description
containers Array<Object> [] List of KeyCardDoorContainer objects β€” the crates/boxes that spawn inside the room, with per-container loot pools, spawn chances, replacements, locks and open timers. Documented in full on 3. Advanced Loot System.
doorSpecificLootPools Array<Object> [] Loot pools defined inside this door config, which override the global pools of the same name for this door only. See 3. Advanced Loot System.
min_containers_to_spawn Int -1 Minimum number of containers randomly chosen from the containers array. -1 = always spawn all defined containers.
max_containers_to_spawn Int -1 Maximum number of containers to spawn. -1 = spawn all.

πŸ’‘ Tip: Setting min_containers_to_spawn / max_containers_to_spawn to something lower than your container count makes each opening spawn a random subset β€” no two raids look the same.


πŸ›‘οΈ Safety & Persistence

Parameter Type Default Description
persistCooldownOnRestart Bool 1 1 = the door's open/cooldown state is saved and survives server restarts. Highly recommended to keep at 1.
delay_close_if_player_nearby Bool 1 1 = the door will NOT close while alive players are within safety_teleport_radius; it re-checks every 60 seconds until the area is clear.
use_safety_teleport Bool 1 1 = players still inside the room are teleported outside so they don't get trapped. Runs when the door closes AND when a player logs in inside a closed room.
safety_teleport_radius Float 30.0 Radius in meters from the building center used by the safety-teleport scan. The login check uses this same radius β€” raise it for big rooms/bunkers so late log-ins are caught.
use_custom_teleport_points Bool 0 1 = teleports players to a specific point from custom_teleport_points instead of a random nearby position.
custom_teleport_points Array<Vector> [] List of engine vectors as "X Altitude Z" strings (regular in-game vector order β€” not the swapped door coordinates). A random point from the list is chosen each time.

⚠️ Warning: persistCooldownOnRestart protects cooldowns across normal restarts, but running !kcreload (or any manual config reload) is a full reset β€” it wipes all active cooldowns and door states. See 8. Admin Menu Guide and 11. FAQ & Troubleshooting.


πŸ€– AI Defenders

Parameter Type Default Description
aiToSpawnOnOpen Array<Object> [] List of KeyCardAISpawn configurations spawned when the door opens. See 4. AI Spawning System.
min_ai_to_spawn Int -1 Minimum number of AI randomly chosen from the list. -1 = spawn all.
max_ai_to_spawn Int -1 Maximum number of AI to spawn. -1 = spawn all.

πŸš— Vehicles

Parameter Type Default Description
vehiclesToSpawn Array<Object> [] List of KeyCardVehicleSpawn configurations spawned when the door opens. See 5. Vehicle Spawning System.
min_vehicles_to_spawn Int -1 Minimum number of vehicles randomly chosen from the list. -1 = spawn all.
max_vehicles_to_spawn Int -1 Maximum number of vehicles to spawn. -1 = spawn all.

πŸ”— Mod Integrations

Expansion Hardline (Reputation):

Parameter Type Default Description
reputationReward Int 0 Reputation points granted to the player who opens the door (requires Expansion Hardline). 0 = disabled. See 10. Expansion Integration.

Bastardos Hacked Crates:

Parameter Type Default Description
spawn_hacked_crate Bool 0 1 = spawns a hackable crate from the Bastardos Hacked Crates mod when the door opens.
hacked_crate_classname String "" The classname of the hackable crate to spawn.
hacked_crate_position Vector "0 0 0" Engine vector "X Altitude Z" where the crate spawns.
hacked_crate_orientation Vector "0 0 0" Orientation "Yaw Pitch Roll" of the crate.
hacked_crate_config_id String "" The ConfigUniqueID from the Hacked Crates mod configuration, defining which loot table the crate uses.

🍳 Recipes

Recipe 1 β€” Simple One-Key Door

A door that requires one red keycard, stays open for 5 minutes, and spawns 2 containers. Deny sound is left empty, so a wrong key plays the door's native vanilla locked sound.

{
    "x": 3689.39, "y": 5985.54, "z": 403.74,
    "building_x": 3686.41, "building_y": 5982.14, "building_z": 407.67,
    "door_indices": [ 0 ],
    "Location_Name": "GreenMountain_Main_Barracks",
    "BuildingClassName": "Land_Mil_Barracks5",
    "keycard_class_names": [ "BS_keycard_lab_red" ],
    "min_restock_time": 300,
    "max_restock_time": 300,
    "min_containers_to_spawn": 2,
    "max_containers_to_spawn": 2,
    "persistCooldownOnRestart": 1,
    "containers": [],
    "doorSpecificLootPools": []
}

Recipe 2 β€” Multi-Key Military Vault (Alarm + Announcement + AI)

Two keycards can open it, the whole server is warned, an alarm blares, AI guards spawn, players get countdown warnings, and the opener earns Hardline reputation. The hold-to-open action makes the breach take 8 tense seconds.

{
    "x": 4512.11, "y": 10218.65, "z": 339.20,
    "building_x": 4510.02, "building_y": 10215.30, "building_z": 341.85,
    "door_indices": [ 2 ],
    "Location_Name": "Tisy_Weapons_Vault",
    "BuildingClassName": "Land_Underground_Bunker",

    "keycard_class_names": [
        "BS_keycard_military_black",
        "BS_keycard_master"
    ],
    "showRequiredKeys": 0,

    "use_continuous_action": 1,
    "continuous_action_time": 8.0,
    "reputationReward": 250,

    "use_announcement": 1,
    "announcement_title": "VAULT BREACH",
    "announcement_text": "Someone is breaching the weapons vault at Tisy!",
    "announcement_color_rgba": "255,220,53,69",
    "announcement_duration_seconds": 10,

    "use_alarm": 1,
    "alarm_sound": "Alarm_Military",
    "alarm_duration": 60,
    "alarm_loop_delay": 1.1,

    "min_unlock_time": 10,
    "max_unlock_time": 20,
    "min_restock_time": 600,
    "max_restock_time": 900,

    "countdown_notifications": [
        {
            "timeRemainingSeconds": 60,
            "title": "VAULT",
            "message": "Vault seals in 1 minute!",
            "color": "255,255,165,0"
        },
        {
            "timeRemainingSeconds": 15,
            "title": "VAULT",
            "message": "Vault sealing β€” evacuate!",
            "color": "255,220,53,69"
        }
    ],

    "min_containers_to_spawn": 2,
    "max_containers_to_spawn": 4,
    "containers": [],
    "doorSpecificLootPools": [],

    "aiToSpawnOnOpen": [],
    "min_ai_to_spawn": 3,
    "max_ai_to_spawn": 6,

    "persistCooldownOnRestart": 1,
    "use_safety_teleport": 1,
    "safety_teleport_radius": 60.0
}

ℹ️ Note: Fill aiToSpawnOnOpen with your AI entries per 4. AI Spawning System, and containers per 3. Advanced Loot System. The empty arrays above are placeholders to keep the example focused.

Recipe 3 β€” Linked Double-Door with Custom Teleports

Two configs. Opening the main door also opens its linked partner; both send trapped players to fixed exit points instead of random spots. The big 70 m radius makes sure the login safety check covers the whole hall.

{
    "x": 8231.50, "y": 9520.10, "z": 292.30,
    "building_x": 8228.00, "building_y": 9517.40, "building_z": 294.10,
    "door_indices": [ 0 ],
    "linked_doors": [ "Hangar_East_Door" ],
    "Location_Name": "Hangar_West_Door",
    "BuildingClassName": "Land_Mil_Hangar_Big",

    "keycard_class_names": [ "BS_keycard_hangar_blue" ],
    "min_restock_time": 420,
    "max_restock_time": 420,

    "persistCooldownOnRestart": 1,
    "delay_close_if_player_nearby": 1,
    "use_safety_teleport": 1,
    "safety_teleport_radius": 70.0,
    "use_custom_teleport_points": 1,
    "custom_teleport_points": [
        "8210.0 291.5 9540.0",
        "8255.0 291.5 9500.0"
    ],

    "containers": [],
    "doorSpecificLootPools": []
}
{
    "x": 8248.20, "y": 9522.75, "z": 292.30,
    "building_x": 8228.00, "building_y": 9517.40, "building_z": 294.10,
    "door_indices": [ 1 ],
    "linked_doors": [ "Hangar_West_Door" ],
    "Location_Name": "Hangar_East_Door",
    "BuildingClassName": "Land_Mil_Hangar_Big",

    "keycard_class_names": [ "BS_keycard_hangar_blue" ],
    "min_restock_time": 420,
    "max_restock_time": 420,

    "persistCooldownOnRestart": 1,
    "delay_close_if_player_nearby": 1,
    "use_safety_teleport": 1,
    "safety_teleport_radius": 70.0,
    "use_custom_teleport_points": 1,
    "custom_teleport_points": [
        "8210.0 291.5 9540.0",
        "8255.0 291.5 9500.0"
    ],

    "containers": [],
    "doorSpecificLootPools": []
}

πŸ’‘ Tip: Link doors in both directions (each config lists the other in linked_doors) so the pair opens together no matter which side is unlocked first.


➑️ Next Steps

Clone this wiki locally