# commands

## Overview

Commands are configured in `shared/commands.config.lua` within the `Chat.Commands` table. Each command has its own configuration for behavior, templates, logging, and 3D display.

***

## Command Types

| Type               | Property                | Description                         |
| ------------------ | ----------------------- | ----------------------------------- |
| **Distance-based** | `distance`              | Messages visible only within range  |
| **Global**         | `isGlobal = true`       | Messages sent to all players        |
| **Private**        | `isPrivate = true`      | Direct messages between two players |
| **Report**         | `isReport = true`       | Player reports sent to admins       |
| **System**         | `isSystem = true`       | System messages to single player    |
| **50/50 (TRY)**    | `fiftyfifty`            | Random success/fail outcomes        |
| **Default**        | `defaultMessage = true` | Default chat behavior (like OOC)    |

***

## Command Configuration Options

### Basic Options

| Option           | Type   | Description                        |
| ---------------- | ------ | ---------------------------------- |
| `logType`        | string | Log category for Discord webhooks  |
| `distance`       | number | Message visibility range (meters)  |
| `template`       | string | HTML template for message display  |
| `suggestion`     | table  | Command autocomplete configuration |
| `requiredGroups` | table  | Groups allowed to use command      |
| `GroupRoles`     | table  | Color mapping per user group       |
| `GroupColors`    | table  | Alternative color mapping          |

### Display Options (3D Text)

| Option              | Type   | Description                       |
| ------------------- | ------ | --------------------------------- |
| `displayTrigger`    | table  | RGBA color for 3D text            |
| `displayBackground` | table  | RGBA background color for 3D text |
| `displayDuration`   | number | How long 3D text displays (ms)    |
| `displaySettings`   | table  | Override global display settings  |

### Suggestion Configuration

```lua
suggestion = {
    help = 'Command description',
    params = {
        { name = 'param1', help = 'Parameter description' },
        { name = 'param2', help = 'Another parameter' }
    }
}
```

***

## Template Placeholders

Use these placeholders in your HTML templates:

| Placeholder    | Description                           |
| -------------- | ------------------------------------- |
| `{playerId}`   | Player's server ID                    |
| `{name}`       | Player's character/display name       |
| `{message}`    | The message content                   |
| `{time}`       | Current time (HH:MM format)           |
| `{nameColor}`  | Calculated name color                 |
| `{groupColor}` | Group-specific color                  |
| `{targetId}`   | Target player ID (private messages)   |
| `{targetName}` | Target player name (private messages) |
| `{senderId}`   | Sender player ID (private messages)   |
| `{senderName}` | Sender player name (private messages) |

***

## Built-in Commands

### OOC (Out of Character)

Default local OOC chat when typing without command prefix.

```lua
['OOC'] = {
    logType = 'ooc',
    defaultMessage = true,
    distance = 15.0,
    GroupRoles = {
        ['admin'] = 'rgba(255, 0, 0, 0.85)',
        ['mod'] = 'rgba(255, 0, 0, 0.85)',
        ['user'] = 'rgba(255, 255, 255, 0.85)'
    },
    template = '<div>...</div>'
}
```

***

### GLOBALOOC (Global OOC)

Global OOC chat visible to all players.

```lua
['GLOBALOOC'] = {
    logType = 'ooc',
    isGlobal = true,
    suggestion = {
        help = 'Send OOC message to all players',
        params = {}
    },
    template = '<div>...</div>'
}
```

Usage: `/globalooc Hello everyone!`

***

### ME (Action)

Roleplay action command with 3D display.

```lua
['ME'] = {
    logType = 'rp_commands',
    distance = 15.0,
    suggestion = {
        help = 'Perform RP action (visible nearby)',
        params = {
            { name = 'action', help = 'Description of your action' }
        }
    },
    displayTrigger = {
        r = 53, g = 108, b = 143, a = 255
    },
    displayBackground = {
        r = 11, g = 28, b = 41, a = 180
    },
    displayDuration = 5000,
    displaySettings = {
        textScale = 0.15,
        heightOffset = 0.5,
        stackOffset = 0.15,
        minScale = 0.25,
        maxScale = 0.45,
        maxPerPlayer = 3
    },
    template = '<div>...</div>'
}
```

Usage: `/me reaches into his pocket`

***

### DO (Environment Description)

Describe environment or character state.

```lua
['DO'] = {
    logType = 'rp_commands',
    distance = 15.0,
    suggestion = {
        help = 'Describe environment or state',
        params = {
            { name = 'description', help = 'Environment description' }
        }
    },
    displayTrigger = {
        r = 108, g = 63, b = 152, a = 255
    },
    displayBackground = {
        r = 44, g = 20, b = 80, a = 180
    },
    displayDuration = 5000,
    template = '<div>...</div>'
}
```

Usage: `/do The door is slightly open`

***

### MED (Medical Action)

Medical roleplay actions.

```lua
['MED'] = {
    logType = 'rp_commands',
    distance = 15.0,
    suggestion = {
        help = 'Perform medical action',
        params = {
            { name = 'action', help = 'Medical procedure description' }
        }
    },
    displayTrigger = {
        r = 176, g = 60, b = 60, a = 255
    },
    displayBackground = {
        r = 64, g = 24, b = 24, a = 180
    },
    displayDuration = 6000,
    template = '<div>...</div>'
}
```

Usage: `/med checks patient's vitals`

***

### TRY (50/50 Chance)

Random success/fail action.

```lua
['TRY'] = {
    logType = 'rp_commands',
    distance = 15.0,
    suggestion = {
        help = 'Try an action (random result)',
        params = {
            { name = 'action', help = 'Action to attempt' }
        }
    },
    fiftyfifty = {
        iftrue = {
            displayTrigger = { r = 50, g = 205, b = 50, a = 255 },
            displayBackground = { r = 0, g = 80, b = 0, a = 180 },
            displayDuration = 5000,
            template = '<div>...Success: {message}...</div>'
        },
        iffalse = {
            displayTrigger = { r = 255, g = 50, b = 50, a = 255 },
            displayBackground = { r = 80, g = 0, b = 0, a = 180 },
            displayDuration = 5000,
            template = '<div>...Failed: {message}...</div>'
        }
    }
}
```

Usage: `/try picks the lock`

***

### W (Whisper/Private Message)

Private message between two players.

```lua
['W'] = {
    logType = 'private_messages',
    isPrivate = true,
    suggestion = {
        help = 'Send private message to player',
        params = {
            { name = 'id', help = 'Player ID' },
            { name = 'message', help = 'Message content' }
        }
    },
    templateSender = '<div>...Message to {targetName}...</div>',
    templateReceiver = '<div>...Message from {senderName}...</div>'
}
```

Usage: `/w 5 Hey, want to meet up?`

***

### AC (Admin Announcement)

Global admin announcements (restricted).

```lua
['AC'] = {
    logType = 'admin',
    isGlobal = true,
    suggestion = {
        help = 'Send admin announcement',
        params = {
            { name = 'message', help = 'Announcement content' }
        }
    },
    requiredGroups = { 'admin', 'mod', 'helper' },
    GroupColors = {
        ['admin'] = '#FF0000',
        ['mod'] = '#FFA500',
        ['helper'] = '#00FF00'
    },
    template = '<div>...</div>'
}
```

Usage: `/ac Server restart in 5 minutes!`

***

### REPORT (Player Report)

Player reports to admin team.

```lua
['REPORT'] = {
    logType = 'reports',
    isReport = true,
    suggestion = {
        help = 'Send report to administration',
        params = {
            { name = 'content', help = 'Report content' }
        }
    },
    requiredGroups = { 'admin', 'mod', 'helper' },
    templatePlayer = '<div>...Your report...</div>',
    templateAdmin = '<div>...Report from {name}...</div>'
}
```

Usage: `/report Player ID 42 is cheating`

***

### REPORTODP (Report Response)

Admin response to player reports (restricted).

```lua
['REPORTODP'] = {
    logType = 'reports',
    isPrivate = true,
    suggestion = {
        help = 'Respond to player report',
        params = {
            { name = 'id', help = 'Player ID' },
            { name = 'response', help = 'Response content' }
        }
    },
    requiredGroups = { 'admin', 'mod', 'helper' },
    templateSender = '<div>...Response sent to {targetName}...</div>',
    templateReceiver = '<div>...Admin response from {senderName}...</div>'
}
```

Usage: `/reportodp 5 Thank you, we're investigating`

***

### SYSTEM (System Messages)

Internal system messages.

```lua
['SYSTEM'] = {
    logType = 'system',
    isSystem = true,
    template = '<div>...SYSTEM: {message}...</div>'
}
```

Usage: Called programmatically via `SendRPMessage('SYSTEM', playerId, message)`

***

## Adding Custom Commands

### Basic Distance Command

```lua
['SHOUT'] = {
    logType = 'rp_commands',
    distance = 30.0,  -- Larger range for shouting
    suggestion = {
        help = 'Shout to nearby players',
        params = {
            { name = 'message', help = 'What to shout' }
        }
    },
    displayTrigger = {
        r = 255, g = 200, b = 0, a = 255
    },
    displayBackground = {
        r = 100, g = 80, b = 0, a = 180
    },
    displayDuration = 4000,
    template = [[
        <div style="padding: 10px; background: linear-gradient(360deg, rgba(255, 200, 0, 0.8) 0%, rgba(100, 80, 0, 0.8) 100%); border-radius: 5px;">
            <font style="font-weight: bold; color: #FFD700;">SHOUT</font>
            <font style="color: white;"> [{playerId}] {name}: </font>
            <font style="color: #FFD700; font-weight: bold;">{message}</font>
            <font style="float: right; font-size: 12px;">{time}</font>
        </div>
    ]]
}
```

***

### Faction-Restricted Command

```lua
['POLICE'] = {
    logType = 'faction',
    isGlobal = true,
    suggestion = {
        help = 'Police radio communication',
        params = {
            { name = 'message', help = 'Radio message' }
        }
    },
    requiredGroups = { 'police', 'sheriff', 'fbi' },
    GroupColors = {
        ['police'] = '#0066FF',
        ['sheriff'] = '#8B4513',
        ['fbi'] = '#000080'
    },
    template = [[
        <div style="padding: 10px; background: rgba(0, 50, 100, 0.9); border-left: 3px solid #0066FF; border-radius: 5px;">
            <font style="color: #0066FF; font-weight: bold;">[POLICE RADIO]</font>
            <font style="color: {groupColor};"> {name}: </font>
            <font style="color: white;">{message}</font>
        </div>
    ]]
}
```

***

## DisplaySettings Override

Per-command display settings that override global `Chat.Display`:

```lua
displaySettings = {
    textScale = 0.15,      -- Override Chat.Display.textScale
    heightOffset = 0.5,    -- Override Chat.Display.heightOffset
    stackOffset = 0.15,    -- Override Chat.Display.stackOffset
    minScale = 0.25,       -- Override Chat.Display.minScale
    maxScale = 0.45,       -- Override Chat.Display.maxScale
    maxPerPlayer = 3,      -- Override Chat.Display.maxPerPlayer
    fadeTime = 500,        -- Override Chat.Display.fadeTime
    maxDistance = 25.0     -- Override Chat.Display.maxDistance
}
```

***

## Next Steps

* [📋 Logs Configuration](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/logs) - Set up Discord logging
* [⚙️ Framework Bridge](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/framework-bridge) - Framework integration
* [📤 Exports](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/exports) - Available exports