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

> Step by step instructions to install the Masks resource

## Installation Steps

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

    <Card title="ox_lib" icon="book" href="https://github.com/CommunityOx/ox_lib/releases/latest">
      Download ox\_lib
    </Card>
  </Step>

  <Step title="Extract and place the resource">
    Extract the script from the zip file and place it into your standalone folder or a folder that starts before your scripts.
  </Step>

  <Step title="Add items to your inventory">
    Add the items below and the images from the `images` folder (`gasmask.png`, `nightvision.png`) to your inventory.

    <Tabs>
      <Tab title="ox_inventory">
        ```lua theme={null}
        ['gasmask'] = {
            label = 'Gas Mask',
            weight = 450,
            stack = false,
            close = true,
            description = "Phewww..",
            client = {
                event = 'projectx-masks:client:UseGasMask',
            },
        },

        ['nightvision'] = {
            label = 'Nightvision Goggles',
            weight = 450,
            stack = false,
            close = true,
            description = "Phewww..",
            client = {
                event = 'projectx-masks:client:UseNightVision',
            },
        },
        ```
      </Tab>

      <Tab title="qb-inventory">
        ```lua theme={null}
        ['gasmask'] = {['name'] = 'gasmask', ['label'] = 'Gas Mask', ['weight'] = 450, ['type'] = 'item', ['image'] = 'gasmask.png', ['unique'] = false, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = "Phewww.."},
        ['nightvision'] = {['name'] = 'nightvision', ['label'] = 'Nightvision Goggles', ['weight'] = 450, ['type'] = 'item', ['image'] = 'nightvision.png', ['unique'] = true, ['useable'] = true, ['shouldClose'] = true, ['combinable'] = nil, ['description'] = "Phewww.."},
        ```
      </Tab>
    </Tabs>

    <Info>
      The images are provided in the `images` folder that you downloaded. For ox\_inventory, the `client.event` fields are required so using the item triggers the mask/goggles logic.
    </Info>
  </Step>

  <Step title="Configure the resource">
    Open `config.lua` and set your Framework, Inventory, and Notification. See the configuration section below for details.
  </Step>

  <Step title="Add to server.cfg">
    Make sure ox\_lib is started before the script.

    ```cfg theme={null}
    ensure ox_lib
    ensure projectx-masks
    ```
  </Step>
</Steps>

## Configuration

Below is the configuration file with explanations for each option.

```lua theme={null}
Config = Config or {}

Config = {
    Framework = "qb-core", -- "qb-core", "qbox", "esx" or "custom"
    Inventory = "ox", -- "ox" or "qs" or "qb" or "codem" or "esx" or "lj" or "ps"
    Notification = "ox", -- "ox" or "qb" or "esx"

    ["GasMask"] = {
        ["Item"] = "gasmask",
        ["Clothing"] = 129,
        ["Variation"] = 1,
    },

    ["NightVisionGoggles"] = {
        ["Item"] = "nightvision",
        ["Clothing"] = 119,
    },

    ["NotificationDuration"] = 5000,
}
```

### General Settings

<ParamField path="Framework" type="string" default="qb-core">
  Framework adapter. Options: `"qb-core"`, `"qbox"`, `"esx"`, or `"custom"`.
</ParamField>

<ParamField path="Inventory" type="string" default="ox">
  Inventory adapter. Options: `"ox"`, `"qs"`, `"qb"`, `"codem"`, `"esx"`, `"lj"`, or `"ps"`.
</ParamField>

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

<ParamField path="NotificationDuration" type="number" default="5000">
  Duration in milliseconds for notifications.
</ParamField>

### Gas Mask

<ParamField path="GasMask.Item" type="string" default="gasmask">
  Usable item name for the gas mask.
</ParamField>

<ParamField path="GasMask.Clothing" type="number" default="129">
  Ped mask component drawable ID (component slot 1). Adjust if your clothing pack uses different drawables.
</ParamField>

<ParamField path="GasMask.Variation" type="number" default="1">
  Texture variation for the gas mask clothing drawable.
</ParamField>

### Night Vision Goggles

<ParamField path="NightVisionGoggles.Item" type="string" default="nightvision">
  Usable item name for the night vision goggles.
</ParamField>

<ParamField path="NightVisionGoggles.Clothing" type="number" default="119">
  Hat/prop index (prop slot 0). When night vision or thermal is active, the script uses `Clothing - 1` for the on state.
</ParamField>

<Note>
  Clothing drawable IDs may need adjusting per clothing pack. Equipping the gas mask also applies toxic/smoke entity proofs so the player is protected from gas and smoke effects.
</Note>