# logs

## Overview

SL-Chat includes a comprehensive Discord webhook logging system. All chat messages, commands, and player actions can be logged to Discord channels for moderation and record-keeping.

***

## Configuration File

Location: `shared/logs.config.lua`

```lua
Logs = {}

Logs.Enabled = true
Logs.BotName = 'sl-chat Logs'
Logs.BotAvatar = nil
Logs.IncludePlayerInfo = true
Logs.HideIP = false
```

***

## General Settings

| Option              | Type       | Default          | Description                        |
| ------------------- | ---------- | ---------------- | ---------------------------------- |
| `Enabled`           | boolean    | `true`           | Enable/disable all logging         |
| `BotName`           | string     | `'sl-chat Logs'` | Discord webhook bot name           |
| `BotAvatar`         | string/nil | `nil`            | Bot avatar URL (optional)          |
| `IncludePlayerInfo` | boolean    | `true`           | Include player identifiers in logs |
| `HideIP`            | boolean    | `false`          | Hide player IP addresses           |

***

## Log Types

Each log type can have its own webhook and settings.

```lua
Logs.Types = {
    ['rp_commands'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 1752220,
        title = 'RP Command'
    },
    ['ooc'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 9807270,
        title = 'OOC Chat'
    },
    ['private_messages'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 15277667,
        title = 'Private Message'
    },
    ['reports'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 15105570,
        title = 'Report'
    },
    ['admin'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 15158332,
        title = 'Admin'
    },
    ['system'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 3447003,
        title = 'System'
    },
    ['general'] = {
        enabled = true,
        webhook = 'YOUR_WEBHOOK_URL_HERE',
        color = 16777215,
        title = 'General'
    }
}
```

***

## Log Type Options

| Option    | Type    | Description           |
| --------- | ------- | --------------------- |
| `enabled` | boolean | Enable this log type  |
| `webhook` | string  | Discord webhook URL   |
| `color`   | number  | Embed color (decimal) |
| `title`   | string  | Embed title prefix    |

***

## Built-in Log Types

| Type               | Description                   | Used By                      |
| ------------------ | ----------------------------- | ---------------------------- |
| `rp_commands`      | RP actions (ME, DO, MED, TRY) | `/me`, `/do`, `/med`, `/try` |
| `ooc`              | OOC chat messages             | Default chat, `/globalooc`   |
| `private_messages` | Private whispers              | `/w`                         |
| `reports`          | Player reports                | `/report`, `/reportodp`      |
| `admin`            | Admin actions                 | `/ac`                        |
| `system`           | System messages               | Internal system messages     |
| `general`          | General/fallback              | Other logs                   |

***

## Discord Embed Colors

Common colors in decimal format:

| Color  | Decimal    | Hex       |
| ------ | ---------- | --------- |
| Red    | `15158332` | `#E74C3C` |
| Orange | `15105570` | `#E67E22` |
| Yellow | `16776960` | `#FFFF00` |
| Green  | `3066993`  | `#2ECC71` |
| Blue   | `3447003`  | `#3498DB` |
| Purple | `10181046` | `#9B59B6` |
| Pink   | `15277667` | `#E91E63` |
| Cyan   | `1752220`  | `#1ABC9C` |
| White  | `16777215` | `#FFFFFF` |
| Gray   | `9807270`  | `#95A5A6` |

***

## Creating Discord Webhooks

{% stepper %}
{% step %}

### Open Discord Server Settings

Right-click your server → Server Settings → Integrations
{% endstep %}

{% step %}

### Create Webhook

Click "Webhooks" → "New Webhook"
{% endstep %}

{% step %}

### Configure Webhook

{% stepper %}
{% step %}
Name your webhook (e.g., "SL-Chat RP Commands")
{% endstep %}

{% step %}
Select the channel
{% endstep %}

{% step %}
Copy the webhook URL
{% endstep %}
{% endstepper %}
{% endstep %}

{% step %}

### Add to Config

```lua
['rp_commands'] = {
    enabled = true,
    webhook = 'https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN',
    color = 1752220,
    title = 'RP Command'
}
```

{% endstep %}
{% endstepper %}

***

## Complete Configuration Example

```lua
Logs = {}

Logs.Enabled = true
Logs.BotName = 'Server Chat Logs'
Logs.BotAvatar = 'https://your-server.com/logo.png'
Logs.IncludePlayerInfo = true
Logs.HideIP = true  -- GDPR compliance

Logs.Types = {
    ['rp_commands'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 1752220,
        title = '🎭 RP Command'
    },
    ['ooc'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 9807270,
        title = '💬 OOC Chat'
    },
    ['private_messages'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 15277667,
        title = '✉️ Private Message'
    },
    ['reports'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 15105570,
        title = '⚠️ Player Report'
    },
    ['admin'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 15158332,
        title = '🔴 Admin Action'
    },
    ['system'] = {
        enabled = false,  -- Disabled
        webhook = '',
        color = 3447003,
        title = 'System'
    },
    ['general'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 16777215,
        title = '📝 General'
    }
}
```

***

## Log Information

### Player Information (when `IncludePlayerInfo = true`)

Each log includes:

| Field       | Description                      |
| ----------- | -------------------------------- |
| Player Name | Character/display name           |
| Player ID   | Server ID                        |
| Discord     | Discord user mention             |
| License     | Rockstar license                 |
| FiveM       | FiveM account ID                 |
| IP          | IP address (if `HideIP = false`) |

### Example Log Output

```
📋 ME - John Doe [15]
━━━━━━━━━━━━━━━━━━━━━━
reaches into his pocket and pulls out a wallet

Player: John Doe (ID: 15)
Identifiers:
  Discord: @John#1234
  License: license:xxxxx
  FiveM: fivem:xxxxx
  IP: ***HIDDEN***

Footer: sl-chat Logs • 2024-01-15 14:30:00
```

***

## Linking Commands to Log Types

In `commands.config.lua`, each command has a `logType` property:

```lua
['ME'] = {
    logType = 'rp_commands',  -- Links to Logs.Types['rp_commands']
    -- ... other options
}
```

***

## Adding Custom Log Types

{% stepper %}
{% step %}
Add to Logs.Types

```lua
Logs.Types = {
    -- ... existing types
    
    ['faction_chat'] = {
        enabled = true,
        webhook = 'https://discord.com/api/webhooks/xxx/yyy',
        color = 3066993,
        title = '👮 Faction Chat'
    }
}
```

{% endstep %}

{% step %}
Use in Commands

```lua
['POLICE'] = {
    logType = 'faction_chat',
    -- ... command config
}
```

{% endstep %}

{% step %}
Or Use Export

```lua
exports['sl-chat']:LogToDiscord(
    'faction_chat',
    'Police Radio',
    'Officer reporting for duty',
    {},
    source
)
```

{% endstep %}
{% endstepper %}

***

## Custom Logging via Exports

### LogToDiscord

```lua
exports['sl-chat']:LogToDiscord(
    'general',                        -- log type
    'Custom Event',                   -- title
    'Something happened',             -- description
    {                                 -- custom fields
        { name = 'Location', value = 'Legion Square', inline = true },
        { name = 'Time', value = '14:30', inline = true }
    },
    source                            -- player source (optional)
)
```

### LogChatCommand

```lua
exports['sl-chat']:LogChatCommand(
    'CUSTOM_CMD',                     -- command name
    source,                           -- player source
    'Custom message content',         -- message
    {                                 -- extra data
        customField = 'value'
    }
)
```

***

## Disabling Logs

### Disable All Logs

```lua
Logs.Enabled = false
```

### Disable Specific Type

```lua
Logs.Types = {
    ['ooc'] = {
        enabled = false,  -- Disabled
        webhook = '',
        color = 0,
        title = ''
    }
}
```

### Disable for Specific Command

Remove or comment out `logType` in command config:

```lua
['ME'] = {
    -- logType = 'rp_commands',  -- Commented out = no logging
    distance = 15.0,
    -- ...
}
```

***

## Privacy & GDPR

For GDPR compliance:

```lua
Logs.HideIP = true  -- Hide IP addresses
```

This will replace IPs with `***HIDDEN***` in all logs.

***

## Troubleshooting

### Webhook errors and missing logs

{% stepper %}
{% step %}
Check logs not appearing:

* Ensure `Logs.Enabled = true`
* Verify webhook URL is correct
* Check specific log type `enabled = true`
* Ensure webhook URL is not `'YOUR_WEBHOOK_URL_HERE'`
  {% endstep %}

{% step %}
Webhook errors:

* Discord webhooks have rate limits
* Invalid URLs will fail silently
* Check server console for HTTP errors
  {% endstep %}

{% step %}
Missing player info:

* Check `Logs.IncludePlayerInfo = true`
* Player must have valid identifiers
  {% endstep %}
  {% endstepper %}

***

## Next Steps

* [💬 Commands](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/commands) - Set command log types
* [📤 Exports](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/exports) - Custom logging exports
* [🛠️ Configuration](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/configuration) - Main config