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

# Configuration

Zynox Studio Documents > ZYNOX RESOURCES > 🛡️ ZX - Name Guard

## ⚙️ Configuration Guide

Complete option-by-option guide for `config.lua`

***

### 📑 Table of Contents

1. [Brand & Framework Configuration](#1-brand--framework-configuration)
2. [Matching & Normalization Rules](#2-matching--normalization-rules)
3. [Grace Period & In-Game Warning NUI](#3-grace-period--in-game-warning-nui)
4. [UI & Dynamic Theme Color](#4-ui--dynamic-theme-color)
5. [Connection & Queue Enforcement](#5-connection--queue-enforcement)
6. [Discord Webhook Logging](#6-discord-webhook-logging)
7. [Localization & Translation (`Config.Locales`)](#7-localization--translation-configlocales)
8. [Complete Default Configuration](#8-complete-default-configuration)

***

### 1. Brand & Framework Configuration

All core identity and framework detection settings:

```lua
Config.BrandName = "ZynoxDev"
Config.Debug = false
Config.Framework = 'auto'
```

#### `Config.BrandName`

* **Type:** `string`
* **Default:** `"ZynoxDev"`
* **Description:** Your server or brand name displayed in console startup prints and system notices.

#### `Config.Debug`

* **Type:** `boolean`
* **Default:** `false`
* **Description:** When enabled (`true`), outputs detailed debug logs into the server console. Useful during initial setup to trace identifier fetching, character queries, and name comparison results.

#### `Config.Framework`

* **Type:** `string`
* **Default:** `'auto'`
* **Options:** `'auto'`, `'qbx'`, `'qb'`, `'esx'`, `'standalone'`
* **Description:** Specifies the framework environment.
  * `'auto'`: Recommended. Automatically checks started resources in real-time (`qbx_core`, `qb-core`, `es_extended`).
  * `'qbx'`: Forces Qbox core integration.
  * `'qb'`: Forces standard QB-Core integration.
  * `'esx'`: Forces ESX Legacy integration.
  * `'standalone'`: Queries MySQL directly without framework exports.

***

### 2. Matching & Normalization Rules

These rules determine how strictly or flexibly a player's FiveM profile name is compared against their database character name.

```lua
Config.CaseSensitive = false
Config.AllowUnderscoreAsSpace = true
Config.TrimSpaces = true
```

| Setting                         | Default | Description                                                                                                                               |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Config.CaseSensitive`          | `false` | When `false`, names match regardless of capitalization (`Kasun_Perera`, `kasun_perera`, and `KASUN_PERERA` are all treated as identical). |
| `Config.AllowUnderscoreAsSpace` | `true`  | Allows underscores `_` in FiveM profile names to match spaces in character names (`John_Doe` matches `John Doe`).                         |
| `Config.TrimSpaces`             | `true`  | Strips out extra leading, trailing, or double whitespace before comparing.                                                                |

***

### 3. Grace Period & In-Game Warning NUI

```lua
Config.EnableGracePeriod = true
Config.ShowWarningNUI = true
Config.WarningDelay = 2500
```

#### `Config.EnableGracePeriod`

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Allows brand new players (or players who just created a character) to enjoy their first session immediately without being dropped from the server. They are presented with a polite in-game warning to update their name before their next session.

#### `Config.ShowWarningNUI`

* **Type:** `boolean`
* **Default:** `true`
* **Description:** Renders the dark glassmorphism warning window upon spawning into the world if a name mismatch is detected. Includes the **1-Click Copy** character name button and Zynox Development branding watermark.

#### `Config.WarningDelay`

* **Type:** `number` (milliseconds)
* **Default:** `2500`
* **Description:** The delay in milliseconds after the player loads into the game before popping up the warning window. Ensures the player's screen and HUD have finished loading first.

***

### 4. UI & Dynamic Theme Color

```lua
Config.UI = {
    ThemeColor = "#38bdf8"
}
```

#### `Config.UI.ThemeColor`

* **Type:** `string` (HEX Color)
* **Default:** `"#38bdf8"` (Zynox Cyan)
* **Description:** Changes the primary accent color of the entire in-game NUI card dynamically without touching any CSS! The continue button, ambient card glow, and watermark gradient will immediately adapt to this color.
* **Popular Presets:**
  * **Cyan / Sky:** `"#38bdf8"` or `"#00d2ff"`
  * **Purple / Neon:** `"#a855f7"` or `"#8b5cf6"`
  * **Indigo / Classic:** `"#6366f1"`
  * **Emerald / Green:** `"#10b981"`
  * **Crimson / Red:** `"#ef4444"`
  * **Amber / Gold:** `"#f59e0b"`

***

### 5. Connection & Queue Enforcement

```lua
Config.EnforceOnConnection = true
Config.RejectStyle = 'adaptive_card'
```

#### `Config.EnforceOnConnection`

* **Type:** `boolean`
* **Default:** `true`
* **Description:** When an existing player with registered characters in the database connects, verifies their FiveM name against their character name(s) during the connecting/queue handshake (`playerConnecting`).

#### `Config.RejectStyle`

* **Type:** `string`
* **Default:** `'adaptive_card'`
* **Options:**
  * `'adaptive_card'`: Shows the interactive FiveM Adaptive Card on the connection screen with an input box where players can copy their required character name with `Ctrl + C`. Includes an automated 12-second safety disconnect timer to prevent connection limbo.
  * `'text_message'`: Instantly disconnects the player with a cleanly formatted rejection modal. **(Highly recommended if using third-party queue scripts like `connectqueue` to avoid deferral collisions).**

***

### 6. Discord Webhook Logging

```lua
Config.Discord = {
    Enabled = true,
    WebhookURL = "YOUR_DISCORD_WEBHOOK_URL_HERE",
    ServerName = "ZynoxDev Roleplay",
    AvatarURL = "https://cdn.discordapp.com/embed/avatars/0.png",
    LogColorWarning = 16753920, -- Orange
    LogColorBlocked = 15158332  -- Red
}
```

* **`Enabled`**: Set to `true` to activate Discord logs.
* **`WebhookURL`**: Paste your Discord channel webhook URL.
* **`ServerName`**: The bot username displayed on the webhook post.
* **`AvatarURL`**: Direct URL to a logo or bot avatar image.
* **`LogColorWarning`**: Decimal integer for the warning embed color.
* **`LogColorBlocked`**: Decimal integer for the connection blocked embed color.

#### Details Sent in Every Webhook Log:

* 👤 **Player FiveM Name**
* 📋 **Required Character Name**
* 💬 **Discord Account Tag** (`<@DiscordID>`)
* 🔑 **Rockstar License** (`license2:...`)
* ⚡ **Action / Reason**
* 🕒 **Timestamp & Brand Signature**

***

### 7. Localization & Translation (`Config.Locales`)

All in-game UI strings, button labels, guide steps, and adaptive card messages can be translated into any language in `Config.Locales`:

```lua
Config.Locales = {
    UI = {
        Badge = "ATTENTION REQUIRED",
        Title = "Name Synchronization Notice",
        Subtitle = "Your FiveM profile name does not match your in-game Character name.",
        FiveMNameLabel = "Current FiveM Name",
        CharacterNameLabel = "Required Character Name",
        CopyButton = "Copy Character Name",
        CopiedText = "Copied to Clipboard! ✓",
        GuideTitle = "How to update your FiveM name for next time:",
        Step1 = "1. Open your FiveM settings (gear icon on the top right).",
        Step2 = "2. Under 'Player Name', paste your copied Character name.",
        Step3 = "3. Restart FiveM or reconnect to apply the change.",
        GraceNotice = "You may continue playing today, but you must update your FiveM name before your next session to avoid connection rejection.",
        ContinueButton = "I Understand & Continue",
        DisconnectButton = "Disconnect & Fix Now"
    },
    Connection = {
        CardTitle = "NAME SYNC VERIFICATION",
        CardHeader = "Connection Rejected: Name Mismatch",
        CardBody = "Your FiveM profile name does not match your registered Character Name.\n\nPlease update your FiveM display name to match your character name before connecting.",
        ExpectedName = "Required Name:",
        CurrentName = "Your FiveM Name (Mismatch):",
        CopyInstructions = "Required Character Name (Click box & press Ctrl+C to copy):",
        Footer = "Powered by ZynoxDev Protection System",
        DisconnectBtn = "Disconnect & Fix FiveM Name"
    }
}
```

***

### 8. Complete Default Configuration

```lua
Config = {}

Config.BrandName = "ZynoxDev"
Config.Debug = false
Config.Framework = 'auto' -- 'auto', 'qbx', 'qb', 'esx', 'standalone'

Config.CaseSensitive = false
Config.AllowUnderscoreAsSpace = true
Config.TrimSpaces = true

Config.EnableGracePeriod = true
Config.ShowWarningNUI = true
Config.WarningDelay = 2500

Config.UI = {
    ThemeColor = "#38bdf8"
}

Config.EnforceOnConnection = true
Config.RejectStyle = 'adaptive_card' -- 'adaptive_card' or 'text_message'

Config.Discord = {
    Enabled = false,
    WebhookURL = "",
    ServerName = "ZynoxDev Name Guard",
    AvatarURL = "https://cdn.discordapp.com/embed/avatars/0.png",
    LogColorWarning = 16753920,
    LogColorBlocked = 15158332
}
```

***

-# © 2026 Zynox Development • [Official Store](https://zynoxdev.tebex.store/) • [Discord](https://discord.gg/2yuPTmsqjX)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://zynoxdev.gitbook.io/docs/zynox-resources/zx_nameguard/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.