Back to Script

Catalytic Converter Theft System | QBCore • Qbox • OX Documentation

Installation guide, configuration details, and best practices.

About wd-catalytic

wd-catalytic is a highly configurable, universal Catalytic Converter Theft System for FiveM servers, brought to you by Whale Devs. It provides a comprehensive and immersive system for players to steal catalytic converters from vehicles and sell them for rewards.

Key Features

  • Multi-Framework Support: Fully compatible with qb-core, qbox, and ox_core.
  • Targeting System Compatibility: Works out-of-the-box with qb-target and ox_target.
  • Immersive Theft Process:
    • Requires a specific tool (e.g., blowtorch) with configurable durability.
    • Interactive minigame (NumberSlide) for cutting out the converter.
    • Realistic animations and prop handling (converter prop appears in hand).
  • NPC Reactions: Nearby pedestrians can realistically react to the theft—either fleeing in fear or fighting back to defend the area.
  • Police Dispatch Alerts: Integration with dispatch systems (like ps-dispatch, qs-dispatch, or custom) to alert law enforcement of suspicious activity.
  • Vehicle Protection: Built-in limits, cooldowns, and blacklist options to prevent abuse and protect specific vehicle classes (e.g., emergency vehicles, motorcycles).
  • Reward System: Configurable payout options including cash, black money, marked bills, or specific items, facilitated through an interactive Exchange Ped NPC.

Enhance your server's criminal RP with this detailed and engaging catalytic converter theft script!

Installation Guide

Follow these steps to install and configure wd-catalytic on your server.

1. Add Resource

Extract the wd-catalytic folder into your server's resources directory.

2. Add Items

You need to add the required items to your framework's item configuration.

For QB-Core / Qbox

Add the following to qb-core/shared/items.lua (or your equivalent items list):

['blowtorch'] = {
    name = 'blowtorch',
    label = 'Blowtorch',
    weight = 1000,
    type = 'item',
    image = 'blowtorch.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'A tool used for cutting metal.'
},

['catalytic_converter'] = {
    name = 'catalytic_converter',
    label = 'Catalytic Converter',
    weight = 2000,
    type = 'item',
    image = 'catalytic_converter.png',
    unique = false,
    useable = false,
    shouldClose = true,
    combinable = nil,
    description = 'A catalytic converter from a vehicle, used to reduce emissions.'
}

3. Add Item Images

Place the corresponding item images (blowtorch.png and catalytic_converter.png) into your inventory's images folder (e.g., qb-inventory/html/images or ox_inventory/web/images).

4. Dependencies

Ensure the following dependencies are started in your server.cfg before wd-catalytic:

  • oxmysql
  • Your chosen framework (qb-core, qbox, or ox_core)
  • Your chosen target system (qb-target or ox_target)
  • Your dispatch system (optional, e.g., ps-dispatch)
  • bl_ui (optional, for standalone use)

5. Dispatch Integration (ps-dispatch Example)

If you are using ps-dispatch, you need to add the alert configuration.

Step 1: In ps-dispatch/shared/config.lua, add this to Config.Blips:

['vehicletampering'] = {
    radius = 0,
    sprite = 595,
    color = 60,
    scale = 1.5,
    length = 2,
    sound = 'Lose_1st',
    sound2 = 'GTAO_FM_Events_Soundset',
    offset = false,
    flash = false
},

Step 2: In ps-dispatch/client/alerts.lua, add this to the bottom:

local function vehicletampering(vehicle)
    local coords = GetEntityCoords(cache.ped)
    local vehicle = GetVehicleData(vehicle)

    local dispatchData = {
        message = locale('vehicletampering'),
        codeName = 'vehicletampering',
        code = '10-35',
        icon = 'fas fa-car',
        priority = 2,
        coords = coords,
        street = GetStreetAndZone(coords),
        heading = GetPlayerHeading(),
        vehicle = vehicle.name,
        plate = vehicle.plate,
        color = vehicle.color,
        class = vehicle.class,
        doors = vehicle.doors,
        alertTime = nil,
        jobs = { 'leo' }
    }

    TriggerServerEvent('ps-dispatch:server:notify', dispatchData)
end
exports('vehicletampering', vehicletampering)

Step 3: In ps-dispatch/client/eventhandlers.lua, add this:

AddEventHandler('CEventPedJackingMyVehicle', function(_, ped)
    WaitTimer('Autotheft', function()
        if cache.ped ~= ped then return end
        local vehicle = GetVehiclePedIsUsing(ped, true)
        exports['ps-dispatch']:vehicletampering(vehicle)
    end)
end)

6. Server Configuration

Finally, ensure the script is started in your server.cfg:

ensure wd-catalytic

Make sure to adjust shared/config.lua to match your server's needs!

Configuration Options

The shared/config.lua file allows you to heavily customize the behavior of the wd-catalytic system. Below is a detailed explanation of all available configurations.

Core Settings

  • Config.Framework: The core framework used by your server. Options: "qb", "qbox", "ox".
  • Config.Target: The targeting system to use. Options: "qb", "ox".
  • Config.Debug: Set to true to enable debug print statements in the F8 console.

Items & Tools

  • Config.RequiredItem: The item needed to start cutting (default: "blowtorch").
  • Config.CatalyticItem: The item given to the player upon successful theft (default: "catalytic_converter").
  • Config.BlowtorchDurability: Maximum number of uses before the blowtorch wears out or breaks.

Messages

  • Config.Messages: Table containing translation strings for user notifications, such as when they lack a blowtorch or when it breaks.

Rewards

The Config.Rewards table defines what players receive when exchanging the catalytic converter at the NPC. You can enable or disable multiple reward types simultaneously.

  • cash: Standard cash reward (min / max).
  • black_money: Dirty/black money reward (min / max).
  • itema: Specific item reward (configure item, min, max).
  • markedbills: Worth of marked bills for QB-Core / Qbox (min / max).

Timings & Cooldowns

  • Config.CheckDuration: Time (in ms) it takes to check under the vehicle.
  • Config.CutDuration: Time (in ms) it takes to actually cut out the catalytic converter.
  • Config.MaxPlayerCuts: How many successful cuts a player can do before hitting a cooldown.
  • Config.PlayerCooldownMinutes: The duration of the cooldown (in minutes) after reaching MaxPlayerCuts.

NPC Reactions (Config.NpcReaction)

Configures how nearby pedestrians react when they see a theft in progress.

  • Enabled: Toggle the feature on or off.
  • Radius: Distance within which NPCs will react.
  • MaxPeds: Maximum number of peds that will react (prevents lag in busy areas).
  • FearChance: The percentage chance an NPC will flee. The remainder will fight back.
  • Cooldown: Prevents the same NPC from continuously reacting.
  • Flee settings: FleeDistance, FleeTime.
  • Combat settings: FightDuration, GangWeapons, GangWeaponAmmo.
  • Ped Types: GangPedTypes defines which ped types are likely to fight (e.g., Gang members, Criminals).
  • Ignore List: IgnorePedTypes defines who ignores the theft (e.g., Animals, Police, Medics).

Exchange Ped

  • Config.ExchangePed: Configuration for the NPC where players sell the stolen converters. Includes model, coords (location), and interactDist.
  • Config.ExchangeAnimation: The animation played during the exchange (dict, anim, duration).

Dispatch Alerts (Config.Dispatch)

Configures law enforcement notifications.

  • Enabled: Turn alerts on or off.
  • Type: Select the dispatch system ("ps-dispatch", "qs-dispatch", or "custom").
  • Message, CodeName, Code, Icon, Priority, Jobs: Standard alert parameters.
  • Custom: If Type is "custom", configure your custom event name and data structure here.

Minigame (Config.Minigame)

  • Enabled: Toggle the hacking/cutting minigame.
  • MinValue / MaxValue: Range of numbers used in the NumberSlide game.
  • Difficulty: Difficulty parameter determining the speed/step size.

Visuals & Props (Config.CatalyticProp)

Adjusts the visual appearance of the catalytic converter prop in the player's hands when carried in the inventory. Contains settings for model, bone, offset, rotation, and scale.

Vehicle Restrictions

  • Config.BlacklistedVehicles: Array of specific vehicle spawn names that cannot be targeted (e.g., police cars, fire trucks).
  • Config.BlacklistedCategories: Array of vehicle categories (like motorcycles, boats, helicopters) that do not have catalytic converters. Config.CategoryMap maps string names to internal GTA V category IDs.
Claim your coupons here!