# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fiveworld.gitbook.io/fiveworld-docs/x_hud_announce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.