> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virusstudio.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install vrs_permanentid: requirements, resource order, optional ACE permission, and default configuration.

## 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.

<CardGroup cols={2}>
  <Card title="Simplified tracking" icon="clipboard-list">
    Cleaner admin tracking, player reports, bans, clips, logs, and staff communication.
  </Card>

  <Card title="Framework support" icon="layers">
    Fully supports QBox, QBCore, and ESX via [vrs\_bridge](/getting-started/submitting-a-request).
  </Card>

  <Card title="Server-authoritative" icon="shield-check">
    IDs are assigned by MySQL `AUTO_INCREMENT`. Clients cannot influence them.
  </Card>

  <Card title="Statebag replication" icon="tower-broadcast">
    Every online player carries `Player(src).state.vrs_pid` for any HUD or scoreboard.
  </Card>
</CardGroup>

## 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.             |

<Note>
  `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.
</Note>

## Installation Steps

<Steps>
  <Step title="Resource deployment" icon="folder-down">
    Extract or copy the `vrs_permanentid` directory into your server's resources directory (e.g., `resources/[assets]/vrs_permanentid`).
  </Step>

  <Step title="Configuration file setup (server.cfg)" icon="list-ordered">
    Open your `server.cfg` and add the following lines **below** your core framework (`qbx_core`, `qb-core`, or `es_extended`) and `ox_lib`:

    ```cfg theme={null}
    ensure vrs_bridge
    ensure vrs_permanentid
    ```

    <Warning>
      **Critical load order:** `ensure vrs_bridge` must run **before** `ensure vrs_permanentid`. Failure to adhere to this order will prevent execution.
    </Warning>
  </Step>

  <Step title="ACE permissions (optional)" icon="shield">
    If your staff members do not already possess `admin`, `god`, or `superadmin` privileges within your core framework, grant permission explicitly in `server.cfg`:

    ```cfg theme={null}
    add_ace group.admin vrs.permanentid allow
    ```
  </Step>

  <Step title="Verification and first run" icon="circle-check">
    Boot your server and verify the initialization output:

    ```bash theme={null}
    [vrs_permanentid] database ready · framework = qbox · ids start at 1000
    ```

    Connect to the server and confirm the live connection log:

    ```bash theme={null}
    [vrs_pid] #1000 | YourName | netid 1 | connecting
    ```

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

## 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:

<Steps>
  <Step title="Open the patches directory" icon="folder-open">
    Navigate to the local `patches/` directory inside the resource.
  </Step>

  <Step title="Apply the snippet" icon="file-code">
    Follow the instructions in `patches/README.md` to insert the specified code into your framework files.
  </Step>
</Steps>

**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:

```bash theme={null}
/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.

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

## 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.     |

<Warning>
  **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.
</Warning>

## 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:

```sql theme={null}
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:

```sql theme={null}
DROP TABLE vrs_permanent_ids;
```

## Developer API Exports

```lua theme={null}
-- 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.                                                    |