Developers

Exports, events and hooks for connecting lation weed to other resources. Every export is called on exports.lation_weed. A player is their server id (source), and a lab is its id: the number purchaseLab returns, which is also the routing bucket of the lab and the bucketId of its plants.

Server exportsCopy Anchor Link

The exports that change something answer { ok = true, ... } when it worked, and { ok = false, error = '<code>' } when nothing changed and the code says why. The plants and player records the exports hand out are copies: changing one changes nothing in the game.

GetRuntimeConfigCopy Anchor Link

exports.lation_weed:GetRuntimeConfig(section)

The table is the live configuration, not a copy: read it, and change settings in /weedadmin. It is the only export in PascalCase. The logs section holds your Discord webhook, so don't pass it to clients.

local planting = exports.lation_weed:GetRuntimeConfig('planting')
print(('players can own %d plants'):format(planting.max))

purchaseLabCopy Anchor Link

local result = exports.lation_weed:purchaseLab(source, labKey, options)

Buys or grants a lab, for selling labs through your own script. It ignores the lab's Purchase interaction and Marketplace listing switches, but still checks the player's level, the labs-per-player cap and whether someone already owns the lab. Unless skipPayment is set, it charges the lab's price from the Labs > Accounts > Purchase account. The new owner starts with an empty stash.

The error is one of no-identifier, invalid-key, lab-not-found, level-too-low, max-per-player, already-owned, insufficient-funds or insert-failed.

A lab granted with skipPayment still records its price as the price paid, so selling it later refunds the Sell refund share of that price.

local result = exports.lation_weed:purchaseLab(source, 'mission_row_1', { skipPayment = true })
if not result.ok then
    print(('lab purchase failed: %s'):format(result.error))
    return
end
print(('granted lab %d'):format(result.labId))

getLabBalanceCopy Anchor Link

exports.lation_weed:getLabBalance(labId)

There is no export that sells or takes back a lab. However a lab ends (sold, removed by an admin, or reclaimed for inactivity), its wallet goes back to its owner and its stash is emptied; see selling a lab.

local plant = exports.lation_weed:getPlantData(plantId)
if plant and plant.bucketId > 0 then
    print(('that lab holds $%d'):format(exports.lation_weed:getLabBalance(plant.bucketId)))
end

getPlayerDataCopy Anchor Link

exports.lation_weed:getPlayerData(source, field)

A player with no record gets one at level 1 on the first call. The record is the cached one, so treat it as read-only and change XP with addXP, removeXP and setLevel. The level is always the one the player's XP reaches on the live level ladder.

{
    identifier = 'ABC12345',
    level = 2,
    exp = 3150,
    plants_searched = 12,  -- farm searches that found seeds
    plants_grown = 9,      -- harvests
    bud_produced = 84,
    joints_rolled = 30,
    weed_bagged = 15,
}

local level = exports.lation_weed:getPlayerData(source, 'level')
if level and level >= 3 then
    -- let them in
end

addXPCopy Anchor Link

local result = exports.lation_weed:addXP(source, amount)

Gives XP the way a harvest does: the player moves up the level ladder and gets the level up notification through lation_weed:levelUp. The XP is taken as given: no strain's XP multiplier applies. Like gameplay XP, it is saved when the player leaves and every 3 minutes.

local result = exports.lation_weed:addXP(source, 250)
if result.ok then
    print(('now level %d with %d XP'):format(result.level, result.xp))
end

removeXPCopy Anchor Link

local result = exports.lation_weed:removeXP(source, amount)

Takes XP away, stopping at 0. A player whose XP falls below their level's threshold drops to the level the ladder puts them at and is told through lation_weed:levelDown.

exports.lation_weed:removeXP(source, 1000)

setLevelCopy Anchor Link

local result = exports.lation_weed:setLevel(source, level)

Puts a player at a level. XP already inside that level stays; otherwise it moves to the level's threshold. The player is told when the level goes up or down.

exports.lation_weed:setLevel(source, 3)

The error of all three is one of:

addPlayerDataCopy Anchor Link

exports.lation_weed:addPlayerData(source, dataType, amount)

The lower-level way in, for the lifetime counters. Adding exp levels up and notifies like addXP, which is the one to use for XP.

exports.lation_weed:addPlayerData(source, 'joints_rolled', 1)

getLevelDataCopy Anchor Link

exports.lation_weed:getLevelData()

local levels = exports.lation_weed:getLevelData()
-- { 0, 2500, 10000, 20000, 50000, 100000 }

getPlayerPlantCountCopy Anchor Link

exports.lation_weed:getPlayerPlantCount(source)

if exports.lation_weed:getPlayerPlantCount(source) >= 10 then
    -- a big grower
end

getPlantDataCopy Anchor Link

exports.lation_weed:getPlantData(plantId, property)

The plant:

{
    id = 42,
    owner = 'ABC12345',          -- the identifier of who put it down; 'lab_<labId>' for a lab worker's plant
    strainId = 'og_kush',        -- nil until a seed is planted
    model = 'shoe_shuffler_prop_weed_med_green_01a',
    x = 0.0, y = 0.0, z = 0.0, w = 0.0,
    stage = 5,                   -- 1 empty pot, 2 pot with soil, 3 to 8 growing
    growth = 40,                 -- 0 to 100
    health = 100,                -- 0 to 100
    water = 55,                  -- 0 to 100
    fertilizer = 30,             -- 0 to 100
    soil = 'ls_basic_soil',      -- nil until soil is added
    fertilizerType = 'ls_basic_fertilizer',
    isCovered = false,           -- under cover, so no rain
    deathTimer = nil,            -- seconds left while the plant is dying
    bucketId = 0,                -- 0 outdoors; the lab's id inside a lab
}

local health = exports.lation_weed:getPlantData(plantId, 'health')

getAllPlantsCopy Anchor Link

exports.lation_weed:getAllPlants()

for plantId, plant in pairs(exports.lation_weed:getAllPlants()) do
    if plant.growth >= 100 then
        print(('plant %d is ready'):format(plantId))
    end
end

getPlantsByOwnerCopy Anchor Link

exports.lation_weed:getPlantsByOwner(owner)

local mine = exports.lation_weed:getPlantsByOwner(source)
print(('%d plants'):format(#mine))

getPlantsByLabCopy Anchor Link

exports.lation_weed:getPlantsByLab(labId)

for _, plant in ipairs(exports.lation_weed:getPlantsByLab(labId)) do
    print(plant.id, plant.strainId, plant.growth)
end

setPlantDataCopy Anchor Link

local result = exports.lation_weed:setPlantData(plantId, values)
local result = exports.lation_weed:setPlantData(plantId, field, value)

Sets one or more fields of a plant, checked the way the admin panel's plant editor checks them, then saved, put back in the growth loop where it belongs and shown to the players who can see the plant, like a change the game makes itself.

What the game keeps in step for you:

• Setting growth on a growing plant without a stage moves the stage, and the model, to the one that growth shows, as the growth loop does. At 100 the plant is ready to harvest.
• Giving health back to a dying plant stops its death timer.
• A stage or strain change picks the model that stage shows.

Anything else about a plant (its owner, where it stands, its model, its death timer) can't be set. One refused field refuses the whole call, and nothing changes.

After every successful call, lation_weed:server:plantChanged fires with the plant.

-- a sprinkler: top up every plant in a lab
for _, plant in ipairs(exports.lation_weed:getPlantsByLab(labId)) do
    exports.lation_weed:setPlantData(plant.id, { water = 100 })
end

-- one field
local result = exports.lation_weed:setPlantData(42, 'health', 100)
if not result.ok then
    print(('refused: %s'):format(result.error))
end

-- plant a strain in a pot that has soil
exports.lation_weed:setPlantData(42, { strainId = 'og_kush', stage = 3 })

Client exportsCopy Anchor Link

openLabMarketplaceCopy Anchor Link

exports.lation_weed:openLabMarketplace()

Opens the lab marketplace for the local player, from your own phone app or NPC for example. Players buy through it with the usual rules, so labs with their Marketplace listing off aren't shown.

if not exports.lation_weed:openLabMarketplace() then
    print('marketplace unavailable')
end

EventsCopy Anchor Link

ServerCopy Anchor Link

Local server events: listen with AddEventHandler in a server script.

lation_weed:configUpdatedCopy Anchor Link

AddEventHandler('lation_weed:configUpdated', function(snapshot) end)

Fires when the configuration loads on start, and after every save, reset or import in the admin panel.

AddEventHandler('lation_weed:configUpdated', function(snapshot)
    print(('players can now own %d plants'):format(snapshot.planting.max))
end)

lation_weed:server:plantChangedCopy Anchor Link

AddEventHandler('lation_weed:server:plantChanged', function(plantId, plant) end)

Fires when a plant is created, when one is removed by harvest, destroy, death, cleanup, an admin, a sale or a lab being closed, and after every successful setPlantData. Other changes to a living plant (growth, care, the admin panel's editor) don't fire it. The plant passed is the server's own record, so read it without changing it.

AddEventHandler('lation_weed:server:plantChanged', function(plantId, plant)
    if not plant then
        print(('plant %d is gone'):format(plantId))
    end
end)

lation_weed:server:plantNeedsAttentionCopy Anchor Link

AddEventHandler('lation_weed:server:plantNeedsAttention', function(plantId, reason) end)

AddEventHandler('lation_weed:server:plantNeedsAttention', function(plantId, reason)
    if reason ~= 'harvest' then return end
    local owner = exports.lation_weed:getPlantData(plantId, 'owner')
    print(('plant %d owned by %s is ready'):format(plantId, owner))
end)

ClientCopy Anchor Link

lation_weed:runtimeReadyCopy Anchor Link

AddEventHandler('lation_weed:runtimeReady', function() end)

Fires when the configuration reaches this client: after joining, after a restart, and after every save in the admin panel. Listen with AddEventHandler.

lation_weed:levelUpCopy Anchor Link

RegisterNetEvent('lation_weed:levelUp', function(newLevel) end)

Sent by the server when the player levels up, from gameplay, addXP, setLevel or a level ladder edited in the admin panel; lation weed shows its own notification as well. Listen with RegisterNetEvent.

RegisterNetEvent('lation_weed:levelUp', function(newLevel)
    print(('reached weed level %d'):format(newLevel))
end)

lation_weed:levelDownCopy Anchor Link

RegisterNetEvent('lation_weed:levelDown', function(newLevel) end)

Sent by the server when removeXP or setLevel moves the player down a level; lation weed shows its own notification as well. A level ladder edited in the admin panel moves players down without it.

lation_weed:notifyCopy Anchor Link

TriggerClientEvent('lation_weed:notify', source, message, type)

Send it from the server to show a notification through the system set under Setup > Integrations > Notifications.

TriggerClientEvent('lation_weed:notify', source, 'Your harvest is ready', 'success')

HooksCopy Anchor Link

Hooks are functions in files that ship open: server/utils/hooks.lua and client/utils/hooks.lua. Edit them in place.

onLabRaidAttemptCopy Anchor Link

function Hooks.onLabRaidAttempt(data) end

Runs when a player confirms a break-in and the server accepts it, before the skill check. Empty by default; use it for dispatch alerts.

function Hooks.onLabRaidAttempt(data)
    if data.isPolice then return end
    exports['ps-dispatch']:CustomAlert({
        message = 'Possible break in detected',
        coords = data.coords,
        sprite = 499,
        color = 1,
        scale = 1.0,
        length = 3,
        jobs = { 'police' },
    })
end

onLabRaidBreachedCopy Anchor Link

function Hooks.onLabRaidBreached(data) end

Runs after every successful break-in, whatever Labs > Raids > Notify the owner is set to and whether or not the owner is online, so a dispatch, phone or mail script keeps working with the in-game notice off. By default it sends the owner a notification when notifyOwner is on and they are online.

function Hooks.onLabRaidBreached(data)
    if data.notifyOwner and data.ownerSource then
        TriggerClientEvent('lation_weed:notify', data.ownerSource, data.message, 'error')
        return
    end
    -- the owner is offline, or the in-game notice is off: send your own here
    -- exports['my-phone']:SendMail(data.ownerIdentifier, data.labLabel, data.message)
end

If you edited this hook before 4.7.0, check data.notifyOwner before sending your own in-game notice.

onJointSmoked (server)Copy Anchor Link

function Hooks.onJointSmoked(data) end

Runs on the server when a player finishes smoking and the joint is taken from their inventory. Empty by default.

function Hooks.onJointSmoked(data)
    print(('%s smoked a %s joint'):format(data.identifier, data.strainLabel or data.strainId))
end

onJointSmoked (client)Copy Anchor Link

function Hooks.onJointSmoked(data) end

Runs on the player's client once they finish smoking and the effects apply. By default it relieves stress with the hud:server:RelieveStress event that QBCore and Qbox HUDs listen for:

function Hooks.onJointSmoked(data)
    if not data then return end

    local amount = tonumber(data.stressRelief) or 0
    if amount <= 0 then return end

    TriggerServerEvent('hud:server:RelieveStress', amount)
end

If your HUD handles stress another way, change this function.

Open filesCopy Anchor Link

These files ship open, so you can fit the script to your server: