Skip to content

3. Advanced Loot System

cjcarw edited this page Sep 22, 2025 · 17 revisions

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.

3.1. How Containers are Chosen to Spawn

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 min and max). Then, it looks at all available containers in the containers array and picks them one by one, based on the "weight" of their spawnChance, until the target number is reached.
  • Why it Matters: A container with "spawnChance": 1.0 is ten times more likely to be chosen than a container with "spawnChance": 0.1. If spawnChance is not specified in a container, its value defaults to 1.0.

3.2. The Building Blocks of Loot

These are the fundamental components that define what can spawn inside a container.

A. Loot Pools: The Foundation

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.json file. These pools can be used by any door on the server, perfect for general categories like Global_Military_Tools or Global_Medical_Supplies.
  • Door-Specific Pools: Defined inside a door's JSON file within the doorSpecificLootPools array. These pools can only be used by containers within that same door's configuration, ideal for creating unique rewards for a specific location.

Loot Pool Structure (rewards array)

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.

Example of a Loot Pool

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

B. The Attachment System

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.

Attachment Structure

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

Positioning Loot Containers

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.
⚠️ An error in these values can cause containers to spawn inside walls, floating in the air, or under the map.


How to Get Coordinates and Orientation

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.

Recommended Tools

  • 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 GetPos or getpos command.

Step-by-Step Guide

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

  2. Go to the Room
    Use admin flight/teleport to reach your keycard room location.

  3. Place a Container
    Spawn the container (className) you want to use.
    Example: BS_Guncase, BS_Box1_Black.

  4. Position and Rotate
    Move and rotate the object using your tool’s features.
    Make sure it’s not clipping into walls or floating.

  5. Copy the Coordinates
    Use your tool’s inspector or command to get:

    • Position → vector (X, Y, Z).
    • Orientation → vector (Yaw, Pitch, Roll).

Position and Orientation Format

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.

Example

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

3.3. Container Configuration

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.

Method A: Guaranteed Loot (useFixedLoot & fixedItems)

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 to 1 to enable this feature. If set to 0, the fixedItems array will be ignored.
  • fixedItems: An array of items that are guaranteed to spawn if useFixedLoot is 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) Overrides quantity for stackable items. Spawns the item with a random quantity between these two percentages of its maximum capacity (e.g., 0.5 = 50%).

Combining Guaranteed and Random Loot

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
}

Method B: Randomized Loot from Pools

Use this method for dynamic, unpredictable rewards drawn from your Loot Pools. This is the most common way to configure loot.

Parameters

  • 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, lootPoolName is ignored. Its behavior changes based on the spawnFromAllPools parameter below.
  • spawnFromAllPools: (0 or 1) This is a crucial switch for how randomLootPools works:
    • If 0 (or omitted), the system will randomly select one single pool from the randomLootPools list to spawn items from.
    • If 1, the system will attempt to draw items from every pool listed in randomLootPools, effectively merging them into one giant loot table for this container.
  • lootMin / lootMax: (Integers) The total number of random items to spawn from the selected pool(s).
  • preventDuplicateLoot: (0 or 1) If set to 1, the system will not spawn the same item type more than once in this container, even if it's drawn from different pools.

Example 1: Spawning from ONE Randomly Selected Pool

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

Method C: Integration with LBmaster Rework

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

Advanced Feature: Replacement Containers

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.


Parameters

  • replacementChance: The probability (from 0.0 to 1.0) that the replacement will occur. Example: 0.15 = 15% chance.

  • replacementClassName: The className of 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

Comprehensive Example: Using All Parameters

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

Example 1: Standard Replacement

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.

Example 2: Replacement with LBmaster Preset

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

Clone this wiki locally