Skip to content

1. Initial Setup

cjcarw edited this page Jul 15, 2026 · 12 revisions

🛠️ 1. Initial Setup & File Structure

After the first server launch, the mod creates a primary folder named BS_KeyRoom inside your server's profile directory ($profile:). Understanding this structure is essential before you begin configuring the mod.

If the folder does not exist, the mod did not load — go back to 0. Installation and check the verification steps.


📁 Folder Structure

$profile/
└── BS_KeyRoom/
    ├── DoorConfigs/                        ← Individual door JSON files go here
    │   └── GreenMountainRedKeycard.json    ← Auto-generated example
    ├── logs/                               ← Detailed debug/admin logs
    ├── BS_KeyRoom_Settings.json            ← Global settings & global loot pools
    ├── BS_KeyRoom_ItemNames.json           ← Keycard/key names, descriptions, use counts
    ├── BS_KeyRoom_Cooldowns.json           ← Active door cooldowns (auto-managed, do not edit)
    └── admins.txt                          ← Steam64IDs with access to admin commands

What Each File Does

File / Folder Role You edit it?
DoorConfigs/ One JSON file per keycard door event. Each file defines the door, its keycard, timers, loot, AI, vehicles, alarms, and announcements. See 2. Door Configuration. ✅ Yes — this is where most of your work happens
DoorConfigs/GreenMountainRedKeycard.json Fully working example door at Green Mountain, generated on first boot. Copy it as a template for new doors. ✅ Yes — duplicate & modify
logs/ Detailed debug and admin logs (player interactions, door events). Enabled via admin_log in the settings file. ❌ No — read-only for reviewing activity
BS_KeyRoom_Settings.json Global control file: debug mode, logging, timer text, and global loot pools shared across doors. See 7. Main Settings. ✅ Yes
BS_KeyRoom_ItemNames.json Defines which items act as keys/keycards, their in-game display names, descriptions, and number of uses. See 6. Keys and Keycards Configuration. ✅ Yes
BS_KeyRoom_Cooldowns.json Tracks active door cooldowns so restock timers survive server restarts. ❌ Never — auto-managed
admins.txt Steam64IDs of players allowed to use the admin menu and admin commands. ✅ Yes — first thing to set up

⚠️ Warning: Do not manually edit BS_KeyRoom_Cooldowns.json. This file is managed automatically by the mod to persist door states across server restarts. Editing it by hand can desynchronize door cooldowns.


Initial Configuration Steps

Before creating your first door, configure these three essential files.


1. Set Up Admins (admins.txt)

This file grants players access to admin-only features — the in-game admin menu (K key) and the !kcreload chat command.

  • Open admins.txt.
  • Add the Steam64ID of each admin, one per line.
  • You can find a player's Steam64ID using steamid.io.

Example:

76561198000000001
76561198000000002

ℹ️ Note: The admin list is cached for 30 seconds, so a freshly added Steam64ID may take up to 30 seconds to become active. Typing !kcreload in chat applies changes instantly — no waiting, no restart.


2. Review Main Settings (BS_KeyRoom_Settings.json)

This is the global control file. The most critical setting at this stage is debug_build.

Setting Value Description
debug_build 1 Enables the in-game admin tool (BS_DoorLocker) for creating door configs
debug_build 0 Disables the admin tool. Always set to 0 on a live public server
admin_log 1 Writes detailed player interaction logs to the logs/ folder
showDoorTimerText 1 Shows "Door closing in Xm Xs" to players looking at an open door

ℹ️ Note: Full details on all settings are in 7. Main Settings.


3. Understand Key Configuration (BS_KeyRoom_ItemNames.json)

This file lets you customize which items act as keys, what they display in-game, and how many uses they have — all without repacking PBOs.

No changes are required immediately, but it is good to know where it lives. Full details are in 6. Keys and Keycards Configuration.


🚪 First-Boot Example: Green Mountain

On first boot, the mod auto-generates a complete example door config: DoorConfigs/GreenMountainRedKeycard.json — a red-keycard door at Green Mountain. It is a real, working configuration you can test immediately:

  1. Spawn the corresponding red keycard (via the admin menu or your usual admin tools).
  2. Travel to Green Mountain and swipe the keycard at the configured door.
  3. Watch the full event cycle: door opens, loot spawns, timer counts down, door relocks.

💡 Tip: When building your own doors by hand, duplicate this example file, rename it, and adjust the values — it demonstrates the full JSON structure documented in 2. Door Configuration.


Admin Commands & Shortcuts

Once your Steam64ID is listed in admins.txt, you have access to these:

Action How Description
Open admin panel Press K in-game Opens the full BS KeyRoom admin GUI. Only works for players listed in admins.txt.
Reload configs Type !kcreload in chat Reloads all door configs, settings, and the admin list from disk without restarting the server.

💡 Tip: The K key is the main way to access the admin menu in-game. From there you can create doors, edit loot, manage AI/vehicles, and toggle global settings — all without touching any JSON files directly. Full walkthrough in 8. Admin Menu Guide.


⚡ Your First Door in 5 Minutes

The fastest way to create a door is entirely in-game via the admin menu — no JSON editing needed:

  1. Add yourself as admin. Put your Steam64ID in admins.txt (see above). If the server is already running, type !kcreload in chat to apply it instantly.
  2. Join the server and press K. The BS KeyRoom admin menu opens (8. Admin Menu Guide).
  3. Walk up to the door you want to lock and create a new door config from the menu (or use the BS_DoorLocker tool — see the Door Scanner tip below).
  4. Pick the keycard, timers, and loot in the menu — sensible defaults are pre-filled, and you can refine loot pools later in 3. Advanced Loot System.
  5. Save and test. Spawn the keycard, swipe it at the door, and watch your first keyroom event run.

💡 Tip — Finding door indices with the Door Scanner: Buildings often have many doors, and each config needs the right door index. With debug_build set to 1 in 7. Main Settings, hold the BS_DoorLocker item in your hands — floating index tags appear over every door around you, so you can read off the exact index you need. See 2. Door Configuration for how indices are used.

⚠️ Warning: Remember to set debug_build back to 0 before opening your server to the public.


Next Steps

Now you are ready to create your first keycard door. See 2. Door Configuration, then dive into loot (3. Advanced Loot System), AI defenders (4. AI Spawning System), and vehicle rewards (5. Vehicle Spawning System).

Clone this wiki locally