Exports & Events
All exports, hooks, and events available to integrate Safe Crack into other resources.
General Information
safeIdis any string your resource keeps stable for one safe, such as"store:12".tieris a key inConfig.Tiers. Results are"opened","relocked", or"cancelled".Refusal reasons are locale keys of Safe Crack:
"safeRelocked","safeInUse", or"stethoscopeMissing". Their texts are inlocales/en.lua.For the full flow, see Integrating With Other Resources.
Types / Classes
The hook and event data classes are annotated in
server/hooks.luainsidezyke_safecrack.
#Complete Export Index
| Context | Exports |
|---|---|
| Server | PrepareSafeCrack, ConsumeSafeResult, GetSafeCrackRefusal, IsSafeRelocked, ResetSafe, GetSafeCombination |
| Client | StartSafeCrack, 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
StartSafeCrackwithin 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 withinreachof that point when the dial opens and on every handle pull. Moving out of reach during a pull ends the attempt as cancelled.Returns
falseand 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 returnsfalsewithout 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
safeIdof the player's last attempt. It returns them once, within 30 seconds of the attempt ending; after that, or on a second call, it returnsnil. 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
nilwhen 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
nilfor 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
nilstraight away when nothing was prepared, the 30 second window passed, the player is out of reach of the preparedcoords, or a dial is already open.The returned result is for your client only. Check the result on the server with
ConsumeSafeResultbefore opening anything.All options are optional:
dial: a dial prop, such asv_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
coordsandnormal. 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
falsewhen 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.
hasStethoscopeis 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.
resultis"opened","relocked", or"cancelled".wrongPullscounts the wrong pulls in this attempt only.durationMsis the time since the dial opened, or0for 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:
luaAddEventHandler("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:
luaAddEventHandler("zyke_safecrack:OnSafeCrackFinished", function(data) print(data.source, data.safeId, data.tier, data.result, data.wrongPulls, data.durationMs) end)