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

# Installation

> Install and configure the Project X XP skill system

## Installation Steps

<Steps>
  <Step title="Install dependencies">
    <Warning>
      Verify all dependencies below are started **before** this script in your `server.cfg`.
    </Warning>

    <CardGroup cols={2}>
      <Card title="ox_lib" icon="book" href="https://github.com/CommunityOx/ox_lib/releases/latest">
        Download ox\_lib (CommunityOx)
      </Card>

      <Card title="oxmysql" icon="database" href="https://github.com/overextended/oxmysql/releases/latest">
        Download oxmysql (overextended)
      </Card>
    </CardGroup>
  </Step>

  <Step title="Extract and place the resource">
    Extract the script from the zip file and place it into your resources folder (for example `standalone` or `[projectx]`).
  </Step>

  <Step title="Import the SQL">
    Import `sql/install.sql` into your database. This creates the `player_xp` table.

    <Info>
      The script can also auto-add missing columns at runtime if the table already exists.
    </Info>

    <Info>
      Legacy Pickle XP JSON data can migrate automatically when skill keys match entries in `Config.Skills`.
    </Info>
  </Step>

  <Step title="Configure the resource">
    Open `config/config.lua` and adjust the settings to your liking. See the [configuration](#configuration) section below for details.
  </Step>

  <Step title="Add to server.cfg">
    Start `projectx-xp` **after** your framework, ox\_lib, and oxmysql, and **before** any scripts that award XP:

    ```cfg theme={null}
    ensure ox_lib
    ensure oxmysql
    ensure projectx-xp
    ```
  </Step>

  <Step title="Configure the bridge (Optional)">
    If you use [projectx-bridge](/resources/bridge/installation), set `XPSystem` to `'projectx'` or `'auto'`.

    * `'projectx'` — always use projectx-xp
    * `'auto'` — detects projectx-xp when the resource is started

    See the [Bridge Installation](/resources/bridge/installation) page for full setup.
  </Step>

  <Step title="Add the menu item (Optional)">
    If you enable `UseItem`, add the `x_device` item to your inventory so players can open the XP menu from an item.
  </Step>
</Steps>

<Warning>
  Never grant XP from the client. All XP changes must go through server exports only.
</Warning>

## Configuration

Key options in `config/config.lua`:

### General Settings

<ParamField path="Lan" type="string" default="en">
  Language locale used by the resource.
</ParamField>

<ParamField path="Framework" type="string">
  Your server framework (for example QBCore, Qbox, or ESX). Match this to your server setup.
</ParamField>

<ParamField path="Inventory" type="string">
  Your inventory system. Required if you use `UseItem` with `x_device`.
</ParamField>

<ParamField path="OpenCommand" type="string" default="xp">
  Chat command to open the XP menu (e.g. `/xp`).
</ParamField>

<ParamField path="OpenKey" type="string" default="F7">
  Keybind to open the XP menu.
</ParamField>

<ParamField path="UseItem" type="boolean">
  When enabled, using the `x_device` item opens the XP menu. Add the item to your inventory if you enable this.
</ParamField>

### Notifications

<ParamField path="Notification" type="string">
  Notification system: `'customui'`, `'ox'`, `'qb'`, or `'esx'`.
</ParamField>

<ParamField path="NotificationDuration" type="number">
  Default notification display duration.
</ParamField>

<ParamField path="BuffNotificationDuration" type="number">
  Display duration for XP buff notifications.
</ParamField>

<ParamField path="NotifyOnXpGain" type="boolean">
  Notify the player when they gain XP.
</ParamField>

<ParamField path="NotifyOnLevelUp" type="boolean">
  Notify the player when they level up.
</ParamField>

<ParamField path="NotifyOnMilestone" type="boolean">
  Notify the player when they reach a milestone.
</ParamField>

<ParamField path="NotifyOnBuff" type="boolean">
  Notify the player when an XP buff is applied or removed.
</ParamField>

### UI & Leaderboard

<ParamField path="LeaderboardLimit" type="number">
  Maximum number of entries shown on the leaderboard.
</ParamField>

<ParamField path="AccentColor" type="string">
  Primary accent color for the XP UI.
</ParamField>

<ParamField path="UiScale" type="number">
  Overall UI scale multiplier.
</ParamField>

<ParamField path="NotificationScale" type="number">
  Scale multiplier for XP-related notifications.
</ParamField>

<ParamField path="ShowMilestoneRewards" type="boolean">
  Show milestone reward details in the UI.
</ParamField>

<ParamField path="UseLevelTitles" type="boolean">
  Display level titles from each skill's `LevelTitles` table.
</ParamField>

<ParamField path="SkillOrder" type="table">
  Ordered list of skill IDs that controls how skills appear in the UI.
</ParamField>

### Skills (`Config.Skills`)

Each entry in `Config.Skills` is keyed by a skill ID (for example `criminal`) and supports:

| Field         | Description                       |
| ------------- | --------------------------------- |
| `Label`       | Display name shown in the UI      |
| `Description` | Short description of the skill    |
| `Icon`        | Icon used in the UI               |
| `BaseXp`      | Base XP required for early levels |
| `Multiplier`  | XP curve multiplier per level     |
| `MaxLevel`    | Maximum level for the skill       |
| `LevelTitles` | Optional titles keyed by level    |
| `Milestones`  | Level thresholds with `Rewards`   |

Milestone `Rewards` support types such as:

* `money` — cash/bank reward
* `item` — inventory item reward
* `export` — custom export callback

**Default skills:** `criminal`, `fishing`, `crafting`, `mechanic`, `delivery`, `farming`, `diving`, `mining`

```lua theme={null}
Config.Skills = {
    criminal = {
        Label = 'Criminal',
        Description = 'Crime and heists',
        Icon = 'skull',
        BaseXp = 100,
        Multiplier = 1.15,
        MaxLevel = 100,
        LevelTitles = {
            [1] = 'Rookie',
            [25] = 'Career Criminal',
        },
        Milestones = {
            [10] = {
                Rewards = {
                    { type = 'money', amount = 500 },
                    { type = 'item', name = 'lockpick', amount = 2 },
                }
            },
        },
    },
}
```

## UI Build

The shipped UI lives in `web/build`. Only rebuild `web/` if you edit the UI source:

```bash theme={null}
cd web
npm install
npm run build
```