rsg-doorlock – Docs (v3.3.0)#
Contents#
- Files
- How it works
- Configuration
- Admin editor
- Events and callbacks
- Commands
- Database
- Discord webhooks
- Security
- Server owner how-tos
- Troubleshooting
1. Files#
| File | Purpose |
|---|---|
fxmanifest.lua | Manifest; locales via @rsg-core/shared/locale.lua; depends on rsg-core, oxmysql |
shared/config.lua | Distances, cooldown, admin settings, Config.JailDoors |
shared/doorhashes.lua | Built-in list of ~1,750 RedM door hashes (editor picker) |
shared/doorhashes_custom.lua | Your own MLO / custom door hashes |
client/main.lua | Door state, hold prompt, key animation, sync |
client/editor.lua | Admin editor: aim-and-pick doors, NUI bridge |
server/main.lua | Auto database, lock state, toggle validation, admin callbacks |
server/seed_doors.lua | Doors imported once into an empty table |
server/sv_config.lua | Webhook URLs (server only) |
server/webhooks.lua | Discord logging |
server/versionchecker.lua | GitHub version check |
html/ | NUI editor (index.html, style.css, app.js) |
installation/rsg_doorlocks.sql | Manual database install |
locales/*.json | en, cs, de, el, es, fr, it, ja, nl, pl, pt-br, ro, ru |
2. How it works#
- Every lock is a row in
rsg_doorlockswith 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.HoldDurationms and a key animation plays. - On first start with an empty table,
server/seed_doors.luais imported once (Config.ImportConfigDoors). Config.JailDoorslists the Sisika prison front gate hashes, which are locked by default.
3. Configuration#
shared/config.lua:
| Option | Default | Meaning |
|---|---|---|
DefaultDistance | 1.25 | Interaction range when a lock has no distance |
DistanceTolerance | 2.0 | Extra server-side leeway for the distance check |
SyncDistance | 30.0 | Doors within this range are kept in their synced state |
Cooldown | 1500 | ms between door uses per player (server enforced) |
HoldDuration | 750 | ms the player holds ENTER |
RequireOnDuty | false | Job doors need the player on duty |
AdminPermission | 'admin' | RSG permission needed for the editor |
AdminCommand | 'doorlock' | Editor command name |
AdminBypass | true | Admins can open every lock |
MaxDoorsPerLock | 8 | Doors per lock (2 for double doors) |
PickRange | 2.0 | Aim tolerance when selecting a door in the editor |
AllowCustomDoors | true | Allow MLO / custom doors not in the built-in list |
ImportConfigDoors | true | Import seed_doors.lua once into an empty table |
Debug | false | Print MLO door lookups to F8 |
Lockpick.Enabled | true | Lockpickable doors (needs rsg-lockpick) |
Lockpick.Key | 'G' | Key name from RSGCore.Shared.Keybinds for the "Pick lock" prompt |
Lockpick.HoldDuration | 750 | ms 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.Cooldown | 5000 | ms between lockpick requests per player |
Lockpick.RelockAfter | 300 | Seconds 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 againstrsg-reputation:GetRegions()when it is running). Both fields are hidden whenConfig.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#
| Name | Side | Notes |
|---|---|---|
rsg-doorlock:server:getDoors | callback | Returns the door list |
rsg-doorlock:server:requestToggle | server net event | (doorID); validated and rate-limited |
rsg-doorlock:server:admin:check | callback | Editor permission check |
rsg-doorlock:server:admin:save | callback | Create/update a lock (validated) |
rsg-doorlock:server:admin:delete | callback | Delete a lock |
rsg-doorlock:server:admin:teleported | server net event | Logs an admin teleport |
rsg-doorlock:client:setState | client net event | (doorID, locked) |
rsg-doorlock:client:syncAll | client net event | Full state on join |
rsg-doorlock:client:syncDoor | client net event | One door changed |
rsg-doorlock:client:playKeyAnim | client net event | Key animation |
rsg-doorlock:client:openEditor | client net event | Open the editor |
rsg-doorlock:client:editorRefresh | client net event | Refresh the list |
6. Commands#
| Command | Who | What |
|---|---|---|
/doorlock | Config.AdminPermission | Open 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:
- A lock with a
lockpickdifficulty, locked, shows the Pick lock prompt to players whose job does not unlock it (the client check is only a convenience). - 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. - 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 receivessuccess, reason. - 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 thetheftaction to rsg-reputation (honor, plus standing inregionwhen set). - 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.Presetsand 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 toshared/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#
| Problem | Fix |
|---|---|
| Can't pick a door | Check 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 logs | Check URLs in server/sv_config.lua |
| Table not created | Import installation/rsg_doorlocks.sql |
| Editor won't open | You 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#
| Option | Default | Notes |
|---|---|---|
Config.AutoDatabase | true | build the database tables automatically on start (set false and import the SQL file for a manual install) |
Config.DefaultDistance | 1.25 | interaction range when a door has no 'distance' set |
Config.DistanceTolerance | 2.0 | extra server-side leeway for the proximity check (latency) |
Config.SyncDistance | 30.0 | doors within this range are kept in their synced state |
Config.Cooldown | 1500 | ms between door uses per player (server enforced) |
Config.HoldDuration | 750 | ms the player must hold ENTER to use a door |
Config.RequireOnDuty | false | true = 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.AdminBypass | true | admins can open every lock (incl. ones with no jobs) |
Config.MaxDoorsPerLock | 8 | e.g. 2 for double doors |
Config.PickRange | 2.0 | how close your aim must be to a door to select it in the editor |
Config.Debug | false | print MLO door lookups to the F8 console |
Config.AllowCustomDoors | true | allow picking MLO / custom door objects that aren't in shared/doorhashes.lua |
Config.ImportConfigDoors | true | On first start (empty table) the doors in server/seed_doors.lua are imported once. |
Config.JailDoors | table |
Callbacks#
| Callback | Side | Arguments | File |
|---|---|---|---|
rsg-doorlock:server:getDoors | server | _, cb | server/main.lua |
rsg-doorlock:server:admin:check | server | src, cb | server/main.lua |
rsg-doorlock:server:admin:save | server | src, cb, data | server/main.lua |
rsg-doorlock:server:admin:delete | server | src, cb, id | server/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.
| Event | Side | Arguments | File |
|---|---|---|---|
rsg-doorlock:client:openEditor | client | `` | client/editor.lua |
rsg-doorlock:client:playKeyAnim | client | doorID | client/main.lua |
rsg-doorlock:client:setState | client | doorID, locked | client/main.lua |
rsg-doorlock:client:syncAll | client | all | client/main.lua |
rsg-doorlock:client:syncDoor | client | id, door, old | client/main.lua |
rsg-doorlock:server:requestToggle | server | doorID | server/main.lua |
rsg-doorlock:server:admin:teleported | server | id | server/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".