> For the complete documentation index, see [llms.txt](https://usin.gitbook.io/usin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://usin.gitbook.io/usin/free/usin-or-advanced-speed-limiter.md).

# USIN | Advanced Speed Limiter 🏎️

USIN Advanced Speed Limiter is a comprehensive vehicle speed limiting tool for server owners/developers!

## Installation

* Collect the script for free from my [Tebex](https://usin.tebex.io/category/free).
* Download it from [Keymasters](https://keymaster.fivem.net/asset-grants).
* Extract it and drag it to you resources folder.
* Add "ensure usin\_speedlimiter" to you server.cfg file.
* Configure the script to your likings in the "config.lua" file.

## Features

* Limit speed globally
  * This option limits every vehicles speed.
* Limit speed by vehicle categories
  * This option overwrites the global speedlimit for the specified category.
* Limit speed vehicle by vehicle
  * This option overwrites the global and the category limit for the specified vehicle.
* Limit speed by zone (Location)
  * This option overwrites every other one, and places a speedlimit to a designated area.
* You can set the limit in KM/H or in MPH individualy
* You can enable/disable notification when getting into a car. eg.: "This vehicle is limited to 120 MPH"
  * You can use 3 different notify system: ESX, QBCore and OX
* You can add speed limit buffs for performance upgrades
  * U can either set it to addition mode or to not addition mode by removing the "" from the number.
    * eg.: 230 - this is not an addition, "230" - this is an addition to the base value.

## Config

<details>

<summary>Showcase of the config.lua file!</summary>

```lua
Config = {}
Config.Locale = 'en' -- Defines the language file to use from the locales folder.

-- Settings
Config.CheckInterval = 500       -- 0 for every frame, 500 for optimizaiton
Config.EnableEnterVehicleNotification = true
Config.NotificationSystem = 'ox' -- 'esx', 'ox', 'qb', or 'none'
-- This title will be used by ox_lib.
-- For ESX, this can be prepended to the message, or you can include ESX color codes here.
-- For QB, this is less directly used as QB Notify typically takes a title/message separately or just message.
Config.NotificationTitle = "usin_speedlimiter" -- Only used by esx or qb notify.

--------------------------------------------------------------------------------
-- HIERARCHICAL SPEED LIMITS
-- Precedence: 1. Individual -> 2. Category -> 3. Global
--------------------------------------------------------------------------------

-- Global Speed Limit (Applies to ALL vehicles if not overridden)
-- Set to nil or comment out if you don't want a global limit.
Config.GlobalSpeedLimit = {
    base    = { value = 300, unit = 'kmh' },
    engine1 = { value = "+5",  unit = 'kmh' },
    engine2 = { value = "+10", unit = 'kmh' },
    engine3 = { value = "+15", unit = 'kmh' },
    engine4 = { value = "+20", unit = 'kmh' },
    turbo   = { value = "+20", unit = 'kmh' }
}

-- Category Speed Limits
-- Vehicle Class Numbers:
-- 0: Compacts, 1: Sedans, 2: SUVs, 3: Coupes, 4: Muscle, 5: Sports Classics,
-- 6: Sports, 7: Super, 8: Motorcycles, 9: Off-road, 10: Industrial,
-- 11: Utility, 12: Vans, 13: Cycles (Bicycles), 14: Boats, 15: Helicopters,
-- 16: Planes, 17: Service, 18: Emergency, 19: Military, 20: Commercial, 21: Trains
Config.CategorySpeedLimits = {
    [0] = { -- Compacts
        base    = { value = 160, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+20", unit = 'kmh' }
    },
    [1] = { -- Sedans
        base    = { value = 170, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+20", unit = 'kmh' }
    },
    [2] = { -- SUVs
        base    = { value = 180, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+15", unit = 'kmh' }
    },
    [3] = { -- Coupes
        base    = { value = 190, unit = 'kmh' },
        --engine1 = { value = "+7",  unit = 'kmh' },
        --engine2 = { value = "+14", unit = 'kmh' },
        --engine3 = { value = "+21", unit = 'kmh' },
        --engine4 = { value = "+28", unit = 'kmh' },
        --turbo   = { value = "+25", unit = 'kmh' }
    },
    [4] = { -- Muscle
        base    = { value = 200, unit = 'kmh' },
        --engine1 = { value = "+10", unit = 'kmh' },
        --engine2 = { value = "+20", unit = 'kmh' },
        --engine3 = { value = "+30", unit = 'kmh' },
        --engine4 = { value = "+40", unit = 'kmh' },
        --turbo   = { value = "+25", unit = 'kmh' }
    },
    [5] = { -- Sports Classics
        base    = { value = 190, unit = 'kmh' },
        --engine1 = { value = "+8",  unit = 'kmh' },
        --engine2 = { value = "+16", unit = 'kmh' },
        --engine3 = { value = "+24", unit = 'kmh' },
        --engine4 = { value = "+32", unit = 'kmh' },
        --turbo   = { value = "+20", unit = 'kmh' }
    },
    [6] = { -- Sports Cars
        base    = { value = 220, unit = 'kmh' },
        --engine1 = { value = "+10", unit = 'kmh' },
        --engine2 = { value = "+20", unit = 'kmh' },
        --engine3 = { value = "+30", unit = 'kmh' },
        --engine4 = { value = "+40", unit = 'kmh' },
        --turbo   = { value = "+30", unit = 'kmh' }
    },
    [7] = { -- Super Cars
        base    = { value = 160, unit = 'kmh' },
        engine1 = { value = "+15", unit = 'kmh' },
        engine2 = { value = "+30", unit = 'kmh' },
        engine3 = { value = "+45", unit = 'kmh' },
        engine4 = { value = "+60", unit = 'kmh' }, -- theese are always an addicion to the base value!
        turbo   = { value = "+25", unit = 'kmh' }  -- this is always an addicion to the base+engine tuning value!
    },
    [8] = { -- Motorcycles
        base    = { value = 200, unit = 'kmh' },
        --engine1 = { value = "+10", unit = 'kmh' }, --Note: Bike engine mods are different (0-2 usually)
        --engine2 = { value = "+20", unit = 'kmh' }, --Adjust if needed for bikes
        --engine3 = { value = "+30", unit = 'kmh' },
        --turbo   = { value = "+25", unit = 'kmh' }  --Not all bikes have turbo
    },
    [9] = { -- Off-road
        base    = { value = 160, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+15", unit = 'kmh' }
    },
    [10] = { -- Industrial
        base    = { value = 100, unit = 'kmh' },
        --engine1 = { value = "+3",  unit = 'kmh' },
        --engine2 = { value = "+6",  unit = 'kmh' },
        --engine3 = { value = "+9",  unit = 'kmh' },
        --engine4 = { value = "+12", unit = 'kmh' },
        --turbo   = { value = "+10", unit = 'kmh' }
    },
    [11] = { -- Utility
        base    = { value = 130, unit = 'kmh' },
        --engine1 = { value = "+4",  unit = 'kmh' },
        --engine2 = { value = "+8",  unit = 'kmh' },
        --engine3 = { value = "+12", unit = 'kmh' },
        --engine4 = { value = "+16", unit = 'kmh' },
        --turbo   = { value = "+10", unit = 'kmh' }
    },
    [12] = { -- Vans
        base    = { value = 140, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+15", unit = 'kmh' }
    },
    [13] = { -- Cycles (Bicycles) - Speed limit may not be very effective here
        base    = { value = 50, unit = 'kmh' },
    },
    [14] = { -- Boats
        base    = { value = 100, unit = 'kmh' }, -- Or use knots/mph
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
    },
    [15] = { -- Helicopters
        base    = { value = 150, unit = 'kmh' },
        --engine1 = { value = "+10", unit = 'kmh' },
        --engine2 = { value = "+20", unit = 'kmh' },
        --engine3 = { value = "+30", unit = 'kmh' },
        --engine4 = { value = "+40", unit = 'kmh' },
    },
    [16] = { -- Planes
        base    = { value = 200, unit = 'kmh' },
        --engine1 = { value = "+20", unit = 'kmh' },
        --engine2 = { value = "+40", unit = 'kmh' },
        --engine3 = { value = "+60", unit = 'kmh' },
        --engine4 = { value = "+80", unit = 'kmh' },
    },
    [17] = { -- Service (e.g., Taxi, Trashmaster)
        base    = { value = 130, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+10", unit = 'kmh' }
    },
    [18] = { -- Emergency (Police Cars, Ambulance, Firetruck)
        base    = { value = 200, unit = 'kmh' },
        --engine1 = { value = "+10", unit = 'kmh' },
        --engine2 = { value = "+20", unit = 'kmh' },
        --engine3 = { value = "+30", unit = 'kmh' },
        --engine4 = { value = "+40", unit = 'kmh' },
        --turbo   = { value = "+25", unit = 'kmh' }
    },
    [19] = { -- Military
        base    = { value = 150, unit = 'kmh' },
        --engine1 = { value = "+5",  unit = 'kmh' },
        --engine2 = { value = "+10", unit = 'kmh' },
        --engine3 = { value = "+15", unit = 'kmh' },
        --engine4 = { value = "+20", unit = 'kmh' },
        --turbo   = { value = "+10", unit = 'kmh' }
    },
    [20] = { -- Commercial (e.g., Mule, Pounder)
        base    = { value = 110, unit = 'kmh' },
        --engine1 = { value = "+4",  unit = 'kmh' },
        --engine2 = { value = "+8",  unit = 'kmh' },
        --engine3 = { value = "+12", unit = 'kmh' },
        --engine4 = { value = "+16", unit = 'kmh' },
        --turbo   = { value = "+10", unit = 'kmh' }
    },
    [21] = { -- Trains - Speed limit may not be very effective/applicable
        base    = { value = 100, unit = 'kmh' },
    },
}

-- Individual Vehicle Speed Limits (Highest Precedence)
-- Turbo always adds to engine if there is engine tuning.
Config.VehicleSpeedLimits = {
    ['adder'] = { -- Super Car, overriding category 7
        base    = { value = 290, unit = 'kmh' },
        engine1 = { value = "+5",  unit = 'kmh' },
        engine2 = { value = "+10", unit = 'kmh' },
        engine3 = { value = 305, unit = 'kmh' }, -- example for not addic
        engine4 = { value = "+20", unit = 'kmh' },
        turbo   = { value = "+25", unit = 'kmh' }
    },

    ['blista'] = { -- Compact, overriding category 0
        base    = { value = 150, unit = 'kmh' },
        engine1 = { value = "+3",  unit = 'kmh' },
        engine2 = { value = "+6",  unit = 'kmh' },
        engine3 = { value = "+9",  unit = 'kmh' },
        engine4 = { value = "+12", unit = 'kmh' },
        turbo   = { value = "+15", unit = 'kmh' }
    },

    ['panto'] = { -- Compact, another individual override
        base    = { value = 120, unit = 'mph' }, -- Example using MPH for this specific car
        turbo   = { value = "+10", unit = 'mph' }
    },

    ['torero2'] = {
        base    = { value = 200, unit = 'kmh' },
        engine1 = { value = "+5",  unit = 'kmh' },
        engine2 = { value = "+10", unit = 'kmh' },
        engine3 = { value = "+15", unit = 'kmh' },
        engine4 = { value = "+20", unit = 'kmh' },
        turbo   = { value = "+10", unit = 'kmh' }
    },
}

-- Zone-based Speed Limits
-- Location based speed limiting that overrides all other limits
Config.ZoneSpeedLimits = {
    -- Example zones:
    {
        name = "Airport", -- Name for reference
        coords = vector3(-1380.0, -3160.0, 13.0), -- Center coordinates
        radius = 200.0, -- Radius in meters (game world units)
        speedLimit = { value = 80, unit = 'kmh' }, -- Speed limit in zone
        blip = {
            enabled = true, -- Enable/disable zone visualization
            color = 3, -- Zone color: (3 = blue) https://docs.fivem.net/docs/game-references/blips/#blip-colors
            alpha = 80 -- Transparency (0-255)
        }
    },
    {
        name = "Downtown",
        coords = vector3(100.0, -1000.0, 30.0),
        radius = 100.0,
        speedLimit = { value = 60, unit = 'kmh' },
        blip = {
            enabled = true,
            color = 1,
            alpha = 80
        }
    },
    {
        name = "Highway",
        coords = vector3(2000.0, 3000.0, 40.0),
        radius = 500.0,
        speedLimit = { value = 120, unit = 'kmh' },
        blip = {
            enabled = false, -- Example of disabled zone visualization
            color = 2,
            alpha = 80
        }
    }
    -- Add more zones as needed
}

-- Conversion factors. DO NOT CHANGE!!!
Config.BlipScaleFactor = 1.0
Config.MphToMs = 0.44704
Config.KmhToMs = 1 / 3.6
```

</details>

## Pictures

<details>

<summary>Showcase of the script!</summary>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2FvG9Va2Fhryp6sLN3adFQ%2Fusl_220e.png?alt=media&amp;token=7e15403a-194d-4c7f-8ae3-4bf1d52962c0" alt=""><figcaption><p>No performance upgrade is applied! It's capped at 220 KM/H</p></figcaption></figure>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2F0IOZ28ZOOpC0KrJMfpFG%2Fusl_225e.png?alt=media&amp;token=ab80635f-ae20-40e3-8cc7-ae66a017b5c5" alt=""><figcaption><p>Engine upgrade lvl. 1 is applied! It's capped at 225 KM/H (configurable)</p></figcaption></figure>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2Fz3DCH3j2mKNtUfwFn07i%2Fusl_230e.png?alt=media&amp;token=cf24a269-c9a7-4b2e-a247-6380cca13253" alt=""><figcaption><p>Engine upgrade lvl. 2 is applied! It's capped at 230 KM/H (configurable)</p></figcaption></figure>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2FxFOmxL7zq0h94zWGTlrs%2Fusl_235e.png?alt=media&amp;token=6011fccc-1042-419b-a916-d2c59e610573" alt=""><figcaption><p>Engine upgrade lvl. 3 is applied! It's capped at 235 KM/H (configurable)</p></figcaption></figure>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2F1snLdqq28vxPe5XX79Uk%2Fusl_240e.png?alt=media&amp;token=d1651ce0-7a09-482a-a595-e13c0c1ca6f5" alt=""><figcaption><p>Engine upgrade lvl. 4 is applied! It's capped at 240 KM/H (configurable)</p></figcaption></figure>

<figure><img src="https://3313543074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv35OSwS15FeJ53pmKPmN%2Fuploads%2FUbtiBkdtzqaBv7oegKwD%2Fusl_250e.png?alt=media&amp;token=34d57e42-f861-4383-ad36-ea0dd04ceeeb" alt=""><figcaption><p>Engine upgrade lvl. 4 + Turbo is applied! It's capped at 250 KM/H (configurable)</p></figcaption></figure>

</details>

## Video

{% embed url="<https://www.youtube.com/watch?ab_channel=USINScripts&v=Ula7iLQnuk0>" %}