Repository navigation
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.
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:yandzare 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.7in 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_pointsandhacked_crate_positionfields, by contrast, are regular engine vectors in"X Altitude Z"order.
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.
The fastest way to generate a config file in the field:
-
Enable Debug Mode β In
BS_KeyRoom_Settings.json, setdebug_buildto1. -
Get the tool β Spawn the item
BS_DoorLockeras an admin. - Aim and hold β Point at the target door and hold the Left Mouse Button. The action is called "Setup Keycard Door".
-
Check your files β A new
.jsonis generated inDoorConfigs/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.
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.
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.
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/1orfalse/trueβ the loader accepts both. Any parameter you omit falls back to the default listed in the tables below.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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"
}
]| 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_spawnto something lower than your container count makes each opening spawn a random subset β no two raids look the same.
| 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:persistCooldownOnRestartprotects 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.
| 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. |
| 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. |
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. |
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": []
}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
aiToSpawnOnOpenwith your AI entries per 4. AI Spawning System, andcontainersper 3. Advanced Loot System. The empty arrays above are placeholders to keep the example focused.
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.
- Configure what spawns inside the room β 3. Advanced Loot System
- Learn the admin tools and Door Scanner β 8. Admin Menu Guide
- Custom alarms and door sounds β 9. Sounds and Alarms
- Quests, Hardline reputation and notifications β 10. Expansion Integration
- Something not working? β 11. FAQ & Troubleshooting
Getting Started
Configuration
- 2. Door Configuration
- 3. Advanced Loot System
- 4. AI Spawning System
- 5. Vehicle Spawning System
- 6. Keys & Keycards
- 7. Main Settings
In-Game Tools
Integrations & Help