# 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`. | --- # 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://nteamdev.gitbook.io/nteam-development/nitrous.md?ask= ``` 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.