Wanted System in FiveM

Wanted system creates a cat-and-mouse dynamic between criminal and police, which is the core gameplay of the RP server.

System Overview

Criminal offense → Add wanted stars → Police dispatch → Chase → Catch/escape

Config

Config.WantedLevels = {
    [1] = {
        label = '⭐',
        dispatchMessage = 'Suspicious activity has been reported',
        policeRequired = 1,
        decayTime = 120 -- seconds before decay (If not seen)
    },
    [2] = {
        label = '⭐⭐',
        dispatchMessage = 'Suspect escaped from police',
        policeRequired = 1,
        decayTime = 180
    },
    [3] = {
        label = '⭐⭐⭐',
        dispatchMessage = 'The suspect is fully armed — needs reinforcements',
        policeRequired = 2,
        decayTime = 300
    }
}

Config.Crimes = {
    speeding = { stars = 1, label = 'drive fast' },
    running_red_light = { stars = 1, label = 'Red light' },
    assault = { stars = 2, label = 'assault' },
    robbery = { stars = 3, label = 'Robbery' },
    murder = { stars = 5, label = 'murder' }
}

Wanted State Management

-- server.lua
local wantedPlayers = {}

local function SetWanted(src, stars, reason)
    stars = math.max(0, math.min(5, stars))
    
    if stars == 0 then
        wantedPlayers[src] = nil
        TriggerClientEvent('wanted:clear', src)
        return
    end
    
    wantedPlayers[src] = {
        stars = stars,
        reason = reason,
        lastSeen = GetGameTimer(),
        coords = nil -- update when police see
    }
    
    TriggerClientEvent('wanted:update', src, stars, reason)
    
    -- Dispatch notify police
    local xPlayer = ESX.GetPlayerFromId(src)
    if xPlayer then
        DispatchPolice(src, stars, reason, GetPlayerCoords(src))
    end
end

local function GetPlayerCoords(src)
    local ped = GetPlayerPed(tostring(src))
    return GetEntityCoords(ped)
end

local function DispatchPolice(suspectId, stars, reason, coords)
    -- Send dispatch to all police online
    for _, playerId in ipairs(GetPlayers()) do
        local policeId = tonumber(playerId)
        local xPlayer = ESX.GetPlayerFromId(policeId)
        if xPlayer and xPlayer.getJob().name == 'police' then
            TriggerClientEvent('wanted:dispatch', policeId, {
                suspectId = suspectId,
                stars = stars,
                reason = reason,
                coords = coords,
                suspectName = GetPlayerName(tostring(suspectId))
            })
        end
    end
end

-- API for adding wanted
RegisterNetEvent('wanted:addCrime')
AddEventHandler('wanted:addCrime', function(crime)
    local src = source
    local crimeData = Config.Crimes[crime]
    if not crimeData then return end
    
    local current = wantedPlayers[src] and wantedPlayers[src].stars or 0
    SetWanted(src, current + crimeData.stars, crimeData.label)
end)

-- Police caught
RegisterNetEvent('wanted:arrest')
AddEventHandler('wanted:arrest', function(targetId)
    local src = source
    local xPolice = ESX.GetPlayerFromId(src)
    
    if xPolice.getJob().name ~= 'police' then return end
    
    -- Check distance
    local policePed = GetPlayerPed(tostring(src))
    local targetPed = GetPlayerPed(tostring(targetId))
    local dist = GetDistanceBetweenCoords(
        GetEntityCoords(policePed),
        GetEntityCoords(targetPed),
        true
    )
    
    if dist > 5.0 then
        TriggerClientEvent('M2.Notify:Notify', src, 'error', 'Too far away', 3000)
        return
    end
-- catch
    SetWanted(targetId, 0, nil)
    TriggerClientEvent('wanted:arrested', targetId)
    TriggerClientEvent('M2.Notify:Notify', src, 'success', 'Capture successful', 5000)
end)

Client — HUD

-- client.lua
local myStars = 0
local decayTimer = nil

RegisterNetEvent('wanted:update')
AddEventHandler('wanted:update', function(stars, reason)
    myStars = stars
    -- Update HUD
    SendNUIMessage({ action = 'updateWanted', stars = stars })
    exports['M2.Notify']:Notify('error',
        'level wanted increased: ' .. string.rep('⭐', stars) .. ' (' .. reason .. ')',
        5000
    )
end)

RegisterNetEvent('wanted:clear')
AddEventHandler('wanted:clear', function()
    myStars = 0
    SendNUIMessage({ action = 'updateWanted', stars = 0 })
end)

RegisterNetEvent('wanted:dispatch')
AddEventHandler('wanted:dispatch', function(data)
    -- Show dispatch on police screen
    SendNUIMessage({
        action = 'showDispatch',
        stars = data.stars,
        reason = data.reason,
        suspect = data.suspectName,
        coords = data.coords
    })
end)

Summary

Wanted system creates good tension between police and criminal with a proper dispatch and decay system, making roleplay more realistic and exciting.