Repository navigation
3. Advanced Loot System
The loot system is the most powerful and flexible feature of BS KeyRoom. It is configured within each door's JSON file through two arrays: doorSpecificLootPools and containers, plus reusable global pools defined in BS_KeyRoom_Settings.json.
⚠️ READ THIS FIRST —chanceToSpawnis a relative WEIGHT, NOT a percentage. Items in a pool are picked by a weighted roll against the other items in the same pool. Two items with weights1.0and0.5result in 66% / 33% odds — not 100% and 50%. If every item in a pool haschanceToSpawn: 1.0, they are all equally likely. To see the real drop rates for any container, use the Simulate Loot button in the admin menu's Containers tab — it performs 1000 virtual openings of the container and reports the actual percentage per item, without spawning anything into the world. See 8. Admin Menu Guide.
Three parameters at the door level control how many containers appear:
| Parameter | Type | Default | Description |
|---|---|---|---|
min_containers_to_spawn |
Int | -1 |
Minimum number of containers to spawn from the containers array. Set to -1 to always spawn all of them. |
max_containers_to_spawn |
Int | -1 |
Maximum number of containers to spawn. |
spawnChance (per container) |
Float | 1.0 |
Relative weight of each container in the random selection. |
When the system picks containers it performs a weighted random selection based on each container's spawnChance. A container with spawnChance: 1.0 is ten times more likely to be chosen than one with spawnChance: 0.1. If spawnChance is omitted it defaults to 1.0.
A Loot Pool is a reusable named list of potential items. You can define them in two places:
-
Global Pools — in
BS_KeyRoom_Settings.json. Available to every door on the server. Ideal for general tiers likeGlobal_Military_T3orGlobal_Medical_Basic. See 7. Main Settings. -
Door-Specific Pools — in the
doorSpecificLootPoolsarray inside a door's JSON. Only available to containers within that same door config. Ideal for unique location-exclusive rewards.
💡 Pools can be created and edited entirely in-game through the admin menu's pool editor windows — you can even copy and paste items between pools so you never have to retype an elaborate weapon-plus-attachments entry. See 8. Admin Menu Guide.
{
"lootPoolName": "Military_Weapons_HighTier",
"rewards": [
{
"name": "M4A1",
"chanceToSpawn": 0.5,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "M4_RISHndgrd",
"quantity": 1
},
{
"name": "M4_OEBttstck",
"quantity": 1
},
{
"name": "Mag_STANAG_30Rnd",
"quantity": 30
}
]
},
{
"name": "AKM",
"chanceToSpawn": 0.5,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "AK_WoodBttstck",
"quantity": 1
},
{
"name": "AK_WoodHndgrd",
"quantity": 1
},
{
"name": "Mag_AKM_30Rnd",
"quantity": 30
}
]
},
{
"name": "SVD",
"chanceToSpawn": 0.2,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "PSO1Optic",
"quantity": 1
},
{
"name": "Mag_SVD_10Rnd",
"quantity": 10
}
]
},
{
"name": "AmmoBox_556x45_20Rnd",
"chanceToSpawn": 1.0,
"quantityMin": 1,
"quantityMax": 3,
"attachments": []
}
]
}| Parameter | Type | Default | Description |
|---|---|---|---|
name |
String | — | The classname of the item to spawn. |
chanceToSpawn |
Float | — | Relative weight, not a percentage. Higher = more likely relative to the other items in the same pool. An item with 1.0 is twice as likely as one with 0.5. |
quantityMin |
Int | — | Minimum quantity to spawn (useful for ammo, food, magazines). |
quantityMax |
Int | — | Maximum quantity. A random value between min and max is used each time. |
attachments |
Array | [] |
Items to attach to this item when it spawns. See 3.3. The Attachment System. |
ℹ️ In the pool above, the odds per single roll are: AmmoBox ≈ 45%, M4A1 ≈ 23%, AKM ≈ 23%, SVD ≈ 9% (each weight divided by the total weight of 2.2). Verify with Simulate Loot.
Attachments work on both loot pool items (rewards) and fixed loot items (fixedItems). The system supports three modes that can be combined and nested recursively to any depth.
The item is always attached. quantity fills its ammo, charges, or durability:
{
"name": "M4A1",
"chanceToSpawn": 1.0,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "Mag_STANAG_30Rnd",
"quantity": 30
},
{
"name": "M4_RISHndgrd",
"quantity": 1
}
]
}Leave name empty and provide a random_names array. One item from the list is chosen randomly each time:
{
"name": "M4A1",
"chanceToSpawn": 1.0,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "Mag_STANAG_30Rnd",
"quantity": 30
},
{
"name": "",
"random_names": [
"ACOGOptic",
"M68Optic",
"BUISOptic"
]
}
]
}Attachments can have their own attachments. The nested items spawn on whichever item was selected. This works for both direct and randomized attachments and can go as deep as needed:
{
"name": "SNAFUKivaari_Tan_GUN",
"chanceToSpawn": 1.0,
"quantityMin": 1,
"quantityMax": 1,
"attachments": [
{
"name": "SNAFUKivaari_10rdMag",
"quantity": 10
},
{
"name": "",
"random_names": [
"ACOGOptic",
"M68Optic",
"BUISOptic"
],
"attachments": [
{
"name": "Battery9V",
"quantity": 1
}
]
}
]
}In this example: the magazine always spawns with 10 rounds. One of the three optics is chosen randomly. Whichever optic is selected will always have a battery already inside it.
💡 Admin menu tip: when adding attachments through the admin menu, the attachment browser automatically filters the item list to attachments actually compatible with the parent item — it matches the parent's config
attachments[]slots against each item'sinventorySlot[], plus directmagazines[]entries. A Show All toggle lets you switch back to the full unfiltered item list at any time. See 8. Admin Menu Guide.
Each container needs a precise position and orientation in the world.
⚠️ Incorrect values cause containers to spawn inside walls, floating in the air, or under the map.
The BS_DoorLocker admin tool only creates the door config — it does not place containers. You must get container coordinates separately.
- DayZ Editor — Offline mode tool for placing objects and exporting coordinates.
-
VPP Admin Tools or Community Online Tools — In-game admin mods with a
getposcommand.
- Load the map in Offline Mode or connect to your server with admin tools.
- Fly/teleport to the keycard room location.
- Spawn the container classname you want to use (e.g.
BS_Guncase). - Move and rotate it until it looks correct — not clipping walls, not floating.
- Use your tool's inspector or
getposcommand to copy the Position (X, Y, Z) and Orientation (Yaw, Pitch, Roll).
| JSON Field | Axis | Notes |
|---|---|---|
position |
[X, Y, Z] | Y = height above terrain |
orientation |
[Yaw, Pitch, Roll] | Yaw = left/right rotation |
Example — tool reports Position: 3678.131, 407.200, 5993.559 and Orientation: -123.196, 0.0, 0.0:
{
"referenceName": "Guncase_Main",
"className": "BS_Guncase",
"position": [
3678.131,
407.200,
5993.559
],
"orientation": [
-123.196,
0.0,
0.0
],
"spawnChance": 1.0,
"lootPoolName": "Military_Weapons_HighTier",
"lootMin": 2,
"lootMax": 2
}The containers array holds all possible containers for a door event. Each container can use one of four loot methods — or combine them freely.
Every field below is read from KeyCardDoorContainer in the mod source. Booleans can be written as 0/1 in JSON.
| Parameter | Type | Default | Description |
|---|---|---|---|
referenceName |
String | "X" |
Unique name for this container, used in logs and in the admin menu list. |
className |
String | "BS_Box1" |
The entity classname to spawn (e.g. BS_Guncase, BS_Box1_Black, BS_Box4_Green). |
position |
Array | [0,0,0] |
World coordinates [X, Y, Z]. |
orientation |
Array | [0,0,0] |
Rotation [Yaw, Pitch, Roll]. |
objectScale |
Float | 1.0 |
Visual scale multiplier. 0.75 = 75% size, 1.5 = 150% size. Only affects appearance, not hitbox. |
spawnChance |
Float | 1.0 |
Relative weight for this container during random container selection. |
| Parameter | Type | Default | Description |
|---|---|---|---|
lootPoolName |
String | "" |
Name of a single loot pool to draw random items from. |
randomLootPools |
Array<String> | [] |
List of pool names. Behavior depends on spawnFromAllPools. |
spawnFromAllPools |
Bool | false |
false = pick ONE pool from randomLootPools randomly. true = draw from EVERY listed pool. |
lootMin |
Int | 0 |
Minimum number of random items to spawn. |
lootMax |
Int | 0 |
Maximum number of random items to spawn. |
preventDuplicateLoot |
Bool | false |
true = the same item classname cannot appear more than once within a single opening of this container. |
useFixedLoot |
Bool | false |
true = enables the guaranteed items defined in fixedItems. |
fixedItems |
Array | [] |
List of guaranteed items. See Method A. |
lb_preset_name |
String | "" |
LBmaster Rework preset name. If set, bypasses the entire internal loot system. See Method C. |
⚠️ spawnFromAllPoolschanges whatlootMin/lootMaxmean. WithspawnFromAllPools: 1, the min/max item count is applied PER POOL, not in total. Three pools withlootMin: 2, lootMax: 4yield 6–12 items, not 2–4. Budget accordingly — and confirm with Simulate Loot.
| Parameter | Type | Default | Description |
|---|---|---|---|
requiredItem |
String | "" |
If set, the spawned container (must be a BS_Storage_Base crate) spawns locked and requires this item classname in the player's hands to unlock it. Can be any item classname — a shipped BS key, a keycard, or any mod/vanilla item. |
unlockTime |
Float | 3.0 |
Seconds of continuous hold time required to unlock the crate with requiredItem. |
consumeItem |
Bool | true |
true = the item used to unlock the crate is consumed/destroyed on use. false = the player keeps it. |
open_sound |
String | "" |
Custom sound set played when the crate opens. Empty = default. |
unlock_sound |
String | "" |
Custom sound set played when the crate is unlocked. Empty = default. |
unlock_anim_type |
String | "crafting" |
Player animation used during the unlock action. See the animation reference below. |
min_open_time |
Float | 0.0 |
0 = the crate opens instantly after unlocking. > 0 = the server schedules the crate to open automatically at a random time within [min_open_time, max_open_time] seconds. |
max_open_time |
Float | 0.0 |
Upper bound of the random open delay. Clamped to at least min_open_time. |
skip_open_item |
String | "" |
Classname of an item that, when held, bypasses the open countdown and opens the crate immediately. |
consume_skip_item |
Bool | true |
true = the skip item is destroyed on use. false = it is kept (e.g. a reusable master key). |
ℹ️ How the timed opening works: after a crate with
min_open_time > 0is unlocked, players see an "Opening in MM:SS" countdown on the interact prompt. Re-triggering the action during the countdown does nothing. Once the countdown completes (or the crate is opened viaskip_open_item), the opened state is sticky — the countdown never repeats for that spawned crate; closing and reopening it is instant for the rest of its lifetime.
💡 Combine the lock and timer for raid-style events:
requiredItemgates who can start the crate,min/max_open_timeforces defenders to hold the room, andskip_open_itemgives a rare bypass item a reason to exist.
These are the animation names accepted by the unlock action (the admin menu's animation picker lists the same set):
| Stance required | Animations |
|---|---|
| Crouch only |
crafting (default), bandage, cpr, shovel_dig, breaking_stick, cleaning_weapon, splitting_firewood, patching_tire, patching_ducttape, patching_sewing, patching_leather_kit
|
| Erect or crouch |
interact, disassemble, attach_scope, attach_barrel, clean_wounds_target
|
| Parameter | Type | Default | Description |
|---|---|---|---|
replacementChance |
Float | 0.0 |
Probability (0.0–1.0) that this container is replaced by the rarer variant on spawn. |
replacementClassName |
String | "" |
Classname of the replacement container. |
replacementLootPoolName |
String | "" |
Replaces lootPoolName when the swap occurs. |
replacementRandomLootPools |
Array<String> | [] |
Replaces randomLootPools. |
replacementLootMin |
Int | 0 |
Replaces lootMin. |
replacementLootMax |
Int | 0 |
Replaces lootMax. |
replacementUseFixedLoot |
Bool | false |
Replaces useFixedLoot. |
replacementFixedItems |
Array | [] |
Replaces fixedItems. |
replacementPreventDuplicateLoot |
Bool | false |
Replaces preventDuplicateLoot. |
replacement_lb_preset_name |
String | "" |
Replaces lb_preset_name. |
See Method D for details and examples.
Items in fixedItems always spawn regardless of anything else. They appear in addition to any random loot from pools.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
String | "" |
Item classname. |
quantity |
Int | 1 |
For non-stackable items (weapons, clothing): spawns this many individual units. For stackables: the stack amount. |
quantityMinPercent |
Float | 1.0 |
(Optional) Minimum fill level as a 0–1 fraction of the item's maximum stack/quantity (0.5 = 50% full). Use to spawn partially filled magazines, ammo stacks, food, or liquid containers. |
quantityMaxPercent |
Float | 1.0 |
(Optional) Maximum fill fraction. A random value between min and max percent is rolled each spawn. |
attachments |
Array | [] |
Attachments using the same recursive system from 3.3, including random_names variant lists and nested sub-attachments. |
Example — guaranteed medkit plus random extras:
{
"referenceName": "Medical_Crate",
"className": "BS_Box1_White",
"spawnChance": 1.0,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "BandageDressing",
"quantity": 4
},
{
"name": "SalineBag",
"quantity": 1
},
{
"name": "Morphine",
"quantity": 1
}
],
"lootPoolName": "Global_HighTier_Medical",
"lootMin": 0,
"lootMax": 2
}This container always contains 4 bandages, 1 saline bag, and 1 morphine, plus 0–2 random items from the medical pool.
Example — partially filled magazine using percent quantities:
{
"referenceName": "Partial_Ammo_Crate",
"className": "BS_Box4_Green",
"spawnChance": 1.0,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "Mag_STANAG_30Rnd",
"quantityMinPercent": 0.25,
"quantityMaxPercent": 0.75
}
],
"lootMin": 0,
"lootMax": 0
}The magazine spawns with between 25% and 75% of its maximum capacity — between 7 and 22 rounds. The same technique works for food (partially eaten cans), water bottles, and any stackable ammo.
💡 Admin menu tip: the Fixed Items editor has its own Duplicate button that deep-copies an entry including all of its nested attachments — handy for rows of similar magazines. See 8. Admin Menu Guide.
The simplest random loot setup. The container draws items from one named pool:
{
"referenceName": "Weapons_Crate",
"className": "BS_Box4_Green",
"spawnChance": 1.0,
"lootPoolName": "Military_Weapons_HighTier",
"lootMin": 1,
"lootMax": 3
}Use randomLootPools when you want to pull from several pools. The behavior is controlled by spawnFromAllPools.
Pick ONE pool randomly (spawnFromAllPools: 0):
The system selects one pool from the list at random, then draws items from it. The container will contain only weapons OR only gear, not both. lootMin/lootMax applies to that single selected pool.
{
"referenceName": "Random_Tier4_Crate",
"className": "BS_Box4_Green",
"spawnChance": 0.25,
"randomLootPools": [
"Global_Military_Weapons_T4",
"Global_Military_Gear_T4"
],
"spawnFromAllPools": 0,
"lootMin": 1,
"lootMax": 2,
"preventDuplicateLoot": 1
}Draw from ALL pools (spawnFromAllPools: 1):
The container rolls items from every listed pool in the same spawn, making the loot more diverse.
{
"referenceName": "Mixed_Tier4_Crate",
"className": "BS_Box4_Green",
"spawnChance": 0.25,
"randomLootPools": [
"Global_Military_Weapons_T4",
"Global_Military_Gear_T4",
"Global_Medical_Basic"
],
"spawnFromAllPools": 1,
"lootMin": 2,
"lootMax": 4,
"preventDuplicateLoot": 1
}
⚠️ Remember: withspawnFromAllPools: 1,lootMin/lootMaxis per pool. The crate above spawns 2–4 items from each of the three pools — 6 to 12 items total.
When enabled, the same item classname can never be rolled twice within one opening of the container. This is the tool for "pick 2 different rifles out of 5" style crates — without it, a small pool with a high lootMax will frequently spawn the same item multiple times. It applies across all pools drawn in that opening.
Bypasses the entire internal loot system and uses a preset defined in the LBmaster Rework mod. No fixedItems, lootPoolName, or lootMin/lootMax needed.
{
"referenceName": "SNAFU_M4_Crate",
"className": "BS_Guncase_Black",
"spawnChance": 1.0,
"lb_preset_name": "Full_SNAFU_M4_Kit"
}ℹ️
lb_preset_namemust match thepreset_namevalue in LBmaster's configuration exactly (case-sensitive). A replacement container can use its own preset viareplacement_lb_preset_name— see Method D.
A base container that has a chance to be swapped for a rarer one. When the roll succeeds, the replacement swaps the container classname AND its entire loot configuration — pools, fixed items, min/max counts, duplicate prevention, even the LBmaster preset. The swap is invisible to the player: they never see the original spawn, only the outcome.
Example — common tools box with a rare gun jackpot:
{
"referenceName": "Tools_or_Rare_Gun",
"className": "BS_Box1_White",
"spawnChance": 1.0,
"lootPoolName": "Global_Industrial_Tools",
"lootMin": 3,
"lootMax": 5,
"replacementChance": 0.10,
"replacementClassName": "BS_Guncase_Black",
"replacementUseFixedLoot": 1,
"replacementFixedItems": [
{
"name": "SVD",
"quantity": 1,
"attachments": [
{
"name": "PSO1Optic",
"quantity": 1
},
{
"name": "Mag_SVD_10Rnd",
"quantity": 10
}
]
}
],
"replacementLootMin": 0,
"replacementLootMax": 0
}- 90% of the time → White box with 3–5 random industrial tools.
- 10% of the time → Black guncase containing a scoped SVD with a loaded mag.
Example — common food box with a rare LBmaster kit:
{
"referenceName": "Food_or_LBmaster_Kit",
"className": "BS_Box4_Black",
"spawnChance": 1.0,
"lootPoolName": "Global_Civilian_Food",
"lootMin": 2,
"lootMax": 3,
"replacementChance": 0.05,
"replacementClassName": "BS_Guncase_Black",
"replacement_lb_preset_name": "Full_SNAFU_SVD_Kit"
}- 95% of the time → Black box with 2–3 food items.
- 5% of the time → Black guncase with a full SVD kit from LBmaster.
Everything on this page can be configured without touching a text editor. Highlights from 8. Admin Menu Guide:
- Simulate Loot (Containers tab) — runs 1000 virtual openings of the selected container using the exact same code path as a real spawn and shows the resulting per-item percentages and quantities. Use it after every pool change; it is the ground truth for your weights.
- Pool editor windows — edit global and door-specific pools side by side, with an item preview and per-item weight/quantity fields.
- Copy / paste items between pools — a clipboard lets you move a fully configured reward (attachments included) from one pool to another.
- Duplicate Container — performs a full deep copy of a container: loot pool references, fixed items, nested attachments, lock settings, and replacement config are all cloned. Ideal for placing a row of similar crates.
- Attachment browser compatibility filter — when picking attachments, the browser lists only items compatible with the parent (matched via config attachment slots and magazines), with a Show All toggle to lift the filter.
A full door config combining global pools, door-specific pools, fixed loot, replacements, and a locked, timed crate:
{
"Location_Name": "GreenMountain_Barracks_Main",
"BuildingClassName": "Land_Mil_Barracks5",
"keycard_class_name": "BS_keycard_lab_red",
"min_restock_time": 300,
"max_restock_time": 600,
"min_containers_to_spawn": 2,
"max_containers_to_spawn": 3,
"doorSpecificLootPools": [
{
"lootPoolName": "GreenMountain_Exclusive",
"rewards": [
{
"name": "NVGoggles",
"chanceToSpawn": 0.3,
"quantityMin": 1,
"quantityMax": 1,
"attachments": []
},
{
"name": "GPS",
"chanceToSpawn": 0.5,
"quantityMin": 1,
"quantityMax": 1,
"attachments": []
}
]
}
],
"containers": [
{
"referenceName": "Main_Weapons_Crate",
"className": "BS_Box4_Green",
"position": [
3678.131,
407.200,
5993.559
],
"orientation": [
-123.196,
0.0,
0.0
],
"spawnChance": 1.0,
"lootPoolName": "Global_Military_Weapons_T3",
"lootMin": 1,
"lootMax": 2,
"preventDuplicateLoot": 1,
"replacementChance": 0.10,
"replacementClassName": "BS_Guncase_Black",
"replacementLootPoolName": "Global_Military_Weapons_T4",
"replacementLootMin": 1,
"replacementLootMax": 2
},
{
"referenceName": "Locked_Special_Crate",
"className": "BS_Box1_Black",
"position": [
3680.000,
407.200,
5991.000
],
"orientation": [
0.0,
0.0,
0.0
],
"spawnChance": 0.5,
"requiredItem": "BS_keycard_lab_blue",
"unlockTime": 5.0,
"consumeItem": 1,
"unlock_anim_type": "crafting",
"min_open_time": 60.0,
"max_open_time": 180.0,
"skip_open_item": "BS_keycard_lab_black",
"consume_skip_item": 1,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "NVGoggles",
"quantity": 1
}
],
"lootPoolName": "GreenMountain_Exclusive",
"lootMin": 1,
"lootMax": 2
},
{
"referenceName": "Medkit_Box",
"className": "BS_Box1_White",
"position": [
3676.500,
407.200,
5994.000
],
"orientation": [
45.0,
0.0,
0.0
],
"spawnChance": 0.75,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "BandageDressing",
"quantity": 3
},
{
"name": "Epinephrine",
"quantity": 1
}
],
"lootPoolName": "Global_Medical_Basic",
"lootMin": 0,
"lootMax": 1
}
]
}The Locked_Special_Crate above tells a complete story: it needs a blue lab keycard (consumed) and a 5-second unlock hold, then announces itself with a 1–3 minute opening countdown that attackers must defend — unless someone holds the rare black keycard to skip the wait.
- Configure AI defenders → 4. AI Spawning System
- Set up doors and keycards → 2. Door Configuration, 6. Keys and Keycards Configuration
- Learn the in-game editor → 8. Admin Menu Guide
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