# Documentation

### Features

* **Multi-Bottle System** — Install up to 5 NOS bottles per vehicle, each with individual NOS levels
* **Multi-Bottle Types** - Install NOS bottles in Cars and Bikes
* **Purge Kit System** — Up to 3 purge kits per car and 2 Per bike with customizable nozzle positions and colors
* **Two Boost Modes** — `power` (raw engine multiplier) or `drive` (respects speed caps)
* **10 Pressure Levels** — Each level increases boost strength, camera shake, and flame size
* **Custom Gizmo Placement** — Drag, rotate, and position bottle props and purge nozzles with freecam
* **Custom HUD** — Drag/scale/rotate HUD elements via `/nitrohud` editor
* **Flame & Purge Colors** — Per-vehicle RGB customization through tint items
* **Compressor System** — Mechanic and public refill stations (world props with ox\_target)
* **Job-Based Permissions** — Per-job and per-action access control (install, remove, tint, refuel, etc.)
* **Drain Discounts** — More bottles installed = less NOS drain per second
* **Blacklisted Vehicles** — Block specific vehicle models from installing nitrous
* **Triple Framework Support** — Qbox, QBCore, and ESX via bridge system
* **Custom Notification Support** — Override the notification system with your own
* **State Exports** — Query NOS state from external resources (custom HUDs, etc.)
* **Automatic Database Setup** — All SQL tables created on first start (no manual SQL required)
* **Multi-Language** — English, Português, Français, Türkçe

### RDH\_Nitro Keybinds

```lua
All keybinds are rebindable in FiveM's Settings → Key Bindings → FiveM menu.

| Action         | Default Key  | Description |

| Activate Nitro | `Left Shift` | Hold to boost (in boost mode) or purge (in purge mode) |
| Toggle Mode    | `Left Shift`   | Switch between boost and purge mode |
| Pressure Up    | `Arrow Up`   | Increase pressure level (+1) |
| Pressure Down  | `Arrow Down` | Decrease pressure level (-1) |

    { key: "Left Shift",       label: "Hold to boost (in boost mode) or purge (in purge mode)" },
    { key: "Left Shift",       label: "Switch between boost and purge mode" },
    { key: "Arrow Up",         label: "Increase pressure level (+1)" },
    { key: "Arrow Down",       label: "Decrease pressure level (-1) " },
```

### RDH\_Gizmo Keybinds

```lua
 Gizmo Keys
    { key: "H",         label: "Freecam" },
    { key: "G",         label: "Cursor" },
    { key: "W",         label: "Translate" },
    { key: "R",         label: "Rotate" },
    { key: "Q",         label: "Relative / World" },
    { key: "LALT",      label: "Snap Ground" },
    { key: "Enter",     label: "Confirm" },
    { key: "Backspace", label: "Cancel" },


Free Cam Keys 
    { key: "WASD",      label: "Move" },
    { key: "Mouse",     label: "Look" },
    { key: "Space",     label: "Up" },
    { key: "Ctrl",      label: "Down" },
    { key: "Q / E",     label: "Roll" },
    { key: "H",         label: "Back to Gizmo" },
    { key: "Backspace", label: "Cancel" },

```

#### Custom Notifications

```lua
-- Default (nil) uses built-in system (Custom UI or lib.notify)
Config.Notify = nil

-- Override with your own notification resource:
Config.Notify = function(description, nType, duration)
    exports['okokNotify']:Alert('RDH Nitro', description, duration or 3000, nType)
end
```

#### Boost Mode

```lua
Config.BoostMode = "drive"  -- "power" or "drive"
```

* **`power`** — Direct engine power multiplier. Can bypass speed caps from other scripts.
* **`drive`** — Additive driveForce that fades to zero at the vehicle's speed cap. Recommended for balanced gameplay and compatibility with handling/performance scripts.

### Effects

*shake = Camera Shake* *purgeScale = Scale how much steam comes out of the Purge kits* *fxScale = Scale how big the Exhaust Flame gets while using Nitrous*

#### Bottles & Purge

```lua
Config.MaxBottles = 5           -- Max bottles per vehicle (1–5)
Config.NosDrainRate = 1.0       -- NOS drain per second while boosting
Config.DefaultPressure = 2      -- Starting pressure level (1–10)
Config.MaxPurgeKits = 3         -- Max purge kits per vehicle
Config.PurgeDrainRate = 5.0     -- Purge bar drain rate per second
Config.PurgeChargeRate = 10.0   -- Purge bar charge rate per second
Config.PurgeNosDrainRate = 5.0  -- NOS drain when purging with empty purge bar
Config.MinSpeedMPH = 5          -- Minimum speed to activate nitro (0 = no limit)
Config.RequireTurbo = true      -- Require turbo mod to install NOS
```

#### Drain Discount

```lua
-- More bottles = less drain. Index = bottle count, value = discount fraction.
Config.DrainDiscount = {
    [1] = 0.10,  -- 10% less drain
    [2] = 0.20,  -- 20%
    [3] = 0.30,  -- 30%
    [4] = 0.40,  -- 40%
    [5] = 0.50,  -- 50%
}
```

#### Blacklisted Vehicles

```lua
Config.BlacklistedVehicles = {
    ['rhino']      = true,
    ['hydra']      = true,
    ['lazer']      = true,
    ['oppressor2'] = true,
}
```

#### Default Colors (RGB 0–255)

```lua
Config.FlameColor = { r = 0, g = 80, b = 255 }       -- Nitrous exhaust flames
Config.PurgeColor = { r = 255, g = 255, b = 255 }     -- Purge steam
```

### Fake Plates GUIDE

```lua

-- Enable if your server uses a fake-plate script that changes the visible
-- plate text while keeping the original ("real") plate in the database.
-- When enabled, RDH_Nitro resolves the real plate so that NOS data is
-- always saved under the REAL plate.  Applying or removing fake plates
-- will never lose NOS / purge data.
-- Supports Also MT_Fakeplates
 Config.FakePlate = false

-- Method to resolve the real plate:
--   "export" = Call a server export from the fakeplate script
--              (e.g. brazzers-fakeplates, or any script that exposes an export)
--   "sql"    = Query the vehicle DB table directly for the fakeplate column
--              (works with mt_fakeplates, brazzers-fakeplates, and most scripts)
## Config.FakePlateMethod = "sql"

-- ── Export method settings (only used when FakePlateMethod = "export") ──
-- Resource name of the fake-plate script (must expose a server export)
## Config.FakePlateResource = 'brazzers-fakeplates'
-- Name of the SERVER-SIDE export that receives a (possibly fake) plate
-- and returns the real (original) plate.  If the plate is not fake, the
-- export should return nil so we fall back to the visible plate.
## Config.FakePlateExport = 'getPlateFromFakePlate'

-- ── SQL method settings (only used when FakePlateMethod = "sql") ──
-- Table name where vehicles are stored.
--   QBX / QB-Core: "player_vehicles"
--   ESX:           "owned_vehicles"
## Config.FakePlateTable = 'player_vehicles'
-- Column that holds the REAL (original) plate
## Config.FakePlateRealColumn = 'plate'
-- Column that holds the FAKE plate (nil/NULL when no fakeplate is applied)
## Config.FakePlateColumn = 'fakeplate'
```

### Purge Overheat System

```lua
-- When the purge bar reaches 100%, the system enters "overheat" mode.
-- The player must purge (release steam) to relieve pressure.

-- Enable or disable the entire overheat system
 Config.PurgeOverheat = true
-- Grace period (seconds) after purge bar hits 100% before warnings start
 Config.OverheatGracePeriod = 1
-- Warning phase duration (seconds) — beep + flashing before engine damage starts
 Config.OverheatWarningDuration = 5
-- Engine damage per tick while overheating (applied every OverheatDamageTick seconds)
-- Stock engine health = 1000. At 250 damage per 2 seconds = disabled in ~8 seconds
 Config.OverheatDamagePerTick = 250.0
-- How often (seconds) engine damage is applied during overheat
 Config.OverheatDamageTick = 2.0
-- Duration (seconds) of the visual fire effect when engine reaches 0
 Config.OverheatFireDuration = 10
-- GTA native sound for the overheat beep (3D, audible to nearby players)
-- Change these if you want a different beep sound
 Config.OverheatBeepSound = "Beep_Red"
 Config.OverheatBeepSoundSet = "DLC_HEIST_HACKING_SNAKE_SOUNDS"
-- Minimum speed (initial) of the beep interval in ms (fastest beeping)
 Config.OverheatBeepMinInterval = 200
-- Maximum speed (initial) of the beep interval in ms (slowest beeping)
 Config.OverheatBeepMaxInterval = 1000
-- If true, when a vehicle explodes all NOS bottles and purge kits are destroyed (removed from DB, items NOT returned)
 Config.DestroyNitroOnExplosion = true
```

### Compressors

```lua
-- Mechanic compressor (placed by players with placeCompressor permission)
Config.CompressorProp = "prop_compressor_02"
Config.CompressorRefillCost = 500
Config.CompressorRefillTime = 30          -- seconds
Config.CompressorTargetDistance = 2.0     -- target interaction range

-- Public compressor (placed by admins with RDH_Nitro.admin ace)
Config.PublicCompressorProp = "prop_compressor_03"
Config.PublicCompressorRefillCost = 2000
Config.PublicCompressorRefillTime = 45
Config.PublicCompressorTargetDistance = 2.0
```

#### Permissions

Permissions are job-based with a fallback for all players:

```lua
Config.Permissions = {
    everyone = {
        installBottles     = false,
        replaceBottles     = true,
        removeBottles      = false,
        removePurgeKits    = false,
        installPurgeKits   = false,
        installNitroTint   = true,
        installPurgeTint   = true,
        usePurgeNozzlesCmd = false,
        useNitroBottleCmd  = false,
        placeCompressor    = false,
        refuelNos          = false,
        refuelNosPublic    = true,
    },
    jobs = {
        mechanic = { installBottles = true, ... },
        police   = { removeBottles = true, removePurgeKits = true, ... },
    },
}
```

**Resolution order:** Job-specific override → `everyone` fallback.

\| Permission | Description |

\| `installBottles` | Install NOS bottles into empty slots | | `replaceBottles` | Swap a bottle in an already-positioned slot | | `removeBottles` | Remove NOS bottles from a vehicle | | `removePurgeKits` | Remove purge kits from a vehicle | | `installPurgeKits` | Install purge kits | | `installNitroTint` | Change exhaust flame color | | `installPurgeTint` | Change purge steam color | | `usePurgeNozzlesCmd` | Use `/purgenozzle` command | | `useNitroBottleCmd` | Use `/nitrobottle` command | | `placeCompressor` | Place a mechanic compressor | | `refuelNos` | Refuel at a mechanic compressor | | `refuelNosPublic` | Refuel at a public compressor |

***

### Commands

\| Command | Description | Permission |

\| `/nitrohud` | Open the HUD layout editor (drag, scale, rotate elements) | Everyone | | `/nitrobottle` | Reposition NOS bottle props on the vehicle (gizmo mode) | `useNitroBottleCmd` | | `/purgenozzle` | Reposition purge nozzle props on the vehicle (gizmo mode) | `usePurgeNozzlesCmd` | | `/removebottle` | Admin command — remove NOS bottles from the current vehicle | `RDH_Nitro.admin` ace | | `/removepurgekit` | Admin command — remove purge kits from the current vehicle | `RDH_Nitro.admin` ace |

***

***

### State Exports (Client-Side)

These exports allow external scripts to query the current NOS state. Useful for custom HUDs, racing scripts, or logging.

```lua
-- Single value exports
local level    = exports.RDH_Nitro:getNitroLevel()      -- number (0.0–100.0) average NOS across all bottles
local active   = exports.RDH_Nitro:isNitroActive()      -- boolean — boost particles active
local purgeOn  = exports.RDH_Nitro:isPurgeActive()       -- boolean — purge particles active
local pressure = exports.RDH_Nitro:getPressureLevel()    -- number (1–10)
local bottles  = exports.RDH_Nitro:getBottleCount()      -- number (0–MaxBottles)
local pLevel   = exports.RDH_Nitro:getPurgeLevel()       -- number (0.0–100.0) purge bar level
local mode     = exports.RDH_Nitro:getBoostMode()        -- string "boost" or "purge"
local hasPurge = exports.RDH_Nitro:isPurgeInstalled()    -- boolean — purge kit installed

-- Full state snapshot (single call, returns a table)
local state = exports.RDH_Nitro:getNitroState()
--[[
    state = {
        nitroLevel     = 75.5,       -- average NOS (0.0–100.0)
        isActive       = true,       -- boost active
        isPurgeActive  = false,      -- purge active
        pressureLevel  = 3,          -- pressure (1–10)
        bottleCount    = 2,          -- installed bottles
        purgeLevel     = 50.0,       -- purge bar (0.0–100.0)
        boostMode      = "boost",    -- "boost" or "purge"
        purgeInstalled = true,       -- has purge kit
        purgeKitCount  = 1,          -- number of purge kits
    }
]]
```

#### Example: Custom HUD Integration

```lua
CreateThread(function()
    while true do
        local state = exports.RDH_Nitro:getNitroState()
        if state.bottleCount > 0 then
            -- Update your custom HUD with NOS data
            SendNUIMessage({
                type = 'updateNitro',
                nos = state.nitroLevel,
                pressure = state.pressureLevel,
                purge = state.purgeLevel,
                active = state.isActive,
            })
        end
        Wait(100)
    end
end)
```

***

### Database

All tables are created automatically on first server start. No manual SQL is required.

\| Table | Description |

\| `rdh_nitro_bottles` | Bottle positions, rotations, and NOS levels per vehicle slot | | `rdh_nitro_vehicles` | Per-vehicle metadata (pressure, purge kit count, flame color) | | `rdh_nitro_purge_nozzles` | Purge nozzle positions, rotations, and colors per kit/side | | `rdh_nitro_compressors` | Mechanic compressor locations (placed by players) | | `rdh_nitro_public_compressors` | Public compressor locations (placed by admins) |

***

### Locales

The language is set in `config.lua`:

```lua
Config.Locale = "en"  -- "en", "pt", "fr", "tr"
```

Locale files are in the `locales/` folder. You can add new languages by copying `en.lua` and translating the strings.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rdhub.gitbook.io/rdhub-documentation/documentation/rdh-nitro/rdhnitrodocs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.