Examples

Practical code examples demonstrating Framework Core features and exports.

Zone & Prompt System

A complete example showing how to create zones and prompt groups for player interactions.

Citizen.CreateThread(function()
    -- Create a circular zone
    exports.core:AddCircleZone('shop_zone', vector3(-223.7, -1536.3, 31.6), 2.0, {
        useZ = true,
        data = {
            shopType = 'general'
        }
    })

    -- Create a prompt group for shop interactions
    ShopPrompt = exports.core:CreatePromptGroup({
        {
            Id = 'open_shop',
            Complete = function()
                -- Open shop menu
                TriggerEvent('shops:client:openShop', 'general')
                exports.core:HidePromptGroup(ShopPrompt)
            end,
            Title = 'Open Shop',
            Icon = 'fas fa-shopping-cart',
            AutoComplete = false
        },
        {
            Id = 'restock_shop',
            Complete = function()
                -- Restock shop (admin only)
                TriggerServerEvent('shops:server:restock', 'general')
                exports.core:HidePromptGroup(ShopPrompt)
            end,
            Title = 'Restock Shop',
            Icon = 'fas fa-box',
            AutoComplete = false
        }
    })

    -- Show prompts when entering zone
    exports.core:AddPolyZoneEnterHandler('shop_zone', function(data)
        if exports.core:HasJob('police') then
            -- Show all prompts for police
            exports.core:ShowPromptGroup(ShopPrompt)
        else
            -- Only show shop prompt for regular players
            exports.core:ShowPromptGroup(ShopPrompt, { 'open_shop' })
        end
    end)

    -- Hide prompts when leaving zone
    exports.core:AddPolyZoneExitHandler('shop_zone', function()
        if exports.core:IsPromptGroupVisible(ShopPrompt) then
            exports.core:HidePromptGroup(ShopPrompt)
        end
    end)
end)

Progress Bar with Cancel Option

Example of a progress bar with cancellation support and movement restrictions.

-- Start a progress bar with cancellation enabled
exports.core:StartProgressBar(function(complete)
    if complete then
        -- Progress completed successfully
        exports.core:Notify('Task completed!', 'success')
        -- Do your task logic here
    else
        -- Progress was cancelled
        exports.core:Notify('Task cancelled', 'error')
    end
end, 10000, 'Processing...', 'Please wait, do not move', {
    canCancel = true,
    disableMovement = true,
    disableCombat = true,
    disableCarMovement = true,
    disableMouse = false,
    disableInventory = true
})

-- Update progress bar value manually
Citizen.CreateThread(function()
    Wait(5000)
    exports.core:SetProgressBar(50) -- Set to 50%
    
    Wait(3000)
    exports.core:UpdateProgressBar('Almost done...', 'Finalizing process')
    
    Wait(2000)
    exports.core:SetProgressBar(100) -- Complete
end)

Notification System

Various notification examples for different scenarios.

-- Simple notification
exports.core:Notify('Welcome to the server!', 'info', 5000)

-- Notification with subtitle
exports.core:Notify('Item Added', 'success', 3000, 'You received: Bread')

-- Rich notification with icon
exports.core:Notify({
    text = 'Vehicle Locked',
    caption = 'Your vehicle has been secured'
}, 'success', 3000, nil, 'top-right', nil, 'fas fa-lock', '#00ff00')

-- Persistent notification
exports.core:PersistentNotify('mission_progress', 'Mission in progress...', 'info', -1)

-- Remove persistent notification later
exports.core:StopNotify('mission_progress')

Menu System

Creating and managing interactive menus.

-- Open a menu
exports.core:openMenu('vehicle_menu', {
    {
        name = 'engine',
        label = 'Toggle Engine',
        type = 'button',
        icon = 'fas fa-power-off'
    },
    {
        name = 'doors',
        label = 'Lock Doors',
        type = 'button',
        icon = 'fas fa-lock',
        disabled = false
    },
    {
        name = 'trunk',
        label = 'Open Trunk',
        type = 'button',
        icon = 'fas fa-box'
    }
}, function(data) -- Close callback
    print('Menu closed')
end, function(data) -- Selected callback
    print('Selected:', data.elementSelected)
    if data.elementSelected == 'engine' then
        TriggerEvent('vehicle:client:toggleEngine')
    elseif data.elementSelected == 'doors' then
        TriggerEvent('vehicle:client:toggleLock')
    elseif data.elementSelected == 'trunk' then
        TriggerEvent('vehicle:client:openTrunk')
    end
end, function(data) -- Change callback
    print('Menu changed:', data.elementSelected)
end)

-- Update menu element dynamically
exports.core:UpdateMenuElement({
    name = 'doors',
    label = 'Unlock Doors',
    disabled = true
})

-- Close menu
exports.core:closeMenu('vehicle_menu')

Prop Animation

Attaching props to players with animations.

-- Start drinking animation with beer bottle
local animData = exports.core:StartPropAnim({
    dict = 'amb@world_human_drinking@beer@male@idle_a',
    anim = 'idle_a',
    prop = 'prop_beer_bottle',
    placement = {0.0, 0.0, 0.0, 0.0, 0.0, 0.0},
    boneIndex = 18905, -- Right hand bone
    movement = 50,
    duration = 5000 -- 5 seconds
})

-- Stop animation after duration
Citizen.SetTimeout(5000, function()
    exports.core:StopPropAnim(animData)
end)

Entity Management

Managing entities and coordinates.

-- Get player coordinates
local playerCoords = exports.core:GetCoords()
print('Player position:', playerCoords.x, playerCoords.y, playerCoords.z)

-- Get closest object
local obj, distance = exports.core:GetClosestObject('prop_chair_01')
if obj and distance < 2.0 then
    print('Found chair at distance:', distance)
end

-- Spawn a local object
exports.core:SpawnLocalObject('prop_barrier_work05', vector3(0, 0, 0), function(object)
    print('Object spawned:', object)
    -- Do something with the object
end)

-- Teleport player
exports.core:TeleportToCoords(vector3(0, 0, 72.0), true, 1000, 500, 500, true)

Server-Side Reputation System

Managing player reputation on the server.

-- In your crafting script
RegisterNetEvent('crafting:server:craftItem', function(itemName, tier)
    local src = source
    local Player = exports.core:GetPlayer(src)
    
    if not Player then return end
    
    -- Give reputation based on tier
    local repAmount = tier == 1 and 5 or (tier == 2 and 10 or 15)
    exports.core:SetReputation(Player.PlayerData.citizenid, "crafting", repAmount)
    
    -- Give item
    Player.Functions.AddItem(itemName, 1)
    TriggerClientEvent('inventory:client:ItemBox', src, QBCore.Shared.Items[itemName], "add")
end)

-- Subtract reputation example
RegisterNetEvent('crime:server:commitCrime', function()
    local src = source
    local Player = exports.core:GetPlayer(src)
    
    if not Player then return end
    
    -- Subtract reputation (negative value)
    exports.core:SetReputation(Player.PlayerData.citizenid, "crime", -10)
end)

Player Management

Server-side player management examples.

-- Get player and check job
RegisterNetEvent('job:server:checkAccess', function()
    local src = source
    local Player = exports.core:GetPlayer(src)
    
    if not Player then return end
    
    -- Check if player has specific job
    if exports.core:HasJob(src, 'police') then
        exports.core:Notify(src, 'Access granted', 'success')
    else
        exports.core:Notify(src, 'Access denied', 'error')
    end
    
    -- Get all players with a job
    local count, players = exports.core:GetDutyCountJob('police')
    print('Police officers on duty:', count)
end)

-- Get player by identifier
local player = exports.core:GetPlayerByCitizenId('ABC12345')
if player then
    print('Player found:', player.PlayerData.name)
end

Notification System (Server)

Sending notifications from server to client.

-- Simple server notification
RegisterNetEvent('resource:server:doSomething', function()
    local src = source
    exports.core:Notify(src, 'Action completed!', 'success', 3000)
end)

-- Rich notification from server
RegisterNetEvent('resource:server:rewardPlayer', function(rewardText)
    local src = source
    exports.core:Notify(src, {
        text = 'Reward Received',
        caption = rewardText
    }, 'success', 5000, nil, 'top-right', nil, 'fas fa-gift', '#ffd700')
end)

UI Integration

Updating HUD and sending messages to React NUI.

-- Update player status data
exports.core:UpdateStatusData({
    health = GetEntityHealth(PlayerPedId()),
    armor = GetPedArmour(PlayerPedId()),
    food = 80,
    water = 70,
    stress = 20,
    citizenId = 'ABC12345'
})

-- Send custom message to React NUI
exports.core:SendReactMessage('updateCustomUI', {
    show = true,
    data = {
        score = 100,
        level = 5
    }
})

-- Show/Hide HUD
exports.core:HideHUD() -- Hide during cutscene
-- ... cutscene logic ...
exports.core:ShowHUD() -- Show after cutscene

Routing Buckets

Managing routing buckets for isolation.

-- Client-side: Check bucket
local bucket = exports.core:GetPlayerBucket(PlayerId())
print('Current bucket:', bucket)

-- Server-side: Set player bucket
RegisterNetEvent('admin:server:setPlayerBucket', function(targetId, bucketId)
    local src = source
    
    -- Check if admin
    if not exports.core:HasPermission(src, 'admin') then return end
    
    exports.core:SetPlayerBucket(targetId, bucketId)
    exports.core:Notify(src, 'Player moved to bucket ' .. bucketId, 'info')
end)

-- Get players in bucket
local players = exports.core:GetPlayersInBucket(5)
print('Players in bucket 5:', #players)

Item System

Registering and using items.

-- Server-side: Register useable item
exports.core:CreateUseableItem('bread', function(source, item)
    local Player = exports.core:GetPlayer(source)
    
    if not Player then return end
    
    -- Remove item
    Player.Functions.RemoveItem('bread', 1)
    
    -- Add hunger
    local hunger = Player.PlayerData.metadata.hunger or 100
    Player.Functions.SetMetaData('hunger', math.min(100, hunger + 10))
    
    -- Notify player
    exports.core:Notify(source, 'You ate bread', 'success')
    
    -- Trigger client event to update HUD
    TriggerClientEvent('hud:client:updateHunger', source, hunger + 10)
end)

-- Check if item is useable
local useable = exports.core:CanUseItem('bread')
if useable then
    print('Bread is useable')
end

Animation Loading

Loading animations and models properly.

-- Load animation dictionary
exports.core:LoadAnimDict('amb@world_human_drinking@beer@male@idle_a')

-- Play animation
TaskPlayAnim(PlayerPedId(), 'amb@world_human_drinking@beer@male@idle_a', 'idle_a', 8.0, -8.0, -1, 49, 0, false, false, false)

-- Clean up when done
Citizen.SetTimeout(5000, function()
    exports.core:RemoveAnimDict('amb@world_human_drinking@beer@male@idle_a')
end)

-- Load model
exports.core:LoadModel('prop_chair_01')
local obj = CreateObject(GetHashKey('prop_chair_01'), 0, 0, 0, true, true, true)

Metadata Integration

For proper integration with food and drink systems, Framework Core supports multiple methods of updating hunger and thirst:

Method 1: Direct Export Calls (Recommended)

-- In your food/drink resource
RegisterNetEvent('consumables:client:useItem', function(itemName, amount)
    local Player = QBCore.Functions.GetPlayerData()
    if Player.metadata then
        -- Update hunger directly
        exports.core:UpdateHunger(Player.metadata.hunger or 100)
        -- Update thirst directly  
        exports.core:UpdateThirst(Player.metadata.thirst or 100)
        -- Update stress directly
        exports.core:UpdateStress(Player.metadata.stress or 0)
    end
end)

Method 2: Event-Based Updates

-- Listen for hunger/thirst changes from any source
RegisterNetEvent('hud:client:updateHunger', function(value)
    exports.core:UpdateHunger(value)
end)

RegisterNetEvent('hud:client:updateThirst', function(value)
    exports.core:UpdateThirst(value)
end)

RegisterNetEvent('hud:client:updateStress', function(value)
    exports.core:UpdateStress(value)
end)

Method 3: StateBag Integration

-- Listen for hunger changes via StateBag
local serverId = GetPlayerServerId(PlayerId())
AddStateBagChangeHandler('hunger', ('player:%s'):format(serverId), function(_, _, value)
    if value then
        exports.core:UpdateHunger(value)
    end
end)

-- Listen for thirst changes via StateBag
AddStateBagChangeHandler('thirst', ('player:%s'):format(serverId), function(_, _, value)
    if value then
        exports.core:UpdateThirst(value)
    end
end)

-- Listen for stress changes via StateBag
AddStateBagChangeHandler('stress', ('player:%s'):format(serverId), function(_, _, value)
    if value then
        exports.core:UpdateStress(value)
    end
end)

Checking Rep

This is a example usage of how to check reputation levels using our

local function getRep(src, type)
    local Player = exports.core:GetPlayer(src)
    if not Player then return 0 end
    
    local repData = Player.Functions.CheckRep(type)
    if repData then
        return repData.value or 0
    end
    return 0
end

local function checkingrep(src)
    local crimeRep = getRep(src, 'crime')

    if crimeRep == 50 then
        print("has rep")
    else
        print("no")
    end
end