Framework Documentation

Welcome to the Framework Core documentation — a comprehensive guide to help you get started with our framework and tools.

This documentation covers all client and server exports, functions, and examples for the Framework Core system.

Getting Started

This documentation will guide you through all available functions and exports. Use the sidebar to navigate between different sections.

Interaction Prompts

Register core managed prompts, remember, these are client-sided.

CreatePromptGroup

Create a group of prompts that can be enabled/disabled.

Parameters

Parameter Required Type Description
prompts Yes List A list of prompts to create the prompt group for
local promptGroupId = exports.core:CreatePromptGroup({
    {
        Id = 'prompt_internal_name',
        Complete = function()
            -- function to call when user selects item
        end,
        Title = '', -- The title of the prompt
        Description = '', -- Optional description text
        Icon = '', -- The font-awesome icon I.e. 'fad fa-circle'
        AutoComplete = false, -- Optional, auto-complete the prompt selection if only 1 prompt is available
    }
})

DeletePromptGroup

Remove a prompt group and delete it.

Parameters

Parameter Required Type Description
promptGroupId Yes Int The prompt group id
exports.core:DeletePromptGroup(promptGroupId)

ShowPromptGroup

Enable interaction and visibility of a prompt group

Parameters

Parameter Required Type Description
promptGroupId Yes Int The prompt group Id to enable
promptRestrictions No List A list of prompts to enable if you don't want to enable them all
forceUpdate No Boolean If we should force an update when the prompt group is already enabled. I.e. to enable a new restricted set of prompts
exports.core:ShowPromptGroup(promptGroupId, { 'prompt_internal_name' })

HidePromptGroup

Hides all prompts from a group

exports.core:HidePromptGroup(promptGroupId)

CreatePrompt

Create a new prompt within an existing prompt group.

exports.core:CreatePrompt({
    Id = 'new_prompt',
    Complete = function()
        -- function to call when user selects item
    end,
    Title = 'New Prompt',
    Description = 'This is a new prompt',
    Icon = 'fad fa-star',
    AutoComplete = false
}, promptGroupId)

UpdatePromptTitle

Update the title of an existing prompt.

exports.core:UpdatePromptTitle(promptGroupId, 'prompt_id', 'New Title')

UpdatePromptDescription

Update the description of an existing prompt.

exports.core:UpdatePromptDescription(promptGroupId, 'prompt_id', 'New Description')

UpdatePromptIcon

Update the icon of an existing prompt.

exports.core:UpdatePromptIcon(promptGroupId, 'prompt_id', 'fad fa-heart')

IsPromptGroupVisible

Check if a prompt group is currently visible.

local isVisible = exports.core:IsPromptGroupVisible(promptGroupId)

IsPromptVisible

Check if a specific prompt is currently visible.

local isVisible = exports.core:IsPromptVisible(promptGroupId, 'prompt_id')

Polyzone Functions

AddBoxZone

Create a rectangular zone for interactions.

local zone = exports.core:AddBoxZone('test_zone', vector3(-223.7, -1536.3, 31.6), 5.0, 5.0, {
    useZ = true,
    data = {
        job = 'police'
    }
})

AddCircleZone

Create a circular zone for interactions.

local zone = exports.core:AddCircleZone('test_zone', vector3(-223.7, -1536.3, 31.6), 5.0, {
    useZ = true,
    data = {
        job = 'police'
    }
})

AddPolyZoneEnterHandler

Add a callback function that triggers when a player enters a zone.

exports.core:AddPolyZoneEnterHandler('test_zone', function(data)
    if exports.core:HasJob('police') then
        exports.core:ShowPromptGroup(TestPrompt)
    end
end)

AddPolyZoneExitHandler

Add a callback function that triggers when a player exits a zone.

exports.core:AddPolyZoneExitHandler('test_zone', function()
    exports.core:HidePromptGroup(TestPrompt)
end)

Player Functions

HasJob

Check if the player has a specific job.

local hasJob = exports.core:HasJob('police')

HasGroup

Check if the player has any of the specified groups (jobs, gangs, etc.).

local hasGroup = exports.core:HasGroup('police')
local hasGroupWithGrade = exports.core:HasGroup({police = 2})

HasPrimaryGroup

Check if the player has the specified group as their primary job/gang.

local hasPrimaryGroup = exports.core:HasPrimaryGroup('police')

GetPlayerData

Get the current player's data.

local playerData = exports.core:GetPlayerData()

UI Functions

ShowPrompt

Display a simple interaction prompt.

exports.core:ShowPrompt('interact', 'Press E to interact', 'fad fa-square-exclamation', 1)

HidePrompt

Hide a specific prompt.

exports.core:HidePrompt('interact')

HideAllPrompts

Hide all currently visible prompts.

exports.core:HideAllPrompts()

UpdatePromptTitle

Update the title of a visible prompt.

exports.core:UpdatePromptTitle('interact', 'New Title')

Progress Bar System

The progress bar system provides functionality for creating interactive progress bars with customizable options.

StartProgressBar

Start a progress bar with customizable options.

Parameters

Parameter Required Type Description
cb Yes Function Callback function when progress completes. Receives boolean parameter (true = completed, false = cancelled)
length No Number Duration in milliseconds. If undefined, progress bar won't auto-tick and must be controlled with SetProgressBar()
title Yes String Title text for the progress bar
description No String Description text (optional)
config No Table Configuration options (optional)

Configuration Options

Option Type Default Description
canCancel Boolean true Allow player to cancel progress with X key
disableMovement Boolean true Disable player movement during progress
disableCarMovement Boolean true Disable vehicle movement during progress
disableMouse Boolean false Disable mouse input during progress
disableCombat Boolean true Disable combat actions during progress
ragdollCancel Boolean false Cancel progress if player ragdolls

Basic Usage Examples

-- Basic progress bar with duration (auto-ticking)
exports.core:StartProgressBar(function(complete)
    if complete then
        exports.core:ShowNotification('Task completed successfully!', 'success')
    else
        exports.core:ShowNotification('Task was cancelled!', 'error')
    end
end, 5000, 'Processing...', 'Please wait while we process your request')

-- Manual progress bar (no duration - controlled with SetProgressBar)
exports.core:StartProgressBar(function(complete)
    if complete then
        exports.core:ShowNotification('Manual task completed!', 'success')
    else
        exports.core:ShowNotification('Manual task was cancelled!', 'error')
    end
end, nil, 'Manual Progress', 'Use SetProgressBar to control progress')

SetProgressBar

Update the current progress bar value. Only works when progress bar was started without duration.

exports.core:SetProgressBar(25) -- 25% complete

UpdateProgressBar

Update the title and description of the active progress bar.

exports.core:UpdateProgressBar('New Title', 'Updated description text')

CancelProgressBar

Cancel the current progress bar. Will trigger the callback with false parameter.

exports.core:CancelProgressBar()

Notification System

PersistentNotify

Create a persistent notification that stays visible until manually stopped. This is the recommended way to create notifications that need to persist.

-- Client-side persistent notification
exports.core:PersistentNotify({
    message = 'This is a persistent notification!',
    id = 'my_notification',
    notifType = 'warning',
    icon = 'fad fa-exclamation-triangle',
    style = {
        backgroundColor = '#ff6b35',
        border = '2px solid #ff0000'
    }
})

StopNotify

Remove a persistent notification by its ID.

exports.core:StopNotify('my_notification')

Notify (Legacy)

Display a regular notification to the player. This is for temporary notifications that auto-hide.

-- Regular notification (positional parameters)
exports.core:Notify('Hello World!', 'info', 5000)

-- Table-based syntax (recommended)
exports.core:Notify({
    message = 'Test notification',
    notifType = 'info',
    length = 3000,
    icon = 'fad fa-bell'
})

HUD Functions

ShowHUD

Display the player HUD.

exports.core:ShowHUD()

HideHUD

Hide the player HUD.

exports.core:HideHUD()

UpdateStatusData

Update player status data (health, armor, hunger, thirst, etc.).

exports.core:UpdateStatusData({
    health = 100,
    armor = 50,
    food = 80,
    water = 70,
    stress = 20,
    citizenId = 'ABC123'
})

UpdateHunger

Update player hunger level directly (for food systems).

exports.core:UpdateHunger(75)

UpdateThirst

Update player thirst level directly (for drink systems).

exports.core:UpdateThirst(60)

UpdateStress

Update player stress level directly.

exports.core:UpdateStress(25)

ShowVehicleHUD

Display the vehicle HUD.

exports.core:ShowVehicleHUD()

HideVehicleHUD

Hide the vehicle HUD.

exports.core:HideVehicleHUD()

UpdateVehicleHUD

Update vehicle HUD data.

exports.core:UpdateVehicleHUD({
    speed = 60,
    fuel = 75,
    speedPercent = 30,
    gear = '3',
    seatbelt = true
})

Reputation API

Server-side storage uses a dedicated `rep` table with a JSON map of reputation types per `citizenid`.

Server Exports

-- Absolute set (negative subtracts from current; positive sets absolute with clamp)
exports['core']:SetReputation(citizenid, 'weed', 25)

-- Delta operations
exports['core']:AddReputation(citizenid, 'weed', 5)
exports['core']:RemoveReputation(citizenid, 'weed', 3)

-- Read
local rep = exports['core']:GetReputation(citizenid, 'weed')

Server Helpers

KCore.Functions.SetReputation(citizenid, 'weed', 25)
KCore.Functions.AddReputation(citizenid, 'weed', 5)
KCore.Functions.RemoveReputation(citizenid, 'weed', 3)
local current = KCore.Functions.GetReputation(citizenid, 'weed')

Client Helpers

-- Triggers server-side handlers for the invoking player
KCore.Functions.SetReputation('weed', 25)
KCore.Functions.AddReputation('weed', 5)
KCore.Functions.RemoveReputation('weed', 3)

UI Configuration

exports['core']:SetReputationUI({
  position = 'middle-right',      -- 'middle-right' | 'middle-left' | 'top-right' | 'top-left'
  displayTime = 10,               -- seconds visible before removal
  changeDisplayTime = 3,          -- seconds showing delta before switching to total
  transitionTime = 0.3            -- seconds for fade transitions
})

Clipboard Component

A simple clipboard popup component that allows users to copy text to their clipboard. Perfect for sharing coordinates, Discord invites, or any other text data.

Core.Functions.Clipboard

Display a clipboard popup with copyable text.

-- Basic usage
KCore.Functions.Clipboard('https://discord.gg/kcore', 'Kcore Discord')

-- Or using exports
exports['core']:Clipboard('https://discord.gg/kcore', 'Kcore Discord')

-- Or using the full export name
exports['core']:ShowClipboard('https://discord.gg/kcore', 'Kcore Discord')

Custom UI Stats

Create custom HUD elements that appear alongside the core stats. Positions supported: `primary`, `secondary`.

CreateUIStat

Create a new UI stat element.

exports.core:CreateUIStat('testStat', 'primary', {
    icon = 'fad fa-circle',
    iconColor = nil,
    color = '#6c757d',
    alwaysShow = false,
    useAlerts = false,
    showPreferences = {
        isMinimum = true,
        value = 0
    }
})

UpdateUiStat

Update the runtime state of an existing UI stat.

exports.core:UpdateUiStat('testStat', {
    icon = 'fad fa-bolt',
    count = 3,
    percentage = 72,
    active = true,
    visible = true,
    iconColour = '#ffcc00'
})

Timers

Create small circular timer chips that count down and optionally invoke a callback when finished.

StartTimer

exports.core:StartTimer('test', 10000, 'Test Tooltip', 'fad fa-timer', function()
    -- timer completed
end)

StopTimer

exports.core:StopTimer('test')

Entity Functions

DeleteEntity

Delete a networked entity safely.

exports.core:DeleteEntity(vehicle)

SpawnLocalObject

Spawn a local object at specified coordinates.

local obj = exports.core:SpawnLocalObject('prop_chair_01', vector3(0, 0, 0), function(object)
    print('Object spawned:', object)
end)

TeleportToCoords

Teleport player to specified coordinates.

exports.core:TeleportToCoords(vector3(0, 0, 0), true, 1000, 200, 200, true)

Animation Functions

LoadAnimDict

Load an animation dictionary.

exports.core:LoadAnimDict('anim@heists@prison_heiststation@cop_reactions')

RemoveAnimDict

Remove an animation dictionary from memory.

exports.core:RemoveAnimDict('anim@heists@prison_heiststation@cop_reactions')

LoadModel

Load a model hash.

exports.core:LoadModel('prop_chair_01')

Particle Effects

LoadParticleFx

Load a particle effect asset.

exports.core:LoadParticleFx('scr_trevor3')

StartParticleFxInArea

Start a particle effect in an area visible to nearby players.

exports.core:StartParticleFxInArea(10.0, vector3(0, 0, 0), 'scr_trevor3', 1, {})

Server Exports - Notification System

Send notifications to a specific player from the server. Supports both regular and persistent notifications with two syntax options.

Notify

-- Regular server notification (positional parameters)
exports.core:Notify(source, 'Server notification!', 'info', 3000)

-- Table-based server notification
exports.core:Notify(source, {
    message = 'Server notification!',
    notifType = 'info',
    length = 3000,
    icon = 'fad fa-server'
})

-- Persistent server notification (table-based)
exports.core:Notify(source, {
    message = 'This will persist until stopped',
    id = 'server_persistent',
    persist = true,
    notifType = 'warning',
    icon = 'fad fa-exclamation-triangle',
    style = {
        backgroundColor = '#ff4444',
        border = '3px solid #ff0000'
    }
})

StopNotify

Remove a persistent notification from a specific player by its ID.

exports.core:StopNotify(source, 'server_persistent')

Full Example

This is a full example of the features available with the Framework Core system:

Citizen.CreateThread(function()
    -- Create a zone
    exports.core:AddCircleZone('test_zone', vector3(-223.7, -1536.3, 31.6), 5.0, {
        useZ = true,
        data = {
            job = 'police'
        }
    })

    -- Create a prompt group
    TestPrompt = exports.core:CreatePromptGroup({
        {
            Id = 'test_prompt',
            Complete = function()
                -- Do work
                exports.core:HidePromptGroup(TestPrompt)
                exports.core:ShowNotification('Test Prompt')
            end,
            Title = 'Test Prompt',
            Description = 'This is a test prompt, see what it can do',
            AutoComplete = true,
            Icon = 'fa-solid fa-circle-question'
        },
        {
            Id = 'test_job_prompt',
            Complete = function()
                exports.core:ShowNotification('Test Job Prompt')
            end,
            Title = 'Hidden Job Prompt',
            Description = 'This is a private prompt, ooh scary :D',
            AutoComplete = false,
            Icon = 'fa-solid fa-circle-question'
        }
    })

    -- Add zone enter handler
    exports.core:AddPolyZoneEnterHandler('test_zone', function(data)
        if exports.core:HasJob('police') then
            -- Show all as player has the job
            exports.core:ShowPromptGroup(TestPrompt)
        else
            -- Only show the main prompt
            exports.core:ShowPromptGroup(TestPrompt, { 'test_prompt' })
        end
    end)

    -- Add zone exit handler
    exports.core:AddPolyZoneExitHandler('test_zone', function()
        if exports.core:IsPromptGroupVisible(TestPrompt) then
            exports.core:HidePromptGroup(TestPrompt)
        end
    end)
end)

Metadata Integration

Food and Drink Systems

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 = KCore.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)

Events

Client Events

  • core:showPrompt - Triggered when a prompt should be shown
  • core:hidePrompt - Triggered when a prompt should be hidden
  • core:updatePromptTitle - Triggered when a prompt title should be updated
  • core:hideAllPrompts - Triggered when all prompts should be hidden
  • core:client:showHUD - Triggered when the HUD should be shown
  • core:client:hideHUD - Triggered when the HUD should be hidden
  • core:client:notify - Triggered when a notification should be displayed

Commands

  • +core_menu_interact - Default key: E - Opens the interaction menu when prompts are available
  • -cancelProgressBar - Default key: END - Cancels the current progress bar
  • id - Toggles the display of the player's citizen ID

Exports

All functions listed above are available as exports for use by other resources:

getCore / GetCoreObject

Get the KCore object to access functions, players, shared data, and more. This is the primary way to interact with the core from other resources.

-- Client-side usage
local KCore = exports.core:getCore()

-- Access player data
local playerData = KCore.PlayerData
local isLoggedIn = KCore.IsLoggedIn

-- Access shared data (jobs, gangs, vehicles, etc.)
local jobs = KCore.Shared.Jobs
local vehicles = KCore.Shared.Vehicles

-- Use functions from KCore.Functions
KCore.Functions.Notify('Hello', 'info')
KCore.Log.Error('Something went wrong!')