> For the complete documentation index, see [llms.txt](https://nteamdev.gitbook.io/nteam-development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nteamdev.gitbook.io/nteam-development/nitrous.md).

# Nitrous

## cfx-nteam-nitrous

**FiveM Nitrous System Technical Documentation**

***

### Overview

The resource is built on top of **ox\_lib** and **oxmysql**, and supports both the **ESX** and **QBCore** frameworks. Vehicle nitrous data is persisted in the database, so upgrades survive server restarts.

***

### Dependencies & Requirements

| Dependency        | Notes                                                     |
| ----------------- | --------------------------------------------------------- |
| `ox_lib`          | Required — shared library for callbacks and notifications |
| `oxmysql`         | Required — database connector for MySQL                   |
| `ESX` or `QBCore` | Required — one framework must be active                   |
| MySQL / MariaDB   | Required — must include a vehicle table                   |

***

### Installation

#### 1. Resource Placement

Copy the `cfx-nteam-nitrous` folder into your server's `resources` directory, then add the following line to your `server.cfg`:

```
ensure cfx-nteam-nitrous
```

#### 2. Database Setup ( Auto - Install )

Database will be installed autautomatically on first start, **you can skip this** and in case something is wrong:

You must add three columns to your vehicle table before starting the resource. Run the appropriate SQL for your framework.

**ESX** (`owned_vehicles` table):

```sql
ALTER TABLE `owned_vehicles`
  ADD COLUMN `hasnitro` int(11) DEFAULT 0,
  ADD COLUMN `noslevel` int(11) DEFAULT 0,
  ADD COLUMN `nosbottle` int(11) DEFAULT 1;
```

**QBCore** (`player_vehicles` table):

```sql
ALTER TABLE `player_vehicles`
  ADD COLUMN `hasnitro` int(11) DEFAULT 0,
  ADD COLUMN `noslevel` int(11) DEFAULT 0,
  ADD COLUMN `nosbottle` int(11) DEFAULT 1;
```

#### 3. Item Registration

The resource uses two inventory items. Register them in your framework's item database:

| Item             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `nitrous`        | Consumable item — adds one nitrous bottle to the current vehicle |
| `tablet_nitrous` | Tool item — opens the in-game configuration tablet               |

***

### Configuration (`config.lua`)

All server-owner settings live in `config.lua`. The file is excluded from escrow so you can edit it freely.

#### Core Settings

| Key                      | Description                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `Config.Framework`       | `'QB'` or `'ESX'` - selects which framework bridge to load                                       |
| `Config.BoostMultiplier` | Torque multiplier applied during boost. Formula: `1.0 + (flowRate × multiplier)`. Default: `1.5` |
| `Config.FakePlate`       | Set `true` if your server uses a fake-plate system and has a `fakeplate` column in the DB        |
| `Config.TurboRequired`   | If `true`, the vehicle must have a turbo mod installed before nitrous can be added               |
| `Config.Debug`           | Enables extra console commands for testing. Set `false` in production                            |
| `Config.DBTableName`     | The database table name for vehicles. Default: `player_vehicles`                                 |
| `Config.VisualEffects`   | Enables/disables screen shake and motion blur during boost                                       |
| `Config.UseNitrousBar`   | Shows/hides the HUD nitrous progress bar                                                         |
| `Config.Item`            | Item name that triggers adding a nitrous bottle. Default: `nitrous`                              |
| `Config.TabletItem`      | Item name that opens the configuration tablet. Default: `tablet_nitrous`                         |

#### Nitrous Capacity

| Key                           | Description                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `Config.DefaultNitrousNumber` | Maximum number of bottles allowed on vehicles without a custom offset entry. Default: `1` |
| `Config.NitroPerBottle`       | Nitrous units added per bottle (also the max level per bottle). Default: `100`            |

#### Vehicle Bottle Offsets

`Config.NitroVehicleOffset` defines the 3D position and rotation of each nitrous bottle for specific vehicle models. The number of entries in the table for a model also determines how many bottles that vehicle can hold.

```lua
Config.NitroVehicleOffset = {
  ['sultanrs'] = { -- this vehicle supports 2 bottles
    [1] = {
      vehiclebone = 'chassis',
      offsetx = 0.15, offsety = -0.25, offsetz = 0.35,
      rotation = vector3(0.0, 0.0, 0.0)
    },
    [2] = {
      vehiclebone = 'chassis',
      offsetx = -0.15, offsety = -0.25, offsetz = 0.35,
      rotation = vector3(0.0, 0.0, 0.0)
    }
  },
}
```

`Config.NitroVehicleDefaultOffset` is used as a fallback for any vehicle model not listed in `Config.NitroVehicleOffset`.

#### Blacklisted Vehicles

Vehicles listed in `Config.BlackListedVehicles` cannot have nitrous installed. Useful for supercars, tanks, or other vehicles where nitrous would be unbalanced.

```lua
Config.BlackListedVehicles = {
  ['formula'] = true,
  ['rhino'] = true,
}
```

#### Tablet Offsets

`Config.TabletOffsetVehicles` sets the position and rotation of the in-game tablet prop for specific vehicle models. `Config.TabletDefaultOffset` is the fallback for unlisted vehicles. The tablet attaches to the `windscreen` bone.

#### Notifications

The `Notification` function at the bottom of `config.lua` controls how alerts are displayed. By default it uses `lib.notify` from ox\_lib. You can replace it with any notification system (e.g. ESX notifications, QB notifications, or a custom UI).

```lua
Notification = function(message, type)
  -- type 1 = success, type 2 = error
  lib.notify({ title = 'Nitrous', description = message, type = 'success' })
end
```

***

### Exports

Two client-side exports are provided for integration with custom HUDs or other resources:

| Export            | Description                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nitrousLevel()`  | Returns the current nitrous level as a normalized value (`0.0` to `1.0`). Returns `0` if the player is not in a vehicle or the vehicle has no nitrous. |
| `nitrousActive()` | Returns `true` if the player is currently using nitrous, `false` otherwise.                                                                            |

#### Usage Example

```lua
-- In another resource's client script:
local level  = exports['cfx-nteam-nitrous']:nitrousLevel()  -- 0.0 - 1.0
local active = exports['cfx-nteam-nitrous']:nitrousActive() -- true / false
```

***

### Commands & Key Bindings

#### Default Commands

| Command / Binding | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `UseNitro`        | Key binding (keyboard) — activates nitrous while held. Assign in GTA V settings.                |
| `Effects`         | Console command — toggles visual effects (screen shake, motion blur) on/off while in a vehicle. |

#### Debug Commands

> These commands are only available when `Config.Debug = true`.

| Command                     | Description                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `givenitro`                 | Triggers the `addNos` event as if the player used the nitrous item.                            |
| `shownitro`                 | Prints the current nitrous level for the player's vehicle to the console.                      |
| `nitroui`                   | Opens the tablet UI while in a vehicle, regardless of whether the tablet item is in inventory. |
| `nitrobar`                  | Toggles the nitrous HUD bar visibility with a test value of 75%.                               |
| `clearnitro`                | Deletes all spawned nitrous bottle props.                                                      |
| `nitro_bottleoffset [bone]` | Opens the offset editor for bottle positioning. Default bone: `chassis`.                       |
| `nitro_tabletoffset [bone]` | Opens the offset editor for tablet positioning. Default bone: `windscreen`.                    |