> For the complete documentation index, see [llms.txt](https://petrisservices.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://petrisservices.gitbook.io/docs/scripts/loot-bags/usage.md).

# Usage

### Manual Export Function

```lua
exports["petris-lootbags"]:DropPlayerLootBag(playerId, bypass)
```

{% hint style="info" %}
The bypass parameter should be a boolean value. If true, it bypasses the whitelisted/blacklisted areas & IsPlayerLootable open function restrictions.
{% endhint %}

### Blacklisted Items Configuration

```lua
BlacklistedItems = {
        ["Items"] = {
            "id_card", 
            "driver_license",
        },
        ["Money"] = {
            "bank",
        },
        ["Weapons"] = {
            "WEAPON_STUNGUN",
        }
    },
```

{% hint style="info" %}
You can put any items/money types and weapons in your blacklisted inventory items list.
{% endhint %}

### Whitelisted/Blacklisted Areas Configuration

```lua
Locations = {
        ["System"] = "blacklisted", -- Possible Values: whitelisted | blacklisted (Define if you want to blacklisted areas and whitelist the other map locations or whitelist areas and block the other map locations)

        ["WhitelistedLocations"] = { -- The only locations where loot bags can be dropped
            { AreaName = "Test1", AreaCoordinates = vector3(0.0, 0.0, 0.0), AreaRange = 10.0 }, -- Area Name is not used, but it is recommended to fill so you know which areas are whitelisted.
            { AreaName = "Test2", AreaCoordinates = vector3(0.0, 0.0, 0.0), AreaRange = 5.0 } -- Area Name is not used, but it is recommended to fill so you know which areas are whitelisted.
        },

        ["BlacklistedLocations"] = { -- Location that loot bags won't be dropped even if the function is triggered.
            { AreaName = "Test1", AreaCoordinates = vector3(0.0, 0.0, 0.0), AreaRange = 10.0 }, -- Area Name is not used, but it is recommended to fill so you know which areas are blacklisted.
            { AreaName = "Test2", AreaCoordinates = vector3(0.0, 0.0, 0.0), AreaRange = 5.0 } -- Area Name is not used, but it is recommended to fill so you know which areas are blacklisted.
        },
    },
```

{% hint style="info" %}
Firstly, you must select how the location restriction system will work.\
\
In <mark style="background-color:red;">\["System"]</mark> value, change between <mark style="color:purple;">whitelisted</mark> and <mark style="color:purple;">blacklisted</mark> values.\
\
Then, you will add your own blacklisted/whitelisted locations just like the examples above.
{% endhint %}

### Define Lootable Players

```lua
IsPlayerLootable = function(playerId)
        --[[if Config["Framework"] == "ESX" then -- ESX Example: if player is not a simple user and has a permission group then don't drop his loot bag
            local xPlayer = ESX.GetPlayerFromId(playerId)
            if xPlayer.getGroup() ~= 'user' then
                return false
            end
        elseif Config["Framework"] == "QBCore" then -- QBCore Example: if player's permission is admin then don't drop his loot bag
            if QBCore.Functions.HasPermission(playerId, 'admin') then
                return false
            end
        end--]]
        return true
    end,
```

{% hint style="info" %}
There is already a built-in check which checks if the player is staff. So, when the player is a server's staff the loot bag will not spawn upon his death. You can add your own restrictions there, freely.
{% endhint %}

### Allow/Block Players From Collecting

```lua
CanPlayerCollectBag = function()
        if Config["Framework"] == "ESX" then -- ESX Example: if player is working for ambulance, he can't pick-up the bag.
            if ESX.PlayerLoaded then
                if ESX.PlayerData.job and ESX.PlayerData.job.name == "ambulance" then
                    return false
                end
            end 
        elseif Config["Framework"] == "QBCore" then -- QBCore Example: if player is working for ambulance, he can't pick-up the bag.
            local PlayerData = QBCore.Functions.GetPlayerData()
            local jobName = PlayerData.job.name
            if jobName == 'ambulance' then
                return false
            end
        end
        return true
    en
```

{% hint style="info" %}
There is already a built-in check which checks if the player is working for the ambulance. You can freely remove or change this restriction as was added as an example.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://petrisservices.gitbook.io/docs/scripts/loot-bags/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.