> For the complete documentation index, see [llms.txt](https://tyrix.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://tyrix.gitbook.io/docs/script-resources/tyrix-dice/configuration.md).

# Configuration

All configuration options are in `shared/config.lua`.

## Basic Settings

| Option                      | Default   | Description                                                 |
| --------------------------- | --------- | ----------------------------------------------------------- |
| `Config.DebugMode`          | `false`   | Enable server console logging                               |
| `Config.Command`            | `'dice'`  | Command name for rolling dice                               |
| `Config.DefaultDiceColor`   | `'white'` | Default color when none specified (`white`, `black`, `red`) |
| `Config.RollCooldown`       | `3000`    | Cooldown between rolls in ms (0 = disabled)                 |
| `Config.RenderDistance`     | `30.0`    | How far players can see dice                                |
| `Config.ChatNotifyDistance` | `30.0`    | How far chat notifications reach                            |

```lua
Config.DebugMode = false
Config.Command = 'dice'
Config.DefaultDiceColor = 'white'
Config.RollCooldown = 3000
Config.RenderDistance = 30.0
Config.ChatNotifyDistance = 30.0
```

## Dice Mode & Items

| Option               | Default     | Description                                      |
| -------------------- | ----------- | ------------------------------------------------ |
| `Config.DiceMode`    | `'command'` | `'command'`, `'item'`, or `'both'`               |
| `Config.ConsumeItem` | `true`      | Remove item after use (items returned on pickup) |

```lua
Config.DiceMode = 'command'    -- 'command' = /dice only
                               -- 'item' = inventory items only
                               -- 'both' = command + items

Config.ConsumeItem = true      -- When true, item is consumed on use
                               -- but returned when dice are picked up
```

### Dice Mode Behaviors

| Mode        | Command | Items | Fallback                       |
| ----------- | ------- | ----- | ------------------------------ |
| `'command'` | Yes     | No    | -                              |
| `'item'`    | No      | Yes   | Command if no inventory system |
| `'both'`    | Yes     | Yes   | Command always available       |

## Pickup Settings

| Option                  | Default | Description                                |
| ----------------------- | ------- | ------------------------------------------ |
| `Config.PickupKeybind`  | `true`  | Enable E key to pickup dice                |
| `Config.PickupDistance` | `3.0`   | Max distance to pickup dice                |
| `Config.UseOxLib`       | `true`  | Use ox\_lib for "\[E] Pick Up Dice" prompt |

```lua
Config.PickupKeybind = true
Config.PickupDistance = 3.0
Config.UseOxLib = true         -- Requires ox_lib installed
```

## Physics Settings

### Bounce Simulation

| Option                      | Default | Description                   |
| --------------------------- | ------- | ----------------------------- |
| `Config.BounceEnabled`      | `true`  | Enable bounce physics         |
| `Config.InitialBounceForce` | `5.5`   | Force on first bounce         |
| `Config.BounceDamping`      | `0.6`   | Each bounce = previous × this |
| `Config.MaxBounces`         | `3`     | Maximum bounce count          |

```lua
Config.BounceEnabled = true
Config.InitialBounceForce = 5.5
Config.BounceDamping = 0.6
Config.MaxBounces = 3
```

### Throwing Motion

| Option                        | Default | Description                    |
| ----------------------------- | ------- | ------------------------------ |
| `Config.ForceUp`              | `3.0`   | Upward force (arc height)      |
| `Config.ForceForward`         | `3.5`   | Forward force (throw distance) |
| `Config.AngularVelocityRange` | `15.0`  | Random tumbling intensity      |

```lua
Config.ForceUp = 3.0
Config.ForceForward = 3.5
Config.AngularVelocityRange = 15.0
```

## Text Display

| Option                     | Default             | Description                      |
| -------------------------- | ------------------- | -------------------------------- |
| `Config.TextFont`          | `4`                 | GTA V font ID (0-8)              |
| `Config.TextScale`         | `0.55`              | Base text size                   |
| `Config.TextColor`         | `{255,255,255,255}` | RGBA color                       |
| `Config.TextOutline`       | `true`              | Draw outline                     |
| `Config.SimpleTextDisplay` | `true`              | Show just number vs "Dice #1: 5" |

```lua
Config.TextFont = 4
Config.TextScale = 0.55
Config.TextColor = {255, 255, 255, 255}
Config.TextOutline = true
Config.SimpleTextDisplay = true    -- true = "5", false = "Dice #1: 5"
```

## Example Full Configuration

```lua
-- Debug
Config.DebugMode = false

-- Dice mode
Config.DiceMode = 'both'
Config.ConsumeItem = true

-- Command
Config.Command = 'dice'
Config.DefaultDiceColor = 'white'
Config.RollCooldown = 3000

-- Distance
Config.RenderDistance = 30.0
Config.ChatNotifyDistance = 30.0

-- Pickup
Config.PickupKeybind = true
Config.PickupDistance = 3.0
Config.UseOxLib = true

-- Physics
Config.BounceEnabled = true
Config.InitialBounceForce = 5.5
Config.BounceDamping = 0.6
Config.MaxBounces = 3
Config.ForceUp = 3.0
Config.ForceForward = 3.5

-- Text
Config.TextFont = 4
Config.TextScale = 0.55
Config.TextColor = {255, 255, 255, 255}
Config.TextOutline = true
Config.SimpleTextDisplay = true
```