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, plus reusable global pools defined in BS_KeyRoom_Settings.json.

⚠️ READ THIS FIRST — chanceToSpawn is 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 weights 1.0 and 0.5 result in 66% / 33% odds — not 100% and 50%. If every item in a pool has chanceToSpawn: 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.


3.1. How Containers Are Chosen to Spawn

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.


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. See 7. Main Settings.
  • 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.

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

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


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 recursively 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 (random_names)

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.

💡 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's inventorySlot[], plus direct magazines[] entries. A Show All toggle lets you switch back to the full unfiltered item list at any time. See 8. Admin Menu Guide.


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

Every field below is read from KeyCardDoorContainer in the mod source. Booleans can be written as 0/1 in JSON.

Identity and Placement

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.

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

⚠️ spawnFromAllPools changes what lootMin/lootMax mean. With spawnFromAllPools: 1, the min/max item count is applied PER POOL, not in total. Three pools with lootMin: 2, lootMax: 4 yield 6–12 items, not 2–4. Budget accordingly — and confirm with Simulate Loot.

Crate Lock and Timed Opening

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 > 0 is 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 via skip_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: requiredItem gates who can start the crate, min/max_open_time forces defenders to hold the room, and skip_open_item gives a rare bypass item a reason to exist.

unlock_anim_type values

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

Replacement Container

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.


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


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. 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: with spawnFromAllPools: 1, lootMin/lootMax is per pool. The crate above spawns 2–4 items from each of the three pools — 6 to 12 items total.

preventDuplicateLoot

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.


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/lootMax 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 replacement container can use its own preset via replacement_lb_preset_name — see Method D.


Method D — Replacement Containers

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.

3.6. Editing Loot In-Game (Admin Menu)

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.

3.7. Complete Door JSON Example

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.


Next Steps

Clone this wiki locally