Skip to content

3. Advanced Loot System

cjcarw edited this page Jul 15, 2026 · 17 revisions

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.


3.1. How Containers Are Chosen to Spawn

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.


3.2. Loot Pools

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 like Global_Military_T3 or Global_Medical_Basic.
  • Door-Specific Pools — in the doorSpecificLootPools array inside a door's JSON. Only available to containers within that same door config. Ideal for unique location-exclusive rewards.

⚠️ chanceToSpawn is 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.

Loot Pool Structure

{
    "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": []
        }
    ]
}

Reward Item Parameters

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.

3.3. The Attachment System

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.

Direct Attachment

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
        }
    ]
}

Randomized Attachment

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"
            ]
        }
    ]
}

Nested Attachments

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.


3.4. Positioning Loot Containers

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.

Recommended Methods

  • DayZ Editor — Offline mode tool for placing objects and exporting coordinates.
  • VPP Admin Tools or Community Online Tools — In-game admin mods with a getpos command.

Step-by-Step

  1. Load the map in Offline Mode or connect to your server with admin tools.
  2. Fly/teleport to the keycard room location.
  3. Spawn the container className you want to use (e.g. BS_Guncase).
  4. Move and rotate it until it looks correct — not clipping walls, not floating.
  5. Use your tool's inspector or getpos command to copy the Position (X, Y, Z) and Orientation (Yaw, Pitch, Roll).

Coordinate Format

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
}

3.5. Container Configuration

The containers array holds all possible containers for a door event. Each container can use one of four loot methods — or combine them freely.

Complete Container Parameter Reference

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.

Method A — Guaranteed Loot (useFixedLoot + fixedItems)

Items in fixedItems always spawn regardless of anything else. They appear in addition to any random loot from pools.

Fixed Item Parameters

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).


Method B — Randomized Loot from a Single Pool

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
}

Method B2 — Randomized Loot from Multiple Pools

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
}

Method C — LBmaster Rework Integration

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).


Method D — Replacement Containers

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.

Replacement Parameters

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.

3.6. Complete Door JSON Example

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
        }
    ]
}

Next Steps

Configure AI defenders → [4. AI Spawning System](4.-AI-Spawning-System)

Clone this wiki locally