> For the complete documentation index, see [llms.txt](https://fiveworld.gitbook.io/fiveworld-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fiveworld.gitbook.io/fiveworld-docs/x_hud_announce.md).

# X\_HUD\_Announce

### 🌟 Overview

`X_HUD_Announce` is designed to enhance the communication system on your FiveM server by providing a flexible and powerful way to manage announcements and notifications. It supports multiple languages, integrates with popular frameworks like ESX and QBCore, and offers extensive customization options.

***

### ✨ Features

* **🌐 Multilingual Support**: Supports English, German, Spanish, French, and Italian.
* **📣 Admin Announcements**: Send global and internal announcements.
* **👮‍♂️ Job-related Announcements**: Send global and internal announcements for specific jobs.
* **👤 Player-specific Notifications**: Send notifications to individual players.
* **🔄 Automatic Announcements**: Schedule automatic announcements at regular intervals.
* **🔗 Discord Webhook Integration**: Log announcements to Discord.
* **⏱️ Cooldown System**: Prevent spam by setting cooldowns for different types of announcements.
* **⚙️ Framework Support**: Compatible with ESX and QBCore.
* **🎨 Customizable Prefixes and Styles**: Customize the appearance of announcements.
* **🔌 TxAdmin Integration**: Seamless integration with txAdmin features.

***

### 🌍 Language Support

`X_HUD_Announce` supports multiple languages. You can change the current language in `config.lua` using the `Config.Language` variable:luaCopy

```lua
Config.Language = 'en' -- Available options: 'en', 'de', 'es', 'fr', 'it'
```

To add a new language, edit the `shared/translation.lua` file and extend the `Translations.Languages` and `Translations.Messages` sections.

***

### 🔄 Integration with Other Scripts

`X_HUD_Announce` offers various exports and events that can be used by other scripts.

#### 📮 Server-side Exports

```lua
-- Send an announcement to all players
exports['X_HUD_Announce']:SendAnnounceToAll(message, type, duration)

-- Send an announcement to a specific player
exports['X_HUD_Announce']:SendAnnounceToPlayer(playerId, message, type, duration)

-- Send an announcement to all players with a specific job
exports['X_HUD_Announce']:SendAnnounceToJob(job, message, type, duration)

-- Send a notification to a specific player
exports['X_HUD_Announce']:SendNotification(playerId, message, type, duration)

-- Get a translation based on a key
local translation = exports['X_HUD_Announce']:GetTranslation(key, language, ...)
```

#### 📥 Server-side Events

```lua
-- Send an announcement to all players
TriggerEvent('X_Announce:SendToAll', message, type, duration)

-- Send an announcement to a specific player
TriggerEvent('X_Announce:SendToPlayer', playerId, message, type, duration)

-- Send an announcement to all players with a specific job
TriggerEvent('X_Announce:SendToJob', job, message, type, duration)

-- Send a notification to a specific player
TriggerEvent('X_Announce:Notify', playerId, message, type, duration)
```

#### 📱 Client-side Exports

```lua
-- Show an announcement for the local player
exports['X_HUD_Announce']:ShowAnnouncement(message, type, duration)

-- Get a translation based on a key
local translation = exports['X_HUD_Announce']:GetTranslation(key, ...)

-- Send an announcement to all players (triggers to server and back)
exports['X_HUD_Announce']:TriggerServerAnnounce(message, type, duration)

-- Send an announcement to a specific player
exports['X_HUD_Announce']:TriggerServerAnnounceToPlayer(playerId, message, type, duration)

-- Send an announcement to all players with the same job
exports['X_HUD_Announce']:TriggerServerAnnounceToJob(job, message, type, duration)
```

#### 📲 Client-side Events

```lua
-- Show a local announcement
TriggerEvent('X_Announce:ShowLocal', message, type, duration)
```

#### 🔄 Using Translations

You can use translation keys with an `@` at the beginning:luaCopy

```lua
-- Server-side
exports['X_HUD_Announce']:SendNotification(playerId, "@enter_message", 'error')

-- With formatting parameters
exports['X_HUD_Announce']:SendNotification(playerId, "@player_not_found", 'error', nil, targetId)
```

#### 🎨 Notification Types

The following types can be used for notifications:

* 'info' (default, blue) 🟦
* 'success' (green) 🟢
* 'warning' (yellow) 🟨
* 'error' (red) 🟥
* Job names (e.g., 'police', 'ambulance', 'mechanic') 👮‍♂️🚑🔧
* TxAdmin types ('txadminannounce', 'txadminrestart', 'txadminwarning', 'txadmindm') 📢🔄⚠️💬

#### 📏 Parameters

* `message`: The text to display (string)
* `type`: The type of notification (string, optional, default: 'info')
* `duration`: The duration in milliseconds (number, optional, default: from config)
* `playerId`: The server ID of the player (number)
* `job`: The job name (string)
* `key`: The translation key (string)
* `language`: The language (string, optional, default: from config)

***

### ⚙️ Configuration Guide

#### 🌟 Core Settings

```lua
Config.BetterDriveBy = true        -- Master switch
Config.DebugMode = false           -- Enable for troubleshooting
Config.DebugCommandName = "carseat"
```

#### 🌍 Language Configuration

```lua
Config.Language = 'en' -- Available options: 'en', 'de', 'es', 'fr', 'it'
```

#### 📢 Notification Configuration

```lua
Config.DefaultDuration = 5000 -- Standard display duration of notifications in milliseconds
```

#### 🛠️ Framework Configuration

```lua
Config.Framework = 'esx' -- 'auto', 'esx', 'qbcore'
Config.UseOldESX = false -- Set to 'true' for older ESX versions that use TriggerEvent instead of Export
```

#### ⏱️ Cooldown Configuration

```lua
Config.AnnounceCooldown = 60      -- Global cooldown for automatic announcements
Config.AdminAnnounceCooldown = 30 -- Cooldown for admin announcements
Config.AdminInternalAnnounceCooldown = 15 -- Cooldown for internal admin announcements
Config.JobAnnounceCooldown = 120  -- Cooldown for job announcements
Config.JobInternalAnnounceCooldown = 30 -- Cooldown for internal job announcements
Config.PlayerAnnounceCooldown = 20 -- Cooldown for player-specific announcements
```

#### 🔄 Automatic Announcement Configuration

```lua
Config.EnableAutoAnnounces = true      -- Enables/Disables automatic announcements
Config.AutoAnnounceInterval = 6000      -- Interval in seconds between automatic announcements

Config.AutoAnnounces = {
    {message = "Welcome to our server! Have fun playing.", type = "info", duration = 8000},
    {message = "Visit our Discord server for more information.", type = "info", duration = 6000},
    {message = "Need help? Contact an admin with /report.", type = "warning", duration = 7000},
    {message = "Respect other players and follow the rules.", type = "error", duration = 9000},
    {message = "Don't forget to read our server rules!", type = "success", duration = 5000},
}
```

#### 🛡️ Admin Permissions Configuration

```lua
Config.AdminAnnounceAllPerms = {
    ['superadmin'] = true,
    ['admin'] = true,
    ['moderator'] = true,
    ['supporter'] = true
}

Config.AdminAnnounceTeamPerms = {
    ['superadmin'] = true,
    ['admin'] = true,
    ['moderator'] = true,
    ['supporter'] = true
}

Config.AdminAnnouncePlayerPerms = {
    ['superadmin'] = true,
    ['admin'] = true,
    ['moderator'] = true,
    ['supporter'] = true
}
```

#### 👮‍♂️ Job Announcements Configuration

```lua
Config.JobsWithAnnouncePerms = {
    ['police'] = true,
    ['ambulance'] = true,
    ['mechanic'] = true,
    ['taxi'] = true,
    ['reporter'] = true,
}

Config.JobsWithInternalAnnounce = {
    ['police'] = true,
    ['ambulance'] = true,
    ['mechanic'] = true,
    ['taxi'] = true,
    ['reporter'] = true,
}
```

***

### 📋 Examples

#### 📢 Example 1: Sending an announcement to all players from a server script

```lua
exports['X_HUD_Announce']:SendAnnounceToAll("[SYSTEM] Server restart in 5 minutes!", "warning", 10000)
```

#### 📢 Example 2: Sending a notification to a player with translation

```lua
-- With a custom translation key
exports['X_HUD_Announce']:SendNotification(playerId, "@player_not_found", 'error', nil, targetId)
```

#### 📢 Example 3: Sending an announcement to all police officers

```lua
exports['X_HUD_Announce']:SendAnnounceToJob("police", "[LSPD] All available units to headquarters!", "police", 8000)
```

#### 📢 Example 4: Triggering a client-side notification

```lua
exports['X_HUD_Announce']:ShowAnnouncement("Mission objective completed!", "success", 5000)
```

***

### 🔄 TxAdmin Integration

This resource provides seamless integration with txAdmin features:

#### 📢 Announcements

Automatically captures and formats txAdmin announcements from administrators using the `txAdmin:events:announcement` event. Displays these announcements to all players using your configured styling.

#### 🔄 Scheduled Restarts

Displays countdown notifications when a server restart is scheduled through txAdmin using the `txAdmin:events:scheduledRestart` event. The script automatically calculates the minutes remaining and formats a message according to your configuration.

#### ⚠️ Warnings

Shows warning notifications to players when they receive a warning from an administrator through the `txAdmin:events:playerWarned` event. Can be configured to also notify staff members.

#### 💬 Direct Messages

Displays direct messages sent from administrators to players through txAdmin using the `txAdmin:events:playerDirectMessage` event. Can be configured to also notify staff about sent messages.

***

### 📤 Discord Logging

Configuration for logging various announcements to Discord:luaCopy

```lua
Config.DiscordLogs = {
    enabled = false,                                  -- Enables/Disables Discord logging in general
    forceDisableIfNoHTTP = false,                     -- Dont touch
    -- Discord Webhook URLs for different announcement types
    -- Set to nil or empty ("") to disable a specific log type
    webhooks = {
        admin = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",       -- Admin announcements to all
        team = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",        -- Team-internal announcements
        player = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",      -- Player-specific announcements
        job = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",         -- Job announcements to all
        jobInternal = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE", -- Job-internal announcements
        auto = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",        -- Automatic announcements
        txadmin = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE"      -- TxAdmin announcements
    },
    
    -- Bot name displayed in Discord
    botName = "X_HUD_Announce",
    
    -- Avatar URL for the bot (optional)
    botAvatar = "https://i.imgur.com/.png",    -- URL to an image for the bot avatar
    
    -- Embed colors for different message types (decimal value of the color)
    -- Discord uses decimal values instead of hex colors
    colors = {
        admin = 15105570,       -- Orange (decimal value of hex color)
        team = 16727113,        -- Red
        player = 16766720,      -- Gold
        job = 3447003,          -- Blue
        jobInternal = 2067276,  -- Dark Blue
        auto = 5763719,         -- Green
        txadmin = 10181046,     -- Purple
        
        -- Colors for different notification types
        info = 3447003,         -- Blue
        success = 5763719,      -- Green
        error = 15548997,       -- Red
        warning = 16776960      -- Yellow
    },
    
    -- General settings
    serverName = "Your Server Name",   -- Name of the server displayed in logs
    includeTimestamp = true,          -- Add timestamp to embed
    
    -- Content displayed in logs
    logContent = {
        showPlayerId = true,          -- Shows player ID in logs
        showPlayerIdentifiers = false, -- Shows player identifiers (steam, license, etc.) in logs
        includeType = true            -- Shows the type of announcement in the log
    }
}
```

***

### 🎨 Customization

#### 📐 Appearance Settings

```lua
Config.appearance = {
    transparency = 0.75,        -- 0.0 (fully transparent) to 1.0 (fully opaque)
    backgroundColor = '#2a2a2a', -- Dark grey background for all notifications
    accentColorOpacity = 0.35,  -- Opacity of accent color in background when glass effect is enabled
    iconGlow = true,
    iconGlowColor = 'rgba(255, 255, 255, 0.7)',
    iconGlowSize = '6px',
    iconSize = '36px',        -- Size of the icon - increased
    iconPack = 'ionicons',     -- Icon pack to use: 'fontawesome' or 'ionicons'
    rounded = true,
    roundedSize = '10px',
    notificationGlow = {
        enabled = true,
        color = '#ffffff',
        strength = '10px',
        opacity = 0.5,
        useAccentColor = true
    },
    realGlassEffect = {
        enabled = true,
        blurStrength = 3.0,       -- Blur effect strength (0-20)
        transparency = 0.5,       -- Background transparency (0.0-1.0) 
        performanceMode = false   -- Performance mode with reduced quality for weaker devices
    },
    boxShadow = {
        enabled = false,
        color = 'rgba(0, 0, 0, 0.92)',
        blur = '15px',
        spread = '0px',
        x = '0px',
        y = '5px'
    },
    font = {
        family = 'Poppins, "Segoe UI", sans-serif',
        color = '#FFFFFF',
        size = '14px',
        weight = 'normal',
        lineHeight = '1.4',
        availableFonts = [
            'Poppins',
            'Montserrat',
            'Kanit',
            'Gidole',
            'Pacifico',
            'Dancing Script',
            'Segoe UI'
        ]
    }
}
```

#### 🔄 Animation Settings

```lua
Config.animation = {
    type = 'slide',            -- Animation type: 'slide', 'fade', 'scale', 'flip', 'none'
    direction = 'top',       -- Direction for slide animation: 'left', 'right', 'top', 'bottom'
    duration = 750,            -- Duration in ms
    distance = '110%',         -- Distance to slide (for slide animations)
    easing = 'cubic-bezier(0.25, 1, 0.5, 1)', -- Easing function
    
    -- Advanced animation options
    scaleFrom = 0.8,           -- Starting scale for scale animations
    scaleTo = 1,               -- Ending scale for scale animations
    fadeFrom = 0,              -- Starting opacity for fade animations
    fadeTo = 1,                -- Ending opacity for fade animations
    rotateFrom = -90,          -- Starting rotation for flip animations (degrees)
    rotateTo = 0               -- Ending rotation for flip animations (degrees)
}
```

***

### 🛠️ Troubleshooting

#### 🔄 Common Issues

* **"Drive-By Not Working"**:
  * Check `Config.BetterDriveBy = true`
  * Verify seat permissions for the vehicle
  * Use `/carseat` debug command
* **Conflicts with Other Resources**:
  * Disable sky-to-ground transitions if using multicharacter scripts
  * luaCopy

    ```lua
    Config.transition.enabled = false
    ```

***

### 📥 Download & Support

* **Tebex Store**: [Download Link](https://fiveworldshop.tebex.io/package/6789318)
* **Discord Support**: [Join Discord](https://discord.gg/8MzHYRtKME)