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.
Three parameters at the door level control how many containers appear:
| Parameter | Type | Description |
|---|---|---|
min_containers_to_spawn |
Int | Minimum number of containers to spawn from the containers array. Set to -1 to always spawn all. |
max_containers_to_spawn |
Int | Maximum number of containers to spawn. |
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. -
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.
⚠️ chanceToSpawnis a relative WEIGHT, not a percentage. Items are picked by weighted roll within the pool: weights 1.0 and 0.5 mean 66%/33%, not 100%/50%. Use Simulate Loot in the Containers tab (1000 virtual openings) to verify real drop rates.
{
"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 | Description |
|---|---|---|
name |
String | The className of the item to spawn. |
chanceToSpawn |
Float | Relative weight — not a percentage. Higher = more likely relative to other items in the same pool. Example: 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 the Attachment System below. |
Attachments work on both loot pool items (rewards) and fixed loot items (fixedItems). The system supports three modes that can be combined and nested 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.
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
classNameyou 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.
| Parameter | Type | Default | Description |
|---|---|---|---|
referenceName |
String | — | Unique name for this container, used in logs. |
className |
String | — | The entity classname to spawn (e.g. BS_Guncase, BS_Box1_Black, BS_Box4_Green). |
position |
Array | — | World coordinates [X, Y, Z]. |
orientation |
Array | — | Rotation [Yaw, Pitch, Roll]. |
spawnChance |
Float | 1.0 |
Weighted probability this container is selected during random spawn. |
objectScale |
Float | 1.0 |
Visual scale multiplier. 0.75 = 75% size, 1.5 = 150% size. Only affects appearance, not hitbox. |
requiredItem |
String | "" |
If set, the spawned container (must be a BS_Storage_Base) is locked and requires this item classname to open it. |
unlockTime |
Float | 0 |
Seconds of hold time required to unlock the container using requiredItem. |
consumeItem |
0 or 1 | 0 |
1 = The item used to unlock the container is consumed/destroyed on use. |
useFixedLoot |
0 or 1 | 0 |
1 = Enables guaranteed fixed items defined in fixedItems. |
fixedItems |
Array | [] |
List of guaranteed items. See Method A. |
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 |
0 or 1 | 0 |
0 = pick ONE pool randomly. 1 = draw from ALL listed pools combined. |
lootMin |
Int | 0 |
Minimum number of random items to spawn. |
lootMax |
Int | 0 |
Maximum number of random items to spawn. |
preventDuplicateLoot |
0 or 1 | 0 |
1 = The same item classname cannot appear more than once in this container. |
lb_preset_name |
String | "" |
LBmaster Rework preset name. If set, bypasses the entire internal loot system. |
replacementChance |
Float | 0.0 |
Probability (0.0–1.0) this container is replaced by a rarer variant on spawn. |
replacementClassName |
String | "" |
The classname of the replacement container. |
Items in fixedItems always spawn regardless of anything else. They appear in addition to any random loot from pools.
| Parameter | Type | Description |
|---|---|---|
name |
String | Item classname. |
quantity |
Int | For non-stackable items (weapons, clothing): spawns this many individual units. |
quantityMinPercent |
Float |
(Optional) For stackable items only: minimum fill as a fraction of max capacity (0.5 = 50%). Overrides quantity when set. |
quantityMaxPercent |
Float | (Optional) Maximum fill fraction. A random value between min and max percent is used. |
attachments |
Array | Attachments using the same nested system from section 3.3. |
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 — weapon with partial ammo using quantityMinPercent:
{
"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 ammo capacity (between 7 and 22 rounds).
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.
{
"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 combined (spawnFromAllPools: 1):
All listed pools are merged into one big temporary table. The container can contain items from any of them 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
}Bypasses the entire internal loot system and uses a preset defined in the LBmaster Rework mod. No fixedItems, lootPoolName, or lootMin/Max needed.
{
"referenceName": "SNAFU_M4_Crate",
"className": "BS_Guncase_Black",
"spawnChance": 1.0,
"lb_preset_name": "Full_SNAFU_M4_Kit"
}lb_preset_name must match the preset_name value in LBmaster's configuration exactly (case-sensitive).
A base container that has a chance to be swapped for a rarer one with a completely different classname and loot configuration. The replacement is invisible to the player — they never see the original spawn.
| Parameter | Overrides |
|---|---|
replacementChance |
Probability (0.0–1.0) the replacement occurs |
replacementClassName |
className |
replacementUseFixedLoot |
useFixedLoot |
replacementFixedItems |
fixedItems |
replacementLootPoolName |
lootPoolName |
replacementRandomLootPools |
randomLootPools |
replacementLootMin |
lootMin |
replacementLootMax |
lootMax |
replacementPreventDuplicateLoot |
preventDuplicateLoot |
replacement_lb_preset_name |
lb_preset_name |
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.
A full door config combining global pools, door-specific pools, fixed loot, replacements, and a locked 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,
"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
}
]
}Configure AI defenders → [4. AI Spawning System](4.-AI-Spawning-System)
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