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

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

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.

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.

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

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

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