All resources

rsg-doorlock – Docs (v3.3.0)#

Contents#

  1. Files
  2. How it works
  3. Configuration
  4. Admin editor
  5. Events and callbacks
  6. Commands
  7. Database
  8. Discord webhooks
  9. Security
  10. Server owner how-tos
  11. Troubleshooting

1. Files#

FilePurpose
fxmanifest.luaManifest; locales via @rsg-core/shared/locale.lua; depends on rsg-core, oxmysql
shared/config.luaDistances, cooldown, admin settings, Config.JailDoors
shared/doorhashes.luaBuilt-in list of ~1,750 RedM door hashes (editor picker)
shared/doorhashes_custom.luaYour own MLO / custom door hashes
client/main.luaDoor state, hold prompt, key animation, sync
client/editor.luaAdmin editor: aim-and-pick doors, NUI bridge
server/main.luaAuto database, lock state, toggle validation, admin callbacks
server/seed_doors.luaDoors imported once into an empty table
server/sv_config.luaWebhook URLs (server only)
server/webhooks.luaDiscord logging
server/versionchecker.luaGitHub version check
html/NUI editor (index.html, style.css, app.js)
installation/rsg_doorlocks.sqlManual database install
locales/*.jsonen, cs, de, el, es, fr, it, ja, nl, pl, pt-br, ro, ru

2. How it works#

  • Every lock is a row in rsg_doorlocks with one or more door hashes, text coordinates, allowed jobs, interaction distance and locked state.
  • The server owns the lock state. Clients only send a request (rsg-doorlock:server:requestToggle) and the server checks the player, the door, distance, job (and duty), cooldown and admin bypass before changing anything.
  • The door list goes to each client once. Lock state changes are broadcast to everyone, and players who join late receive the full state.
  • A light 500 ms loop looks for nearby doors. A per-frame loop only runs while the player stands at a door, to show the hold prompt.
  • Locked doors are frozen shut; the player holds ENTER for Config.HoldDuration ms and a key animation plays.
  • On first start with an empty table, server/seed_doors.lua is imported once (Config.ImportConfigDoors).
  • Config.JailDoors lists the Sisika prison front gate hashes, which are locked by default.

3. Configuration#

shared/config.lua:

OptionDefaultMeaning
DefaultDistance1.25Interaction range when a lock has no distance
DistanceTolerance2.0Extra server-side leeway for the distance check
SyncDistance30.0Doors within this range are kept in their synced state
Cooldown1500ms between door uses per player (server enforced)
HoldDuration750ms the player holds ENTER
RequireOnDutyfalseJob doors need the player on duty
AdminPermission'admin'RSG permission needed for the editor
AdminCommand'doorlock'Editor command name
AdminBypasstrueAdmins can open every lock
MaxDoorsPerLock8Doors per lock (2 for double doors)
PickRange2.0Aim tolerance when selecting a door in the editor
AllowCustomDoorstrueAllow MLO / custom doors not in the built-in list
ImportConfigDoorstrueImport seed_doors.lua once into an empty table
DebugfalsePrint MLO door lookups to F8
Lockpick.EnabledtrueLockpickable doors (needs rsg-lockpick)
Lockpick.Key'G'Key name from RSGCore.Shared.Keybinds for the "Pick lock" prompt
Lockpick.HoldDuration750ms the player holds the key
Lockpick.Presets{ 'easy', 'medium', 'hard' }Difficulties offered in the editor; names must exist in rsg-lockpick's Config.Presets
Lockpick.Cooldown5000ms between lockpick requests per player
Lockpick.RelockAfter300Seconds before a picked door locks again (0 = never automatically)
Lockpick.Reputation'theft'rsg-reputation action reported on success; must be listed in rsg-lockpick's Config.Reputation.Actions (nil = none)

server/sv_config.lua holds the webhook URLs. Never add it to shared_scripts.

4. Admin editor#

Open it with /doorlock (needs Config.AdminPermission).

  • Search the lock list by name, job or hash, sorted by nearest.
  • Create, edit and delete locks without restarting the resource.
  • Door picking: aim at a door and press ENTER. The HUD shows the model, hash, selection count and keys, and warns if the door already belongs to another lock. A door can belong to only one lock.
  • Set job tags, interaction range and the default locked/unlocked state.
  • Lockpicking: Off / Easy / Medium / Hard buttons (Config.Lockpick.Presets). Reputation Region: optional rsg-reputation region id (checked against rsg-reputation:GetRegions() when it is running). Both fields are hidden when Config.Lockpick.Enabled = false.
  • Teleport to any lock.
  • MLO doors: add the hashes to shared/doorhashes_custom.lua, or pick the door prop directly (Config.AllowCustomDoors).

5. Events and callbacks#

NameSideNotes
rsg-doorlock:server:getDoorscallbackReturns the door list
rsg-doorlock:server:requestToggleserver net event(doorID); validated and rate-limited
rsg-doorlock:server:admin:checkcallbackEditor permission check
rsg-doorlock:server:admin:savecallbackCreate/update a lock (validated)
rsg-doorlock:server:admin:deletecallbackDelete a lock
rsg-doorlock:server:admin:teleportedserver net eventLogs an admin teleport
rsg-doorlock:client:setStateclient net event(doorID, locked)
rsg-doorlock:client:syncAllclient net eventFull state on join
rsg-doorlock:client:syncDoorclient net eventOne door changed
rsg-doorlock:client:playKeyAnimclient net eventKey animation
rsg-doorlock:client:openEditorclient net eventOpen the editor
rsg-doorlock:client:editorRefreshclient net eventRefresh the list

6. Commands#

CommandWhoWhat
/doorlockConfig.AdminPermissionOpen the door editor (name changes with Config.AdminCommand)

7. Database#

CREATE TABLE IF NOT EXISTS `rsg_doorlocks` (
    `id` INT NOT NULL AUTO_INCREMENT,
    `name` VARCHAR(64) NOT NULL,
    `doors` LONGTEXT NOT NULL,
    `text_coords` LONGTEXT NOT NULL,
    `jobs` LONGTEXT NOT NULL,
    `distance` FLOAT NOT NULL DEFAULT 1.25,
    `locked` TINYINT(1) NOT NULL DEFAULT 1,
    `lockpick` VARCHAR(16) NULL DEFAULT NULL,
    `region` VARCHAR(32) NULL DEFAULT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

lockpick is the difficulty (empty = not pickable) and region the rsg-reputation region. Tables from older versions get the two columns added automatically on start (never destructive). For a manual upgrade run the two ALTER TABLE lines at the top of installation/rsg_doorlocks.sql; without the columns lockpicking stays off. The table is created on start. If your database user lacks CREATE permission, import installation/rsg_doorlocks.sql manually. Lock states survive restarts.

8. Discord webhooks#

Set URLs in server/sv_config.lua (SvConfig.Webhooks). Separate channels, or one default channel, for: door use, denied access, admin actions, security and system. Embeds include character name, citizen ID, job and grade, server ID and Discord mention. Edit logs show a before → after list. Messages are batched and Discord 429 replies are handled. Security alerts (non-admin editor requests, fake doors, using doors from far away) can ping a role.

8b. Lockpicking#

Optional, needs rsg-lockpick (and rsg-reputation for the theft part). Flow:

  1. A lock with a lockpick difficulty, locked, shows the Pick lock prompt to players whose job does not unlock it (the client check is only a convenience).
  2. The client sends rsg-doorlock:server:requestLockpick(doorID). The server checks: ready, door exists, not dead or handcuffed, Config.Lockpick.Cooldown, no attempt already running for the player, the door is locked and has a difficulty, rsg-lockpick is started, distance (distance + DistanceTolerance), and that the player does not already have a key.
  3. The server calls exports['rsg-lockpick']:StartAttempt(src, { preset = lock.lockpick, coords = lock.textCoords, radius = distance + DistanceTolerance, reputation = { action = Config.Lockpick.Reputation, region = lock.region } }, cb). rsg-lockpick validates the minigame result, wears the pick and sends its own lawman alerts; the callback receives success, reason.
  4. On success the door is set unlocked in memory only and broadcast with rsg-doorlock:client:setState; the database keeps the saved state. A relock timer (RelockAfter) locks it again, and a manual toggle, an admin edit or a delete cancels a pending relock. rsg-lockpick reports the theft action to rsg-reputation (honor, plus standing in region when set).
  5. A failed attempt tells the player and is logged; cancelled or expired attempts change nothing. Discord: log type Lockpick (SvConfig.Webhooks.Urls.Lockpick, Log.Lockpick).

9. Security#

  • Server checks player, door, distance, job, duty, permission and all input data.
  • Per-player server cooldown. Clients never decide lock state.
  • Door hashes and coordinates are validated (integers, finite values, map bounds).
  • Admin callbacks are permission-checked and logged.
  • A duplicate door is rejected with the name of the lock that owns it.
  • Lockpicking is decided on the server: the difficulty comes from the saved lock, never from the client, and the result comes from rsg-lockpick's ticket system. The editor only accepts difficulties listed in Config.Lockpick.Presets and region ids that exist in rsg-reputation.

10. How-tos#

  • Add a lock to an MLO house: /doorlock → create → aim at the door → ENTER → set jobs/distance → save. If the door isn't in the hash list, add it to shared/doorhashes_custom.lua.
  • Double door: select both doors in one lock (up to MaxDoorsPerLock).
  • Change the language: setr rsg:locale "de" in server.cfg.

11. Troubleshooting#

ProblemFix
Can't pick a doorCheck AllowCustomDoors; add the hash to doorhashes_custom.lua; turn on Debug
"Door already belongs to another lock"Remove it from the other lock first
No Discord logsCheck URLs in server/sv_config.lua
Table not createdImport installation/rsg_doorlocks.sql
Editor won't openYou need Config.AdminPermission

Support the Project : https://rexshack.tebex.store/

<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-doorlock 3.3.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, oxmysql

Database#

Tables: rsg_doorlocks.

Tables are created automatically on start while Config.AutoDatabase = true (default). Nothing is ever dropped or overwritten. For a manual install set Config.AutoDatabase = false and import installation/rsg_doorlocks.sql once.

-- shared/config.lua
Config.AutoDatabase = true -- false = import the SQL file yourself

Configuration#

OptionDefaultNotes
Config.AutoDatabasetruebuild the database tables automatically on start (set false and import the SQL file for a manual install)
Config.DefaultDistance1.25interaction range when a door has no 'distance' set
Config.DistanceTolerance2.0extra server-side leeway for the proximity check (latency)
Config.SyncDistance30.0doors within this range are kept in their synced state
Config.Cooldown1500ms between door uses per player (server enforced)
Config.HoldDuration750ms the player must hold ENTER to use a door
Config.RequireOnDutyfalsetrue = player must be on duty to use job doors
Config.AdminPermission'admin'RSG permission needed for /doorlock (god, developer, headadmin, admin, mod)
Config.AdminCommand'doorlock'
Config.AdminBypasstrueadmins can open every lock (incl. ones with no jobs)
Config.MaxDoorsPerLock8e.g. 2 for double doors
Config.PickRange2.0how close your aim must be to a door to select it in the editor
Config.Debugfalseprint MLO door lookups to the F8 console
Config.AllowCustomDoorstrueallow picking MLO / custom door objects that aren't in shared/doorhashes.lua
Config.ImportConfigDoorstrueOn first start (empty table) the doors in server/seed_doors.lua are imported once.
Config.JailDoorstable

Callbacks#

CallbackSideArgumentsFile
rsg-doorlock:server:getDoorsserver_, cbserver/main.lua
rsg-doorlock:server:admin:checkserversrc, cbserver/main.lua
rsg-doorlock:server:admin:saveserversrc, cb, dataserver/main.lua
rsg-doorlock:server:admin:deleteserversrc, cb, idserver/main.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-doorlock:server:getDoors', function(result)
    -- use result
end)

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
rsg-doorlock:client:openEditorclient``client/editor.lua
rsg-doorlock:client:playKeyAnimclientdoorIDclient/main.lua
rsg-doorlock:client:setStateclientdoorID, lockedclient/main.lua
rsg-doorlock:client:syncAllclientallclient/main.lua
rsg-doorlock:client:syncDoorclientid, door, oldclient/main.lua
rsg-doorlock:server:requestToggleserverdoorIDserver/main.lua
rsg-doorlock:server:admin:teleportedserveridserver/main.lua
-- from a client script
TriggerServerEvent('rsg-doorlock:server:requestToggle', doorID)
-- from a server script
TriggerClientEvent('rsg-doorlock:client:openEditor', source)

Locales#

Language files in locales/: cs, de, el, en, es, fr, it, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->