> For the complete documentation index, see [llms.txt](https://new-era-2.gitbook.io/benjyyis-script/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://new-era-2.gitbook.io/benjyyis-script/business-announcement-system/editor.md).

# Installation & Config

### 📦 Installation Guide – `b_announces`

This script allows businesses in your FiveM server to post dynamic and styled announcements via a UI. Each announcement supports emojis, markdown formatting, and logos, and fades out individually after a configurable time.

***

#### 🔧 Requirements

* **ESX, QBCore or QBox** (selectable in the config)\
  \
  You can change the core related export in `cl_utils.lua`

***

#### 📁 Installation Steps

1. **Place the Resource**
   * Drop the `b_annonces` folder into your `resources` directory.
2. **Ensure the Resource**\
   Add the following to your `server.cfg`:

   ```cfg
   ensure b_annonces
   ```
3. **Configure It**\
   Open `config.lua` and edit:

   ```lua
   Config = Config or {}

   Config.Core = 'esx' -- 'esx' 'qbcore' or 'qbox' Set your core here, it will be used to get the player job

   Config.UseCommand = true -- Set to true to use a command to open the announcement system, set to false to disable it
   Config.CommandName = 'announces' -- Command to open the announcement system, you can change it to whatever you want
   Config.UseKeyMapping = true -- Set to true to use a key mapping to open the announcement system, set to false to disable it
   Config.KeyMapping = 'F3' -- Key to open the announcement system, you can change it to whatever you want, leave it as is if you don't want to use key mapping
   Config.KeyMappingTitle = "Open Announcement System" -- Title of the key mapping, you can change it to whatever you want, leave it as is if you don't want to use key mapping
   Config.TestAnnounce = false -- (/testannounce) Set to true to test the announcement system, it will show a test announcement when you open the system, set to false to disable it

   Config.Time = 15000 -- Time in ms before the announcement disappears, you can change it to whatever you want
   Config.ProgressBar = true -- Set to true to show a progress bar when the announcement is displayed, set to false to disable it
   Config.PlaySound = true -- Set to true to play a sound when the announcement is displayed, set to false to disable it 


   -- The webhooks is sended only when a player sends an announcement, it will not be sent for scheduled announcements.
   Config.SendWebhook = false -- Set to true to send a webhook when an announcement is sent, set to false to disable it
   Config.WebhookURL = "https://discord.com/api/webhooks/your_webhook_url_here" -- Webhook URL to send the announcement, you can change it to whatever you want, leave it as is if you don't want to use webhooks


   -- You can translate some text in index.html


   -- The job was taken automatically from the player data, this config is used to set the company name ONLY ('Benny's Custom Garage' instead of mechanic for example) for each job.
   Config.JobToCompanyName = {
       police = 'Los Santos Police Department',
       ambulance = 'San Andreas Medical Services',
       mecano = 'Benny\'s Custom Garage',
       mechanic = 'Benny\'s Custom Garage',
       burger = 'Burger Shot',
       pizza = 'Pizza This'

       -- Add more jobs and their corresponding company names here : 
       -- jobname = 'Company Name',
       -- For logo, add the .png file in html/logo/ with the same name as the job for example : police.png for police job, ambulance.png for ems etc.
   }

   Config.ScheduledAnnouncements = { -- Scheduled announcements will be displayed at the specified time, you can add as many as you want
       --{
       --    time = "13:40", -- Time in HH:MM format, it will be displayed at this time
       --    job = "police", -- Job that will send the announcement
       --    message = ":police_car: **Rappel**\nLes recrutements sont ouverts !", -- Message to display, you can use emojis from Config.Emojis
       --    image = "https://imgs.search.brave.com/xB93cgrB3oZ7Os6iVJ74r18s_LZcYgUSH5N7a4jzLCE/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9zaGFy/ZWQuZmFzdGx5LnN0/ZWFtc3RhdGljLmNv/bS9zdG9yZV9pdGVt/X2Fzc2V0cy9zdGVh/bS9idW5kbGVzLzQ4/Mzc4L3cwdG16cW96/eGwzZXdsbmQvNDQz/NDY4NGRhYjEzZjJj/ZWYwNjhkZmMzNGQw/MTJjYWZiNWUxMmM3/ZS9oZWFkZXJfNTg2/eDE5Mi5qcGc_dD0x/NzMzODYxMDQ5", -- Optional image URL to display in the announcement, you can remove this line if you don't want to use images
       --    progressBar = true, -- Set to true to show a progress bar when the announcement is displayed
       --    sound = true, -- Set to true to play a sound when the announcement is displayed
       --    duration = 10000 -- Time in ms before the announcement disappears, you can change it to whatever you want
       --},
       --{
       --    time = "20:00",
       --    job = "mecano",
       --    message = "**:tools: Promo spéciale ce soir !**",
       --    progressBar = false,
       --    sound = true,
       --    duration = 8000
       --}
   }


   Config.Emojis = {-- Use :name: to use the emojis in annoucements (ex: :fire: → 🔥) you can add many more emojis 
       smile = "😄", sad = "😢", fire = "🔥", heart = "❤️", star = "⭐", warning = "⚠️",
       check = "✅", cross = "❌", clock = "⏰", money = "💰", car = "🚗", truck = "🚚",
       wrench = "🔧", hammer = "🔨", tools = "🛠️", phone = "📞", alert = "🚨", police = "👮",
       ambulance = "🚑", hospital = "🏥", burger = "🍔", pizza = "🍕", drink = "🥤", party = "🥳",
       gift = "🎁", info = "ℹ️", boom = "💥", skull = "💀", ghost = "👻", blood = "🩸",
       explosion = "💣", love = "😍", cool = "😎", gun = "🔫", knife = "🔪", lock = "🔒",
       unlock = "🔓", id = "🆔", doc = "📄", box = "📦", note = "📝", eyes = "👀",
       door = "🚪", radio = "📻", gas = "⛽", store = "🏪", bank = "🏦", crown = "👑",
       calendar = "📅", globe = "🌍", location = "📍", light = "💡", megaphone = "📢",
       rocket = "🚀", medal = "🎖️", trophy = "🏆", shopping = "🛒", sale = "🏷️",
       mechanic = "🛠️", music = "🎶", mic = "🎤", camera = "📸", film = "🎬", bar = "🍻",
       cocktail = "🍸", wine = "🍷", beer = "🍺", confetti = "🎉", siren = "🔊",
       spark = "✨", moon = "🌙", sun = "☀️", thunder = "⚡", snow = "❄️", star2 = "🌟",
       bag = "👜", airplane = "✈️", map = "🗺️", laptop = "💻", cpu = "🧠", building = "🏢",
       house = "🏠", hotel = "🏨", ticket = "🎟️", art = "🎨", recycle = "♻️", test = "🧪",
       pill = "💊", shield = "🛡️", judge = "⚖️", alarm = "⏳", time = "🕒", handshake = "🤝",
       moneybag = "💰", robot = "🤖", hacker = "💻", bandit = "🥷", chef = "👨‍🍳", paintbrush = "🖌️",
       pin = "📌", pushpin = "📍", zap = "🏴", camera_flash = "📷", fuel = "⛽", bell = "🔔",
       books = "📚", box_open = "📦", hourglass = "⌛", medal_1st = "🥇", medal_2nd = "🥈", medal_3rd = "🥉",
       truck_delivery = "🚛", taxi = "🚕", motorcycle = "🏍️", police_car = "🚓", helicopter = "🚁", train = "🚆",
       boat = "🚤", warehouse = "🏭", clipboard = "📋", cart = "🛍️", bag_shopping = "🛍️",
       warning_red = "🟥", green_circle = "🟢", red_circle = "🔴", yellow_circle = "🟡",
       white_circle = "⚪", black_circle = "⚫", boom_cloud = "🌩️", chat = "💬",
       loudspeaker = "📣", scroll = "📜", envelope = "✉️", package = "📦", fuel_pump = "⛽", rotating_light = "🚨"
   }
   ```

***

### 💡 Features

* ✅ Display styled announcements from any job
* 🖼️ Show job-specific logos
* 📝 Supports markdown formatting: `**bold**`, `*italic*`, `__underline__`
* 😊 Emoji support via `:emoji:` syntax
* 🕦 Scheduled Announcement via Config.lua

***

### 🕦 Scheduled Announcements 

To use the scheduled announcement feature, you need to go in `config.lua`

The scheduled announcements will be sended one time per day. You can use HTML balise in the text and discord markdowns too.

```lua
Config.ScheduledAnnouncements = { -- Scheduled announcements will be displayed at the specified time, you can add as many as you want
    {
        time = "13:40", -- Time in HH:MM format, it will be displayed at this time
        job = "police", -- Job that will send the announcement
        message = ":police_car: **Rappel**\nLes recrutements sont ouverts !", -- Message to display, you can use emojis from Config.Emojis
        image = "https://imgs.search.brave.com/xB93cgrB3oZ7Os6iVJ74r18s_LZcYgUSH5N7a4jzLCE/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9zaGFy/ZWQuZmFzdGx5LnN0/ZWFtc3RhdGljLmNv/bS9zdG9yZV9pdGVt/X2Fzc2V0cy9zdGVh/bS9idW5kbGVzLzQ4/Mzc4L3cwdG16cW96/eGwzZXdsbmQvNDQz/NDY4NGRhYjEzZjJj/ZWYwNjhkZmMzNGQw/MTJjYWZiNWUxMmM3/ZS9oZWFkZXJfNTg2/eDE5Mi5qcGc_dD0x/NzMzODYxMDQ5", -- Optional image URL to display in the announcement, you can remove this line if you don't want to use images
        progressBar = true, -- Set to true to show a progress bar when the announcement is displayed
        sound = true, -- Set to true to play a sound when the announcement is displayed
        duration = 10000 -- Time in ms before the announcement disappears, you can change it to whatever you want
    },
    {
        time = "20:00",
        job = "mecano",
        message = "**:tools: Promo spéciale ce soir !**",
        progressBar = false,
        sound = true,
        duration = 8000
    }
}

```

If you don't want to use it, just delete the announcement and let the config like this.

```lua
Config.ScheduledAnnouncements = { -- Scheduled announcements will be displayed at the specified time, you can add as many as you want

}

```

***

### 🧪 Usage

#### 📜 Command

Players can type `/announce` in chat to open the input UI.

> This will only work if their job is configured in `JobToCompanyName`.

***

#### ⚙️ Export Usage

You can trigger a company announcement programmatically using the export:

```lua
exports["b_announces"]:SendAnnounce(text)

For example : 

exports["b_announces"]:SendAnnounce("**Big Sale** :gift: \n Tonight only, we offer a big deal :gift:")

```

> The script will detect the player’s current job and auto-assign the appropriate name and logo.

***

#### ✍️ Markdown & Emoji Format Examples

In your message, you can use:

* `**bold**`
* `*italic*`
* `__underline__`
*  for new lines
* Emojis like `:gift:`, `:fire:`, `:tools:` (mapped in config)

Example:

```lua
"**Special Offer**\n:gift: 20% Off on Repairs! :tools:\nCall us now :phone:"
```

***

### 🛠️ UI Customization

Logos should be placed in:

```
b_announces/html/logo/
```

Example:\
For a job `mechanic`, put `mechanic.png` in that folder.

Make sure the image name matches the job name in lowercase.

***

### 📞 Support

If you run into any issues, join our discord [here](https://discord.gg/mmZCuR3Egq).