Documentation

Exports & Events

Client and server exports, state bags, and events for angle grinder integrations.

General Information

plyId is a player's server ID. Durability and charge run from 0 to 100. Progress runs from 0 to 1. A disc state is empty, loaded, or broken.

Stages are a list of {checks, seconds}. checks lists easy, medium, or hard skill check presets, or false for none; seconds adds length. A pressure cut turns them into cut time and difficulty. See Pressure Cut.

The grinder notifies the player about every grinder-side outcome, such as a missing disc, a failed cut, or a broken disc, so integrations only notify their own results. Tool actions and busy checks belong to the resource that registers them and are removed when it stops. See Integrations for a full worked example.

Types / Classes

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

#Complete Export Index

ContextExports
ClientStartGrind, RegisterToolAction, RemoveToolAction, RunGrindSession, RegisterBusyCheck, RemoveBusyCheck, BeginCustomGrind, SetCustomGrindContact, SetCustomGrindProp, ReportCustomGrindCut, FinishCustomGrind, SetGrindingGrip, SetGrinderRest, GetGrinderDiscEdge, IsGrinderEquipped, GetGrinderDiscState, GetGrinderProp, IsGrinderInteracting
ServerCreateGrindSession, ConsumeGrindSession, GetEquippedGrinder, WearGrinderDisc

#Client Sided Exports

#Start Grind

Runs a whole grind and returns whether it completed. Every option can be left out; without entity or coords, it grinds the spot just above the ground in front of the player.

The stages, wear, and result come from and go back to the client, and ConsumeGrindSession cannot read these sessions. Use it only when a modified client gaining a free cut costs nothing; when a cut unlocks something, open the session on your server with CreateGrindSession instead.

Example:

lua
---@param options? GrindOptions
---@return boolean completed
local completed = exports["zyke_anglegrinder"]:StartGrind({
    coords = vector3(215.3, -810.1, 30.2), -- Or entity with an entity-local offset
    stages = {{checks = {"easy"}, seconds = 2}}, -- One easy 2 second stage when left out
    durabilityLoss = {min = 8, max = 15}, -- Disc wear for the whole grind, the config's when left out
    legal = true, -- true skips witness checks, nil uses witnesses.defaultLegal
    crime = "fenceCutting", -- Optional, label handed to OnIllegalGrind
    witnessDistance = 30.0, -- Optional, overrides witnesses.maxDistance
    label = "Cutting Fence", -- Optional, title shown on the minigame
    approach = {coords = standCoords, heading = standHeading}, -- Optional, where the player walks first
    crouch = true, -- Optional, nil leaves it to the work animation
    isValid = function() return true end, -- Optional, returning false stops the grind
    cinematic = false, -- Optional, false keeps the gameplay camera, a table frames your own shot
    progress = 0.5, -- Optional, share already cut, 0 to 1
})

A cinematic table takes camera, look, fov, blendInMs, and blendOutMs; values left out fall back to grinding.cinematic. With grinding.cinematic.enabled = false, no grind gets a cinematic camera.

#Register Tool Action

Offers your targets as interest points while the grinder is out. getPoints(range) is called twice a second and returns every target within range as a point. Aiming at a point within reach shows the use key on it, and the press calls onUse with the point's data. Registering again under the same name replaces the action. Register again when zyke_anglegrinder restarts, as it forgets every action.

Points take entity with an optional entity-local offset, or world coords, plus an optional reach (2.0 metres by default), prompt label, and data.

Example:

lua
---@param name string @ Unique within the registering resource
---@param action GrinderToolAction
---@return boolean registered
exports["zyke_anglegrinder"]:RegisterToolAction("cutFence", {
    getPoints = function(range)
        local points = {}

        for _, fence in ipairs(findFencesInRange(range)) do
            points[#points + 1] = {
                entity = fence,
                offset = vector3(0.0, 0.0, 1.0),
                reach = 2.0,
                label = "Cut Fence",
                data = {netId = NetworkGetNetworkIdFromEntity(fence)},
            }
        end

        return points
    end,
    onUse = function(data)
        -- Open a session on your server, then RunGrindSession
    end,
})

#Remove Tool Action

Removes an action registered by the calling resource.

Example:

lua
---@param name string
---@return boolean removed
exports["zyke_anglegrinder"]:RemoveToolAction("cutFence")

#Run Grind Session

Runs a session your server opened with CreateGrindSession, usually from a tool action's onUse. The return value only drives your client flow; read the verified result on the server with ConsumeGrindSession. target takes the same placement, label, approach, crouch, isValid, and cinematic options as StartGrind.

Example:

lua
---@param sessionId string
---@param target GrindTarget
---@return boolean completed
local completed = exports["zyke_anglegrinder"]:RunGrindSession(sessionId, {
    entity = fence,
    offset = vector3(0.0, 0.0, 1.0),
    label = "Cutting Fence",
    crouch = true,
    isValid = function() return DoesEntityExist(fence) end,
})

#Register Busy Check

While isBusy() returns true, the player cannot take the grinder out, put it away, or swap its disc or battery. Use it when your resource has the player's hands full. Registering again under the same name replaces the check.

Example:

lua
---@param name string
---@param isBusy fun(): boolean
---@return boolean registered
exports["zyke_anglegrinder"]:RegisterBusyCheck("carrying", function()
    return IsCarryingSomething()
end)

#Remove Busy Check

Removes a busy check registered by the calling resource.

Example:

lua
---@param name string
---@return boolean removed
exports["zyke_anglegrinder"]:RemoveBusyCheck("carrying")

#Begin Custom Grind

For resources that run their own minigame while the grinder handles wear, sound, sparks, and witnesses. Starts a session opened with minigame = "custom" once your player is in place with your work animation playing. Returns every stage, the disc durability the first cut starts from, and the fitted disc's wear multiplier, or nil when the session cannot begin. Each stage carries a cut with its length (ms), graceMs, maxMs, penalty, difficulty, rolled wear, and start for a resumed cut.

Example:

lua
---@param sessionId string
---@return GrindSessionStage[]? stages
---@return number? durability
---@return number? wearMultiplier
local stages, durability, wearMultiplier = exports["zyke_anglegrinder"]:BeginCustomGrind(sessionId)

#Set Custom Grind Contact

Drives your own sparks and reports the disc contact to nearby players. intensity is 1 for a clean cut, and nil stops the sparks. level is 1 for an idle or skating disc, 2 for a clean cut, and 3 for a forced or binding one.

Example:

lua
---@param intensity? number
---@param level? 1 | 2 | 3
---@return boolean applied
exports["zyke_anglegrinder"]:SetCustomGrindContact(1.0, 2)

#Set Custom Grind Prop

Passes a local stand-in prop with the held grinder's model, for a close-up framed by your resource. The held grinder hides for this client only, and your sparks move onto the stand-in's disc. Other players keep seeing the held grinder. nil goes back to the held grinder.

Example:

lua
---@param prop? integer
---@return boolean applied
exports["zyke_anglegrinder"]:SetCustomGrindProp(prop)

#Report Custom Grind Cut

Reports one stage's cut, however it ended. progress is how far through the cut the disc got, and drain is the disc drain in clean-cut lengths, 1 for a clean cut. The server caps both by how long the cut ran. Returns whether the grind can continue and the disc durability the next cut starts from.

Example:

lua
---@param progress number
---@param drain number
---@return boolean canContinue
---@return number? durability
local canContinue, remaining = exports["zyke_anglegrinder"]:ReportCustomGrindCut(progress, drain)

#Finish Custom Grind

Ends the custom grind and returns the server-verified result. It also clears the grip set with SetGrindingGrip. A custom grind is released automatically when your resource stops.

Example:

lua
---@param completed boolean @ Whether every stage's cut ran to the end
---@return boolean verified
local verified = exports["zyke_anglegrinder"]:FinishCustomGrind(completed)

#Set Grinding Grip

Sets the held grinder's grip for your own work animation, seen by every client. bone is 57005 for the right hand or 18905 for the left, and defaults to prop.bone. nil goes back to grinding.grip.

Example:

lua
---@param grip? GrinderPropGrip
---@return boolean set
exports["zyke_anglegrinder"]:SetGrindingGrip({offset = {x = 0.1, y = 0.02, z = -0.02}, rotation = {x = 0.0, y = 180.0, z = 90.0}})

#Set Grinder Rest

Lays the held grinder at a spot within 3 metres of the player, seen by every client, while their hands do other work. nil puts it back in the hand.

Example:

lua
---@param coords? vector3
---@param rotation? vector3
---@return boolean set
exports["zyke_anglegrinder"]:SetGrinderRest(coords, vector3(0.0, 0.0, 90.0))

#Get Grinder Disc Edge

Returns the world position of the held disc's front edge, for lining your props up with it.

Example:

lua
---@return vector3? coords
local edge = exports["zyke_anglegrinder"]:GetGrinderDiscEdge()

#Is Grinder Equipped

Returns whether the local player has the grinder out. To follow changes without polling, listen to zyke_anglegrinder:OnGrinderEquipChanged.

Example:

lua
---@return boolean equipped
local equipped = exports["zyke_anglegrinder"]:IsGrinderEquipped()

#Get Grinder Disc State

Returns the disc state of the local player's held grinder, or nil when none is out.

Example:

lua
---@return "empty" | "loaded" | "broken" | nil state
local state = exports["zyke_anglegrinder"]:GetGrinderDiscState()

#Get Grinder Prop

Returns the local handle of the local player's held grinder prop.

Example:

lua
---@return integer? prop
local prop = exports["zyke_anglegrinder"]:GetGrinderProp()

#Is Grinder Interacting

Returns whether the local player is in a grinder interaction. Without a name, any interaction counts. Names include equippingGrinder, unEquippingGrinder, loadingDisc, unloadingDisc, and grinding.

Example:

lua
---@param name? string
---@return boolean interacting
local grinding = exports["zyke_anglegrinder"]:IsGrinderInteracting("grinding")

#Server Sided Exports

CreateGrindSession, ConsumeGrindSession, and WearGrinderDisc are trusted server operations. Do not expose them directly through an unrestricted network event.

#Create Grind Session

Opens a grind session for a player once your own target and permission checks pass. Use it when a cut unlocks something, such as removing a clamp or giving loot: your server decides the difficulty and wear, and only it can read the result. Returns nil when the grinder is not ready; the player is already told why.

Only the resource that opened the session can consume it. durabilityLoss defaults to no wear, so pass your own range. Pass minigame = "custom" when your resource runs its own minigame through the custom grind exports.

Example:

lua
---@param plyId integer
---@param options GrindSessionOptions
---@return string? sessionId
local sessionId = exports["zyke_anglegrinder"]:CreateGrindSession(plyId, {
    stages = { -- Required, one entry per cut
        {checks = {"easy", "medium"}, seconds = 3},
        {checks = false, seconds = 2},
    },
    durabilityLoss = {min = 8, max = 15}, -- Disc wear for the whole grind
    context = {netId = netId}, -- Any value, returned by ConsumeGrindSession
    legal = false, -- true skips witness checks, nil uses witnesses.defaultLegal
    crime = "fenceCutting", -- Optional, label handed to OnIllegalGrind
    witnessDistance = 30.0, -- Optional, overrides witnesses.maxDistance
    targetNetId = netId, -- Optional, a witness's line of sight hitting it still counts as seen
    progress = 0.0, -- Optional, from an earlier ConsumeGrindSession; cut stages are skipped
})

#Consume Grind Session

Reads a session's verified result once. Only the resource that opened the session can consume it. Also returns how far the grind got, from 0 to 1, even when it failed. Pass it as progress to the next CreateGrindSession so a player whose disc broke continues instead of starting over.

Example:

lua
---@param plyId integer
---@param sessionId string
---@return boolean completed
---@return any context
---@return number? progress
local completed, context, progress = exports["zyke_anglegrinder"]:ConsumeGrindSession(plyId, sessionId)

#Get Equipped Grinder

Returns the player's held grinder, or nil when none is out: its slot, item name, grinderId, disc item, durability, battery charge, and disc state.

Example:

lua
---@param plyId integer
---@return EquippedGrinder? grinder
local grinder = exports["zyke_anglegrinder"]:GetEquippedGrinder(plyId)

#Wear Grinder Disc

Wears the fitted disc and drains the battery outside a grind session. Without a range, it uses durabilityLoss, and drainScale multiplies batteryDrain. Returns nil when the grinder has no usable disc or, while batteries are enabled, no charged battery.

Example:

lua
---@param plyId integer
---@param minLoss? number
---@param maxLoss? number
---@param drainScale? number
---@return number? durability
---@return boolean broke
local durability, broke = exports["zyke_anglegrinder"]:WearGrinderDisc(plyId, 2, 5)

#Server Local Events

These events are local server integration notifications. They are not network event entry points and cannot block an action. Listen with AddEventHandler on the server. Default Discord logging for these events lives in server/unlocked/hooks.lua.

#On Grind Start

Fires when the disc starts spinning in a session. owner is the resource that opened it.

Example:

lua
---@param data GrindHookData
AddEventHandler("zyke_anglegrinder:OnGrindStart", function(data)
    print(data.source, data.owner, data.sessionId, data.legal)
end)

#On Grind Complete

Fires when a grind is verified as passed.

Example:

lua
---@param data GrindHookData
AddEventHandler("zyke_anglegrinder:OnGrindComplete", function(data)
    print(data.source, data.owner, data.context)
end)

#On Grind Failed

Fires when a grind fails, is cancelled, or is interrupted. reason is failedOrCancelled, expired, replaced, disconnected, resourceStopped, or consumedBeforeFinish. A session that expires or is replaced before it began also fires this event.

Example:

lua
---@param data GrindHookData
AddEventHandler("zyke_anglegrinder:OnGrindFailed", function(data)
    print(data.source, data.owner, data.reason)
end)

#On Disc Broken

Fires when a fitted disc wears down to zero.

Example:

lua
---@param data GrinderWearHookData
AddEventHandler("zyke_anglegrinder:OnDiscBroken", function(data)
    print(data.source, data.discItem, data.previousDurability)
end)

#On Battery Depleted

Fires when a fitted battery drains to zero.

Example:

lua
---@param data GrinderWearHookData
AddEventHandler("zyke_anglegrinder:OnBatteryDepleted", function(data)
    print(data.source, data.grinderId, data.previousBatteryDurability)
end)

#Illegal Grind Witnessed

Fires once per session when NPCs first witness an illegal grind, right after OnIllegalGrind in server/unlocked/hooks.lua. witnesses lists each witness's network ID, distance, and whether they heard it or saw it from a vehicle.

Example:

lua
---@param data IllegalGrindData
AddEventHandler("zyke_anglegrinder:IllegalGrindWitnessed", function(data)
    print(data.source, data.coords, data.crime, #data.witnesses)
end)

#Client Local Events

#On Grinder Equip Changed

Fires on the local client when the player's own grinder comes out or goes away. equipped is the new state.

Example:

lua
---@param equipped boolean
AddEventHandler("zyke_anglegrinder:OnGrinderEquipChanged", function(equipped)
    print(equipped)
end)

#State Bags

State BagTypeMeaning
zyke_anglegrinder:grindertable or nilSet on a player while their grinder is out: state, grinderId, discItem, durability, hasBattery, and batteryDurability.

For custom permission rules, use Can-Check Hooks.