# Crowe Notification System

A modern, smart notification system for RedM scripts. Features include:

* **Multi-position support** (5 positions: top-right, top-left, bottom-right, bottom-left, center)
* **Stacking notifications** (multiple visible at once, smooth sliding)
* **Priority-based ordering** (emergency, job, social, info)
* **Context-aware grouping** (combine related messages)
* **Auto-priority detection** (based on configurable keywords)
* **Configurable colors** (all notification types customizable via config.lua)
* **Custom animations, sounds, and persistent notifications**
* **Instant clearing capabilities** (clear all, by group, by type, or by ID)
* **Easy API for use in any script**

***

## 🚀 Quick Start

1. **Install:**\
   Place `crowe_notification` in your server's resources and add `ensure crowe_notification` to your `server.cfg`.
2. **Basic Usage Example:**

   ```lua
   -- Info notification
   exports['crowe_notification']:NotifyInfo('Tip', 'Press E to interact')

   -- Emergency notification
   exports['crowe_notification']:NotifyEmergency('WANTED', 'You are now wanted by the law!')
   ```

***

## �� Exported Functions & Examples

You can use these from any client script. **Function signatures and examples are below:**

### 1. `Notify` (General Notification)

**Signature:**

```lua
exports['crowe_notification']:Notify(data)
```

* `data` (table):
  * `type` (string): "info", "success", "error", "warning"
  * `title` (string, optional)
  * `message` (string, required)
  * `position` (string, optional): "top-right", "top-left", "bottom-right", "bottom-left", "center"
  * `priority` (number, optional): 1=Info, 2=Social, 3=Job, 4=Emergency
  * `duration` (number, optional): seconds
  * `animation` (string, optional): "fade-in-up", "shake", "pulse", "slide"
  * `sound` (string, optional)
  * `persistent` (bool, optional)
  * `group` (string, optional)
  * `template` (string, optional)
  * `background` (string, optional): "dark" or "light"

**Example:**

```lua
exports['crowe_notification']:Notify({
    type = "success",
    title = "Welcome!",
    message = "You have joined the server!",
    position = "center",
    priority = 2,
    duration = 5,
    animation = "fade-in-up",
    sound = "typewriter.ogg",
    persistent = false
})
```

### 2. `NotifyEmergency`

**Signature:**

```lua
exports['crowe_notification']:NotifyEmergency(title, message, options)
```

* `title` (string)
* `message` (string)
* `options` (table, optional): `{ position, animation, sound, duration, ... }`

**Example:**

```lua
exports['crowe_notification']:NotifyEmergency('WANTED', 'You are now wanted by the law!', {
    animation = 'shake',
    sound = 'alert',
    duration = 8
})
```

### 3. `NotifyJob`

**Signature:**

```lua
exports['crowe_notification']:NotifyJob(title, message, options)
```

* `title` (string)
* `message` (string)
* `options` (table, optional)

**Example:**

```lua
exports['crowe_notification']:NotifyJob('Sheriff', 'Report to the station', {
    animation = 'slide',
    sound = 'alert',
    duration = 6
})
```

### 4. `NotifySocial`

**Signature:**

```lua
exports['crowe_notification']:NotifySocial(title, message, options)
```

* `title` (string)
* `message` (string)
* `options` (table, optional)

**Example:**

```lua
exports['crowe_notification']:NotifySocial('Friend', 'John Doe sent you a message', {
    animation = 'fade-in-up',
    sound = 'typewriter.ogg',
    duration = 4
})
```

### 5. `NotifyInfo`

**Signature:**

```lua
exports['crowe_notification']:NotifyInfo(title, message, options)
```

* `title` (string)
* `message` (string)
* `options` (table, optional)

**Example:**

```lua
exports['crowe_notification']:NotifyInfo('Tip', 'Press E to interact', {
    animation = 'fade-in-up',
    duration = 3
})
```

### 6. `NotifyGroup` (Grouped Notifications)

**Signature:**

```lua
exports['crowe_notification']:NotifyGroup(groupId, title, message, options)
```

* `groupId` (string): Unique group key
* `title` (string)
* `message` (string)
* `options` (table, optional)

**Example:**

```lua
exports['crowe_notification']:NotifyGroup('bank_heist', 'Bank Robbery', 'Vault breached!')
exports['crowe_notification']:NotifyGroup('bank_heist', 'Bank Robbery', 'Alarm triggered!')
exports['crowe_notification']:NotifyGroup('bank_heist', 'Bank Robbery', 'Law enforcement en route!')
```

### 7. `ClearNotifications` (Clear/Dismiss Notifications)

**Signature:**

```lua
exports['crowe_notification']:ClearNotifications(options)
```

* `options` (table, optional):
  * `group` (string, optional): Clear notifications from specific group
  * `id` (string, optional): Clear specific notification by ID
  * `type` (string, optional): Clear notifications of specific type ("info", "success", "error", "warning")
  * `clearAll` (boolean, optional): Clear all notifications (default: false)

**Example:**

```lua
-- Clear all notifications
exports['crowe_notification']:ClearNotifications({ clearAll = true })

-- Clear notifications from specific group
exports['crowe_notification']:ClearNotifications({ group = 'bank_heist' })

-- Clear all error notifications
exports['crowe_notification']:ClearNotifications({ type = 'error' })

-- Clear specific notification by ID
exports['crowe_notification']:ClearNotifications({ id = 'unique_notification_id' })
```

### 8. `addNotification` (Simple/Legacy)

**Signature:**

```lua
exports['crowe_notification']:addNotification(message, type, duration)
```

* `message` (string)
* `type` (string): "info", "success", "error", "warning"
* `duration` (number): milliseconds

**Example:**

```lua
exports['crowe_notification']:addNotification('Your message here', 'success', 4000)
```

***

## 📍 Position Management

You can control where each notification appears on screen by setting the `position` parameter:

### Available Positions:

* `top-right` (default) - Top right corner
* `top-left` - Top left corner
* `bottom-right` - Bottom right corner
* `bottom-left` - Bottom left corner
* `center` - Center of screen

### Usage:

```lua
-- Notification in center
exports['crowe_notification']:Notify({
    type = "info",
    title = "Centered",
    message = "This notification appears in center",
    position = "center"
})

-- Notification in bottom-left
exports['crowe_notification']:NotifyEmergency('ALERT', 'Danger nearby!', {
    position = "bottom-left"
})

-- If no position is specified, uses default from config (top-right)
exports['crowe_notification']:NotifyInfo('Tip', 'This appears in default position')
```

***

## 🧩 Using Crowe Notifications in Other Scripts

You can call these exports from any other client script in your resources. Here are some examples:

### **Direct Export Usage**

```lua
-- Show a simple info notification
exports['crowe_notification']:NotifyInfo('Welcome', 'You have joined the server!')

-- Show a job notification with custom options
exports['crowe_notification']:NotifyJob('Sheriff', 'Report to the station', { animation = 'slide', sound = 'alert' })

-- Show a grouped notification (e.g., mission progress)
exports['crowe_notification']:NotifyGroup('mission_1', 'Mission', 'Objective updated!')

-- Show a custom notification with all options
exports['crowe_notification']:Notify({
    type = 'error',
    title = 'Bank Heist',
    message = 'Alarm triggered!',
    priority = 4,
    animation = 'shake',
    sound = 'alert',
    persistent = true,
    group = 'bank_heist'
})

-- Show notification with light background theme
exports['crowe_notification']:Notify({
    type = 'success',
    title = 'Light Theme',
    message = 'This notification uses light background',
    background = 'light'
})

-- Clear notifications instantly
exports['crowe_notification']:ClearNotifications({ clearAll = true })

-- Clear only bank heist notifications
exports['crowe_notification']:ClearNotifications({ group = 'bank_heist' })
```

### **Event-Based Usage**

You can also trigger notifications using events (useful for compatibility with older scripts):

```lua
-- Simple notification
TriggerEvent('Crowe:NotifySimple', 'Your message here', 'info', 4000)

-- Advanced notification
TriggerEvent('Crowe:Notify', {
    type = 'success',
    title = 'Bank',
    message = 'Transaction completed!',
    priority = 3,
    group = 'banking'
})
```

***

## 🧹 Clearing Notifications

You can instantly clear notifications using the `ClearNotifications` export function:

### **Clear All Notifications**

```lua
exports['crowe_notification']:ClearNotifications({ clearAll = true })
```

### **Clear by Group**

```lua
-- Clear all notifications from a specific group
exports['crowe_notification']:ClearNotifications({ group = 'bank_heist' })
```

### **Clear by Type**

```lua
-- Clear all error notifications
exports['crowe_notification']:ClearNotifications({ type = 'error' })

-- Clear all job notifications
exports['crowe_notification']:ClearNotifications({ type = 'warning' })
```

### **Clear Specific Notification**

```lua
-- Clear a specific notification by ID
exports['crowe_notification']:ClearNotifications({ id = 'unique_notification_id' })
```

### **Server-Side Clearing**

```lua
-- Clear all notifications for a player
TriggerClientEvent('Crowe:ClearNotifications', playerId, { clearAll = true })

-- Clear specific group for a player
TriggerClientEvent('Crowe:ClearNotifications', playerId, { group = 'mission_1' })
```

***

## 🏷️ Notification Types & Priority

| Type      | Priority | Visual        | Use For                  |
| --------- | -------- | ------------- | ------------------------ |
| info      | 1        | Default       | Tips, info, help         |
| success   | 1        | Green accent  | Success, confirmations   |
| warning   | 3        | Orange border | Warnings, cautions       |
| error     | 4        | Red, pulsing  | Errors, failures, alerts |
| social    | 2        | Default       | Player messages, chat    |
| job       | 3        | Orange border | Missions, jobs           |
| emergency | 4        | Red pulsing   | Death, wanted, alerts    |

**Note:** All these types are supported. `error` notifications are treated as "emergency" priority by default, and will appear with red coloring and alert sound. You can use any of these types in your scripts and customize their behavior in `config.lua`.

* **Priority is auto-detected** by keywords, or you can set it manually.

***

## 🧠 Features

* **Stacking:** Multiple notifications appear at once, slide smoothly when one is removed.
* **Priority:** Higher priority notifications appear above lower ones.
* **Grouping:** Related notifications combine (e.g., mission updates).
* **Animations:** Choose from fade, shake, pulse, slide.
* **Sounds:** Play a sound per notification.
* **Persistent:** Set `persistent = true` to require click to dismiss.
* **Instant clearing:** Clear all, by group, by type, or by ID.

***

## 🛠️ Configuration

Edit `config.lua` to customize:

* **Default Settings**: Default type, title, duration, and position
* **Background Theme**: Choose between 'dark' (default) or 'light' background for notifications
* **Colors**: Customize colors for each notification type (info, success, error, warning)
* **Sound Files**: Set custom sounds for each notification type
* **Templates**: Pre-defined message templates for common notifications
* **Priority Keywords**: Words that automatically set notification priority levels
* **Legacy Support**: Default settings for older notification functions

***

## 📚 Example: All Features

```lua
exports['crowe_notification']:Notify({
    type = "error",
    title = "Bank Heist",
    message = "Alarm triggered!",
    priority = 4,
    animation = "shake",
    sound = "alert",
    persistent = true,
    group = "bank_heist"
})
```

***

## 📦 Server Events

You can trigger notifications from the server:

```lua
TriggerClientEvent('Crowe:NotifyEmergency', playerId, 'WANTED', 'You are now wanted!')
TriggerClientEvent('Crowe:NotifyJob', playerId, 'Sheriff', 'Report to the station')
TriggerClientEvent('Crowe:NotifyGroup', playerId, 'bank_heist', 'Bank Robbery', 'Vault breached!')

-- Clear notifications from server
TriggerClientEvent('Crowe:ClearNotifications', playerId, { clearAll = true })
TriggerClientEvent('Crowe:ClearNotifications', playerId, { group = 'bank_heist' })
```

***

## 📝 Credits

Crowe Scripts Team

***

**For advanced usage, see the code or ask for more examples!**


---

# 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://crowescripts.gitbook.io/documentation/about-our-scripts/redm-script-documentation/crowe-notification-system.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.