Documentation

Integrating With Other Resources

Start the minigame on your own safes and act on the server-checked result.

A resource that owns a safe, such as a robbery script, runs an attempt in three steps. The server prepares the attempt, the client opens the dial, and the server reads the checked result before opening anything.

#Prepare on the Server

Call PrepareSafeCrack(plyId, safeId, options) when the player starts on the safe. safeId is any string your resource keeps stable for one safe. Pass a tier from Config.Tiers, and the dial's coords so the server can check the player stays within reach, 3.0 metres by default.

It returns true, or false and a refusal reason: "safeRelocked", "safeInUse", or "stethoscopeMissing". The preparation lasts 30 seconds.

#Start on the Client

Call StartSafeCrack(options) from a thread. It opens the close-up, runs the minigame, and returns once the dial has closed. Pass the dial prop, or the dial's coords and normal, so the camera looks at the dial.

#Read the Result on the Server

Call ConsumeSafeResult(plyId) and only open the safe on "opened". The result can be read once, within 30 seconds of the attempt ending.

#Example

lua
-- Server
Z.callback.register("my_resource:StartSafe", function(plyId, safeId)
    return exports["zyke_safecrack"]:PrepareSafeCrack(plyId, safeId, {tier = "store", coords = safeCoords})
end)

Z.callback.register("my_resource:FinishSafe", function(plyId)
    local result, safeId = exports["zyke_safecrack"]:ConsumeSafeResult(plyId)
    if (result ~= "opened") then return false end

    -- Open the safe

    return true
end)

-- Client
local prepared = Z.callback.request("my_resource:StartSafe", nil, safeId)
if (prepared) then
    exports["zyke_safecrack"]:StartSafeCrack({dial = dialEntity, coords = dialCoords, normal = dialNormal})

    Z.callback.request("my_resource:FinishSafe")
end

Look up the safe's tier and coordinates on the server from your own data, not from values the client sends.

#Dial Prop & Camera

  • dial is a prop such as v_ilev_gangsafedial. It turns with the player's input and is put back afterwards. It has to be a free prop, not attached to another entity.
  • coords is the centre of the dial for the camera. It defaults to the dial prop's position.
  • normal points out of the dial's face toward the player. It defaults to the dial prop's back.

Without a dial prop, pass both coords and normal. Otherwise the camera looks at a point in front of the player.

#Before the Player Walks Up

GetSafeCrackRefusal(plyId, safeId, tierName) returns the same refusal reasons as PrepareSafeCrack, without preparing or holding anything. Use it to hide or disable your interaction. IsSafeRelocked(safeId) only checks the relocker.

#Resetting a Safe

An opened safe gets a new combination by itself. Call ResetSafe(safeId) to clear a relocked safe, for example when your resource restocks it, or when relockDuration = false.

#Server Checks

The client learns where the gates are so it can play the clicks, so the server only accepts an open that took at least 0.9 seconds per wheel. A quicker open ends as "cancelled" and prints a warning to the server console. A pull while the player is out of reach of coords also ends the attempt as "cancelled".

Use StartSafeCrack's return value only for client feedback. Open the safe only on the result of ConsumeSafeResult.

#Cancelling

CancelSafeCrack() closes an attempt started by the calling resource. If your resource stops during an attempt, the attempt is cancelled.

For the full list of exports, hooks, and events, see Exports & Events.