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


---

# 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://botiv.gitbook.io/rdr2/honor-system.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.