XS-DoorLock

Requirements

Short list:

• ox_lib
• oxmysql
• Qbox (qbx_core) or QBCore (qb-core)

Keys and keycards are items, so they need an inventory that stores item data: ox_inventory, qb-inventory, qs-inventory, ps-inventory or lj-inventory. Every other lock works without one.

A target is optional. ox_target, qb-target, sleepless_interact, interact and qtarget are found on their own. Without one, players press E at a door and G to pick it.

No ESX.

Installation

1. Drop the folder into your resources.
2. Add ensure XS-DoorLock after ox_lib and oxmysql.
3. Give your staff the console: add_ace group.admin xs.doorlock.admin allow.
4. Paste the two items from items/ into your items file, ox_inventory.lua or qb_core.lua, and copy the pictures from inventory_images/ into your inventory's images folder.
5. Restart, then run /doors in game.

The tables are made on first start. sql/xs_doorlock.sql is there if you would rather run it by hand.

Turn off any other door lock on the same doors. Two door locks on one door fight each other, and the door swings back open after locking.

The Access Console

/doors opens the console. Buildings are down the left, the one you pick is on the satellite map, and its doors are in a table under it with their lock, who can open them and a switch to lock or unlock them from anywhere.

Pick a door and its settings open on the right: the lock, who can open it, the door itself and a few extras. Go to door takes you there, Copy to puts its lock or its people on other doors, and the search box finds any door on the server by name.

The menu next to a building's name renames it, hands out a building card, re-codes building cards, and locks or unlocks every door in it at once.

Only admins open the console. Business doors are set up by an admin for the business.

Scanning a building

1. Stand inside the building and press Scan building.
2. Every door near you gets a number in the world. Mirrored pairs are joined into double doors.
3. Untick anything that is not a door. Anything the scan is unsure about, like a wardrobe, starts unticked. Hover a row to see that door outlined in the world, or press Look around to walk through and check.
4. Rename them if you like, pick the building they go in, and set the lock and who can open them once.
5. Press Add. Every ticked door is live for every player.

You can change any door on its own afterwards.

Adding one door

Press Add door, pick the kind of door, then fly to it and aim. The door you aim at gets a coloured box:

• Green: a door. Press Enter to pick it.
• Yellow: might not be a door. Enter picks it anyway.
• Red: already set up.
• Blue: the half of a double door you already picked.

New doors copy the last one you added in that building: the lock, the code and the people. A banner says so, and Start blank clears it. The wall device is never copied.

Keypads, card readers and scanners have a wall device, a prop next to the door. Press Put it on the wall and aim where it goes. Players then use the device instead of the door.

Single, double, sliding, double sliding and garage doors swing or slide like any door. Vault doors and barrier arms turn instead.

The locks

The lock decides how a door opens:

• Key: this door's key, or being on the list. Can be picked.
• Keycard: a card for this door or its building, or being on the list.
• Keypad: the code. People on the list skip it.
• Padlock: the combination. People on the list skip it. Can be picked.
• Fingerprint and eye scanner: only people on the list.
• Button: people on the list press it.

Each lock has its own screen when a player uses it. Each door can switch picking on or off. The defaults for new doors and the wall device for each lock are in Config.Locks.

Who can open it

Every door has one list. Add a job and the lowest rank that gets in, a gang and its rank, named players, or everyone. On duty only keeps job members out while they are off duty.

Players are added from who is online, or by searching every character on the server.

Still use the lock. People on the list skip a door's key, card, keypad or padlock. Turn on Still type the code under Who can open it (Still swipe a card, Still need the key or Still need the combination on the other locks) and they have to use it like anyone else. Then only people on the list get in. If nobody is on the list, the code, card or key opens it for anyone.

Keys and keycards

Open a door with a key or keycard lock and press Give a key or Give a card. It goes straight into a player's pockets, or yours to hand over. Keys and cards carry the name of their door.

Change the lock makes every key or card made for that door stop working. The building menu has Give a building card, which opens every keycard door in the building, and Re-code building cards to cancel them all at once.

The items are xs_doorkey and xs_keycard, named in Config.Items.

Codes and lockouts

Keypad codes are 4 to 8 digits and padlocks have 4 wheels, set in Config.Codes. After 3 wrong codes in a row the lock refuses everyone for a minute and the alarm rings. Each door can change the number of tries, the time and the alarm.

Using doors

With a target running, every door goes on it. Players aim at the door, or at its wall device, and pick the option: Enter code, Swipe card, Scan finger, Unlock, and Pick the lock when they carry a lockpick. Set Config.Bridges.target to force one, or to 'none'.

Without a target, players walk up and press E, or G to pick the lock. Both can be rebound in Settings, Key Bindings, FiveM.

Lockpicking is an ox_lib skill check. A failed attempt can break the pick. The items, break chance and difficulty are in Config.Items.lockpicks.

Under More, a door can lock itself again after a set time, play its own sound, hide its lock icon, and start locked after a restart. Garage and sliding doors can stay open while unlocked.

Other scripts

Server exports:

exports['XS-DoorLock']:IsLocked(doorId)
exports['XS-DoorLock']:SetLocked(doorId, true)
exports['XS-DoorLock']:SetBuildingLocked(buildingId, true)
exports['XS-DoorLock']:GetDoor(doorId)
exports['XS-DoorLock']:GetDoorByName('Back Room')
exports['XS-DoorLock']:GiveKey(source, doorId)
exports['XS-DoorLock']:GiveCard(source, doorId)
exports['XS-DoorLock']:ChangeLock(doorId)
exports['XS-DoorLock']:SetCode(doorId, '4719')
exports['XS-DoorLock']:AddCivilian(doorId, citizenid, name)

Server events:

AddEventHandler('XS-DoorLock:stateChanged', function(doorId, locked, source, how) end)
AddEventHandler('XS-DoorLock:lockedOut', function(doorId, source, seconds) end)
AddEventHandler('XS-DoorLock:picked', function(doorId, source) end)

how is list, key, keycard, code, pick, admin, auto or script. The README on GitHub has the full list, client exports included.

Troubleshooting

/doors does nothing

You do not have access. Run add_ace group.admin xs.doorlock.admin allow, or add your group to Config.Admin.groups. /doordiag shows what the script sees.

A door does not open for someone who should get in

Stand at it and run /doordiag. It prints their job, rank, gang and duty, and whether they are on the list. With Still use the lock on, they need the code, card or key as well.

Keys or cards do nothing

The items are missing from your inventory, or it cannot store item data. The server console says which at start.

A door swings back open after locking

Another door lock is running on the same door. Turn it off for that door.

The scan finds furniture

Untick it. Anything the scan is unsure about starts unticked.

A wall device does not show

That prop is not in your game files. Set another prop name in Config.Locks.

Updating

1. Back up the database first.
2. Keep a copy of your edited config.lua.
3. Replace the resource folder, merge your config back and restart.

Your doors, buildings and codes live in the database, so nothing you set up is lost.

Support

Bugs and questions go to the Discord. Include your server's console output — the resource prints the reason when it refuses to do something, and that line is usually the whole answer.

XS-DoorLock on GitHub