All resources

rsg-trapdoors – Developer & Server Owner Docs#

Version 2.1.0. For installation and player usage see README.md.

Contents#

  1. Architecture
  2. Data & state
  3. Callbacks and events
  4. Exports
  5. Security model
  6. Database schema
  7. How-tos
  8. Troubleshooting

1. Architecture#

FileSideRole
shared/config.luasharedTimings, passcode rules, Config.Trapdoors
server/sv_config.luaserverWebhooks (WebhookConfig) and DatabaseConfig.AutoInstall
server/database.luaserverTrapdoorDB.Install() – numbered migrations tracked in rsg_trapdoors_schema
server/server.luaserverDoor state, passcodes, validation, lockouts, admin command
server/logs.luaserverBatched Discord logger (TrapdoorLog, export Log)
server/versionchecker.luaserverGitHub version check
client/client.luaclientFinds the map props, animates them, rsg-target options, keypad bridge
html/*NUIKeypad (modes unlock, set, change, remove)

The script moves existing map props – it never spawns them.

2. Data & state#

GlobalState keyValueMeaning
trapdoor:<id>boolDoor open
trapdoorCode:<id>citizenid or falseOwner of the passcode (codes themselves never leave the server)

Server memory: codes[id] = { code, owner }, failures[license][id] = { count, lockUntil }. All doors start closed on resource start. Open doors auto-close after Config.AutoCloseTime.

3. Callbacks and events#

All callbacks are rsg-core callbacks (RSGCore.Functions.CreateCallback) and return ok, message.

NameTypeArgsNotes
rsg-trapdoors:server:opencallbackid, code?Code required only when the door is locked
rsg-trapdoors:server:setCodecallbackid, newCodeFails if a code exists or codes are disabled
rsg-trapdoors:server:changeCodecallbackid, current, newCodeOwner only
rsg-trapdoors:server:removeCodecallbackid, currentOwner only
rsg-trapdoors:server:closenet eventidNever needs a code

NUI callbacks: close, submit ({ mode, code?, newCode? }).

Command: /<Config.AdminResetCommand> <id> (rsg-core admin, also console).

4. Exports#

-- server: write to the trapdoor Discord logger
exports['rsg-trapdoors']:Log(event, source, { door = id, description = 'text', fields = { { name = 'x', value = 'y', inline = true } } })

event must be a key of WebhookConfig.Events.

5. Security model#

Every client request goes through validate() on the server:

  1. Door id must exist in Config.Trapdoors (otherwise logged as suspicious).
  2. RSG player must be loaded and the database ready.
  3. Per-player cooldown Config.PlayerCooldown.
  4. Server-side distance: interactDistance + 3.0 from closedPosition (else suspicious).
  5. Passcode: 4 digits, owner check by citizenid, lockout after Config.MaxCodeAttempts per licence (character swapping does not reset it).

The script handles no money or items. Codes are stored in plain text in SQL – restrict DB access accordingly.

6. Database schema#

CREATE TABLE IF NOT EXISTS `rsg_trapdoors` (
    `door_id`    VARCHAR(64) NOT NULL,
    `passcode`   CHAR(4)     NOT NULL,
    `owner`      VARCHAR(50) NOT NULL,
    `updated_at` TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`door_id`)
);

Built automatically when DatabaseConfig.AutoInstall = true (default). Set it to false and import rsg_trapdoors.sql to install manually. New schema changes go in as a new numbered migration in server/database.lua and in rsg_trapdoors.sql.

7. How-tos#

  • Add a door: add an entry to Config.Trapdoors (see README) and its label key to all 11 locale files.
  • Public door that nobody can lock: set allowCode = false on that door.
  • Admin-only passcodes: Config.AllowPlayerCodes = false.
  • Clear a squatted door: /resettrapdoorcode <id>.

8. Troubleshooting#

ProblemFix
No target optionsStart rsg-target first; prop must be within 3 m of closedPosition.
Keypad does nothingCheck the server console for database install failed; requests are ignored until the DB is ready.
Text shows keysLocale file for rsg:locale is missing keys – compare with en.json.
"Set Passcode" missingConfig.AllowPlayerCodes is false or the door has allowCode = false.

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-trapdoors 3.0.0. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, oxmysql, rsg-target

Database#

Tables: rsg_trapdoors, rsg_trapdoors_schema.

For a manual install set Config.AutoDatabase = false and import rsg_trapdoors.sql once.

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

Configuration#

OptionDefaultNotes
Config.MoveDuration2000ms the open/close animation takes
Config.AutoCloseTime30000ms before an open trapdoor closes itself (0 = never)
Config.PlayerCooldown1000ms between toggle requests per player
Config.StreamDistance100.0distance at which clients look for / sync the prop
Config.AllowPlayerCodestruefalse = only admins can manage passcodes (stops players locking public doors). Per door: allowCode = false
Config.MaxCodeAttempts3wrong guesses before a player is locked out of that door
Config.CodeLockoutTime60000ms lockout after too many wrong guesses
Config.AdminResetCommand'resettrapdoorcode'/resettrapdoorcode <door id> (group.admin)
Config.Trapdoorstablerotations are pitch/roll/yaw in degrees (rotation order 2)

Exports#

Server

ExportArgumentsFile
Log``server/logs.lua
-- example
local result = exports['rsg-trapdoors']:Log()

Callbacks#

CallbackSideArgumentsFile
rsg-trapdoors:server:openserversrc, cb, id, codeserver/server.lua
rsg-trapdoors:server:setCodeserversrc, cb, id, newCodeserver/server.lua
rsg-trapdoors:server:changeCodeserversrc, cb, id, current, newCodeserver/server.lua
rsg-trapdoors:server:removeCodeserversrc, cb, id, currentserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('rsg-trapdoors:server:open', function(result)
    -- use result
end, id, code)

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-trapdoors:server:closeserveridserver/server.lua
-- from a client script
TriggerServerEvent('rsg-trapdoors:server:close', id)

Locales#

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

<!-- END AUTO-REFERENCE -->