## Components in this reference | plsr.X | Side | Covers | |---|---|---| | `Doors` | both | lock/unlock, forced-open, disable, elevator locks, door CRUD (server) / restriction checks, current-look target (client) | # plsr.Doors (server) All methods accept either the numeric `id` row or the string `identifier` for `doorId` — string values are resolved through `DOORS_IDS` first. ### SetLock(doorId, newState?) Sets (or toggles, if `newState` is omitted) a door's locked state. Since a double door is one row with two leaves, this only ever needs one `doorId` to lock/unlock both. Clears `forcedOpen` if it was set. | Param | Type | Description | |---|---|---| | `doorId` | `number \| string` | | | `newState` | `boolean?` | omit to toggle | **Returns:** `boolean` new locked state, or `nil` if the door doesn't exist ```lua plsr.Doors:SetLock("lombank_front_gate", false) -- explicit unlock plsr.Doors:SetLock("lombank_front_gate") -- toggle ``` Broadcasts `Doors:Client:UpdateState` to every client, but only if the state actually changed — calling `SetLock(id, false)` on an already-unlocked door is a no-op network-wise, still returns `false`. ### IsLocked(doorId) **Returns:** `boolean` ```lua if plsr.Doors:IsLocked("lombank_front_gate") then end ``` ### SetForcedOpen(doorId) Forces a door open (used by heist/robbery stages) — sets `forcedOpen` in the in-memory cache and broadcasts `Doors:Client:SetForcedOpen`. Clients snap the door open and clear it back to a normal locked/unlocked state next time `SetLock` changes anything. **Returns:** nothing ```lua plsr.Doors:SetForcedOpen("lombank_upper_vault_gate") ``` ### DisableDoor(doorId, seconds) Temporarily disables interaction with a door (shows "This Door is Disabled" instead of the lock prompt, and the `Doors:ToggleLocks` callback refuses to act on it) for `seconds` from now. **Returns:** nothing ```lua plsr.Doors:DisableDoor("lombank_lower_vault", 300) -- disable for 5 minutes ``` ### SetElevatorLock(elevatorId, floorId, newState?) Same toggle/set pattern as `SetLock`, but for one floor of one elevator (`_elevatorConfig` index + floor key). Broadcasts `Doors:Client:UpdateElevatorState`. **Returns:** `boolean` new locked state, or `nil` if the elevator/floor doesn't exist ```lua plsr.Doors:SetElevatorLock(1, 13, true) -- lock floor 13 of elevator #1 ``` ### GetAllDoors() / GetDoor(doorId) Read the in-memory `_doorConfig` cache (rebuilt from the DB on every boot and after any CRUD change). `GetAllDoors` returns every row as a flat array; `GetDoor` returns one. **Returns:** `table[]` / `table | nil` ```lua local allDoors = plsr.Doors:GetAllDoors() local door = plsr.Doors:GetDoor("lombank_front_gate") ``` ### CreateDoor(doorData) Inserts a new row and refreshes every connected client. `doorData.doors` (at least one `{ model, coords }` leaf) is required — anything else missing just no-ops. | Param | Type | Description | |---|---|---| | `doorData` | `table` | `{ identifier?, type?, category?, label?, doors, locked?, autoRate?, autoDist?, holdOpen?, special?, maxDist?, canLockpick?, restricted?, garageZone? }` — see [Door data shape](#door-data-shape) | **Returns:** `number` new row id, or `false` ```lua local newId = plsr.Doors:CreateDoor({ identifier = "my_new_door", label = "My New Door", doors = { { model = -222270721, coords = { x = 17.99, y = -919.95, z = 30.05 } } }, locked = true, }) ``` ### EditDoor(doorId, doorData) Merges `doorData` onto the existing row (only touches fields you actually pass — `nil` means "leave alone", including for booleans, since a real `false` has to survive the merge). Refreshes every client on success. **Returns:** `boolean` ```lua plsr.Doors:EditDoor("my_new_door", { canLockpick = true, maxDist = 3.0 }) ``` ### RemoveDoor(doorId) Deletes the row and refreshes every client. **Returns:** `boolean` ```lua plsr.Doors:RemoveDoor("my_new_door") ``` ### RefreshAllClients() Re-runs `LoadDoorsFromDatabase` then fires `Doors:Client:Resync` at everyone (full drop + rebuild of every registered door on the native door system). Called automatically by `CreateDoor`/`EditDoor`/`RemoveDoor` — not something you'd normally call directly. **Returns:** nothing ```lua plsr.Doors:RefreshAllClients() ``` `pulsar_admin`'s Doors page (`Admin:GetDoorsCatalog`/`CreateDoor`/`EditDoor`/`RemoveDoor` callbacks) is a thin passthrough to these four methods, staff-gated. The in-world door picker used to capture new door coordinates lives in `pulsar_admin/client/doorpicker.lua`, not here. # plsr.Doors (client) ### IsLocked(doorId) Reads the client-side `DOORS_STATE` mirror. **Returns:** `boolean` ```lua if plsr.Doors:IsLocked("lombank_front_gate") then end ``` ### CheckRestriction(doorId) Checks whether the local player currently has legitimate access to a door (used both by the garage keyfob action and, cached per-door via `CheckDoorAuth`, for what the proximity prompt shows). Any player on the `dgang` job always passes. **Returns:** `boolean` ```lua if plsr.Doors:CheckRestriction(doorId) then plsr.Callbacks:ServerCallback("Doors:ToggleLocks", doorId, function(success, newState) end) end ``` ### GetCurrentDoor() **Returns:** `doorId, entity, coords, radius, special` (all `false` if not currently looking at a door) ```lua local doorId, entity, coords, radius, special = plsr.Doors:GetCurrentDoor() ``` Not the same as the `Doors:GetCurrentDoor` client callback (see [Events & callbacks](#events--callbacks)) — that's the server asking a player; this is a purely local read. # Door data shape Each `doors` row: `id` (number), `identifier` (string, nullable/unique), `type` (`'standard'` or `'garage'`), `category` (string, defaults `'misc'`, admin-panel filtering only), `label` (string, nullable), `created_at`/`updated_at` (unix seconds), and a `data` JSON blob: | Field | Type | Description | |---|---|---| | `doors` | `{ model, coords }[]` | 1 or 2 leaves. 2 = a double door — both leaves share this one `doorId`/lock state | | `aliases` | `string[]?` | alternate identifiers that resolve to this row (a merged double door's second leaf keeps its own old id working) | | `locked` | `boolean?` | default state on load | | `autoRate` / `autoDist` | `number?` | passed to `DoorSystemSetAutomaticRate`/`DoorSystemSetAutomaticDistance` if `> 0.0` | | `holdOpen` | `boolean?` | `DoorSystemSetHoldOpen` | | `special` | `boolean?` | suppresses the normal proximity E-prompt (garage/keyfob-triggered doors) | | `maxDist` | `number?` | proximity radius for the lock prompt, defaults `2.0` | | `canLockpick` | `boolean?` | gates the `Doors:Lockpick` callback | | `restricted` | `table[]? \| {}` | `nil`/non-table = unrestricted (anyone can toggle); `{}` = nobody has legitimate access (force/lockpick only); array = see below | | `garageZone` | `table?` | `{x,y,z,length,width,heading,minZ,maxZ}` for `type = 'garage'` doors, captured by the admin picker — not populated by the shipped default set | ```lua -- one row from default_doors.sql, decoded { doors = { { model = -222270721, coords = { x = 17.99, y = -919.95, z = 30.05 } } }, restricted = {}, autoRate = 10.0, locked = true, } ``` Toggle state (`locked`/`forcedOpen`/`disabledUntil`) stays in-memory only (`DOORS_CACHE`) and resets to the row's saved `locked` default on every restart — a mid-heist unlocked vault relocking on a crash is intentional. ## Restricted rule types Checked by `CheckPlayerAuth` (server) / `CheckRestriction` (client) — first matching rule wins: | `type` | Shape | Grants access when | |---|---|---| | `character` | `{ type="character", SID }` | player's state ID matches | | `job` | `{ type="job", job, workplace, grade, gradeLevel, reqDuty, jobPermission }` | `plsr.Jobs.Permissions:HasJob(...)` | | `job` (permission-only) | `{ type="job", jobPermission }` (no `job`) | `plsr.Jobs.Permissions:HasPermission(jobPermission)` | | `propertyData` | `{ type="propertyData", key, value }` | `plsr.Properties.Keys:HasAccessWithData(source, key, value)` — e.g. a house's key holders | ```lua restricted = { { type = "job", job = "police", workplace = false, gradeLevel = 0, jobPermission = false, reqDuty = true }, } ``` # Lockpicking `Config.Lockpick` (`config.lua`): `maxAttempts` (2), `animDuration` (5s), `chance` (30, 0–100%). ```lua Config.Lockpick = { maxAttempts = 2, animDuration = 5, chance = 30, } ``` Using the `lockpick` item (or `adv_lockpick`/`lockpick_pd`, which both set `imitate = 'lockpick'` and so route through the same hook) while looking at a door with `canLockpick = true` that you *don't* already have legitimate access to: 1. Client plays a cancellable `plsr.Progress` bar (`mp_arresting`/`a_uncuff`, `Config.Lockpick.animDuration` seconds). 2. On completion (not cancelled), calls the `Doors:Lockpick` server callback with `{ doorId, item }`. 3. Server rolls `Config.Lockpick.chance` itself (not trusting the client) — success unlocks via `SetLock(doorId, false)`. On failure, a separate 40% roll breaks the lockpick (`plsr.Inventory.Items:RemoveSlot` on the used item's slot). 4. Failed attempts count toward `maxAttempts` per door via a client-side counter (`AddLockpickFailedAttempt`) — reset on character spawn and again automatically 15 minutes after hitting the cap. `CheckDoorAuth`/`CheckRestriction` gate this too: a door you're already authorized for refuses lockpicking ("You can't lockpick a door that you have the keys for..."). # Elevators Entirely separate from the `doors` table — plain static config (`shared/elevatorConfig.lua`'s `_elevatorConfig`), not admin-editable, not persisted. Each entry: `name`, optional `canLock` (a restricted-rule array — who can lock/unlock any floor), and `floors` keyed by an arbitrary numeric level (can be negative, e.g. basements). Each floor: `name`, `coords` (`vector4` destination + heading), `zone` (a box: `center`/`length`/`width`/`heading`/`minZ`/`maxZ`), optional `defaultLocked`, optional `bypassLock` (a restricted-rule array that lets someone visit a locked floor without full lock/unlock authority). ```lua { name = "Diamond Casino Main Elevator", canLock = { { type = "job", job = "casino", jobPermission = "CASINO_LOCK_ELEVATOR" } }, floors = { [1] = { name = "Main Floor", coords = vector4(960.21, 43.19, 71.70, 278.52), zone = { center = vector3(959.87, 43.14, 71.7), length = 2.4, width = 0.4, heading = 12, minZ = 70.7, maxZ = 73.1 }, }, [9] = { defaultLocked = true, name = "Roof - Main Terrace", coords = vector4(964.80, 58.58, 112.55, 60.63), zone = { --[[ ... ]] } }, }, } ``` - `ELEVATOR_CACHE` (server) is rebuilt from `defaultLocked` every boot; `ELEVATOR_STATE` (client) mirrors it. No DB, no persistence. - Standing in a floor's zone shows a targeting option ("Use Elevator") that fires `Doors:Client:OpenElevator`, opening a `plsr.ListMenu` of every floor on that elevator. Locked floors are disabled unless you pass `bypassLock` or are authorized via `canLock` (which also adds a "Lock/Unlock Floor" submenu item per floor). - Picking a floor (`Doors:Client:UseElevator`) validates through the `Doors:Elevator:Validate` server callback (a `TempPosIgnore` anti-cheat allowance, not a permission re-check), then checks the floor's own `locked` state before showing a 2s cancellable progress bar and screen-fade teleport. # Garages Not a separate system — a garage is a normal door row (`type = 'garage'`), just interacted with differently: a keybind instead of the proximity E-prompt, and a `special = true` flag that suppresses the normal prompt. - Keybind `doors_garage_fob` (default **F10**) → `DoGarageKeyFobAction`: checks the player's current polyzone for a `door_garage_id` tag, and if found, `CheckRestriction` then the same `Doors:ToggleLocks` callback every other door uses. Rate-limited to one action per 650ms. - Zones for garage doors are created client-side from each door's `garageZone` field (`CreateDatabaseGarageZones`, tagged `door_garage_id = `) whenever doors load or resync — there's no static zone config file anymore, it's fully driven by what's in the `doors` table. # Events & callbacks ## Server callbacks (`plsr.Callbacks:RegisterServerCallback`) | Name | Data | Does | |---|---|---| | `Doors:Fetch` | — | `cb(_doorConfig, DOORS_CACHE, ELEVATOR_CACHE)` — full state dump, used on spawn/resync | | `Doors:ToggleLocks` | `doorId` | the actual lock/unlock action (E-prompt and garage keyfob both use this) — gated by `not IsDoorDisabled` + `CheckPlayerAuth` | | `Doors:Lockpick` | `{ doorId, item }` | see [Lockpicking](#lockpicking) | | `Doors:Elevators:ToggleLocks` | `{ elevator, floor }` | gated by `canLock` + `CheckPlayerAuth` | | `Doors:Elevator:Validate` | floor data | `TempPosIgnore` only, always succeeds | ```lua plsr.Callbacks:ServerCallback("Doors:ToggleLocks", doorId, function(success, newState) end) plsr.Callbacks:ServerCallback("Doors:Elevators:ToggleLocks", { elevator = elevatorId, floor = floorId }, function(success, newState) end) ``` ## Client callback | Name | Does | |---|---| | `Doors:GetCurrentDoor` | `cb(_lookingAtDoor)` — lets the server ask a specific player what door they're looking at | ## Client events (`TriggerClientEvent`/`AddEventHandler`) | Event | Params | Broadcast? | |---|---|---| | `Doors:Client:UpdateState` | `(doorId, locked)` | all players | | `Doors:Client:SetForcedOpen` | `(doorId)` | all players | | `Doors:Client:DisableDoor` | `(doorId, disabledUntil)` | all players | | `Doors:Client:UpdateElevatorState` | `(elevatorId, floorId, locked)` | all players | | `Doors:Client:Resync` | — | all players, after any admin CRUD change — full drop + rebuild | | `Doors:Client:AttemptLockpick` | `(item)` | targeted at whoever used the lockpick | | `Doors:Client:OpenElevator` / `LockElevator` / `UseElevator` | `(data)` | local only, fired by the elevator targeting zone's menu options |

Doorlock