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

# Installation

> How to install NEX Crutch System on your FiveM server.

## Requirements

| Dependency                                               | Required | Notes                                                                                                                                                                                                                                  |
| -------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`ox_lib`](https://github.com/overextended/ox_lib)       | yes      | Callbacks, notifications, command registration, textUI, points.                                                                                                                                                                        |
| **Inventory**                                            | one of   | [`ox_inventory`](https://github.com/overextended/ox_inventory) (preferred), [`qb-inventory`](https://github.com/qbcore-framework/qb-inventory), or ESX's legacy inventory.                                                             |
| **Framework**                                            | one of   | [`qbx_core`](https://github.com/Qbox-project/qbx_core), [`qb-core`](https://github.com/qbcore-framework/qb-core), [`es_extended`](https://github.com/esx-framework/esx_core), or [`ND_Core`](https://github.com/ND-Framework/ND_Core). |
| [`ox_target`](https://github.com/overextended/ox_target) | optional | Needed for the EMS player target option, and for the medic NPC when `Config.Interaction = 'target'`.                                                                                                                                   |

## Steps

1. Drop the `nex_crutchsystem/` folder into your `resources/` tree, e.g.:

   ```
   resources/[assets]/nex_crutchsystem
   ```

2. Add it to your `server.cfg` after `ox_lib` and your inventory:

   ```
   ensure ox_lib
   ensure ox_inventory   # if you use it
   ensure ox_target      # if you want the target option
   ensure nex_crutchsystem
   ```

3. Register the `crutch` item in your inventory — see [Inventory item](#inventory-item) below.

4. Copy the bundled icon into your inventory's image folder:

   * `ox_inventory/web/images/crutch.png`
   * `qb-inventory/html/images/crutch.png`

   The source PNG ships at `install/crutch.png` inside the resource.

5. Restart the server.

The UI ships **ready to use** — there is no build step and nothing to compile.

## Inventory item

Pick the snippet that matches your inventory. The full reference lives in `install/items.lua` inside the resource.

### ox\_inventory

Add this entry to `ox_inventory/data/items.lua`:

```lua theme={null}
['crutch'] = {
    label       = 'Crutch',
    weight      = 1500,
    stack       = false,
    close       = true,
    description = 'A medical crutch. Use to toggle limping on or off.',
    client = {
        image = 'crutch.png',
    },
    server = {
        export = 'nex_crutchsystem.useCrutch',
    },
},
```

The `server.export` points at the existing `useCrutch` handler in `nex_crutchsystem/server/crutches.lua`, which already handles the per-player use counter, breaking, and the equip / unequip toggle.

### QBCore / Qbox

Add to `qb-core/shared/items.lua` (or `qbx_core/shared/items.lua`):

```lua theme={null}
crutch = {
    name        = 'crutch',
    label       = 'Crutch',
    weight      = 1500,
    type        = 'item',
    image       = 'crutch.png',
    unique      = false,
    useable     = true,
    shouldClose = true,
    description = 'A medical crutch. Use to toggle limping on or off.',
},
```

Then register the use callback in any server script:

```lua theme={null}
QBCore.Functions.CreateUseableItem('crutch', function(source, item)
    exports['nex_crutchsystem']:useCrutch(source, item, item.slot, nil)
end)
```

### ESX legacy

Register the item in your DB / items table, then bind its use callback:

```lua theme={null}
ESX.RegisterUsableItem('crutch', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    local item    = xPlayer.getInventoryItem('crutch')
    exports['nex_crutchsystem']:useCrutch(source, item, item and item.slot, nil)
end)
```

## Checking it worked

From your server console:

```
state nex_crutchsystem
```

Should print `started`. From F8 in-game:

```
lua print(GetResourceState('nex_crutchsystem'))
```

Stand near a configured `MedicLocations` entry — the NPC should spawn within `Config.SpawnDistance` and the blip should be on the map.

## Updating

`config.lua` and the `bridge/*.lua` files are listed under `escrow_ignore`, so your settings and any custom framework / inventory adapters survive updates.

1. Replace the resource files with the new version (keep your edited `config.lua` and any bridge tweaks).
2. Restart the resource:

   ```
   restart nex_crutchsystem
   ```