Installation - Virus Studio

Overview

vrs_permanentid assigns a permanent, static ID number (e.g., #1042) to each player account. Unlike standard FiveM server slot IDs (1, 2, 3…), a permanent ID never changes when a player reconnects, when the server restarts, or when they switch characters.

Simplified tracking

Cleaner admin tracking, player reports, bans, clips, logs, and staff communication.

Framework support

Fully supports QBox, QBCore, and ESX via vrs_bridge.

Server-authoritative

IDs are assigned by MySQL AUTO_INCREMENT. Clients cannot influence them.

Statebag replication

Every online player carries Player(src).state.vrs_pid for any HUD or scoreboard.

Prerequisites

Ensure the following dependencies are installed and running before installation:

Dependency	Required Version	Purpose
`vrs_bridge`	`1.2.0` or newer	Framework detection system (required).
`ox_lib`	Any	UI notifications and callback handlers.
`oxmysql`	Any	Database interaction layer.

ox_lib and oxmysql are included by default in QBox and QBCore project templates. No manual SQL import is required; database tables are generated automatically on first run.

Installation Steps

Resource deployment

Extract or copy the vrs_permanentid directory into your server’s resources directory (e.g., resources/[assets]/vrs_permanentid).

Configuration file setup (server.cfg)

Open your server.cfg and add the following lines below your core framework (qbx_core, qb-core, or es_extended) and ox_lib:

ensure vrs_bridge
ensure vrs_permanentid

Critical load order: ensure vrs_bridge must run before ensure vrs_permanentid. Failure to adhere to this order will prevent execution.

ACE permissions (optional)

If your staff members do not already possess admin, god, or superadmin privileges within your core framework, grant permission explicitly in server.cfg:

add_ace group.admin vrs.permanentid allow

Verification and first run

Boot your server and verify the initialization output:

[vrs_permanentid] database ready · framework = qbox · ids start at 1000

Connect to the server and confirm the live connection log:

[vrs_pid] #1000 | YourName | netid 1 | connecting

Execute /id in the in-game chat to confirm your assigned ID (e.g., #1000).

Optional Integrations

Option A: Enable permanent IDs in core commands

To allow core framework commands (e.g., /giveitem 1042 water) to target permanent IDs alongside standard slot IDs:

Open the patches directory

Navigate to the local patches/ directory inside the resource.

Apply the snippet

Follow the instructions in patches/README.md to insert the specified code into your framework files.

ID resolution logic: Permanent IDs default to starting at 1000, while server slot IDs correspond to sv_maxclients (e.g., 1–64). The script differentiates input automatically:

/giveitem 5 water      # Targets player currently connected to Slot 5
/giveitem 1042 water   # Targets player assigned Permanent ID #1042

Option B: txAdmin integration

To display permanent IDs within txAdmin interface elements:

Player list display: modify <artifacts>/citizen/system_resources/monitor/resource/sv_playerlist.lua
Badge display: modify <artifacts>/citizen/system_resources/monitor/panel/index-*.js

Refer to Patch 3 in patches/README.md for implementation instructions.

Artifact update notice: updating your FXServer artifacts overwrites txAdmin core files. These modifications must be reapplied after any FXServer artifact upgrade.

Reference

Command reference

Command	Target audience	Functionality
`/id`	All players	Displays the caller’s own permanent ID.
`/pid <slotId>`	Staff	Displays permanent ID for a given server slot.
`/findpid <permId>`	Staff	Identifies the owner of a permanent ID (works offline).
`/showids`	Staff	Toggles overhead permanent ID display tags.

Configuration options (`config.lua`)

Parameter	Default	Description
`Config.StartId`	`1000`	Initial ID value for sequence auto-increment.
`Config.MinPid`	`1000`	Threshold below which inputs default to slot IDs.
`Config.DisplayPrefix`	`'#'`	Prefix appended to numeric IDs (e.g., `VRS-1042`).
`Config.Locale`	`'en'`	System locale language setting.
`Config.Console`	`true`	Enables or disables connection logging output.

Configuration guardrail: ensure Config.StartId is strictly greater than your sv_maxclients setting before the initial startup. Modifying this parameter after database population will not re-index existing records.

Migration and Upgrades (v1.0.0 → v1.1.0+)

Version 1.1.0 transitions from per-character tracking to per-account tracking. Database migrations execute automatically upon launch.

Database backup command

Before updating from v1.0.0, execute:

CREATE TABLE vrs_permanent_ids_backup AS SELECT * FROM vrs_permanent_ids;

Manual database reset (development / fresh servers only)

To clear all data and re-index ID sequences on an unlaunched server:

DROP TABLE vrs_permanent_ids;

Developer API Exports

-- Server-side retrieval
local pid = exports.vrs_permanentid:GetPermanentId(source)

-- Client-side retrieval
local pid = exports.vrs_permanentid:GetMyPermanentId()

-- Global state bag access (client/server)
local pid = Player(serverId).state.vrs_pid

Troubleshooting

Issue	Root cause	Resolution
`FATAL: vrs_bridge is not started`	Load order error.	Reorder `server.cfg` so `vrs_bridge` starts before `vrs_permanentid`.
`FATAL: vrs_bridge 1.2.0+ required`	Outdated dependency.	Update `vrs_bridge` to `1.2.0` or higher.
Duplicate `/id` response	Framework command conflict.	Disable the default framework `/id` command per `patches/README.md`.
`No ID assigned yet` response	Database connection issue.	Validate `mysql_connection_string` in `server.cfg` and verify `oxmysql` status.
`/giveitem` fails on permanent ID	Unpatched core framework.	Complete Option A above.

​Overview

Simplified tracking

Framework support

Server-authoritative

Statebag replication

​Prerequisites

​Installation Steps

​Optional Integrations

​Option A: Enable permanent IDs in core commands

​Option B: txAdmin integration

​Reference

​Command reference

​Configuration options (config.lua)

​Migration and Upgrades (v1.0.0 → v1.1.0+)

​Database backup command

​Manual database reset (development / fresh servers only)

​Developer API Exports

​Troubleshooting

Overview

Prerequisites

Installation Steps

Optional Integrations

Option A: Enable permanent IDs in core commands

Option B: txAdmin integration

Reference

Command reference

Configuration options (`config.lua`)

Migration and Upgrades (v1.0.0 → v1.1.0+)

Database backup command

Manual database reset (development / fresh servers only)

Developer API Exports

Troubleshooting