Skip to content

6. Keys and Keycards Configuration

cjcarw edited this page Jul 15, 2026 · 2 revisions

🔑 6. Keys and Keycards Configuration

The BS_KeyRoom_ItemNames.json file lets you customize any key or keycard item without repacking PBOs. You can change its in-game display name, its description, and define how many uses it has before being destroyed.

💡 You don't have to edit this file by hand at all — every entry can be created and edited live in-game from the admin menu's Keycards tab, which includes a rotating 3D preview of the selected item. See 8. Admin Menu Guide.


File Location

$profile/BS_KeyRoom/BS_KeyRoom_ItemNames.json

If the file does not exist, the server generates it on first start, pre-populated with default names and descriptions for every shipped key and keycard.


Structure

The file contains a single KeyCardEntries array. Each object in the array targets one item classname.

{
    "KeyCardEntries": [
        {
            "ClassName": "BS_keycard_lab_red",
            "DisplayAndDescription": "Red Laboratory Keycard|Grants access to the most restricted military research zones. Single use.",
            "MaxUses": 1
        },
        {
            "ClassName": "BS_bluekey1",
            "DisplayAndDescription": "Tisy Prison Key|Opens the prison block at Tisy Military Base.",
            "MaxUses": 5
        },
        {
            "ClassName": "BS_keycard_lab_green",
            "DisplayAndDescription": "Green Access Card|Standard facility access. Reusable.",
            "MaxUses": 0
        },
        {
            "ClassName": "BS_yellowkey2",
            "DisplayAndDescription": "Bunker Master Key|Infinite-use administrative override.",
            "MaxUses": -1
        }
    ]
}

Parameter Reference

Parameter Type Default Description
ClassName String — The exact classname of the item you want to customize. Must match the in-game classname exactly (case-sensitive).
DisplayAndDescription String — The item's display name and description in one string, separated by a single pipe character. Format: "Display Name|Description text here."
MaxUses Int 1 Controls how many times the item can be used before being destroyed. See the table below.

⚠️ The DisplayAndDescription format uses exactly one pipe | as the separator between name and description. Do not use | inside the name or description text itself.


MaxUses Explained

The use counter is appended to the item's display name in-game and updates live as the key is used.

Value Behavior Counter shown in name
1 Single-use. Destroyed after one use. [1/1]
N > 1 (e.g. 5) Multiple uses. Counter counts down; the item is destroyed on the last use. [5/5] → [4/5] → …
-1 Infinite uses. Never destroyed. [∞]
0 Hidden single-use. Consumed after one use, but no counter is shown in the name. (none)

ℹ️ How it works under the hood: the remaining-use count is stored on each individual item and synchronized to clients, so two copies of the same key class can show different counters. A key is deleted the moment its remaining uses reach 0 — unless MaxUses is -1.


Keys Can Be ANY Item

The entries in this file are not limited to the shipped BS_* keys. Doors and locked crates accept any item classname as their required item (keycard_class_name on doors, requiredItem / skip_open_item on crates) — a vanilla Screwdriver, a custom mod item, anything. Add an entry for that classname here and it gains a custom name, description, and use counter just like a shipped key.

See 2. Door Configuration and 3. Advanced Loot System for where required items are assigned.


Editing In-Game (Keycards Tab)

The admin menu's Keycards tab is the fastest way to manage this file:

  • Browse and filter every key/keycard entry, with a live 3D item preview.
  • Edit the display name, description, and Max Uses fields directly — no JSON syntax to get wrong.
  • Changes are saved back to BS_KeyRoom_ItemNames.json on the server.

Full walkthrough: 8. Admin Menu Guide.


Expansion Integration

When DayZ Expansion is loaded, your custom names and descriptions are picked up automatically — no extra configuration:

  • Expansion Quests — quest reward lists show the custom key/keycard name instead of the raw classname.
  • Expansion item tooltips — hovering a key shows your custom name and description.

Details: 10. Expansion Integration.


Shipped Key and Keycard Classes

These are the item classes included in the mod (from Keys/config.cpp). Use them in door configs, crate locks, loot pools, and this file.

Grey Keys

Classname Default assignment
BS_Key1 Fire Station, Chernogorsk
BS_Key2 Police booth, Balota Airfield
BS_Key3 Hunting cabin, Skalisty Island
BS_Key4 Police Department, Elektrozavodsk
BS_Key5 Police office, Elektrozavodsk
BS_Key6 Medical clinic, Berezino
BS_Key7 Factory, Berezino industrial area
BS_Key8 Garages, Chernogorsk
BS_Key9 Orlets Factory offices
BS_Key10 Restaurant, Svetlojarsk
BS_Key11 Hospital, Chernogorsk
BS_Key12 ATC tower, Krasnostav Airfield
BS_Key13 Pub, Severograd
BS_Key14 Guardhouse, Myshkino military tents
BS_Key23 General store, Zelenogorsk

Colored Keys

Classname Default assignment
BS_bluekey1 Prison block, Tisy Military Base
BS_bluekey2 Police HQ, Severograd
BS_bluekey3 Officer barracks, NWAF
BS_bluekey4 ATC Tower, NEAF
BS_greenkey1 Main checkpoint, Pavlovo Military Base
BS_greenkey2 Large hangar, NWAF
BS_greenkey3 Radar Command building, Tisy
BS_greenkey4 Industrial Barracks, Veresnik
BS_redkey1 Fire station, Tisy Military Base
BS_redkey2 HQ building, Krasnostav Airfield
BS_redkey3 Main hospital, Pavlovo Military
BS_redkey4 Guard tower, hidden military outpost
BS_yellowkey1 Holding cells, Myshkino Tents
BS_yellowkey2 Hidden underground bunker
BS_yellowkey3 Captain's quarters, Rify shipwreck
BS_blackkey1 (unassigned — free for custom use)
BS_blackkey2 (unassigned — free for custom use)

Lab Keycards

Classname Default assignment
BS_keycard_lab_white Unknown purpose (free for custom use)
BS_keycard_lab_green Restricted office, Tisy Command Center
BS_keycard_lab_blue ATC control room, NEAF
BS_keycard_lab_orange Main hangar, NWAF
BS_keycard_lab_red High-clearance / top-secret locations
BS_keycard_lab_violet Experimental labs (mystery card)
BS_keycard_lab_yellow Contaminated area, Rify shipwreck
BS_keycard_lab_black Fortified underground bunker

ℹ️ "Default assignment" is only the flavor text shipped in the auto-generated BS_KeyRoom_ItemNames.json — every key is fully re-assignable to any door or crate. The default file also pre-seeds name entries for the extended BS_New_* key series (White/Blue/Green/Red/Silver/Medic/Yellow variants) used by companion key packs.


Practical Examples

Standard high-tier keycard — single use, dramatic name

{
    "ClassName": "BS_keycard_lab_red",
    "DisplayAndDescription": "Red Laboratory Keycard|Eyes Only. Single-use access to restricted research areas.",
    "MaxUses": 1
}

Reusable key for a regular locked room

{
    "ClassName": "BS_bluekey1",
    "DisplayAndDescription": "Sector B Key|Opens Sector B storage. Returns to pocket after use.",
    "MaxUses": 10
}

Mystery keycard — players can't see how many uses remain

{
    "ClassName": "BS_keycard_lab_violet",
    "DisplayAndDescription": "Unknown Access Card|Its purpose is unclear...",
    "MaxUses": 0
}

Admin/event key that never breaks

{
    "ClassName": "BS_blackkey1",
    "DisplayAndDescription": "Master Override Key|Administrative access. Infinite uses.",
    "MaxUses": -1
}

A vanilla item as a key

{
    "ClassName": "Screwdriver",
    "DisplayAndDescription": "Improvised Lockpick|Looks like it could force a simple lock. Once.",
    "MaxUses": 1
}

Notes

  • Only items listed in this file have their names and use counts customized. Items not listed keep their default values from the PBO config.
  • You do not need to restart the server after editing this file — type the !kcreload admin chat command to reload configs live, or edit through the Keycards tab which saves immediately.
  • Entries are matched by exact, case-sensitive classname.

Next Steps

Configure global mod settings and global loot pools → 7. Main Settings

Clone this wiki locally