# exports

## Overview

SL-Chat provides various exports for both client and server-side scripts. These allow you to integrate the chat system with your other resources.

***

## Client Exports

### Chat State

#### `isChatActive`

Check if chat input is currently active.

```lua
local isActive = exports['sl-chat']:isChatActive()

if isActive then
    -- Chat is open
end
```

| Returns    | Type    | Description            |
| ---------- | ------- | ---------------------- |
| `isActive` | boolean | `true` if chat is open |

***

### Messages

#### `addMessage`

Add a message to the chat.

```lua
-- Simple message
exports['sl-chat']:addMessage('Hello World!')

-- Structured message
exports['sl-chat']:addMessage({
    template = '<div style="color: red;">{0}</div>',
    args = { 'Red colored message' }
})

-- With color
exports['sl-chat']:addMessage({
    color = { 255, 0, 0 },
    args = { 'Server', 'This is a red message' }
})
```

| Parameter | Type         | Description                           |
| --------- | ------------ | ------------------------------------- |
| `message` | string/table | Message content or structured message |

***

### Suggestions

#### `addSuggestion`

Add a command suggestion.

```lua
exports['sl-chat']:addSuggestion('/mycommand', 'My command description', {
    { name = 'param1', help = 'First parameter' },
    { name = 'param2', help = 'Second parameter' }
})
```

| Parameter | Type   | Description           |
| --------- | ------ | --------------------- |
| `name`    | string | Command name (with /) |
| `help`    | string | Command description   |
| `params`  | table  | Parameter definitions |

***

#### `addSuggestions`

Add multiple suggestions at once.

```lua
exports['sl-chat']:addSuggestions({
    {
        name = '/command1',
        help = 'First command',
        params = {}
    },
    {
        name = '/command2',
        help = 'Second command',
        params = {
            { name = 'id', help = 'Player ID' }
        }
    }
})
```

***

#### `removeSuggestion`

Remove a command suggestion.

```lua
exports['sl-chat']:removeSuggestion('/mycommand')
```

***

### 3D Display

#### `addDisplay`

Add 3D text above a player's head.

```lua
local displayId = exports['sl-chat']:addDisplay(
    'Hello World!',           -- text
    playerId,                 -- server ID of player
    { 255, 255, 255 },       -- color {r, g, b}
    5000,                     -- duration in ms
    { r = 0, g = 0, b = 0, a = 150 },  -- background (optional)
    {                         -- settings override (optional)
        textScale = 0.35,
        heightOffset = 0.5
    }
)
```

| Parameter         | Type   | Description                |
| ----------------- | ------ | -------------------------- |
| `text`            | string | Text to display            |
| `serverId`        | number | Player's server ID         |
| `color`           | table  | RGB color `{r, g, b}`      |
| `duration`        | number | Duration in milliseconds   |
| `background`      | table  | Optional background color  |
| `displaySettings` | table  | Optional settings override |

| Returns     | Type   | Description               |
| ----------- | ------ | ------------------------- |
| `displayId` | number | Unique ID for the display |

***

#### `removeDisplay`

Remove a 3D display by ID.

```lua
exports['sl-chat']:removeDisplay(displayId)
```

***

### Cursor

#### `isCursorActive`

Check if cursor is active in chat.

```lua
local cursorActive = exports['sl-chat']:isCursorActive()
```

***

#### `setCursorActive`

Set cursor state.

```lua
exports['sl-chat']:setCursorActive(true)  -- Enable cursor
exports['sl-chat']:setCursorActive(false) -- Disable cursor
```

***

#### `toggleCursor`

Toggle cursor on/off.

```lua
exports['sl-chat']:toggleCursor()
```

***

#### `disableCursor`

Force disable cursor.

```lua
exports['sl-chat']:disableCursor()
```

***

### Streamer Mode

#### `isStreamerMode`

Check if streamer mode is active.

```lua
local isStreamer = exports['sl-chat']:isStreamerMode()
```

***

#### `setStreamerMode`

Set streamer mode state.

```lua
exports['sl-chat']:setStreamerMode(true)  -- Enable
exports['sl-chat']:setStreamerMode(false) -- Disable
```

***

## Server Exports

#### SendTemplate

**NEW!** Send predefined template messages to players.

```lua
exports['sl-chat']:SendTemplate(templateType, playerId, message)
```

| Parameter      | Type   | Description                                                   |
| -------------- | ------ | ------------------------------------------------------------- |
| `templateType` | string | Template name: SYSTEM, WELCOME, ERROR, SUCCESS, INFO, WARNING |
| `playerId`     | number | Target player server ID                                       |
| `message`      | string | Message content                                               |

**Examples:**

```lua
-- Success notification
exports['sl-chat']:SendTemplate('SUCCESS', playerId, 'Vehicle purchased!')

-- Error message
exports['sl-chat']:SendTemplate('ERROR', playerId, 'Not enough money')

-- System notification
exports['sl-chat']:SendTemplate('SYSTEM', playerId, 'Server restart in 5 minutes')

-- Info message
exports['sl-chat']:SendTemplate('INFO', playerId, 'New event starting!')

-- Warning
exports['sl-chat']:SendTemplate('WARNING', playerId, 'Low fuel!')

-- Welcome message
exports['sl-chat']:SendTemplate('WELCOME', playerId, 'Welcome to the server!')
```

***

### Messages

#### `addMessage`

Send message to player(s).

```lua
-- To all players
exports['sl-chat']:addMessage('Global message!')

-- To specific player
exports['sl-chat']:addMessage(playerId, 'Personal message!')

-- Structured message to player
exports['sl-chat']:addMessage(playerId, {
    template = '<div style="color: green;">{0}</div>',
    args = { 'Green message' }
})
```

| Parameter | Type         | Description               |
| --------- | ------------ | ------------------------- |
| `target`  | number       | Player ID or `-1` for all |
| `message` | string/table | Message content           |

***

### Suggestions

#### `addSuggestion`

Add suggestion (server-side).

```lua
-- To all players
exports['sl-chat']:addSuggestion('/servercommand', 'Description', {})

-- To specific player
exports['sl-chat']:addSuggestion(playerId, '/playercommand', 'Description', {})
```

***

#### `addSuggestions`

Add multiple suggestions.

```lua
exports['sl-chat']:addSuggestions({
    { name = '/cmd1', help = 'Help 1', params = {} },
    { name = '/cmd2', help = 'Help 2', params = {} }
})

-- To specific player
exports['sl-chat']:addSuggestions(playerId, suggestions)
```

***

#### `removeSuggestion`

Remove suggestion.

```lua
exports['sl-chat']:removeSuggestion('/oldcommand')

-- From specific player
exports['sl-chat']:removeSuggestion(playerId, '/oldcommand')
```

***

### Modes

#### `registerMode`

Register a chat mode/channel.

```lua
local success = exports['sl-chat']:registerMode({
    name = 'staff',
    displayName = 'Staff Chat',
    color = '#ff0000',
    isChannel = true,
    isGlobal = true,
    seObject = 'group.staff',  -- ACE permission (optional)
    cb = function(source, outMessage, hookRef)
        -- Custom callback for this mode
    end
})
```

| Parameter     | Type     | Description             |
| ------------- | -------- | ----------------------- |
| `name`        | string   | Unique mode identifier  |
| `displayName` | string   | Display name in UI      |
| `color`       | string   | Mode color (hex)        |
| `isChannel`   | boolean  | Is this a channel       |
| `isGlobal`    | boolean  | Is globally visible     |
| `seObject`    | string   | ACE permission required |
| `cb`          | function | Message callback        |

***

### Hooks

#### `registerMessageHook`

Register a hook for all messages.

```lua
exports['sl-chat']:registerMessageHook(function(source, outMessage, hookRef)
    -- Modify message
    hookRef.updateMessage({
        template = '<div>Modified: {}</div>'
    })
    
    -- Or cancel message
    hookRef.cancel()
    
    -- Or change routing
    hookRef.setRouting(targetPlayerId)
    hookRef.setSeObject('group.admin')
end)
```

Hook Reference Methods:

| Method                        | Description               |
| ----------------------------- | ------------------------- |
| `hookRef.updateMessage(data)` | Modify message properties |
| `hookRef.cancel()`            | Cancel message            |
| `hookRef.setRouting(target)`  | Set message target        |
| `hookRef.setSeObject(object)` | Set ACE permission filter |

***

### Logging

#### `LogToDiscord`

Send log to Discord webhook.

```lua
exports['sl-chat']:LogToDiscord(
    'rp_commands',                    -- log type
    'Custom Log Title',               -- title
    'Log description here',           -- description
    {                                 -- fields (optional)
        { name = 'Field 1', value = 'Value 1', inline = true },
        { name = 'Field 2', value = 'Value 2', inline = true }
    },
    source                            -- player source (optional)
)
```

***

#### `LogChatCommand`

Log a chat command.

```lua
exports['sl-chat']:LogChatCommand(
    'ME',                    -- command name
    source,                  -- player source
    'example action',        -- message
    { distance = 15.0 }      -- extra data (optional)
)
```

***

#### `GetPlayerIdentifiersData`

Get player's identifiers.

```lua
local ids = exports['sl-chat']:GetPlayerIdentifiersData(playerId)

-- ids.steam
-- ids.license
-- ids.discord
-- ids.ip
-- ids.fivem
```

***

## Events

### Client Events

| Event                   | Description              |
| ----------------------- | ------------------------ |
| `chat:addMessage`       | Add chat message         |
| `chat:addSuggestion`    | Add command suggestion   |
| `chat:addSuggestions`   | Add multiple suggestions |
| `chat:removeSuggestion` | Remove suggestion        |
| `chat:addMode`          | Add chat mode            |
| `chat:removeMode`       | Remove chat mode         |
| `chat:addTemplate`      | Add message template     |
| `chat:clear`            | Clear chat               |
| `w-chat:SendRPMessage`  | Send RP command message  |
| `w-chat:triggerDisplay` | Trigger 3D text display  |
| `w-chat:chatClosed`     | Chat was closed          |

### Server Events

| Event                      | Description             |
| -------------------------- | ----------------------- |
| `chat:init`                | Player chat initialized |
| `_chat:messageEntered`     | Player sent message     |
| `w-chat:server:log`        | Log to Discord          |
| `w-chat:server:logCommand` | Log chat command        |

***

## Usage Examples

### Custom Notification System

```lua
-- Client-side
RegisterNetEvent('myresource:notify', function(message, type)
    local colors = {
        success = { 0, 255, 0 },
        error = { 255, 0, 0 },
        info = { 0, 128, 255 }
    }
    
    exports['sl-chat']:addMessage({
        template = '<div style="background: rgba(' .. table.concat(colors[type] or colors.info, ',') .. ', 0.8); padding: 10px; border-radius: 5px;">{0}</div>',
        args = { message }
    })
end)
```

### Integration with Other Scripts

```lua
-- Server-side logging from another script
RegisterNetEvent('myresource:logAction', function(action)
    local src = source
    exports['sl-chat']:LogToDiscord(
        'general',
        'Player Action',
        action,
        {},
        src
    )
end)
```

### Custom 3D Text

```lua
-- Show floating text above player
local function ShowFloatingText(playerId, text, duration)
    exports['sl-chat']:addDisplay(
        text,
        playerId,
        { 255, 255, 255 },
        duration or 3000,
        { r = 0, g = 0, b = 0, a = 180 }
    )
end
```

***

## Next Steps

* [📋 Logs Configuration](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/logs) - Discord webhook logging
* [💬 Commands](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/commands) - Chat commands
* [⚙️ Framework Bridge](https://scriptlock.gitbook.io/script-lock-docs/resources/chat-system/framework-bridge) - Framework integration