Repository navigation
3. Advanced Loot System
The loot system is the most powerful and flexible feature of BS KeyRoom. This guide explains how to master it, from creating simple loot lists to building complex, multi-layered reward scenarios.
The entire system is configured within each door's JSON file, primarily through two arrays: doorSpecificLootPools and containers.
Before defining a container's content, it is crucial to understand how the system decides which and how many containers will spawn in the world. This is controlled by three parameters at the top level of your door's JSON configuration:
| Parameter | Type | Description |
|---|---|---|
min_containers_to_spawn |
int |
The minimum number of containers (from the containers array) that will spawn. If you want all defined containers to always spawn, set this to -1. |
max_containers_to_spawn |
int |
The maximum number of containers that will spawn. |
When you use these parameters to generate a random number of containers (e.g., between 2 and 4), the system performs a weighted random selection. This is where the spawnChance parameter on each individual container becomes critical.
-
The Logic: The system first decides how many containers it will generate (a number between your
minandmax). Then, it looks at all available containers in thecontainersarray and picks them one by one, based on the "weight" of theirspawnChance, until the target number is reached. -
Why it Matters: A container with
"spawnChance": 1.0is ten times more likely to be chosen than a container with"spawnChance": 0.1. IfspawnChanceis not specified in a container, its value defaults to1.0.
These are the fundamental components that define what can spawn inside a container.
A "Loot Pool" is a reusable list of potential items. Think of it as a themed category of loot. You can define them in two places:
-
Global Pools: Defined once in the
BS_KeyRoom_Settings.jsonfile. These pools can be used by any door on the server, perfect for general categories likeGlobal_Military_ToolsorGlobal_Medical_Supplies. -
Door-Specific Pools: Defined inside a door's JSON file within the
doorSpecificLootPoolsarray. These pools can only be used by containers within that same door's configuration, ideal for creating unique rewards for a specific location.
Each item within a loot pool's rewards array has the following parameters:
| Parameter | Type | Description |
|---|---|---|
name |
string |
The className of the item. |
chanceToSpawn |
float |
This is a weight, not a percentage. It determines the item's chance of being selected relative to other items in the same pool. An item with a weight of 0.5 is twice as likely to be picked as an item with a weight of 0.25. |
quantityMin |
int |
The minimum quantity the item should spawn with (useful for ammo, bandages, etc.). |
quantityMax |
int |
The maximum quantity. A random value between min and max will be chosen. |
attachments |
array |
A list of attachments to spawn on this item, using the advanced attachment system detailed below. |
Below is a practical example of a loot pool definition named "Military_Weapons_HighTier". This structure can be placed inside the doorSpecificLootPools array in a door's JSON, or inside the lootPools array in the global BS_KeyRoom_Settings.json file.
This example demonstrates the correct usage of all parameters, including quantity for attachments like magazines.
{
"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": "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": []
}
]
}This powerful system is used in both Loot Pools (rewards) and Fixed Loot containers (fixedItems). It allows you to define attachments that are guaranteed, randomized, and even nested within each other.
{
"name": "SNAFUKivaari_Tan_GUN",
"quantity": 1,
"attachments": [
{
"name": "SNAFUKivaari_10rdMag",
"quantity": 10
},
{
"name": "",
"random_names": [
"ACOGOptic",
"M68Optic",
"BUISOptic"
],
"attachments": [
{
"name": "Battery9V"
}
]
}
]
}-
Direct Attachment: The item will always spawn with a SNAFUKivaari_10rdMag attached. The magazine itself will contain 10 rounds ("quantity": 10).
-
Randomized Attachment: By leaving name empty and providing an array for random_names, the mod will randomly select one of the three optics from the list to attach.
-
Nested Attachment: The Battery9V is nested inside the randomized optic. This means whichever optic is randomly chosen, it is guaranteed to spawn with a battery already inside it. You can nest attachments as deep as you need.
Once your door is configured, the next step is to place the loot containers inside the room.
Each container needs a precise position and orientation to spawn correctly.
The BS_DoorLocker admin tool is only for creating the initial door configuration; it does not place loot containers.
You must get the coordinates for each container manually.
✅ The recommended method is to use an admin tool that allows you to see object coordinates in real time.
- DayZ Editor: Similar to Offline Mode, powerful for placing objects and exporting data.
-
Other server admin tools(VPP ADMIN TOOLS-Community-Online-Tool) that provide a
GetPosorgetposcommand.
-
Load the Map
Start your server in Offline Mode or open the map in DayZ Editor.
👉 You can also do this online by moving the container with coordinates using admin tools like VPP or Community Online Tools. -
Go to the Room
Use admin flight/teleport to reach your keycard room location. -
Place a Container
Spawn the container (className) you want to use.
Example:BS_Guncase,BS_Box1_Black. -
Position and Rotate
Move and rotate the object using your tool’s features.
Make sure it’s not clipping into walls or floating. -
Copy the Coordinates
Use your tool’s inspector or command to get:- Position → vector (X, Y, Z).
- Orientation → vector (Yaw, Pitch, Roll).
The coordinates are written exactly as they appear in-game — no axis swapping.
| JSON Field | In-Game Axis | Description |
|---|---|---|
position |
(X, Y, Z) | World-space position (Y = height). |
orientation |
(Yaw, Pitch, Roll) | Object rotation. |
Your admin tool shows:
-
Position:
3678.131, 407.200, 5993.559→ (X, Y, Z) -
Orientation:
-123.196, 0.0, 0.0→ (Yaw, Pitch, Roll)
You would enter this into your containers array like this:
{
"referenceName": "Guncase1",
"className": "BS_Guncase",
"spawnChance": 1.0,
"position": [
3678.131, // X value (East/West)
407.200, // Y value (Height)
5993.559 // Z value (North/South)
],
"orientation": [
-123.196, // Yaw
0.0, // Pitch
0.0 // Roll
],
"lootPoolName": "Weapons1",
"lootMin": 2,
"lootMax": 2
}Summary
-
position = [X, Y, Z] → Y is always the height.
-
orientation = [Yaw, Pitch, Roll].
A container is the physical object (a crate, a chest, etc.) that will hold the loot. The containers array in your door's JSON holds a list of all potential containers for that location.
Each container can use one of three distinct loot spawning methods.
This method allows you to add a layer of predictable, guaranteed items to a container. These items will spawn in addition to any random loot generated from loot pools.
-
useFixedLoot: Must be set to1to enable this feature. If set to0, thefixedItemsarray will be ignored. -
fixedItems: An array of items that are guaranteed to spawn ifuseFixedLootis enabled. It uses the same advanced attachment structure. -
Special Parameters for
fixedItems:-
quantity: For non-stackable items (like rifles), this will spawn that many individual units. -
quantityMinPercent/quantityMaxPercent: (Optional) Overridesquantityfor stackable items. Spawns the item with a random quantity between these two percentages of its maximum capacity (e.g.,0.5= 50%).
-
The true power of the system comes from using both methods together. A container can have guaranteed items from fixedItems and still draw random items from a lootPoolName or randomLootPools.
Comprehensive Example:
This container is configured to always spawn a basic medical kit, but also has a chance to spawn additional, high-tier random medical supplies.
{
"referenceName": "Medical_Supply_Crate",
"className": "BS_Box1_White",
"spawnChance": 1.0,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "BandageDressing",
"quantity": 4
},
{
"name": "SalineBag",
"quantity": 1
}
],
"lootPoolName": "Global_HighTier_Medical",
"lootMin": 0,
"lootMax": 2
}Use this method for dynamic, unpredictable rewards drawn from your Loot Pools. This is the most common way to configure loot.
-
lootPoolName: (String) The name of a single pool to draw items from. -
randomLootPools: (Array of Strings) An array of pool names. If this is used,lootPoolNameis ignored. Its behavior changes based on thespawnFromAllPoolsparameter below. -
spawnFromAllPools: (0 or 1) This is a crucial switch for howrandomLootPoolsworks:- If
0(or omitted), the system will randomly select one single pool from therandomLootPoolslist to spawn items from. - If
1, the system will attempt to draw items from every pool listed inrandomLootPools, effectively merging them into one giant loot table for this container.
- If
-
lootMin/lootMax: (Integers) The total number of random items to spawn from the selected pool(s). -
preventDuplicateLoot: (0 or 1) If set to1, the system will not spawn the same item type more than once in this container, even if it's drawn from different pools.
- This is the default behavior. The container will spawn loot from either the Weapons pool OR the Gear pool, but not both.
{
"referenceName": "Random_Military_Crate_Single_Pool",
"className": "BS_Box4_Green",
"spawnChance": 0.25,
"randomLootPools": [
"Global_Military_Weapons_T4",
"Global_Military_Gear_T4"
],
"spawnFromAllPools": 0,
"lootMin": 1,
"lootMax": 2,
"preventDuplicateLoot": 1
}How This Works:
-
Each time this container spawns, it will first randomly choose one loot pool from the randomLootPools list.
-
Then, it will spawn between 1 and 2 unique items from that single chosen pool. Example 2: Spawning from ALL Pools Combined This example uses spawnFromAllPools to create a more diverse loot container that mixes weapons and gear.
{
"referenceName": "Random_Military_Crate_All_Pools",
"className": "BS_Box4_Green",
"spawnChance": 0.25,
"randomLootPools": [
"Global_Military_Weapons_T4",
"Global_Military_Gear_T4"
],
"spawnFromAllPools": 1,
"lootMin": 1,
"lootMax": 2,
"preventDuplicateLoot": 1
}How This Works:
-
Because spawnFromAllPools is set to 1, the system effectively merges Global_Military_Weapons_T4 and Global_Military_Gear_T4 into a single, temporary loot table.
-
It will then spawn between 1 and 2 unique items from this combined list. This means the container could spawn with one weapon and one piece of gear, something that is impossible in the first example.
This method bypasses the mod's internal loot system entirely and spawns a full preset from the LBmaster_Rework mod.
- lb_preset_name: The exact preset_name from LBmaster's configuration to spawn.
Example:
{
"referenceName": "LBmaster Preset Crate",
"className": "BS_Guncase_Black",
"spawnChance": 1.0,
"lb_preset_name": "Full_SNAFU_M4_Kit"
}This powerful feature adds another layer of randomness by allowing a common container to sometimes be replaced by a rarer one with its own completely separate loot rules.
-
replacementChance: The probability (from
0.0to1.0) that the replacement will occur. Example:0.15= 15% chance. -
replacementClassName: The
classNameof the new container that spawns.
You can override every loot parameter for the replacement by adding the replacement prefix:
| Replacement Parameter | Overrides |
|---|---|
replacementUseFixedLoot |
useFixedLoot |
replacementFixedItems |
fixedItems |
replacementLootPoolName |
lootPoolName |
replacementRandomLootPools |
randomLootPools |
replacementLootMin |
lootMin |
replacementLootMax |
lootMax |
replacementPreventDuplicateLoot |
preventDuplicateLoot |
replacement_lb_preset_name |
lb_preset_name |
This example demonstrates a complex scenario where every single replacement parameter is used to completely change the container's behavior and loot table.
{
"referenceName": "Medical_Cache_Or_Weapon_Jackpot",
"className": "BS_Box1_White",
"spawnChance": 1.0,
"useFixedLoot": 1,
"fixedItems": [
{
"name": "BandageDressing",
"quantity": 4
},
{
"name": "SalineBag",
"quantity": 1
}
],
"replacementChance": 0.05,
"replacementClassName": "BS_Guncase_Black",
"replacementUseFixedLoot": 0,
"replacementFixedItems": [],
"replacementLootPoolName": "",
"replacementRandomLootPools": [
"Global_HighTier_Weapons",
"Door_Specific_HighTier_Gear"
],
"replacementLootMin": 2,
"replacementLootMax": 3,
"replacementPreventDuplicateLoot": 1,
"replacement_lb_preset_name": ""
}JSON
{
"referenceName": "Normal Tools or Rare Gun",
"className": "BS_Box1_White",
"lootPoolName": "Global_Industrial_Tools",
"lootMin": 3,
"lootMax": 5,
"replacementChance": 0.10,
"replacementClassName": "BS_Guncase_Black",
"replacementUseFixedLoot": 1,
"replacementFixedItems": [
{
"name": "SVD",
"quantity": 1
}
]
}-
90% Chance: Spawns a white box with 3–5 industrial tools.
-
10% Chance: Spawns a black guncase with a guaranteed SVD.
JSON
{
"referenceName": "Normal Crate or LBmaster Kit",
"className": "BS_Box4_Black",
"lootPoolName": "Global_Civilian_Food",
"lootMin": 2,
"lootMax": 3,
"replacementChance": 0.05,
"replacementClassName": "BS_Guncase_Black",
"replacement_lb_preset_name": "Full_SNAFU_SVD_Kit"
}-
95% Chance: Spawns a black box with 2–3 food items.
-
5% Chance: Spawns a black guncase with a full SVD kit from LBmaster.
Next Step: 4. Keys and Keycards Configuration
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