Andrew's Username Sync

Overview

Andrew’s Username Sync is a FiveM server-side script designed to ensure that player identities are consistent across Discord and the server. By validating a player’s in-game name against their Discord nickname, the script enhances role-play immersion, improves moderation accuracy, and increases accountability.

The script provides the following core features:

1. Discord–In-Game Name Enforcement

Players attempting to join the server will be blocked if their in-game name does not exactly match their Discord nickname.

2. Customizable Kick Message

A dynamic kick message informs players why they were removed and how to fix their name. The message supports two %s placeholders:

• %s → the player’s current in-game name

• %s → the player’s Discord nickname

3. ACE Permission Exemptions

Server administrators can create ACE permissions that exempt specific users or groups from the name-matching requirement. This is useful for staff, bots, special characters, or legacy player names.

Configuration File Documentation

Below is your script’s configuration file rewritten with full documentation, including explanations of each setting.

Config = {}

---------------------------------------------------------------------
-- Andrew's Username Sync - Configuration File
-- This file controls how the script validates player names,
-- communicates with Discord, and handles connection rejections.
---------------------------------------------------------------------

-- Config.KickMessage:
-- This message is shown to players when they are kicked for having
-- an in-game name that does not match their Discord nickname.
--
-- ⚠ IMPORTANT:
-- You may ONLY use **two %s placeholders** in this message.
-- The first %s = player's in-game name
-- The second %s = player's Discord nickname
--
-- You should only edit the message text — do NOT remove or add %s
---------------------------------------------------------------------
Config.KickMessage = '\n\n❌ Your connection was suspended...\n💬 Your in-game name (%s) must match your discord name (%s).\n🍾 Please update your name in your FiveM settings and reconnect.'


---------------------------------------------------------------------
-- Config.discordToken:
-- The token of your Discord bot used for making API requests.
--
-- ⚠ SECURITY WARNING:
-- NEVER share this token publicly. Treat it like a password.
-- If it becomes exposed, regenerate it immediately on Discord.
---------------------------------------------------------------------
Config.discordToken = 'YOUR_DISCORD_BOT_TOKEN_HERE'  -- Replace with your bot token


---------------------------------------------------------------------
-- Config.serverID:
-- The Discord Server (Guild) ID to check player nicknames against.
--
-- This must be the guild where the bot is present and has
-- permissions to read member information.
---------------------------------------------------------------------
Config.serverID = '1294937973552316479'

How the Script Works

1. Player Connection Attempt

When a player attempts to connect:

1. The script retrieves:

   • Their in-game name

   • Their Discord identifier (via Discord ACE integration)

2. The script fetches the user’s Discord nickname from the specified guild using the bot token.

3. It compares:

   in-game name == discord nickname

2. Name Mismatch Handling

If the names do not match and the player does not have an ACE exemption:

• The player is immediately kicked

• The kick message is generated using:

  string.format(Config.KickMessage, ingameName, discordNickname)

3. ACE Permissions

Your script supports creating ACE rules like:

add_ace identifier.steam:11000010abcdef sync.bypass allow

Administrators can use these permissions to:

• Allow staff to retain custom names

• Exempt bots or special users

• Bypass strict formatting rules

Any player with the sync.bypass permission will not be checked.