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_electricianFramework adapter (shared/framework.lua)
Section titled “Framework adapter (shared/framework.lua)”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.
Detection
Section titled “Detection”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.
Framework functions
Section titled “Framework functions”| 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. |
Target functions
Section titled “Target functions”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.
Inventory functions
Section titled “Inventory functions”| 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. |
Adapt to another framework
Section titled “Adapt to another framework”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.
-
Choose a name and set it in
config.lua:Config.Framework = 'myfw' -
In
InitializeFramework(), load your framework object:elseif CurrentFramework == 'myfw' thenFrameworkObject = exports['myfw']:GetCore() -
Optional: make
'auto'find it. InDetectFramework()add a check before the error message:elseif GetResourceState('myfw') == 'started' thenreturn 'myfw' -
Add a branch for
'myfw'in every framework function. The pattern is the same everywhere:function Framework.GetPlayerFromId(source)if CurrentFramework == 'esx' thenreturn FrameworkObject.GetPlayerFromId(source)elseif CurrentFramework == 'qb-core' thenreturn FrameworkObject.Functions.GetPlayer(source)elseif CurrentFramework == 'myfw' thenreturn FrameworkObject:GetPlayer(source)endreturn nilend -
Do the same for
GetPlayerData,IsPlayerLoaded,GetIdentifier,GetCharName, the money functions,GetJob,SetJob,RegisterPlayerLoadedEventandRegisterJobUpdateEvent. -
Restart the resource and read the console for errors.
Adapt to another inventory
Section titled “Adapt to another inventory”The example uses a made-up inventory called my_inventory.
-
Set it in
config.lua:Config.Inventory = 'my_inventory' -
Optional: make
'auto'find it. InDetectInventory()add:elseif GetResourceState('my_inventory') == 'started' thenreturn 'my_inventory' -
In
AddItem,RemoveItemandHasItem, add a branch for your inventory before theqb-inventorybranch:function Framework.Inventory.AddItem(source, item, count)if not CurrentInventory then CurrentInventory = DetectInventory() enditem = ResolveItemName(item)if CurrentInventory == 'ox_inventory' thenreturn exports.ox_inventory:AddItem(source, item, count)elseif CurrentInventory == 'my_inventory' thenreturn exports['my_inventory']:GiveItem(source, item, count) == trueelseif CurrentInventory == 'qb-inventory' or Framework.IsQBCore() then-- existing QBCore code stays hereendend -
HasItemClientneeds no change. For any inventory other thanox_inventoryit asks the server, so only the serverHasItembranch is needed. -
Add your inventory’s item names to
Config.InventoryAliaseswhere they differ:water = {['qb-inventory'] = 'water_bottle',['ox_inventory'] = 'water',['my_inventory'] = 'water_bottle'},
Adapt to another target resource
Section titled “Adapt to another target resource”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.
-
Set it in
config.lua:Config.Target = 'my_target' -
Optional: make
'auto'find it by adding aGetResourceState('my_target')check inDetectTarget(). -
Add a branch to
Framework.Target.AddBoxZone:elseif CurrentTarget == 'my_target' thenlocal 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 zoneNameReturn a value that your target can use later to remove the zone.
-
Add similar branches to
Framework.Target.AddEntityandFramework.Target.RemoveZone.RemoveZonereceives the value thatAddBoxZonereturned. -
Each option is a table with
name,icon,label,canInteractandonSelect. 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. |
Use your own notification system
Section titled “Use your own notification system”-
Set the option in
config.lua:Config.Notification = 'custom' -
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' thenlocal types = { inform = 'primary', success = 'success', error = 'error', warning = 'primary' }TriggerEvent('QBCore:Notify', title .. ': ' .. message, types[type] or 'primary', 5000)returnendif Config.Notification == 'ox_lib' thenlib.notify({title = title or '',description = message or '',type = type or 'inform'})returnendend -
For ESX, replace the
TriggerEventline with:TriggerEvent('esx:showNotification', title .. ': ' .. message) -
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)
Dispatcher prompt (nuiNotify)
Section titled “Dispatcher prompt (nuiNotify)”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 and other scripts
Section titled “Vehicle keys and other scripts”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.
