Exports and integration
Kivo Weedshop registers no exports. There are two open integration points:
- 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. - The bridge file.
shared/framework.luaholds the framework, inventory, target and vehicle key adapters. It is meant to be edited when you run something the script does not support.
State bags
Section titled “State bags”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.
Plant plots
Section titled “Plant plots”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_plot3kivo_plant_plot4 kivo_plant_plot5 kivo_plant_plot6Value (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. |
Drying racks
Section titled “Drying racks”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_dryingRack3Value (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.
Reading the values
Section titled “Reading the values”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')endServer, 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 countendClient, 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' }) endend)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())endIf you add or rename plots or racks in the config, use the new ids in the key.
The bridge file
Section titled “The bridge file”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.
Framework functions
Section titled “Framework functions”| 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 functions
Section titled “Inventory functions”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 functions
Section titled “Target functions”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. |
Adapting the bridge
Section titled “Adapting the bridge”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.
Use another inventory
Section titled “Use another inventory”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.
- 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- At the top of each server function, add a branch for the new type (these functions are inside the
if IsDuplicityVersion() thenblock):
-- Inventory.GetItemCount(source, item)if inventoryType == 'my' then return exports.my_inventory:GetItemCount(source, item) or 0end
-- Inventory.RemoveItem(source, item, count)if inventoryType == 'my' then return exports.my_inventory:RemoveItem(source, item, count) and true or falseend
-- Inventory.AddItem(source, item, count)if inventoryType == 'my' then return exports.my_inventory:AddItem(source, item, count) and true or falseend
-- Inventory.CanCarryItem(source, item, count)if inventoryType == 'my' then return exports.my_inventory:CanCarryItem(source, item, count) and true or falseend- The client function
Inventory.HasItem(item, count)already asks the server for every inventory exceptox_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).
Use another framework
Section titled “Use another framework”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 elseelseif resourceName == 'myfw' then frameworkType = 'myfw' frameworkObj = exports['myfw']:GetCore()
-- Framework.GetPlayerJob(source), serverif 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), serverif frameworkType == 'myfw' then local player = frameworkObj.GetPlayer(source) return player and player.addMoney(account, amount) == true or falseendThe 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.
Use another target system
Section titled “Use another target system”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.
Vehicle keys
Section titled “Vehicle keys”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 belowNotifications
Section titled “Notifications”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.
Money accounts
Section titled “Money accounts”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.
