> For the complete documentation index, see [llms.txt](https://botiv.gitbook.io/rdr2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://botiv.gitbook.io/rdr2/honor-system.md).

# Honor system

***

### ✨ Features

* **Honor gain/loss** per action (good vs. crime)
* **Honor Pool** (optional): smooths changes over time instead of instant jumps
* **Discord webhook** logs with customizable display name
* **Configurable detection interval** (`ScanInterval`)
* **Honor titles** for male/female, from *Living Saint* → *Living Demon*
* **Keybind** to display current honor (default **LALT**)
* **Extendable animal detection** (`DogHashes`, `CatHashes`)
* **Server exports** to read/update honor
* **StateBags** for client-side access

***

### ⚙️ Configuration

All configuration is done in `config.lua`.

* `Config.ScanInterval` → frequency of crime/good deed scans (in seconds)
* `Config.DiscordWebHook` & `Config.DiscordName` → webhook integration
* `Config.HonorPoolEnabled` & `Config.HonorPoolTickMs` → enable and tune honor pool
* `Config.DogHashes` / `Config.CatHashes` → define which animals are considered dogs or cats
* Bonus/Malus values → fully adjustable (`BanditKillBonus`, `InnocentKillMalus`, etc.)

***

### 🖥️ Server Exports

The resource provides several exports to interact with the honor system from other scripts.

#### Add Honor

```lua
exports.bt_honor:addHonor(src, amount_to_add [number], ignoreAddFunction [bool])
```

* **src** → player ID
* **amount\_to\_add** → amount of honor to give (positive number)
* **ignoreAddFunction** *(optional, default: false)* →
  * If `true`, the `honorAdded()` function in `config.lua` will **not** be triggered.
  * If `false`, `honorAdded()` will be triggered as usual.

***

#### Remove Honor

```lua
exports.bt_honor:removeHonor(src, amount_to_remove [number], ignoreRemoveFunction [bool])
```

* **src** → player ID
* **amount\_to\_remove** → amount of honor to remove (positive number)
* **ignoreRemoveFunction** *(optional, default: false)* →
  * If `true`, the `honorRemoved()` function in `config.lua` will **not** be triggered.
  * If `false`, `honorRemoved()` will be triggered as usual.

***

#### Set Honor

```lua
exports.bt_honor:setHonor(src, new_honor_value [number])
```

* **src** → player ID
* **new\_honor\_value** → directly sets the player’s honor to this value (overwrites previous honor).

***

#### Get Honor

```lua
exports.bt_honor:getHonor(src)
```

* **src** → player ID
* **return** → current honor value of the player (number).

***

⚠️ **Note:**

* `ignoreAddFunction` and `ignoreRemoveFunction` are optional parameters (default = `false`).
* These allow you to **bypass the default functions** `honorAdded()` and `honorRemoved()` in `config.lua` if you don’t want them to run.

***

### 📦 StateBags

Each player has a StateBag key `honor` automatically synchronized to clients.

```lua
-- Server side: read honor
local playerHonor = Player(source).state.honor or 0

-- Client side: read honor
local playerHonor = LocalPlayer.state.honor or 0
```

This makes it easy to **display honor in your UI** or use it in other scripts without additional events.

***

### 🔔 Discord Integration

* Send logs of honor changes, publications and removals directly to Discord.
* Fully configurable webhook URL and bot name.
* Example messages include player name, honor before/after and player coords.

***

### 🎮 Keybind

Default key: **LALT** (`Config.DisplayHonorKey = 0x8AAA0AD4`)\
Shows the player’s current honor when pressed.

***

### 📊 Honor Titles

Players see dynamic descriptions of their reputation depending on honor range.

* Separate sets for male and female characters.
* Categories: **Transcendent, Legendary, Very High, High, Neutral, Low, Very Low, Abysmal, Damned**.

***

### 📑 Example Configuration (`config.lua`)

Below is a partial extract of the configuration file.

```lua
Config = {}

-- Discord webhook for sending logs
Config.DiscordWebHook = ""

-- The name that will appear in Discord logs
Config.DiscordName = "BT_HONOR"

-- Time (in seconds) between each scan of player actions
Config.ScanInterval = 30

-- Key to display honor in-game (default: LALT)
Config.DisplayHonorKey = 0x8AAA0AD4 -- LALT

-- Honor pool system
Config.HonorPoolEnabled = true       -- Smooth honor changes over time
Config.HonorPoolTickMs  = 5000       -- Tick interval in ms

-- BONUS
Config.BanditKillBonus = 2

-- MALUS
Config.InnocentKillMalus = 2
Config.PlayerKillMalus   = 3
Config.HorseKillMalus    = 5
Config.DogKillMalus      = 6
Config.CatKillMalus      = 6

-- Honor texts
Config.honorTexts = { ... }
-- (full male/female honor titles included in the script)

-- Animal hashes
Config.DogHashes = { ... }
Config.CatHashes = { ... }
```

ℹ️ *The full configuration file is included in the script. This example only shows the main adjustable options.*

***

### 📌 Notes

* The script is **encrypted** for distribution.
* All customization is available via `config.lua`.
* Fully compatible with VORP framework and other resources through exports & StateBags.