Exports & Events
Client and server exports, state bags, and events for angle grinder integrations.
General Information
plyIdis a player's server ID. Durability and charge run from0to100. Progress runs from0to1. A disc state isempty,loaded, orbroken.Stages are a list of
{checks, seconds}.checkslistseasy,medium, orhardskill check presets, orfalsefor none;secondsadds 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.luainsidezyke_anglegrinder.
#Complete Export Index
| Context | Exports |
|---|---|
| Client | StartGrind, RegisterToolAction, RemoveToolAction, RunGrindSession, RegisterBusyCheck, RemoveBusyCheck, BeginCustomGrind, SetCustomGrindContact, SetCustomGrindProp, ReportCustomGrindCut, FinishCustomGrind, SetGrindingGrip, SetGrinderRest, GetGrinderDiscEdge, IsGrinderEquipped, GetGrinderDiscState, GetGrinderProp, IsGrinderInteracting |
| Server | CreateGrindSession, ConsumeGrindSession, GetEquippedGrinder, WearGrinderDisc |
#Client Sided Exports
#Start Grind
Runs a whole grind and returns whether it completed. Every option can be left out; without
entityorcoords, 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
ConsumeGrindSessioncannot 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 withCreateGrindSessioninstead.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
cinematictable takescamera,look,fov,blendInMs, andblendOutMs; values left out fall back togrinding.cinematic. Withgrinding.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 withinrangeas a point. Aiming at a point within reach shows the use key on it, and the press callsonUsewith the point'sdata. Registering again under the same name replaces the action. Register again whenzyke_anglegrinderrestarts, as it forgets every action.Points take
entitywith an optional entity-localoffset, or worldcoords, plus an optionalreach(2.0 metres by default), promptlabel, anddata.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'sonUse. The return value only drives your client flow; read the verified result on the server withConsumeGrindSession.targettakes the same placement,label,approach,crouch,isValid, andcinematicoptions asStartGrind.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()returnstrue, 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, ornilwhen the session cannot begin. Each stage carries acutwith its length (ms),graceMs,maxMs,penalty,difficulty, rolledwear, andstartfor 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.
intensityis1for a clean cut, andnilstops the sparks.levelis1for an idle or skating disc,2for a clean cut, and3for 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.
nilgoes 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.
progressis how far through the cut the disc got, anddrainis the disc drain in clean-cut lengths,1for 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.
boneis57005for the right hand or18905for the left, and defaults toprop.bone.nilgoes back togrinding.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.
nilputs 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
nilwhen 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, andgrinding.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
nilwhen the grinder is not ready; the player is already told why.Only the resource that opened the session can consume it.
durabilityLossdefaults to no wear, so pass your own range. Passminigame = "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
0to1, even when it failed. Pass it asprogressto the nextCreateGrindSessionso 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
nilwhen 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, anddrainScalemultipliesbatteryDrain. Returnsnilwhen 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.
owneris 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.
reasonisfailedOrCancelled,expired,replaced,disconnected,resourceStopped, orconsumedBeforeFinish. 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
OnIllegalGrindinserver/unlocked/hooks.lua.witnesseslists 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.
equippedis the new state.Example:
lua---@param equipped boolean AddEventHandler("zyke_anglegrinder:OnGrinderEquipChanged", function(equipped) print(equipped) end)
#State Bags
| State Bag | Type | Meaning |
|---|---|---|
zyke_anglegrinder:grinder | table or nil | Set on a player while their grinder is out: state, grinderId, discItem, durability, hasBattery, and batteryDurability. |
For custom permission rules, use Can-Check Hooks.