Ox Doorlock (esx-framework/ox_doorlock)

Ox Doorlock

https://github.com/esx-framework/ox_doorlock
Admin
Ox Doorlock is a door management resource for FiveM, offering compatibility with multiple core...

Tokens:5,584
Snippets:30
Trust Score:9.2
Update:2 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Ox Doorlock

## Introduction

Ox Doorlock is a comprehensive door management resource for FiveM servers running GTA5. It provides a robust system for controlling access to doors, gates, and other lockable objects within the game world. The resource features seamless integration with popular frameworks including ox_core, es_extended, nd_core, and qbox, making it versatile for different server setups. This is a successor to nui_doorlock with improved functionality and reduced issues.

The system stores door configurations in a MySQL database for easy management and data persistence across server restarts. It includes a web-based UI for creating and editing door locks, support for passcodes, lockpicking mechanics, automatic door locking, and various authorization methods including character IDs, group/job permissions, and inventory items. The resource also provides both client and server APIs for programmatic door control, making it suitable for complex role-playing scenarios where fine-grained access control is essential.

## APIs and Key Functions

### Client Export: Use Closest Door

Toggle lock state of the nearest door to the player.

```lua
-- Unlock or lock the closest door the player is near
-- This still performs server-side authorization checks
exports.ox_doorlock:useClosestDoor()

-- Example: Bind to a custom key or trigger from another resource
RegisterCommand('toggledoor', function()
    exports.ox_doorlock:useClosestDoor()
end, false)
```

### Client Export: Lockpick Closest Door

Initiate lockpicking on the nearest door with skill check.

```lua
-- Attempt to pick the lock of the closest door
-- Requires lockpick item in inventory and door must have lockpick enabled
exports.ox_doorlock:pickClosestDoor()

-- Example: Custom lockpicking trigger
RegisterCommand('picklock', function()
    local hasLockpick = exports.ox_inventory:Search('slots', 'lockpick')[1]
    if hasLockpick then
        exports.ox_doorlock:pickClosestDoor()
    else
        lib.notify({type = 'error', description = 'You need a lockpick'})
    end
end, false)
```

### Client Export: Get Closest Door Data

Retrieve information about the nearest door.

```lua
-- Get the closest door object with all its properties
local closestDoor = exports.ox_doorlock:getClosestDoor()

if closestDoor then
    print(string.format('Closest door: %s (ID: %d, State: %d)',
        closestDoor.name,
        closestDoor.id,
        closestDoor.state
    ))
    print('Distance: ' .. closestDoor.distance)
    print('Max interaction distance: ' .. closestDoor.maxDistance)
end
```

### Server Export: Get Door by ID

Retrieve door data by numeric ID.

```lua
-- Get door information by ID
local door = exports.ox_doorlock:getDoor(1)

if door then
    print(json.encode(door, {indent = true}))
    -- Returns: {id, name, state, coords, characters, groups, items, maxDistance}
end

-- Example: Check if a specific door is locked
local mrpdDoor = exports.ox_doorlock:getDoor(1)
if mrpdDoor and mrpdDoor.state == 1 then
    print('MRPD front door is locked')
else
    print('MRPD front door is unlocked')
end
```

### Server Export: Get Door by Name

Retrieve door data by its configured name.

```lua
-- Get door by name instead of ID
local lockerRoom = exports.ox_doorlock:getDoorFromName('mrpd locker rooms')

if lockerRoom then
    print(string.format('Door %s is currently %s',
        lockerRoom.name,
        lockerRoom.state == 1 and 'locked' or 'unlocked'
    ))
end

-- Example: Check multiple doors by name
local doorNames = {'front entrance', 'back door', 'evidence room'}
for _, doorName in ipairs(doorNames) do
    local door = exports.ox_doorlock:getDoorFromName(doorName)
    if door then
        print(doorName .. ' status: ' .. (door.state == 1 and 'LOCKED' or 'UNLOCKED'))
    end
end
```

### Server Export: Get All Doors

Retrieve complete list of all configured doors.

```lua
-- Get array of all doors in the system
local allDoors = exports.ox_doorlock:getAllDoors()

print('Total doors configured: ' .. #allDoors)

for _, door in ipairs(allDoors) do
    print(string.format('[%d] %s - %s',
        door.id,
        door.name,
        door.state == 1 and 'LOCKED' or 'UNLOCKED'
    ))
end

-- Example: Find all locked doors
local lockedDoors = {}
for _, door in ipairs(allDoors) do
    if door.state == 1 then
        table.insert(lockedDoors, door)
    end
end
print('Locked doors count: ' .. #lockedDoors)
```

### Server Event: Set Door State

Change door lock state programmatically.

```lua
-- Set door state (0 = unlocked, 1 = locked)
-- This bypasses authorization checks when triggered server-side
local doorId = 1
local newState = 1  -- Lock the door

TriggerEvent('ox_doorlock:setState', doorId, newState)

-- Example: Lock all doors at a specific time
CreateThread(function()
    while true do
        local hour = GetClockHours()

        -- Lock all police station doors at 10 PM
        if hour == 22 then
            TriggerEvent('ox_doorlock:setState', 1, 1)  -- Front door
            TriggerEvent('ox_doorlock:setState', 2, 1)  -- Back entrance
            TriggerEvent('ox_doorlock:setState', 3, 1)  -- Evidence room
        end

        Wait(60000)  -- Check every minute
    end
end)
```

### Server Export: Set Door State with Return

Programmatically set door state with authorization and success feedback.

```lua
-- Set door state with return value indicating success
local success = exports.ox_doorlock:setDoorState(1, 0)  -- Try to unlock door 1

if success then
    print('Door state changed successfully')
else
    print('Failed to change door state (not authorized or door not found)')
end

-- Example: Unlock door when player completes a mission
RegisterServerEvent('myresource:missionComplete')
AddEventHandler('myresource:missionComplete', function()
    local source = source
    local door = exports.ox_doorlock:getDoorFromName('secret vault')

    if door then
        local unlocked = exports.ox_doorlock:setDoorState(door.id, 0)
        if unlocked then
            TriggerClientEvent('chat:addMessage', source, {
                args = {'System', 'The vault door has been unlocked!'}
            })
        end
    end
end)
```

### Server Export: Edit Door Properties

Modify door properties dynamically.

```lua
-- Edit door properties at runtime
-- Available properties: name, state, groups, items, characters, passcode, autolock, etc.
exports.ox_doorlock:editDoor(1, {
    name = 'Updated Door Name',
    state = 1,  -- Locked
    autolock = 30,  -- Auto-lock after 30 seconds
    passcode = '1234',
    maxDistance = 2.5
})

-- Example: Add a job group to a door
local door = exports.ox_doorlock:getDoor(5)
if door then
    local currentGroups = door.groups or {}
    currentGroups['police'] = 2  -- Minimum grade 2

    exports.ox_doorlock:editDoor(5, {
        groups = currentGroups
    })
end
```

### Server Event: State Changed Listener

Listen for door state changes with item consumption support.

```lua
-- Listen for door state changes and perform actions
-- Parameters: source (player), doorId, state (boolean: true=locked), usedItem
AddEventHandler('ox_doorlock:stateChanged', function(source, doorId, isLocked, usedItem)
    if usedItem then
        print(string.format('Player %s used item "%s" on door %d',
            GetPlayerName(source),
            usedItem,
            doorId
        ))
    end

    -- Example: Remove consumed items
    if usedItem == 'train_ticket' then
        local xPlayer = ESX.GetPlayerFromId(source)
        if xPlayer then
            xPlayer.removeInventoryItem(usedItem, 1)
        end
    end

    -- Example: Log door activity
    if source then
        print(string.format('[DOORLOCK] Player %s %s door %d',
            GetPlayerName(source),
            isLocked and 'locked' or 'unlocked',
            doorId
        ))
    end
end)
```

### Command: Create or Modify Doorlock

Administrative command to open door management UI.

```bash
# Open UI to create a new door
/doorlock

# Open UI with closest door pre-selected for editing
/doorlock closest
```

```lua
-- Usage requires 'command.doorlock' ace permission
-- Configure in server.cfg:
-- add_ace group.admin command.doorlock allow
-- add_principal identifier.fivem:123456 group.admin

-- Example: Custom command wrapper
lib.addCommand('managedoor', {
    help = 'Manage nearby door',
    restricted = 'group.admin'
}, function(source)
    TriggerClientEvent('ox_doorlock:triggeredCommand', source, true)
end)
```

### Client Callback: Input Passcode

Request passcode input from player.

```lua
-- This is called automatically when a door with passcode is used
-- Passcode is validated server-side before allowing access

-- Example custom implementation:
lib.callback.register('ox_doorlock:inputPassCode', function()
    local door = exports.ox_doorlock:getClosestDoor()

    if door and door.passcode then
        local input = lib.inputDialog('Door Security', {
            {
                type = 'input',
                label = 'Enter Passcode',
                password = true,
                required = true,
                icon = 'lock'
            }
        })

        return input and input[1] or nil
    end
end)
```

### Configuration: Lockpick Settings

Configure lockpicking difficulty and behavior.

```lua
-- config.lua settings
Config.LockDifficulty = {'easy', 'easy', 'medium'}  -- Skill check difficulty array
Config.CanPickUnlockedDoors = false  -- Allow lockpicking unlocked doors to lock them
Config.LockpickItems = {'lockpick', 'advanced_lockpick'}  -- Items that work as lockpicks

-- Example: Per-door difficulty override
-- When creating a door via UI or database, set lockpickDifficulty property
-- This overrides Config.LockDifficulty for that specific door
local doorData = {
    name = 'High Security Vault',
    lockpick = true,
    lockpickDifficulty = {'hard', 'hard', 'hard', 'medium'}  -- Custom difficulty
}
```

### Database Schema: Door Storage

Door configurations are stored in MySQL database.

```sql
-- Table structure
CREATE TABLE IF NOT EXISTS `ox_doorlock` (
    `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
    `name` varchar(50) NOT NULL,
    `data` longtext NOT NULL,
    PRIMARY KEY (`id`)
);

-- Example query: Get all police station doors
SELECT * FROM ox_doorlock WHERE name LIKE '%mrpd%';

-- Example: Manual door insertion
INSERT INTO ox_doorlock (name, data) VALUES (
    'test door',
    '{"model":"prop_door_01","coords":{"x":100.0,"y":200.0,"z":30.0},"state":1,"maxDistance":2.0}'
);
```

### Target Integration: Lockpicking with ox_target

Automatic integration with ox_target for lockpicking interaction.

```lua
-- Automatically configured when ox_target is detected
-- Players can use target system (default: LALT) to interact with doors
-- Requires lockpick item in inventory

-- Configuration in config.lua:
Config.LockpickItems = {'lockpick'}  -- Items shown in target menu

-- The system automatically adds this global object option:
-- {
--     name = 'pickDoorlock',
--     label = 'Pick Lock',
--     icon = 'fas fa-user-lock',
--     onSelect = pickLock,
--     canInteract = canPickLock,
--     items = Config.LockpickItems,
--     distance = 1
-- }
```

### Door Properties: Complete Configuration

Full door configuration object structure.

```lua
-- Complete door data structure with all available properties
local doorConfig = {
    -- Required properties
    name = 'Main Entrance',               -- Unique identifier name
    coords = vector3(434.7, -981.9, 30.6), -- Door center position
    model = `v_ilev_ph_gendoor004`,        -- Door model hash or name

    -- State properties
    state = 1,                            -- 0=unlocked, 1=locked (default: 1)

    -- Interaction properties
    maxDistance = 2.0,                    -- Interaction distance in meters
    hideUi = false,                       -- Hide lock icon indicator

    -- Authorization properties
    characters = {'char:1234'},           -- Array of character identifiers
    groups = {                            -- Job/gang requirements
        police = 2,                       -- police job with minimum grade 2
        fbi = 0                           -- fbi job with any grade
    },
    items = {                             -- Required items
        {name = 'police_keycard', remove = false},
        {name = 'master_key', remove = false}
    },
    passcode = '1234',                    -- Optional passcode requirement

    -- Behavior properties
    auto = false,                         -- Sliding/automatic door
    autolock = 30,                        -- Auto-lock after X seconds
    doorRate = 1.0,                       -- Door movement speed multiplier
    holdOpen = false,                     -- Keep door open when unlocked

    -- Lockpicking properties
    lockpick = true,                      -- Allow lockpicking
    lockpickDifficulty = {'medium', 'easy', 'hard'}, -- Skill check difficulty

    -- Audio properties
    lockSound = 'metal_locker',           -- Custom lock sound
    unlockSound = 'metal_locker',         -- Custom unlock sound

    -- Double door configuration
    doors = {                             -- For paired doors
        {
            model = `prop_door_01`,
            coords = vector3(100.0, 200.0, 30.0),
            heading = 90
        },
        {
            model = `prop_door_01`,
            coords = vector3(102.0, 200.0, 30.0),
            heading = 270
        }
    }
}

-- Example: Create simple single door
local simpleDoor = {
    name = 'Simple Office Door',
    coords = vector3(200.0, 300.0, 40.0),
    model = `prop_door_01`,
    heading = 0,
    state = 1,
    maxDistance = 2.0,
    groups = {police = 0}  -- Any police officer can access
}
```

## Integration and Use Cases

Ox Doorlock is designed for FiveM roleplay servers requiring sophisticated access control systems. Common use cases include police departments with different clearance levels for lobby, offices, armory, and evidence rooms; hospital emergency rooms and surgery areas restricted to medical staff; gang hideouts with member-only access and password protection; government buildings with badge-based entry systems; and private businesses where owners can grant employee access. The resource integrates seamlessly with job systems, inventory systems, and targeting resources to create immersive security scenarios.

The framework-agnostic design allows servers to switch between ox_core, ESX, ND Core, or QBox without reconfiguring doors. Authorization can be layered using multiple methods simultaneously - a high-security door might require both a specific job rank AND a physical keycard item AND a passcode. The lockpicking system adds criminal roleplay opportunities with configurable difficulty and item consumption. The database-driven architecture means doors persist across server restarts, and the web UI allows administrators to configure complex door systems without touching code. Events and exports provide developers with hooks to integrate custom logic, such as logging door access, triggering alarms, or consuming single-use access tokens.