Documentation

Exports & Events

All exports, hooks and state bags available to integrate Snow Chains into other resources.

General Information

Wheels are named by their bone: wheel_lf, wheel_rf, wheel_lr, wheel_rr, and wheel_lm1 to wheel_rm3 for middle axles. Chain health is an integer from 1 to 100. Vehicle arguments are entity handles.

Suggestions?

If you wish to have any exports or events added, please head over to our Discord and create a suggestion post. We are happy to allow for easier integration within other resources.

#Complete Export Index

ContextExports
ServerApplyVehicleChain, RemoveVehicleChain, HasChainOnWheel, GetVehicleChains, SetSnowOverride
ClientGetVehicleChainsCount, IsSnowing, GetVehicleChainData, SetVehicleChainData, GetHandlingBase, SetHandlingBase

#Server Sided Exports

Server exports are trusted operations. They bypass the item, job, can-check hooks and the fitting flow. Validate your own caller before using them, and don't expose them through an unrestricted network event.

#Apply Vehicle Chain

Fits a chain to a wheel and saves it. Health defaults to a new chain. Returns false for a missing vehicle or an invalid wheel bone.

Example:

lua
---@param vehicle integer
---@param bone string @ Wheel bone, such as "wheel_lf"
---@param health? integer @ Defaults to 100
---@return boolean applied
local applied = exports["zyke_snowchains"]:ApplyVehicleChain(vehicle, "wheel_lf", health)

#Remove Vehicle Chain

Takes a chain off a wheel. Returns the chain's health, or nil when the wheel had none. No item is given back.

Example:

lua
---@param vehicle integer
---@param bone string
---@return integer? health
local health = exports["zyke_snowchains"]:RemoveVehicleChain(vehicle, "wheel_lf")

#Has Chain On Wheel

Returns whether a wheel has a chain.

Example:

lua
---@param vehicle integer
---@param bone string
---@return boolean hasChain
local hasChain = exports["zyke_snowchains"]:HasChainOnWheel(vehicle, "wheel_lf")

#Get Vehicle Chains

Returns the vehicle's chains as health by wheel bone, or an empty table when it has none.

Example:

lua
---@param vehicle integer
---@return table<string, integer> chains @ {wheel_lf = 100, wheel_rf = 87}
local chains = exports["zyke_snowchains"]:GetVehicleChains(vehicle)

#Set Snow Override

Forces snowy roads on or off for every player, for weather scripts without snow weather or for events. nil follows the weather again. This is the same as the /snowroads command.

Example:

lua
---@param isSnowing? boolean @ true forces snow, false forces dry, nil follows the weather
exports["zyke_snowchains"]:SetSnowOverride(true)

#Client Sided Exports

#Get Vehicle Chains Count

Returns how many chains the vehicle has fitted.

Example:

lua
---@param vehicle integer
---@return integer count
local count = exports["zyke_snowchains"]:GetVehicleChainsCount(vehicle)

#Is Snowing

Returns whether roads currently count as snowy, from the weather or the snow override.

Example:

lua
---@return boolean isSnowing
local isSnowing = exports["zyke_snowchains"]:IsSnowing()

#Get Vehicle Chain Data

Returns the vehicle's chains as health by wheel bone, or nil without chains. Used to save chains in framework vehicle properties; see Vehicle Properties.

Example:

lua
---@param vehicle integer
---@return table<string, integer>? chains
local chains = exports["zyke_snowchains"]:GetVehicleChainData(vehicle)

#Set Vehicle Chain Data

Asks the server to restore the chains saved in the vehicle's framework properties. The server reads the saved properties itself and never trusts the table passed here, which only signals that the vehicle was saved with chains. It waits for a freshly spawned vehicle to become networked, so it is safe to call from a properties setter.

Example:

lua
---@param vehicle integer
---@param chains? table<string, integer>
exports["zyke_snowchains"]:SetVehicleChainData(vehicle, chains)

#Scripts That Change Handling

On snow, the driver's client multiplies fTractionCurveMax, fTractionCurveMin, fLowSpeedTractionLossMult and fBrakeForce. A script that also changes one of these, or keeps its own copy of the stock values, uses the two exports below so the changes stack instead of undoing each other. Vehicle Terrain and Realistic Vehicles already do.

A script that writes these fields directly still works: Snow Chains takes the new value as the base and puts its change back on top within a quarter of a second.

#Get Handling Base

Returns the handling values without the snow change, by field name, or nil when Snow Chains isn't changing this vehicle.

Example:

lua
---@param vehicle integer
---@return table<string, number>? base
local base = exports["zyke_snowchains"]:GetHandlingBase(vehicle)
local stockBrakeForce = base and base.fBrakeForce or GetVehicleHandlingFloat(vehicle, "CHandlingData", "fBrakeForce")

#Set Handling Base

Writes your value for a field through Snow Chains, which keeps the snow change on top. Returns false when Snow Chains doesn't change that field on this vehicle, in which case you write the value yourself.

Example:

lua
---@param vehicle integer
---@param field string
---@param value number
---@return boolean handled
if (not exports["zyke_snowchains"]:SetHandlingBase(vehicle, "fTractionCurveMax", value)) then
    SetVehicleHandlingFloat(vehicle, "CHandlingData", "fTractionCurveMax", value)
end

#Server Hooks

The hooks in server/unlocked/hooks.lua run after chains change, for logs, job payments or your own scripts. The file is unencrypted and safe to edit. By default fitting and removal log to zyke_lib's webhooks under the actions snowChainFitted and snowChainRemoved.

#On Snow Chain Fitted

Runs after a player fits a chain.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param bone string @ Wheel bone, such as "wheel_lf"
---@param health integer @ 1 to 100
function OnSnowChainFitted(plyId, vehicle, bone, health)
end

#On Snow Chain Removed

Runs after a player removes a chain.

Example:

lua
---@param plyId integer
---@param vehicle integer
---@param bone string
---@param health integer @ 1 to 100
function OnSnowChainRemoved(plyId, vehicle, bone, health)
end

#On Snow Chain Snapped

Runs after a worn chain snaps off a wheel. Empty by default.

Example:

lua
---@param vehicle integer
---@param bone string
function OnSnowChainSnapped(vehicle, bone)
end

#State Bags

State BagContents
zyke_snowchains:chainsThe vehicle's chains, health by wheel bone.
zyke_snowchains:workWheels currently being worked on.

Read them, but change chains through the server exports so they are saved.

For custom permission rules, use Can-Check Hooks.