Skip to content

Exports and integration

Kivo Weedshop registers no exports. There are two open integration points:

  1. State bags. The script publishes the state of every plant plot and every drying rack in GlobalState. Any other script, on the client or the server, can read them.
  2. The bridge file. shared/framework.lua holds the framework, inventory, target and vehicle key adapters. It is meant to be edited when you run something the script does not support.

The server writes these values. They are rebuilt from the database when the script starts, so they are correct after a restart. Treat them as read only. The script overwrites them whenever its own data changes, so a value written by another script does not last.

Key format: kivo_plant_<plotId>, where <plotId> is the id of a plot in the farming zones. With the default config the keys are:

kivo_plant_plot1 kivo_plant_plot2 kivo_plant_plot3
kivo_plant_plot4 kivo_plant_plot5 kivo_plant_plot6

Value (a table):

Field Type Meaning
zoneId string The plot id, for example "plot1".
stage number 0 empty (no plant), 1 seed, 2 growing, 3 mature.
health number 0 to 100. A plant can be harvested when this is 100.
water number 0 to 100.
fertilizer number 0 to 20.
lastUpdate number Unix timestamp (seconds, server clock) of the last calculation.

Key format: kivo_rack_<rackId>, where <rackId> is the id of an entry in the drying rack config. With the default config:

kivo_rack_dryingRack1 kivo_rack_dryingRack2 kivo_rack_dryingRack3

Value (a table):

Field Type Meaning
rackId string The rack id, for example "dryingRack1".
status string "idle" (empty), "drying" or "ready" (dried plants can be collected).
startTime number or nil Unix timestamp when drying started. Missing while idle.
endTime number or nil Unix timestamp when drying finishes. Missing while idle.
wetPlants number 6 while a rack is in use, otherwise 0.
isComplete boolean true when drying has finished.
timeRemaining number Seconds left when the value was last written. 0 when idle or complete.

While a rack is drying, the script refreshes status and timeRemaining about once a minute. For a precise countdown on the server compute endTime - os.time() yourself. On a client, treat timeRemaining as accurate to about a minute.

The ids come from your config. Other resources cannot list the keys, so read each id you care about.

Server or client, read once:

local plot = GlobalState['kivo_plant_plot1']
if plot and plot.health >= 100 then
print('plot1 can be harvested')
end

Server, count plots that are ready to harvest:

local plotIds = { 'plot1', 'plot2', 'plot3', 'plot4', 'plot5', 'plot6' }
local function CountHarvestablePlots()
local count = 0
for _, id in ipairs(plotIds) do
local plot = GlobalState['kivo_plant_' .. id]
if plot and plot.health >= 100 then
count = count + 1
end
end
return count
end

Client, react when a rack becomes ready:

AddStateBagChangeHandler('kivo_rack_dryingRack1', 'global', function(bagName, key, value)
if value and value.status == 'ready' then
lib.notify({ description = 'Drying rack 1 is ready', type = 'inform' })
end
end)

Server, seconds left on a rack:

local function RackSecondsLeft(rackId)
local rack = GlobalState['kivo_rack_' .. rackId]
if not rack or not rack.endTime then return 0 end
return math.max(0, rack.endTime - os.time())
end

If you add or rename plots or racks in the config, use the new ids in the key.

File: shared/framework.lua. It creates three global tables for the script: Framework, Inventory and Target. They are not exports, other resources cannot call them. They are the one place that talks to your framework, inventory and target, so this is the file you edit to support something new.

After you edit the file, restart the script.

Function Side Parameters Returns
Framework.Init() both none 'esx', 'qb' or nil. Waits up to 10 seconds for es_extended or qb-core.
Framework.GetType() both none The detected type.
Framework.GetObject() both none The framework core object.
Framework.GetPlayerJob(source) server player id { name, grade, label, onDuty } or nil. grade is a number.
Framework.GetPlayerJob() client none The same table for the local player, or nil.
Framework.GetPlayerIdentifier(source) server player id ESX identifier or QB citizen id, or nil.
Framework.GetPlayerName(source) server player id Character name, or "Unknown".
Framework.AddMoney(source, account, amount) server player id, 'cash' or 'bank', positive number true when the balance went up.
Framework.RemoveMoney(source, account, amount) server player id, account, positive number true when the balance went down.
Framework.SetJob(source, job, grade) server player id, job name, grade number true when the job and grade are confirmed after the change.
Framework.Notify(source, message, type) both player id (server only), text, type such as 'info', 'success', 'error' nothing. On the server it sends the message to that player. On the client it shows an ox_lib notification.
Framework.GiveVehicleKeys(vehicle, plate) client vehicle entity, plate text (optional) nothing. Gives keys to the local player.

Inventory.Init() runs on both sides and returns 'ox', 'qb', 'esx' or nil. Inventory.GetType() returns the detected type.

Function Side Parameters Returns
Inventory.GetItemCount(source, item) server player id, item name Number of items.
Inventory.AddItem(source, item, count) server player id, item name, count Truthy on success, false on failure.
Inventory.RemoveItem(source, item, count) server player id, item name, count Truthy on success, false on failure.
Inventory.HasItem(source, item, count) server player id, item name, count (default 1) true when the player has at least count.
Inventory.CanCarryItem(source, item, count) server player id, item name, count (default 1) true when the items fit.
Inventory.HasItem(item, count) client item name, count (default 1) true when the local player has at least count. With ox_inventory the client reads it directly. With any other inventory the client asks the server.

Target.Init() returns 'ox', 'qb' or nil after waiting up to 10 seconds for ox_target or qb-target. Target.GetSystem() returns the detected system.

Function Parameters Description
Target.AddPolyZone(data) table, see below Adds a polygon zone.
Target.AddSphereZone(data) table, see below Adds a sphere zone.
Target.RemoveZone(id) zone id Removes a zone.

Fields of data:

Field Used by Description
id both Unique zone name.
points poly List of vec3 corners.
thickness poly Vertical size. Default 2.0 with ox_target.
coords sphere vec3 centre.
radius sphere Radius. Default 1.0.
debug both Draw the zone. Default false.
distance both Interaction distance. Default 2.0 with qb-target.
options both List of options. Each option has name, label, icon, distance, onSelect (or action) and canInteract. For qb-target an option can also have type, event and item.
label, icon, onSelect, canInteract both Shortcut for a single option when you do not pass options.

All examples below use placeholder resource names (my_inventory, my_keys, myfw). Replace them and the export names with the real ones from your scripts. Test on a development server first.

The script supports ox_inventory, qb-inventory and the ESX default inventory.

A QB-style inventory with a different folder name. If the inventory has the same exports as qb-inventory, replace every 'qb-inventory' string in shared/framework.lua with its resource name. The detection and the calls then use your resource.

A different inventory. Add a new type in three places.

  1. In Inventory.Init(), detect it before the other checks:
function Inventory.Init()
if isResourceStarted('my_inventory') then
inventoryType = 'my'
elseif isResourceStarted('ox_inventory') then
inventoryType = 'ox'
-- keep the existing branches below
  1. At the top of each server function, add a branch for the new type (these functions are inside the if IsDuplicityVersion() then block):
-- Inventory.GetItemCount(source, item)
if inventoryType == 'my' then
return exports.my_inventory:GetItemCount(source, item) or 0
end
-- Inventory.RemoveItem(source, item, count)
if inventoryType == 'my' then
return exports.my_inventory:RemoveItem(source, item, count) and true or false
end
-- Inventory.AddItem(source, item, count)
if inventoryType == 'my' then
return exports.my_inventory:AddItem(source, item, count) and true or false
end
-- Inventory.CanCarryItem(source, item, count)
if inventoryType == 'my' then
return exports.my_inventory:CanCarryItem(source, item, count) and true or false
end
  1. The client function Inventory.HasItem(item, count) already asks the server for every inventory except ox_inventory, so it needs no change.

Inventory.HasItem on the server is built on GetItemCount, so it works once the functions above do. Also add the five items to your new inventory (see Installation).

The script supports ESX and QB-Core (QBX through its QB-Core bridge). To support another framework, add a new type next to the existing 'esx' and 'qb' branches in these functions:

Function What to add
Framework.Init() Add your resource name to the list passed to the wait helper, then set frameworkType and frameworkObj.
Framework.GetPlayerJob() (client) and Framework.GetPlayerJob(source) (server) Return { name, grade, label, onDuty }. grade must be a number and onDuty a boolean.
Framework.GetPlayerIdentifier(source) Return a stable id for the character.
Framework.GetPlayerName(source) Return the character name.
Framework.AddMoney and Framework.RemoveMoney Credit or debit the account and return true only if it worked.
Framework.SetJob(source, job, grade) Set the job and return true only if it worked.
normalizeAccount(account) Map the account names 'cash' and 'bank' to your framework’s names (ESX maps 'cash' to 'money' here).
Inventory.Init() and the inventory functions Only if your framework brings its own inventory.

The server functions are inside the if IsDuplicityVersion() then block of the file. The client function is inside the if not IsDuplicityVersion() then block. Add your branch inside the existing function, not outside it.

A short example for a framework called myfw:

-- Framework.Init(): add your resource to the list...
local resourceName = waitForSupportedResource({ 'es_extended', 'qb-core', 'myfw' }, 10000)
-- ...and add this branch after the existing elseif branches, before the final else
elseif resourceName == 'myfw' then
frameworkType = 'myfw'
frameworkObj = exports['myfw']:GetCore()
-- Framework.GetPlayerJob(source), server
if frameworkType == 'myfw' then
local player = frameworkObj.GetPlayer(source)
if not player then return nil end
return {
name = player.job.name,
grade = player.job.grade,
label = player.job.label,
onDuty = player.job.onDuty,
}
end
-- Framework.AddMoney(source, account, amount), server
if frameworkType == 'myfw' then
local player = frameworkObj.GetPlayer(source)
return player and player.addMoney(account, amount) == true or false
end

The job from Installation must also exist in the other framework, with grades 0 to 4. Firing an employee sets the player’s job to unemployed, so the framework needs a job with that name.

Target.Init() looks for ox_target and then qb-target. Not every interaction goes through the Target functions. A replacement target system therefore has to expose the ox_target or qb-target API under that resource name, for example with a provide entry in its manifest. Many target scripts ship a compatibility mode for this. If it does, no edit is needed.

The restock mission vehicle gets keys through Framework.GiveVehicleKeys(vehicle, plate). It checks these resources in this order and uses the first one that is running:

Framework Resources checked, in order
ESX wasabi_carlock, qs-vehiclekeys, t1ger_keys, vehiclekeys
QB-Core and QBX qb-vehiclekeys, wasabi_carlock, qs-vehiclekeys

If none of them runs, no keys are given. To add your own key script, put a branch at the top of the function. Use the vehicle argument instead of plate if your script needs the entity.

function Framework.GiveVehicleKeys(vehicle, plate)
if not DoesEntityExist(vehicle) then return end
plate = plate or GetVehicleNumberPlateText(vehicle)
if GetResourceState('my_keys') == 'started' then
exports.my_keys:GiveKey(plate)
return
end
-- keep the existing branches below

Notifications use ox_lib. ox_lib is a required dependency, so the QB-Core and ESX notification fallbacks in Framework.Notify never run. The appearance of the messages comes from ox_lib.

Salary and action payouts go to the account set in EmployeeConfig.salaryAccount ('bank' or 'cash'). On ESX the bridge maps 'cash' to the money account. If your framework names accounts differently, change normalizeAccount in the bridge file instead of changing the config value.