> 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/commands.md).

# Commands

## Rolling Dice

### /dice Command

The `/dice` command is available when `Config.DiceMode` is set to `'command'` or `'both'`.

| Command         | Result                      |
| --------------- | --------------------------- |
| `/dice`         | Roll 2 white dice (default) |
| `/dice 1`       | Roll 1 white die            |
| `/dice 3`       | Roll 3 white dice           |
| `/dice red`     | Roll 2 red dice             |
| `/dice black`   | Roll 2 black dice           |
| `/dice red 3`   | Roll 3 red dice             |
| `/dice black 1` | Roll 1 black die            |

### Command Syntax

```
/dice [color] [count]
```

| Parameter | Options                 | Default                                |
| --------- | ----------------------- | -------------------------------------- |
| color     | `white`, `black`, `red` | `white` (or `Config.DefaultDiceColor`) |
| count     | `1`, `2`, `3`           | `2`                                    |

### Examples

```
/dice              → 2 white dice
/dice 3            → 3 white dice
/dice red          → 2 red dice
/dice black 1      → 1 black die
```

## Picking Up Dice

### Commands

| Command       | Description               |
| ------------- | ------------------------- |
| `/pickupdice` | Pick up your dice         |
| `/dicepickup` | Pick up your dice (alias) |

Both commands do the same thing - pick up all dice you've rolled.

### E Keybind

When `Config.PickupKeybind = true`:

* Walk near your dice (within `Config.PickupDistance`)
* Press **E** to pick them up
* Your character plays a pickup animation

### ox\_lib Text UI

When `Config.UseOxLib = true` and ox\_lib is installed:

* A prompt appears: **\[E] Pick Up Dice**
* Displays when you're near your dice
* Includes a dice icon

## How Rolling Works

{% stepper %}
{% step %}

### Command/Item Used

Server validates and generates random results.
{% endstep %}

{% step %}

### Animation Plays

Your character performs a throwing motion.
{% endstep %}

{% step %}

### Dice Spawn

Physical dice appear and tumble.
{% endstep %}

{% step %}

### Physics Settle

Dice bounce and come to rest.
{% endstep %}

{% step %}

### Results Display

3D text shows the roll values.
{% endstep %}

{% step %}

### Chat Notification

Nearby players see your roll in chat.
{% endstep %}
{% endstepper %}

## Cooldown

A cooldown prevents spam rolling:

* Default: 3000ms (3 seconds)
* Configure with `Config.RollCooldown`
* Set to `0` to disable

## Visibility

| Setting                     | Controls                         |
| --------------------------- | -------------------------------- |
| `Config.RenderDistance`     | How far players can see dice     |
| `Config.ChatNotifyDistance` | How far chat notifications reach |

Players outside these distances won't see the dice or notification.

## Item Return on Pickup

When using item mode with `Config.ConsumeItem = true`:

1. Using an item consumes it from inventory
2. Picking up the dice returns the item
3. If you don't pick up, the item stays consumed
4. Dice auto-despawn after \~12 seconds