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

# Pepper Notify

Free notifications in four types with title, timer bar and sound – standalone for every server.

{% hint style="success" %}
✅ **Get Pepper Notify:** <https://shop.pepperscripts.de/package/7729478>
{% endhint %}

{% hint style="info" %}
🧪 **Tested on our dev server:** Of course we test all scripts continuously on our own dev server “Pepper Scripts”.
{% endhint %}

Free and open source: <https://github.com/PepperScripts/pepper\\_notify>

## Overview

With Pepper Notify every message on your server looks the same: success, error, info or warning, with an optional title, a timer bar and a sound. Your scripts call the export from the client or the server, the message appears in one of 8 positions, the bar runs down and it is gone. If the same `id` comes in again, it replaces the message instead of stacking it.

### Features

* Four types: `success`, `error`, `info`, `warning`, each with its own colour and icon
* Optional title, timer bar and sound (native GTA sounds, no audio files)
* Eight screen positions with an adjustable distance from the edge (`Config.Offset`); colours and durations set in `config.lua`
* Exports for client and server, plus a client event
* Accepts the field names of ox\_lib (`description`, `type = 'inform'`) and QBCore (`text`, `length`, `'primary'`)
* Same `id` replaces a notification instead of stacking it
* No dependencies, no loop running in the background

## Requirements

| Dependency                                      | Required/optional | What for                                                                                           | Link                                                             |
| ----------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| FiveM server (`fx_version 'cerulean'`, Lua 5.4) | required          | Runs the resource                                                                                  | <https://docs.fivem.net/docs/server-manual/setting-up-a-server/> |
| Framework (ESX Legacy, QBCore, Qbox)            | optional          | Not needed – standalone. With a framework you can reroute its notifications (see "For developers") | –                                                                |
| OneSync                                         | not needed        | –                                                                                                  | –                                                                |
| Database                                        | not needed        | Pepper Notify stores nothing – no database, no oxmysql                                             | –                                                                |

## Installation

1. Put the `pepper_notify` folder into your `resources` folder. **Do not rename the folder** – the exports are called `exports.pepper_notify:…` and only work with exactly this name.
2. Add it to your `server.cfg` – **before** the scripts that send notifications:

   ```
   ensure pepper_notify
   # then your other scripts, e.g.
   ensure my_garage
   ```
3. Restart the server. There is no database and there are no items.

### First test

1. In game press **T** and type `/notifytest` (in the F8 console without the slash: `notifytest`).
2. Four messages appear on the right side in the middle: green "Saved successfully.", red "Something went wrong.", blue without a title and orange "Your vehicle is low on fuel.".
3. Watch the timer bar: after about 5 seconds three messages disappear, the orange one stays for about 8 seconds.
4. When everything looks right, set `Config.TestCommand = false`.

## Configuration

| File             | Controls                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `config.lua`     | Position, distance from the edge, duration, count, timer bar, sound, colours, test command |
| `html/style.css` | Look of the notifications (font, corners, background) – for your own adjustments           |

After a change, `restart pepper_notify` in the server console is enough (or a server restart).

### Position and offset

```lua
Config.Position = 'center-right'
Config.Offset = { x = 1.5, y = 2.0 }
```

| Option            | Default                | Description                                                                                                          |
| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Config.Position` | `'center-right'`       | `top-right`, `top-left`, `top-center`, `center-right`, `center-left`, `bottom-right`, `bottom-left`, `bottom-center` |
| `Config.Offset`   | `{ x = 1.5, y = 2.0 }` | Distance from the screen edge (1 = roughly one line of text) – use it to move notifications clear of your HUD        |

### Duration and count

| Option                   | Default | Description                                                            |
| ------------------------ | ------- | ---------------------------------------------------------------------- |
| `Config.DefaultDuration` | `5000`  | Duration in milliseconds when the call does not give one               |
| `Config.MinDuration`     | `1000`  | Shorter values are raised to this                                      |
| `Config.MaxDuration`     | `30000` | Longer values are cut to this                                          |
| `Config.MaxVisible`      | `5`     | How many notifications are visible at once; older ones disappear first |
| `Config.ProgressBar`     | `true`  | Timer bar below the notification                                       |

### Sound and colours

```lua
Config.Sound = {
    enabled = true,
    default = { name = 'SELECT', set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    error   = { name = 'ERROR',  set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
}
Config.Colors = { success = '#3DD68C', error = '#E5484D', info = '#4C9AFF', warning = '#FF8A3D' }
```

| Option                 | Default                                    | Description                                                                   |
| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| `Config.Sound.enabled` | `true`                                     | Sound on show on/off                                                          |
| `Config.Sound.default` | `SELECT` / `HUD_FRONTEND_DEFAULT_SOUNDSET` | GTA sound for every type without its own entry                                |
| `Config.Sound.error`   | `ERROR` / `HUD_FRONTEND_DEFAULT_SOUNDSET`  | Own sound for errors; you can add `success`, `info` or `warning` the same way |
| `Config.Colors`        | see above                                  | Accent colour per type (icon, border, timer bar) as a hex value               |
| `Config.TestCommand`   | `true`                                     | `/notifytest` command on/off                                                  |

## For developers

### Calling it

Client (long form as a table or short form):

```lua
exports.pepper_notify:Notify({ title = 'Garage', message = 'Vehicle parked.', type = 'success', duration = 5000 })
exports.pepper_notify:Notify('Vehicle parked.', 'success', 5000)
```

Server (the first value is the player ID, `-1` = all players):

```lua
exports.pepper_notify:Notify(source, { title = 'Bank', message = 'You received $500.', type = 'info' })
exports.pepper_notify:Notify(-1, 'Server restart in 10 minutes.', 'warning', 10000)
```

| Field      | Meaning                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `message`  | Text (required; `description` or `text` work too)                                                          |
| `title`    | Bold first line (optional)                                                                                 |
| `type`     | `success`, `error`, `info` or `warning` (default `info`); `inform`, `primary` → `info`, `warn` → `warning` |
| `duration` | Milliseconds (also `length`), limited to `MinDuration`–`MaxDuration`                                       |
| `id`       | A notification with the same `id` replaces the previous one                                                |

### Reroute your framework's notifications

* **ESX:** in `es_extended/client/functions.lua`, let `ESX.ShowNotification` call `exports.pepper_notify:Notify(message, notifyType, length)`.
* **QBCore / Qbox:** in `qb-core/client/functions.lua`, let `QBCore.Functions.Notify` call `exports.pepper_notify:Notify(text, texttype, length)`.

## Commands and permissions

| Command       | Who                             | What                                                                            |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `/notifytest` | all players (no ACE permission) | Shows all four notification types; only active with `Config.TestCommand = true` |

There are no other commands, permissions or keys.

## Exports and events

| Side   | Name                       | Call                                                                                       |
| ------ | -------------------------- | ------------------------------------------------------------------------------------------ |
| Client | Export `Notify`            | `exports.pepper_notify:Notify(data)` or `Notify(text, type, duration)`                     |
| Server | Export `Notify`            | `exports.pepper_notify:Notify(playerId, data)` or `Notify(playerId, text, type, duration)` |
| Client | Event `pepper_notify:show` | `TriggerClientEvent('pepper_notify:show', source, { message = 'Hello', type = 'info' })`   |

## FAQ

### How do I use Notify from my script?

On the client `exports.pepper_notify:Notify('Text', 'success')`, on the server `exports.pepper_notify:Notify(source, 'Text', 'success')`. Alternatively the event `pepper_notify:show` – examples under "For developers".

### The server does not know `/notifytest` – what now?

Check that `ensure pepper_notify` is in your `server.cfg`, the folder is named exactly `pepper_notify` and `Config.TestCommand = true` is set. The command is only registered when the test command is switched on.

### How do I change the colours?

Put a hex value per type into `Config.Colors`, e.g. `success = '#22C55E'`, then `restart pepper_notify`.

### The notifications cover my HUD – how do I move them?

`Config.Position` picks one of the 8 positions, `Config.Offset` pushes them further away from the edge (`x` horizontal, `y` vertical, 1 ≈ one line of text).

### Can I show ESX or QBCore notifications through Pepper Notify?

Yes. Let `ESX.ShowNotification` or `QBCore.Functions.Notify` call the export (one line, see "For developers"). The type names `primary` (QBCore) and `inform` (ox\_lib) automatically become `info`.

### Do GTA colour codes like `~r~` or HTML work in the text?

No. Title and message are shown as plain text (`textContent`), so colour codes and HTML appear literally. This keeps player texts from being run as HTML. The colour comes from the type.

### How do I send a notification to all players?

On the server with `-1` as the player ID: `exports.pepper_notify:Notify(-1, 'Restart in 10 minutes.', 'warning', 10000)`.

### How do I stop the same notification from stacking?

Pass a fixed `id`, e.g. `{ id = 'fuel', message = 'Fuel low', type = 'warning' }`. A new notification with the same `id` replaces the old one.

### How long can a notification stay at most?

Between `Config.MinDuration` (1 second) and `Config.MaxDuration` (30 seconds); values outside are adjusted. Without a value `Config.DefaultDuration` (5 seconds) applies.

### How do I turn the sound off or change it?

`Config.Sound.enabled = false` turns it off. For another sound change `name`/`set` (GTA frontend sounds); for single types add an entry like `success = { name = '…', set = '…' }`.

### Are notifications lost right after joining?

No. If notifications arrive before the UI has loaded, the client keeps them and shows them as soon as the NUI is ready.

### How do I update Pepper Notify?

Replace the folder, back up your `config.lua` first and put your values back afterwards. What changed is listed in the `CHANGELOG.md` in the resource folder.

## Support

Open a ticket in our [Discord](https://discord.gg/6NaFJWKDYu) (category “Script Support”) and link your purchase with `/verify` first.

## Changelog

Current version **1.0.2**: new positions `center-right` (new default) and `center-left`, plus `Config.Offset`. All changes are listed in the `CHANGELOG.md` in the resource folder.