Skip to content

Framework adapter

Kivo Electrician Job talks to your framework, target, inventory and notification system through two editable files:

File Purpose
shared/framework.lua The framework adapter. Detects the framework, target and inventory and wraps their functions.
client/framework/notify.lua The notification function used for player messages.

Together with config.lua, these are the integration points. This page does not document events or exports for other resources. To connect the job to another script, change these files.

After you edit any of them, restart the resource:

restart ares_electrician

The file creates one table called Framework. It loads on the client and on the server. Server-only functions take a player source. Client-only functions take no source.

The adapter decides which systems to use when the resource starts. Start your framework, target and inventory before ares_electrician.

Setting Value What the adapter does
Config.Framework 'auto' Uses ESX if es_extended is started. Otherwise uses 'qb-core' if qb-core or qbx-core is started. Otherwise prints an error.
Config.Framework 'esx' or 'qb-core' Uses exactly that framework.
Config.Target 'auto' Uses ox_target if started, otherwise qb-target, otherwise no target (target options are skipped).
Config.Target 'ox_target' or 'qb-target' Uses exactly that target.
Config.Inventory 'auto' Uses ox_inventory if started, otherwise qb-inventory, otherwise none.
Config.Inventory 'ox_inventory' or 'qb-inventory' Uses exactly that inventory.

On QBCore and QBox, if no known inventory is detected, the adapter uses the framework’s own item functions. On ESX, an unknown inventory means items are not given or removed.

Function Side Returns What it does
Framework.GetPlayerFromId(source) Server Player object or nil ESX player or QBCore player for that source.
Framework.GetPlayerData() Client Table The local player’s data.
Framework.IsPlayerLoaded() Client Boolean true when the local player is loaded.
Framework.GetIdentifier(source) Server String or nil ESX identifier, or QBCore citizen id.
Framework.GetCharName(source) Server String Character name, or "Unknown".
Framework.AddMoney(source, amount, moneyType) Server Boolean Adds money. moneyType defaults to 'cash' on QBCore. ESX ignores it and adds cash.
Framework.RemoveMoney(source, amount, moneyType) Server Boolean Removes money. Same moneyType rules.
Framework.GetMoney(source, moneyType) Server Number Money of that type. 0 if the player is not found.
Framework.GetJob(source) Server Table or nil The player’s job table.
Framework.SetJob(source, jobName, grade) Server Boolean Sets the job. grade defaults to 0.
Framework.RegisterPlayerLoadedEvent(callback) Client none Calls callback when the framework’s player-loaded event fires.
Framework.RegisterJobUpdateEvent(callback) Client none Calls callback when the framework’s job-update event fires.
Framework.GetFrameworkName() Both 'esx', 'qb-core' or nil The framework in use.
Framework.GetFrameworkObject() Both Object The framework’s shared object.
Framework.IsESX() Both Boolean true when ESX is in use.
Framework.IsQBCore() Both Boolean true when QBCore or QBox is in use.

All target options use the same shape, a list of entries like this:

Field Meaning
name Unique option name.
icon Font Awesome icon class.
label Text shown to the player.
canInteract Optional function that returns true when the option may show.
onSelect Function that runs when the player picks the option.
Function Side Returns What it does
Framework.Target.AddBoxZone(options) Client Zone id or nil Creates a box zone. options has name, coords, size (vec3), rotation, debug and options (the list above). Used for the job center.
Framework.Target.AddEntity(entity, options) Client Handle or nil Adds target options to an entity. options is the list above. Used for the work van.
Framework.Target.RemoveZone(name) Client Boolean Removes a zone created by AddBoxZone.

With qb-target, the adapter converts the zone and the options automatically and uses a distance of 2.0.

Function Side Returns What it does
Framework.Inventory.AddItem(source, item, count) Server Result or boolean Adds an item. The name goes through Config.InventoryAliases first.
Framework.Inventory.RemoveItem(source, item, count) Server Result or boolean Removes an item. Alias rules apply.
Framework.Inventory.HasItem(source, item, count) Server Boolean true when the player has at least count (default 1). Alias rules apply.
Framework.Inventory.HasItemClient(item, count) Client Boolean With ox_inventory the client checks locally. With any other inventory the client asks the server, which uses HasItem.

Use this when your framework is not ESX, QBCore or QBox. The example uses a made-up framework called myfw. Replace the export and function names with the real ones from your framework.

  1. Choose a name and set it in config.lua:

    Config.Framework = 'myfw'
  2. In InitializeFramework(), load your framework object:

    elseif CurrentFramework == 'myfw' then
    FrameworkObject = exports['myfw']:GetCore()
  3. Optional: make 'auto' find it. In DetectFramework() add a check before the error message:

    elseif GetResourceState('myfw') == 'started' then
    return 'myfw'
  4. Add a branch for 'myfw' in every framework function. The pattern is the same everywhere:

    function Framework.GetPlayerFromId(source)
    if CurrentFramework == 'esx' then
    return FrameworkObject.GetPlayerFromId(source)
    elseif CurrentFramework == 'qb-core' then
    return FrameworkObject.Functions.GetPlayer(source)
    elseif CurrentFramework == 'myfw' then
    return FrameworkObject:GetPlayer(source)
    end
    return nil
    end
  5. Do the same for GetPlayerData, IsPlayerLoaded, GetIdentifier, GetCharName, the money functions, GetJob, SetJob, RegisterPlayerLoadedEvent and RegisterJobUpdateEvent.

  6. Restart the resource and read the console for errors.

The example uses a made-up inventory called my_inventory.

  1. Set it in config.lua:

    Config.Inventory = 'my_inventory'
  2. Optional: make 'auto' find it. In DetectInventory() add:

    elseif GetResourceState('my_inventory') == 'started' then
    return 'my_inventory'
  3. In AddItem, RemoveItem and HasItem, add a branch for your inventory before the qb-inventory branch:

    function Framework.Inventory.AddItem(source, item, count)
    if not CurrentInventory then CurrentInventory = DetectInventory() end
    item = ResolveItemName(item)
    if CurrentInventory == 'ox_inventory' then
    return exports.ox_inventory:AddItem(source, item, count)
    elseif CurrentInventory == 'my_inventory' then
    return exports['my_inventory']:GiveItem(source, item, count) == true
    elseif CurrentInventory == 'qb-inventory' or Framework.IsQBCore() then
    -- existing QBCore code stays here
    end
    end
  4. HasItemClient needs no change. For any inventory other than ox_inventory it asks the server, so only the server HasItem branch is needed.

  5. Add your inventory’s item names to Config.InventoryAliases where they differ:

    water = {
    ['qb-inventory'] = 'water_bottle',
    ['ox_inventory'] = 'water',
    ['my_inventory'] = 'water_bottle'
    },

The job center and the work van use three adapter functions: AddBoxZone, AddEntity and RemoveZone. Add a branch for your target resource in each of them. The example uses a made-up target called my_target.

  1. Set it in config.lua:

    Config.Target = 'my_target'
  2. Optional: make 'auto' find it by adding a GetResourceState('my_target') check in DetectTarget().

  3. Add a branch to Framework.Target.AddBoxZone:

    elseif CurrentTarget == 'my_target' then
    local zoneName = options.name or ('electrician_zone_' .. math.random(100000, 999999))
    exports['my_target']:AddBox(zoneName, options.coords, options.size, options.rotation or 0.0, options.options)
    return zoneName

    Return a value that your target can use later to remove the zone.

  4. Add similar branches to Framework.Target.AddEntity and Framework.Target.RemoveZone. RemoveZone receives the value that AddBoxZone returned.

  5. Each option is a table with name, icon, label, canInteract and onSelect. Convert it to the format your target expects.

Notifications (client/framework/notify.lua)

Section titled “Notifications (client/framework/notify.lua)”

The file defines a global function notify(title, message, type). The script calls it for several player messages. The type is one of 'inform', 'success', 'error' or 'warning'.

Config.Notification Behavior
'ox_lib' Calls lib.notify from ox_lib.
'custom' Runs your own code. The file contains an empty placeholder for it.
  1. Set the option in config.lua:

    Config.Notification = 'custom'
  2. Fill the placeholder in notify.lua. This example sends the message to the QBCore notification:

    _G.notify = function (title, message, type)
    if Config.Notification == 'custom' then
    local types = { inform = 'primary', success = 'success', error = 'error', warning = 'primary' }
    TriggerEvent('QBCore:Notify', title .. ': ' .. message, types[type] or 'primary', 5000)
    return
    end
    if Config.Notification == 'ox_lib' then
    lib.notify({
    title = title or '',
    description = message or '',
    type = type or 'inform'
    })
    return
    end
    end
  3. For ESX, replace the TriggerEvent line with:

    TriggerEvent('esx:showNotification', title .. ': ' .. message)
  4. For a notification resource with its own export, call that export in the same place. Use the real export name and parameters of that resource:

    exports['my_notify']:Send(title, message, type)

notify.lua also contains nuiNotify(text, distance, pay, difficulty, reroll_count). It sends job offer data to the dispatch window. Leave this function in the file and do not edit it. It is not part of the notification system you replace.

Vehicle keys are not handled by the adapter. See Config.WorkVan.giveKeys on the Configuration page and the vehicle keys section of Examples and troubleshooting.