> For the complete documentation index, see [llms.txt](https://project-07.gitbook.io/project_07-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://project-07.gitbook.io/project_07-docs/scripts/project07-namechecker-v3/installation.md).

# Installation

## Dependencies

✅ **Supported Scripts**\
Scripts that are fully tested and officially supported.\
🟢 Compatible and ready to use without any additional changes.

❌ **Unsupported Scripts**\
Scripts that are not tested or officially supported.\
🔴 May require custom edits or additional development to work correctly.

⚠️ **Required Dependency**\
This script is required for this resource to work properly.\
Without this dependency installed, the script will not function.

|        Dependencies        | Support |
| :------------------------: | :-----: |
| Standalone (All Framework) |    ✅    |
|           oxmysql          |    ⚠️   |

***

## Installation

1. **Download the Resource**:
   * Clone or download this repository into your `resources` folder.
   * Ensure the folder name is exactly `Project07_NameChecker` (script will warn and may malfunction if renamed).
2. **Add to Server.cfg**:

* ensure `Project07_NameChecker`

3. **Start the Server**:

* Restart your server or use `refresh` followed by `ensure Project07_NameChecker`.

***

#### Note :

Please do not rename the script folder/resource name. Changing the script name can break important functions, exports, events, and other dependencies inside the resource.

If the script name is changed, some features may stop working because the original resource name is referenced in multiple places. Please keep the original name to avoid any issues.

***

## 🧰 Configuration

Edit `config.lua`. Key options:

<table data-search="false"><thead><tr><th>Setting</th><th>Description</th></tr></thead><tbody><tr><td><code>Project07.EnableBlacklist</code></td><td>Enables/disables the blacklist system</td></tr><tr><td><code>Project07.BlacklistedNames</code></td><td>Blacklisted <strong>keywords</strong></td></tr><tr><td><code>Project07.ExactBlacklistedNames</code></td><td>Blacklisted <strong>full names</strong></td></tr><tr><td><code>Project07.MaxNameLength</code></td><td>Max allowed characters in a name</td></tr><tr><td><code>Project07.ServerImgUrl</code></td><td>Image shown on the connect-time card</td></tr><tr><td><code>Project07.UiImgUrl</code></td><td>Image shown on the in-game NUI lock screen</td></tr><tr><td><code>Project07.WebhookUrl</code></td><td>Discord webhook for logs</td></tr><tr><td><code>Project07.AdminAce</code></td><td>ACE permission required for admin commands</td></tr><tr><td><code>Project07.EnableCharacterLock</code></td><td>Enables the in-game character lock</td></tr><tr><td><code>Project07.AutoDetectFramework</code></td><td>Auto-hooks ESX/QBCore/Qbox player-loaded events</td></tr><tr><td><code>Project07.CharacterLockKickAfter</code></td><td>Seconds before a locked player is disconnected</td></tr><tr><td><code>Project07.WhitelistCommand</code></td><td>Command name for <code>/wlnamechecker</code></td></tr></tbody></table>

***

## 🔒 In-Game Character Name Lock

The connect-time check only proves the player's FiveM name matches *one of* their characters — it can't know which character they actually loaded in a multicharacter menu, since that only happens after spawn. This is a second, in-game check for that moment.

**With `Project07.AutoDetectFramework = true` (default), this is automatic** on QBCore, Qbox, and ESX — no code changes needed elsewhere. See `EXPORTS.md` for the exact events hooked, and for how to wire it up manually on a standalone/custom multicharacter system.

If the loaded character's name doesn't match the player's FiveM name:

1. The player is frozen and shown a full-screen NUI lock overlay (no close button, keyboard/right-click dismiss is blocked).
2. They're disconnected automatically after `Project07.CharacterLockKickAfter` seconds if unresolved.

There is no "unlock" mid-session other than fixing the name and reconnecting, or an admin whitelisting them — a FiveM display name can only change after restarting FiveM. The lock decision and kick timer both live on the **server**, so hiding the NUI client-side doesn't let a player bypass it: the server re-asserts the lock every 10 seconds and still disconnects on schedule regardless of client state.

***

### 🛡️ Admin Whitelist Command

Admins with the `project07.admin` ACE permission (configurable via `Project07.AdminAce`) can permanently bypass **both** checks for a connected player:

```
/wlnamechecker [server id]
```

Saves the player's discord ID + license to `project07_namechecker_whitelist` (auto-created on resource start, or run `sql/install.sql` manually) and immediately clears any active lock.

Grant the permission in `server.cfg`:

```
add_ace group.admin project07.admin allow
add_ace group.admin command.wlnamechecker allow
```

***

## 📤 Exports & Events

See **EXPORTS.md** for the full reference: the `ValidateCharacterName` export, the `project07:validateCharacter` event, and exactly which framework events are auto-hooked.

***

### 📢 Discord Logging

Blacklisted-name kicks, name-mismatch kicks, and in-game lock events are all logged to `Project07.WebhookUrl` when `Project07.EnableLogging` is `true`.