Documentation

Exports & Events

All exports, hooks, and events available to integrate Safe Crack into other resources.

General Information

safeId is any string your resource keeps stable for one safe, such as "store:12". tier is a key in Config.Tiers. Results are "opened", "relocked", or "cancelled".

Refusal reasons are locale keys of Safe Crack: "safeRelocked", "safeInUse", or "stethoscopeMissing". Their texts are in locales/en.lua.

For the full flow, see Integrating With Other Resources.

Types / Classes

The hook and event data classes are annotated in server/hooks.lua inside zyke_safecrack.

#Complete Export Index

ContextExports
ServerPrepareSafeCrack, ConsumeSafeResult, GetSafeCrackRefusal, IsSafeRelocked, ResetSafe, GetSafeCombination
ClientStartSafeCrack, CancelSafeCrack

#Server Sided Exports

Server exports are trusted operations. ResetSafe clears a relocker and GetSafeCombination reveals a combination. Validate your own caller before using them, and don't expose them through an unrestricted network event.

#Prepare Safe Crack

Makes the player's next StartSafeCrack within 30 seconds open this safe. Call it when the player starts on the safe. Preparing cancels any attempt the player already had.

With coords, the player has to be within reach of that point when the dial opens and on every handle pull. Moving out of reach during a pull ends the attempt as cancelled.

Returns false and a refusal reason when the safe is relocked, another player has an attempt on it, or the tier requires a stethoscope the player does not carry. An unknown tier returns false without a reason and prints a warning to the server console.

Example:

lua
---@param plyId integer
---@param safeId string
---@param options {tier: string, coords?: vector3, reach?: number} @ reach defaults to 3.0
---@return boolean prepared
---@return string? reason @ "safeRelocked", "safeInUse" or "stethoscopeMissing"
local prepared, reason = exports["zyke_safecrack"]:PrepareSafeCrack(plyId, "store:12", {tier = "store", coords = vector3(x, y, z)})

#Consume Safe Result

Returns the server-checked result and the safeId of the player's last attempt. It returns them once, within 30 seconds of the attempt ending; after that, or on a second call, it returns nil. Only open the safe on "opened".

Example:

lua
---@param plyId integer
---@return string? result @ "opened", "relocked" or "cancelled"
---@return string? safeId
local result, safeId = exports["zyke_safecrack"]:ConsumeSafeResult(plyId)
if (result ~= "opened") then return end

#Get Safe Crack Refusal

Returns why the player could not start on the safe now, or nil when they could. It prepares nothing and holds nothing, so use it before the player walks up to the safe, for example to hide an interaction.

Example:

lua
---@param plyId integer
---@param safeId string
---@param tierName string
---@return string? reason @ "safeRelocked", "safeInUse" or "stethoscopeMissing"
local reason = exports["zyke_safecrack"]:GetSafeCrackRefusal(plyId, "store:12", "store")

#Is Safe Relocked

Returns whether the safe's relocker has fired and still holds.

Example:

lua
---@param safeId string
---@return boolean relocked
local relocked = exports["zyke_safecrack"]:IsSafeRelocked("store:12")

#Reset Safe

Clears the safe's combination, wrong pulls, and relocker. The next attempt on it gets a new combination. Use it to reset a safe with relockDuration = false, or when your resource restocks a safe.

Example:

lua
---@param safeId string
exports["zyke_safecrack"]:ResetSafe("store:12")

#Get Safe Combination

Returns the combination the safe opens with, as entries in the order they are entered, and the gate window. A safe nobody tried yet gets its combination rolled now, and the next attempt on it uses the same one. Returns nil for an unknown tier.

Pass the tier the safe is prepared with. A different tier gives the safe a new combination.

Example:

lua
---@param safeId string
---@param tierName string
---@return {number: integer, direction: "right" | "left"}[]? entries
---@return integer? window @ Numbers either side of each that still count
local entries, window = exports["zyke_safecrack"]:GetSafeCombination("store:12", "store")

#Client Sided Exports

#Start Safe Crack

Opens the dial for the attempt the server prepared, and returns once the close-up has closed. Call it from a thread that can wait. It returns nil straight away when nothing was prepared, the 30 second window passed, the player is out of reach of the prepared coords, or a dial is already open.

The returned result is for your client only. Check the result on the server with ConsumeSafeResult before opening anything.

All options are optional:

  • dial: a dial prop, such as v_ilev_gangsafedial, that turns with the player's input and is put back afterwards. It has to be a free prop, not attached to another entity.
  • coords: the centre of the dial for the camera. Defaults to the dial prop's position.
  • normal: points out of the dial's face toward the player. 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.

Example:

lua
---@param options? {dial?: integer, coords?: vector3, normal?: vector3}
---@return string? result @ "opened" or "relocked"; nil when cancelled or nothing was prepared
local result = exports["zyke_safecrack"]:StartSafeCrack({dial = dialEntity, coords = dialCoords, normal = dialNormal})

#Cancel Safe Crack

Closes an attempt started by the calling resource. Returns false when no dial is open or another resource started it. If the resource that started an attempt stops, the attempt is cancelled as well.

Example:

lua
---@return boolean cancelled
local cancelled = exports["zyke_safecrack"]:CancelSafeCrack()

#Server Hooks

The hooks in server/hooks.lua run when an attempt starts and finishes, for logs or your own scripts. The file is unencrypted and safe to edit. Both hooks are empty by default and are notifications only; they cannot block an attempt.

#On Safe Crack Started

Runs once the dial opens on the player's screen. hasStethoscope is whether the player carried the stethoscope when the attempt was prepared.

Example:

lua
---@param data {source: integer, safeId: string, tier: string, hasStethoscope: boolean}
function OnSafeCrackStarted(data)
end

#On Safe Crack Finished

Runs when an attempt ends. result is "opened", "relocked", or "cancelled". wrongPulls counts the wrong pulls in this attempt only. durationMs is the time since the dial opened, or 0 for an attempt that was prepared but never opened.

Example:

lua
---@param data {source: integer, safeId: string, tier: string, result: string, wrongPulls: integer, durationMs: integer}
function OnSafeCrackFinished(data)
end

#Server Local Events

These events are local server notifications with the same data as the matching hook. They are not network event entry points. Listen with AddEventHandler on the server instead of editing server/hooks.lua.

Practice dials from /safecracktest fire them too, with a safeId of practice: followed by the player's server ID. A player who disconnects during an attempt does not fire OnSafeCrackFinished.

#On Safe Crack Started

Fires once the dial opens on the player's screen.

Example:

lua
AddEventHandler("zyke_safecrack:OnSafeCrackStarted", function(data)
    print(data.source, data.safeId, data.tier, data.hasStethoscope)
end)

#On Safe Crack Finished

Fires when an attempt ends as opened, relocked, or cancelled.

Example:

lua
AddEventHandler("zyke_safecrack:OnSafeCrackFinished", function(data)
    print(data.source, data.safeId, data.tier, data.result, data.wrongPulls, data.durationMs)
end)