doorlock

Last updated on

A port of ox_doorlock to Open77's world doors: a door has ox's fields under ox's names, is filed under ox's integer id, opens by ox's rules and is edited in a panel built like ox's. The native door keeps its own animation and sound; this module only moves its lock. The server decides every turn: it reads the player's position, bucket, job and bag itself.

• Without character only staff, key items and codes open a door with groups or characters (a group check closes on every doubt).
• Without inventory no key or lockpick works.

At a door

hideUi hides the prompt row, not the lock. A refusal is a toast naming why (see codes).

Who may turn a door

ox's isAuthorised, in this order:

1. Staff holding the plain right opx.doorlock.bypass, only when STAFF_BYPASS is on — or the ACL entry doorlock.<id>. No code asked.
2. A listed character (citizen id). No code asked.
3. The groups: any one job or gang at its minimum grade. Then the code, if the door has one.
4. Else the items: any one held. Then the code.
5. A door with only a code opens for whoever knows it.

A door with none of these opens for staff only. opx.doorlock.bypass is not a command. grant, so an admin role's command.* does not carry it: by default an admin is asked for a key or a code like anyone.

{
  name = 'NCPD front desk',
  native = '0xFC85EAE29622BAC2',        -- or doors = { { native, coords }, { native, coords } }
  coords = { x = -1234.5, y = 456.7, z = 12.0 }, bucket = 0,
  state = 1,                            -- 1 locked, 0 unlocked
  groups = { ncpd = 0 },                -- job or gang -> minimum grade
  items = { { name = 'door_key', metadata = 'ncpd_front', remove = false } },
  characters = { 'ABC12345' },
  passcode = '1234',
  autolock = 10, maxDistance = 2.0,
  lockpick = true, lockpickDifficulty = { 'easy', 'hard' },
  auto = false, hideUi = false, holdOpen = false, onDuty = false,
  lockSound = '', unlockSound = '',
}

• native: the door's opaque id, 0x + 16 hex digits (the panel's Pick in world reads it). Two leaves make a double door; its coords default to the middle.
• items[].metadata: matches the item's metadata type. remove = true spends one on use.
• maxDistance: metres, default USE_RADIUS, clamped to MAX_REACH.
• lockpickDifficulty: steps, each 'easy' | 'medium' | 'hard' or { areaSize, speedMultiplier }. None: LOCKPICK.DEFAULT.
• auto: an automatic door (garage, shutter). holdOpen: stays open while unlocked. onDuty: a job group only counts on duty.
• Limits: name 64 characters, 16 groups, 8 items, 32 characters, code 32 characters, autolock 0..3600 s, 512 doors.

Commands

All restricted: the host checks command.<name>.

<door> is the id /opx.doorlock.list prints, or the key a seeded or carried-over door had. There is no save command: command.opx.doorlock.save gates the panel's Confirm door.

Audit events: doorlock.create, .edit, .remove, .lock, .unlock, .key; security lines doorlock.staffDenied, doorlock.passcode, doorlock.pickEarly.

Staff panel

Opened by /opx.doorlock, the F9 World → Door locks row or the eye's Manage door (the door's settings when it is managed, a new door with that leaf taken when it is not).

1. The table. Id, name, state, distance. Search, sortable columns, pages. Per row: Settings, Copy settings, Lock now / Unlock now, Teleport to door, Delete door (with a confirm). + starts a new door. Seeded doors are tagged config.
2. Settings, General. Name, passcode, autolock, interact distance, the switches Locked, Double, Automatic, Lockpick, Hide UI, Hold open, On duty only, and the door itself with Pick in world.
3. Characters, Groups, Items. Rows of citizen ids; group + grade; item + metadata type + Remove on use.
4. Lockpick. One difficulty per row, or Custom with area size and speed multiplier. No row: LOCKPICK.DEFAULT.
5. Sound. Lock and unlock sounds from SOUNDS.LIST.
6. Pick in world. The panel hides; aim at the door and press E (twice for a double door), Escape cancels. A leaf another door manages and a lift door are refused. Confirm door on a door with no leaf starts this step and saves when it ends.
7. Confirm door saves. Give me a key, copy / apply copied settings and delete sit on the same bar.

• The code. Staff holding command.opx.doorlock.save see it in plain text in the settings; anyone else sees only that one is set. Left empty on save, it is kept; Clear the code removes it.
• A button the ACL refuses is greyed, not hidden.
• The server re-checks every save: an unknown group or grade, an unknown item, a leaf another door holds, or a new or moved door more than 60 m from the staff member is refused.

Backends

open77_doors depends on open77_elevators, which takes the cabins away from the elevators module; servers that need job-gated lifts run local. BACKEND = 'networked' without the service falls back to local and logs an error. /opx.doorlock.list and the panel name the running backend.

Migration from the first table

The first version of this module (PR #70) stored doors in opx77_doorlock (no s). On every boot each of its rows is inserted once into opx77_doorlocks under legacy:<key>; nothing is lost and nothing is written back. Drop the old table by hand once the doors are checked.

• Groups { kind, name, grade } become ox's map { [name] = grade }; locked becomes state.
• A BOUND key item becomes a metadata match on the old key. Keys already cut (door = <old key>) keep opening their door.
• A row whose key a config door also used is skipped, as before.
• The old key still works in every command and export.

DOORS blocks changed shape too:

Configuration

config/doorlock.lua sets OPX.Config.MODULES.doorlock. Shared script.

LOCKPICK = {
  ITEMS = { 'lockpick' },            -- one is needed; a break takes one
  CAN_PICK_UNLOCKED = false,         -- may a pick also lock?
  DEFAULT = { 'easy', 'easy', 'medium' },
  DIFFICULTY = {                     -- one progress bar per step, rolled by the server
    easy   = { DURATION_MS = 2000, CHANCE = 0.85 },
    medium = { DURATION_MS = 2500, CHANCE = 0.6 },
    hard   = { DURATION_MS = 3000, CHANCE = 0.4 },
  },
  BREAK_CHANCE = { SUCCESS = 0.01, FAIL = 0.2 },
},

• Every step must pass. A custom step { areaSize, speedMultiplier } reads as CHANCE = areaSize / 60 / speedMultiplier (0.05..0.95) and DURATION_MS = 2500 / speedMultiplier.

DOORS = {
  ncpd_front = {
    NAME = 'NCPD front desk',
    DOORS = { '0xFC85EAE29622BAC2' },
    COORDS = { x = -1234.5, y = 456.7, z = 12.0 }, BUCKET = 0,
    STATE = 1,
    GROUPS = { ncpd = 0 },
    ITEMS = { { NAME = 'door_key', METADATA = 'ncpd_front' } },
    PASSCODE = '1234', AUTOLOCK = 10, MAX_DISTANCE = 2.0,
    LOCKPICK = true, LOCKPICK_DIFFICULTY = { 'easy', 'hard' },
  },
},

The fields are the door's, upper-cased (CHARACTERS, AUTO, HIDE_UI, HOLD_OPEN, ON_DUTY, LOCK_SOUND, UNLOCK_SOUND too). A block that fails validation is logged as [doorlock] config: DOORS.<key> refused: <code>.

Refusal codes

Shown as toasts, locale key doorlock.error.<code>.

Successes: locked, unlocked, picked, picked_broke (opened, and the lockpick broke), already_locked, already_unlocked (doorlock.answer.<code>).

The contract and the door exports answer a write refusal (create, edit, remove) as doorlock.error.<code>, the same keys as these toasts. Their own codes doorlock.unknownDoor, doorlock.badState, doorlock.noDoor and doorlock.notStaff now have sentences too.