Exports & Events

General Information

Vehicle arguments are entity handles. Lift ids are the integers returned by CreateLift. Heights and travel are metres up from the bottom of the posts. Stops are low, waist, or high.

Rules, trims, and busy checks belong to the resource that registers them and are removed when it stops. Lifts made through CreateLift belong to the calling resource and are removed when it stops.

Types / Classes

All types / classes can be found in types/types.lua inside zyke_vehiclelifts.

#Complete Export Index

#Client Sided Exports

#Get Lift

Returns the lift from the zykeVehicleLifts global state, or nil. Treat it as read-only.

Example:

lua
---@param liftId integer
---@return ZykeVehicleLift? lift
local lift = exports["zyke_vehiclelifts"]:GetLift(liftId)

#Get Lift Travel

Returns how far the carriages stand up on this client right now, and whether they are moving. travel is nil for an unknown lift.

Example:

lua
---@param liftId integer
---@return number? travel @ Metres up from the bottom
---@return boolean moving
local travel, moving = exports["zyke_vehiclelifts"]:GetLiftTravel(liftId)

#Get Lift Under

Returns the lift the vehicle stands between the posts of, or nil. Only lifts streamed in near the player are checked.

Example:

lua
---@param vehicle integer
---@return integer? liftId
local liftId = exports["zyke_vehiclelifts"]:GetLiftUnder(vehicle)

#Is Working Lift

Returns whether the player is at a power unit or setting a lift's arms.

Example:

lua
---@return boolean working
local working = exports["zyke_vehiclelifts"]:IsWorkingLift()

#Get Vehicle Lift

Returns the vehicle's record from its zykeVehicleLift state bag, or nil for a vehicle on no lift. Treat it as read-only.

Example:

lua
---@param vehicle integer
---@return LiftCar? car
local car = exports["zyke_vehiclelifts"]:GetVehicleLift(vehicle)

#Is Vehicle On Lift

Returns whether the vehicle is up on a lift's pads.

Example:

lua
---@param vehicle integer
---@return boolean lifted
local lifted = exports["zyke_vehiclelifts"]:IsVehicleOnLift(vehicle)

#Is Vehicle On Moving Lift

Returns whether the vehicle is on a lift whose carriages are moving.

Example:

lua
---@param vehicle integer
---@return boolean moving
local moving = exports["zyke_vehiclelifts"]:IsVehicleOnMovingLift(vehicle)

#Get Vehicle Lift Stop

Returns the stop the vehicle stands at, or has passed on its way up, and whether the lift is moving. A stop counts from its lock until the next stop's lock is reached. stop is nil between the bottom and low, and for a vehicle on no lift.

Example:

lua
---@param vehicle integer
---@return "low" | "waist" | "high" | nil stop
---@return boolean moving
local stop, moving = exports["zyke_vehiclelifts"]:GetVehicleLiftStop(vehicle)

#Register Busy Check

Registers a check that keeps the player off the lifts. While it returns true, the power unit and the arms are not offered. vehicle is the car the arms would be set under, or nil for the power unit. Registering again under the same name replaces the earlier check. Returns false for an invalid name or function.

Example:

lua
---@param name string @ Unique within the registering resource
---@param isBusy fun(vehicle?: integer): boolean
---@return boolean registered
exports["zyke_vehiclelifts"]:RegisterBusyCheck("myJob", function(vehicle)
    return IsMyMenuOpen()
end)

#Remove Busy Check

Removes a busy check the calling resource registered.

Example:

lua
---@param name string
---@return boolean removed
local removed = exports["zyke_vehiclelifts"]:RemoveBusyCheck("myJob")

#Server Sided Exports

CreateLift and RemoveLift are trusted server operations. They bypass the admin command's permission check. Do not expose them directly through an unrestricted network event.

#Create Lift

Places a lift for the calling resource and returns its id, or nil for invalid options. Calling it again for the same spot, kind, and bucket returns the same lift.

A lift with a bucket is only seen and worked from that routing bucket, so instanced interiors can each have their own at the same coords. Without one, it stands in every bucket.

The lift is removed when the calling resource stops. A car up on it stays up for 15 seconds, so a resource that restarts and places the lift again keeps the car where it was.

Example:

lua
---@param options LiftOptions
---@return integer? liftId
local liftId = exports["zyke_vehiclelifts"]:CreateLift({
    coords = vector3(-1366.5, -3007.1, 12.95), -- On the floor, midway between the posts
    heading = 240.0, -- The way a car's nose points when it is driven in
    kind = "twopost", -- Optional, defaults to "twopost"
    bucket = 7301, -- Optional, the routing bucket it stands in
})

Vehicle Lifts forgets other resources' lifts, rules, and trims when it restarts. Register them when it starts as well:

Example:

lua
local function placeLifts()
    exports["zyke_vehiclelifts"]:CreateLift({coords = vector3(-1366.5, -3007.1, 12.95), heading = 240.0})
end

AddEventHandler("onResourceStart", function(resource)
    if (resource == "zyke_vehiclelifts") then placeLifts() end
end)

if (GetResourceState("zyke_vehiclelifts") == "started") then placeLifts() end

#Remove Lift

Removes a lift. Only the resource that made the lift can remove it. A car on it is set down on its wheels.

Example:

lua
---@param liftId integer
---@return boolean removed
local removed = exports["zyke_vehiclelifts"]:RemoveLift(liftId)

#Get Lift

Returns one lift, or nil. Treat it as read-only.

Example:

lua
---@param liftId integer
---@return ZykeVehicleLift? lift
local lift = exports["zyke_vehiclelifts"]:GetLift(liftId)

#Get Lifts

Returns every lift, keyed by id. Treat the map and its lifts as read-only.

Example:

lua
---@return table<integer, ZykeVehicleLift> lifts
local lifts = exports["zyke_vehiclelifts"]:GetLifts()

#Get Vehicle Lift

Returns the vehicle's lift record, or nil for a vehicle on no lift.

Example:

lua
---@param vehicle integer
---@return LiftCar? car
local car = exports["zyke_vehiclelifts"]:GetVehicleLift(vehicle)

#Is Vehicle On Lift

Returns whether the vehicle is up on a lift's pads.

Example:

lua
---@param vehicle integer
---@return boolean lifted
local lifted = exports["zyke_vehiclelifts"]:IsVehicleOnLift(vehicle)

#Is Vehicle On Moving Lift

Returns whether the vehicle is on a lift whose carriages are moving.

Example:

lua
---@param vehicle integer
---@return boolean moving
local moving = exports["zyke_vehiclelifts"]:IsVehicleOnMovingLift(vehicle)

#Get Vehicle Lift Stop

Same as the client export. Returns the vehicle's stop, or nil, and whether the lift is moving.

Example:

lua
---@param vehicle integer
---@return "low" | "waist" | "high" | nil stop
---@return boolean moving
local stop, moving = exports["zyke_vehiclelifts"]:GetVehicleLiftStop(vehicle)

#Register Lift Rules

Registers rules that apply to every lift. Every function is optional, and registering again under the same name replaces the earlier rules. Returns false for an invalid name or rules. A rule that errors is skipped.

• canWork runs before a player sets the arms or moves a lift. data.action is arms, up, or down, and data.vehicle is the car on the pads, if any. Return false and a message to refuse.
• lowestStop holds a car no lower than low, waist, or high. The message is shown to a player who tries to lower it further. The highest stop any rule returns wins.
• holdFrozen keeps the car frozen once it is back on its wheels while it returns true.

Messages are shown to the player as they are, not as locale keys.

Example:

lua
---@param name string @ Unique within the registering resource
---@param rules LiftRules
---@return boolean registered
exports["zyke_vehiclelifts"]:RegisterLiftRules("myJob", {
    ---@param data LiftWorkData
    canWork = function(data)
        if (data.vehicle and IsMyJobRunning(data.vehicle)) then return false, "Finish the job first." end

        return true
    end,
    lowestStop = function(vehicle)
        if (IsWheelMissing(vehicle)) then return "low", "Put the wheel back on first." end
    end,
    holdFrozen = function(vehicle)
        return IsMyJobHoldingIt(vehicle)
    end,
})

#Remove Lift Rules

Removes rules the calling resource registered.

Example:

lua
---@param name string
---@return boolean removed
local removed = exports["zyke_vehiclelifts"]:RemoveLiftRules("myJob")

#Set Vehicle Lift Trim

Tilts and raises the car on the pads. pitch is degrees with the nose up, and height is metres. Trims from every resource add up, capped at 5 degrees and 0.25 metres either way. The car eases into a new trim as it rises off the pads. The trim stays with the car while it is lowered and raised again, until it is set to nil or the calling resource stops.

Example:

lua
---@param vehicle integer
---@param trim? LiftTrim @ nil clears the calling resource's trim
---@return boolean set
exports["zyke_vehiclelifts"]:SetVehicleLiftTrim(vehicle, {pitch = 1.2, height = 0.02})

#Server Local Events

These events are local server integration notifications. They are not network event entry points and cannot block an action; use RegisterLiftRules for that. Listen with AddEventHandler on the server.

#On Lift Moved

Fires when a player sends a lift up or down, as the carriages set off from from toward goal. netId, modelHash, and plate describe the car on the pads, if there is one. The same data is passed to OnLiftMoved in server/hooks.lua.

Example:

lua
---@param data LiftHookData
AddEventHandler("zyke_vehiclelifts:OnLiftMoved", function(data)
    print(data.source, data.liftId, data.from, data.goal, data.plate)
end)

#On Vehicle Lifted

Fires when the pads take a car off the ground. source is the player at the power unit.

Example:

lua
---@param data LiftCarHookData
AddEventHandler("zyke_vehiclelifts:OnVehicleLifted", function(data)
    print(data.source, data.liftId, data.netId, data.plate)
end)

#On Vehicle Lowered

Fires when a car is back on its wheels and released, including when its lift is removed. source is not set.

Example:

lua
---@param data LiftCarHookData
AddEventHandler("zyke_vehiclelifts:OnVehicleLowered", function(data)
    print(data.liftId, data.netId, data.plate)
end)

#State Bags

The zykeVehicleLifts global state holds every lift, and the zykeVehicleLift state bag on a car holds its lift record. Both are read-only; use the exports above.

For custom permission rules within Vehicle Lifts itself, use Can-Check Hooks.