Cache

Client-side caching system for tracking player state (ped, vehicle, seat, weapon) with automatic updates and event triggers.

---

Concepts

• The cache tracks real-time player state and updates automatically every 100ms.
• When a cached value changes, a game event is triggered for event listeners.
• Access cached values using cv.cache(key).
• The cache automatically handles ped transitions (returns 0 briefly) without updating cached values.

Notes:

• Cache values are always available, even during ped transitions.
• Vehicle seat is automatically detected when entering a vehicle.
• Weapon detection checks for valid weapon hashes (0 = no weapon).
• UpdateFrequency: 100ms (can be adjusted in cache.lua).

---

Tracked Values

Key	Type	Description
ped	number	Current PlayerPed ID
playerId	number	Local player ID
serverId	number	Server player ID
vehicle	number/false	Vehicle handle or false if not in vehicle
seat	number/false	Vehicle seat index (-1 = driver, 0+ = passenger) or false
weapon	number/false	Current weapon hash or false if no weapon

---

Usage

Getting Cached Values

-- Retrieve any cached value
local currentPed = cv.cache('ped')
local currentVehicle = cv.cache('vehicle')
local vehicleSeat = cv.cache('seat')
local currentWeapon = cv.cache('weapon')
local localPlayerId = cv.cache('playerId')
local serverPlayerId = cv.cache('serverId')

-- Check if player is in vehicle
if cv.cache('vehicle') then
    print("In vehicle at seat " .. cv.cache('seat'))
else
    print("Not in vehicle")
end

Listening to Cache Changes

Listen for changes using the event system. The event format is cv_framework:cache:<key>:

-- Listen for ped changes
RegisterNetEvent('cv_framework:cache:ped', function(newValue, oldValue)
    print('Ped changed from ' .. tostring(oldValue) .. ' to ' .. tostring(newValue))
end)

-- Listen for vehicle changes
RegisterNetEvent('cv_framework:cache:vehicle', function(newValue, oldValue)
    if newValue then
        print('Entered vehicle: ' .. newValue)
    else
        print('Left vehicle: ' .. oldValue)
    end
end)

-- Listen for weapon changes
RegisterNetEvent('cv_framework:cache:weapon', function(newValue, oldValue)
    if newValue then
        print('Weapon equipped: ' .. newValue)
    else
        print('Weapon holstered')
    end
end)

Common Patterns

-- Safe ped access
local ped = cv.cache('ped')
if ped and ped ~= 0 then
    -- Safe to use ped
    SetEntityHeading(ped, 90.0)
end

-- Check vehicle seat
if cv.cache('vehicle') ~= false then
    local seat = cv.cache('seat')
    if seat == -1 then
        print("You are the driver")
    else
        print("You are a passenger at seat " .. seat)
    end
end

-- Weapon validation
if cv.cache('weapon') then
    local weapon = cv.cache('weapon')
    -- Use weapon hash for further operations
    TriggerEvent('weapon:used', weapon)
end

Advanced Usage

-- React to entering specific vehicle
RegisterNetEvent('cv_framework:cache:vehicle', function(newValue, oldValue)
    if newValue and oldValue ~= newValue then
        local vehicleModel = GetEntityModel(newValue)
        local vehicleName = GetDisplayNameFromHashKey(vehicleModel)
        print("Entered: " .. vehicleName)
    end
end)

-- Track seat changes within a vehicle
RegisterNetEvent('cv_framework:cache:seat', function(newValue, oldValue)
    if newValue ~= oldValue then
        if newValue == -1 then
            print("You are now the driver")
        else
            print("You are now at seat " .. newValue)
        end
    end
end)

---

Implementation Details

Update Thread

The cache runs a thread that updates values every 100ms:

CreateThread(function()
    while true do
        local ped = PlayerPedId()

        if ped ~= 0 then
            -- Update ped
            cache:set('ped', ped)

            -- Check vehicle
            local vehicle = GetVehiclePedIsIn(ped, false)
            if vehicle > 0 then
                -- Auto-detect seat
                for i = -1, GetVehicleMaxNumberOfPassengers(vehicle) - 1 do
                    if GetPedInVehicleSeat(vehicle, i) == ped then
                        cache:set('seat', i)
                        break
                    end
                end
            end

            -- Check weapon
            local hasWeapon, weapon = GetCurrentPedWeapon(ped, true)
            cache:set('weapon', (hasWeapon and weapon ~= 0) and weapon or false)
        end

        Wait(100)
    end
end)

Value Change Detection

The cache:set() method only triggers events when values actually change:

function cache:set(key, value)
    if value ~= self[key] then  -- Only if different
        TriggerEvent(('cv_framework:cache:%s'):format(key), value, self[key])
        self[key] = value
        return true
    end
end

This prevents unnecessary event spam and improves performance.

---

Performance Notes

• Update frequency: 100ms (configurable)
• Zero overhead when values haven't changed
• Native GTA function calls are cached locally to reduce lookup overhead
• Suitable for real-time applications (combat, vehicle gameplay, etc.)