Documentation

Integrations

Resources that use the grinder, and how to add your own.

The grinder does not cut anything by itself. Each resource that uses it offers its own targets as dots, decides whether a grind is legal, and sets each cut's difficulty and disc wear. The grinder handles the walk-in, minigame, animation, camera, sparks, sound, disc wear, battery drain, and witness checks.

#Supported Resources

ResourceWhat it cuts
Wheel ClampWheel clamps on clamped vehicles.
Towing (Beta)Tow ropes and winch cables, at every reachable end of the line.
Catalytic ConvertersConverters and their guards on parked cars, through its own pipe cut minigame.

Each of these needs the grinder with a disc and a charged battery. Their own docs cover what can be cut and the settings they pass to the grinder.

Shredder includes default recipes that shred angle grinder tools.

Start the grinder before the resources that use it.

#Adding Your Own

Any resource can make things cuttable through the client and server exports.

  • For a quick grind whose result only matters on the client, call StartGrind from the client. /grindexample runs it; its code is in client/unlocked/examples.lua.
  • When a cut unlocks something, such as removing a clamp or giving loot, open the session on your server with CreateGrindSession and read the result with ConsumeGrindSession. Offer your targets as dots with RegisterToolAction, and run the grind with RunGrindSession.
  • To run your own minigame while the grinder handles wear, sound, sparks, and witnesses, open the session with minigame = "custom" and use the custom grind exports.

#Server-Verified Example

The client offers the targets as dots and runs the grind. The server opens the session and reads the result, so a modified client cannot skip the cut. Register the action again when zyke_anglegrinder restarts.

lua
-- Client
local function registerGrinderAction()
    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),
                    data = {netId = NetworkGetNetworkIdFromEntity(fence)},
                }
            end

            return points
        end,
        onUse = function(data)
            local sessionId = Z.callback.await("my_resource:StartCut", data.netId)
            if (not sessionId) then return end

            local fence = NetworkGetEntityFromNetworkId(data.netId)
            exports["zyke_anglegrinder"]:RunGrindSession(sessionId, {
                entity = fence,
                offset = vector3(0.0, 0.0, 1.0),
                isValid = function() return DoesEntityExist(fence) end,
            })

            local cut = Z.callback.await("my_resource:FinishCut", sessionId)
            if (cut) then Z.notify("fenceCut") end
        end,
    })
end

AddEventHandler("onClientResourceStart", function(resource)
    if (resource == "zyke_anglegrinder") then registerGrinderAction() end
end)

CreateThread(function()
    if (GetResourceState("zyke_anglegrinder") == "started") then registerGrinderAction() end
end)
lua
-- Server
Z.callback.register("my_resource:StartCut", function(plyId, netId)
    if (not canCutFence(plyId, netId)) then return nil end

    return exports["zyke_anglegrinder"]:CreateGrindSession(plyId, {
        stages = {{checks = {"easy", "medium"}, seconds = 3}},
        durabilityLoss = {min = 8, max = 15},
        context = {netId = netId},
        legal = false,
        crime = "fenceCutting",
        targetNetId = netId,
    })
end)

Z.callback.register("my_resource:FinishCut", function(plyId, sessionId)
    local completed, context = exports["zyke_anglegrinder"]:ConsumeGrindSession(plyId, sessionId)
    if (not completed or not canCutFence(plyId, context.netId)) then return false end

    cutFence(context.netId)

    return true
end)

To let a player continue a failed cut, store the progress that ConsumeGrindSession returns and pass it to the next CreateGrindSession.

#Camera

A target can frame its own close-up by passing a table as cinematic. Values left out fall back to grinding.cinematic, and cinematic = false keeps the gameplay camera. With grinding.cinematic.enabled = false, no grind gets a cinematic camera.

lua
cinematic = {
    camera = {x = 1.1, y = 0.35, z = 0.55},
    look = {x = 0.0, y = -0.25, z = 0.1},
    fov = 40.0,
    blendInMs = 600,
    blendOutMs = 600,
},

See Exports & Events for every export.