> For the complete documentation index, see [llms.txt](https://docs.qubitstudios.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qubitstudios.net/fivem-scripts/honor-system/usage-and-integration.md).

# Usage & Integration

You can easily integrate the Qubit Honor system into any desired job using the client-side and server-side exports. You can find the exports below.

<details>

<summary>Client Side Usage</summary>

```lua
exports['qubit-honorsystem']:IncreaseHonor(amount, reason)
exports['qubit-honorsystem']:DecreaseHonor(amount, reason)
exports['qubit-honorsystem']:GetHonor()
exports['qubit-honorsystem']:GetHonorPercentage()
exports['qubit-honorsystem']:GetHonorLevel()
```

</details>

<details>

<summary>Server Side Usage</summary>

```lua
exports['qubit-honorsystem']:IncreaseHonor(source, amount, reason)
exports['qubit-honorsystem']:DecreaseHonor(source, amount, reason)
exports['qubit-honorsystem']:GetHonor(source)
exports['qubit-honorsystem']:GetHonorPercentage(source)
exports['qubit-honorsystem']:GetHonorLevel(source)
```

</details>

### Decrease/Increase Honor Export

The "Increase Honor" export is used in both server and client Lua files to increase a user's honor value. Here are a few real usage examples:

Example Script snippet <mark style="color:yellow;">**qbx\_truckrobbery/client/main.lua**</mark>

<pre class="language-lua" data-line-numbers><code class="lang-lua">local function lootTruck()
    local looting = true
	CreateThread(function()
        if lib.progressBar({
            duration = config.lootDuration,
            label = locale('info.looting_truck'),
            useWhileDead = false,
            canCancel = true,
            disable = {
                move = true,
                car = true,
                combat = true,
                mouse = false,
            },
            anim = {
                dict = 'anim@heists@ornate_bank@grab_cash_heels',
                clip = 'grab',
                flag = 1,
            },
            prop = {
                model = `prop_cs_heist_bag_02`,
                bone = 57005,
                pos = vec3(0.0, 0.0, -0.16),
                rot = vec3(250.0, -30.0, 0.0),
            }
        }) then
            local success = lib.callback.await('qbx_truckrobbery:server:giveReward')
            -- WE ARE DECREASE HONOR FOR TRUCK ROBBERY ON CLIENT SIDE
<strong>            exports['qubit-honorsystem']:DecreaseHonor(500, "BANK TRUCK ROBBED")
</strong>            -- exports['qubit-honorsystem']:IncreaseHonor(500, "BANK TRUCK ROBBED")
            if not success then return end
            SetPedComponentVariation(cache.ped, 5, 45, 0, 2)
            resetMission()
        end
        looting = false
    end)
    while looting do
        if #(GetEntityCoords(cache.ped) - GetEntityCoords(truck)) > 6 and lib.progressActive() then
            lib.cancelProgress()
        end
        Wait(1000)
    end
end
</code></pre>

Let's do the same example for the server side:

Example Script snippet <mark style="color:yellow;">**qbx\_truckrobbery/server/main.lua**</mark>

<pre class="language-lua" data-line-numbers><code class="lang-lua">lib.callback.register('qbx_truckrobbery:server:giveReward', function(source)
    if Entity(truck).state.truckstate ~= TruckState.LOOTABLE then return end
    Entity(truck).state:set('truckstate', TruckState.LOOTED, true)
    local cantCarryRewards = {}
    local cantCarryRewardsSize = 0
    for i = 1, #config.rewards do
        local reward = config.rewards[i]
        if not reward.probability or math.random() &#x3C;= reward.probability then
            local amount = math.random(reward.minAmount or 1, reward.maxAmount or 1)
            if exports.ox_inventory:CanCarryItem(source, reward.item, amount) then
                exports.ox_inventory:AddItem(source, reward.item, amount)
            else
                cantCarryRewardsSize += 1
                cantCarryRewards[cantCarryRewardsSize] = {reward.item, amount}
            end
        end
    end
    -- WE ARE DECREASE HONOR FOR TRUCK ROBBERY ON SERVER SIDE
<strong>    exports['qubit-honorsystem']:DecreaseHonor(source, 500, "BANK TRUCK ROBBED")
</strong>    -- exports['qubit-honorsystem']:IncreaseHonor(source, 500, "BANK TRUCK ROBBED")
    if cantCarryRewardsSize > 0 then
        exports.ox_inventory:CustomDrop('Loot', cantCarryRewards, GetEntityCoords(GetPlayerPed(source)))
    end
	exports.qbx_core:Notify(source, locale('success.looted'), 'success')
	return true
end)
</code></pre>

### GetHonorLevel Honor Export

In this way, we can grant or reduce honor for the user within any profession. Now, for example, we want to adjust the user's earnings based on their honor level. To do this, we will use the `GetHonorLevel` export and, depending on the level, define what they will receive using the desired variable.

Example Script snippet <mark style="color:yellow;">**qbx\_truckrobbery/server/main.lua**</mark>

<pre class="language-lua" data-line-numbers><code class="lang-lua">lib.callback.register('qbx_truckrobbery:server:giveReward', function(source)
    if Entity(truck).state.truckstate ~= TruckState.LOOTABLE then return end
    Entity(truck).state:set('truckstate', TruckState.LOOTED, true)
    local cantCarryRewards = {}
    local cantCarryRewardsSize = 0
    for i = 1, #config.rewards do
        local reward = config.rewards[i]
        if not reward.probability or math.random() &#x3C;= reward.probability then
            local amount = math.random(reward.minAmount or 1, reward.maxAmount or 1)

	    -- Start Honor Decrease &#x26; Change Reward Amount
	    ---- We are maked amount multiplie by the honor level
	    ---- This is to make it so the lower your honor level, the more you get because this job is illegal
<strong>	    local currentLevel = exports['qubit-honorsystem']:GetHonorLevel(source)
</strong><strong>	    amount = amount * currentLevel.levelData['qbx_truckrobbery:rewardMultiplier']
</strong>	    -- End Honor Decrease &#x26; Change Reward Amount

            if exports.ox_inventory:CanCarryItem(source, reward.item, amount) then
                exports.ox_inventory:AddItem(source, reward.item, amount)
            else
                cantCarryRewardsSize += 1
                cantCarryRewards[cantCarryRewardsSize] = {reward.item, amount}
            end
        end
    end

    if cantCarryRewardsSize > 0 then
        exports.ox_inventory:CustomDrop('Loot', cantCarryRewards, GetEntityCoords(GetPlayerPed(source)))
    end
	exports.qbx_core:Notify(source, locale('success.looted'), 'success')
	return true
end)
</code></pre>

In the example above, I used the `GetHonorLevel` export to retrieve the user's current level data. This level data includes the following values, which come from `config.lua`

<mark style="color:yellow;">**GetHonorLevel**</mark> Export Response;

<pre class="language-lua"><code class="lang-lua">min = 15,
max = 30,
icon = "bad50.png",
title = "NOTORIOUS OUTLAW",
subtitle = "THREAT TO SOCIETY",
levelSoundtrack = "bad50",
levelSoundtrackVolume = 0.2,
levelData = {
<strong>    ['qbx_truckrobbery:rewardMultiplier'] = 1.4
</strong>}
level = "SlightlyBad"
</code></pre>

Here, I created a custom variable inside the `levelData` variable in `config.lua` by using the script's name, and I named it `rewardMultiplier`. You can define anything you want—this value doesn't have to be a number; it can also be an array or a string, depending on what you want to store for a specific job. Then, I set this value to `1.4` in `config.lua` so that players with the `SlightlyBad` level will receive 1.4 times more items from this heist. The current `config.lua` looks like the following:

{% code lineNumbers="true" %}

```lua
Config.HonorLevels = { -- based on percentage 0% means - Honor Pool Value like (-10000) - 100% means - Honor Pool Value like (10000)
    VeryBad = {
        min = 0, -- min honor for the honor level
        max = 5, -- min and max honor for the honor level
        icon = "bad100.png", -- icon for the honor level
        title = "THE SCARFACE", -- title for the honor level
        subtitle = "THE WORLD IS YOURS", -- subtitle for the honor level
        levelSoundtrack = "bad100", -- soundtrack for the honor level
        levelSoundtrackVolume = 0.6, -- volume for the honor level
        levelData = {
          -- EXAMPLE: 
          -- ['script_name:variable_name'] = 'value',
        } -- You can add more variables for specific job or script integration
    },
    Bad = {
        min = 5,
        max = 15,
        icon = "bad75.png",
        title = "MOST WANTED",
        subtitle = "MOST DANGEROUS CRIMINAL",
        levelSoundtrack = "bad75",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 1.8
        }
    },
    SlightlyBad = {
        min = 15,
        max = 30,
        icon = "bad50.png",
        title = "NOTORIOUS OUTLAW",
        subtitle = "THREAT TO SOCIETY",
        levelSoundtrack = "bad50",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 1.4
        }
    },
    AlmostNeutral = {
        min = 30,
        max = 50,
        icon = "bad25.png",
        title = "STREET THUG",
        subtitle = "CRIMINAL ACTIVITIES",
        levelSoundtrack = "bad25",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 1.2
        }
    },
    Neutral = {
        min = 50,
        max = 50,
        icon = "zero.png",
        title = "NEUTRAL CITIZEN",
        subtitle = "UNKNOWN REPUTATION",
        levelSoundtrack = nil,
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 1.0
        }
    },
    SlightlyGood = {
        min = 50,
        max = 70,
        icon = "good25.png",
        title = "TRUSTED FRIEND",
        subtitle = "GAINING RESPECT",
        levelSoundtrack = "good25",
        levelSoundtrackVolume = 0.3,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 0.8
        }
    },
    Good = {
        min = 70,
        max = 85,
        icon = "good50.png",
        title = "RESPECTED CITIZEN",
        subtitle = "VALUED MEMBER OF SOCIETY",
        levelSoundtrack = "good50",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 0.6
        }
    },
    VeryGood = {
        min = 85,
        max = 95,
        icon = "good75.png",
        title = "FAMOUS PERSON",
        subtitle = "WELL-KNOWN IN THE COMMUNITY",
        levelSoundtrack = "good75",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 0.4
        }
    },
    Legendary = {
        min = 95,
        max = 100,
        icon = "good100.png",
        title = "SAINT OF THE CITY",
        subtitle = "YOU ARE A LEGENDARY HERO",
        levelSoundtrack = "good100",
        levelSoundtrackVolume = 0.2,
        levelData = {
            ['qbx_truckrobbery:rewardMultiplier'] = 0.2
        }
    }
}
```

{% endcode %}


---

# 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://docs.qubitstudios.net/fivem-scripts/honor-system/usage-and-integration.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.