Configuration

Configuration documentation for Nord Doorlock.

Full Configuration Reference

Main configuration file:

config/config.lua

Locale

Config.Locale = 'en'

Included locales:

en
pt

Storage

Config.Storage = 'json'

Values:

json
mysql
auto

json uses KVP as the authoritative store and JSON files as mirrors.

mysql requires oxmysql.

auto uses MySQL when oxmysql is running, otherwise KVP/JSON.

Base Distances & Defaults

Config.InteractionDistance = 2.0
Config.DrawDistance = 12.0
Config.DefaultDoorDistance = 2.0
Config.DefaultLocked = true
Config.DefaultAutoLock = 0

Door Closing

Config.DoorCloseRate = 10.0
Config.DoorCloseTimeoutMs = 2500
Config.DoorCloseSnapFallback = true
Config.DoorPhysicalFallback = true

Controls

Config.ToggleKey = 38
Config.LockpickKey = 74

Defaults:

E = toggle
H = lockpick

Feature Toggles

Config.EnableTarget = true
Config.EnableTextUI = true
Config.EnableLockpick = true
Config.CustomDoorNUI = true
Config.ShowDoorStateIcon = true

Native State Icon

Config.DoorStateIconDistance = 6.0
Config.DoorStateIconOffsetZ = 0.0
Config.DoorStateIconMergeDistance = 0.35

Sprite configuration:

Config.DoorStateSprites = {
    [0] = {
        'mpsafecracking',
        'lock_open',
        0.0, 0.0,
        0.018, 0.018,
        0.0,
        255, 255, 255, 180
    },

    [1] = {
        'mpsafecracking',
        'lock_closed',
        0.0, 0.0,
        0.018, 0.018,
        0.0,
        255, 255, 255, 180
    }
}

State keys:

0 = unlocked
1 = locked

Custom Door UI

Config.DoorUIShowDistance = 6.0
Config.DoorUIInteractDistance = 2.0
Config.DoorUIOffsetZ = 0.15

Administrator Settings

Config.AdminCommand = 'doors'
Config.AdminAce = 'nord.doorlock.admin'

Config.AdminGroups = {
    admin = true,
    superadmin = true,
    god = true
}

Integration Providers

Config.Framework = 'auto'
Config.Notify = 'auto'
Config.TextUI = 'auto'
Config.Target = 'auto'
Config.Inventory = 'auto'

Framework

auto
esx
qb
qbx
nord
standalone

Notify

auto
ox
qb
esx
nord
standalone

Text UI

auto
ox
nord
standalone

Target

auto
ox
qb
nord
standalone

Inventory

auto
ox
qb
esx
nord
standalone

Lockpick

Config.Lockpick = {
    item = 'lockpick',
    consumeOnSuccess = false,
    consumeOnFail = true,
    fallbackSuccessChance = 45,
    oxDifficulty = { 'easy', 'easy', 'medium' },
    oxInputs = { 'w', 'a', 's', 'd' }
}

Server Security

Config.RateLimitMs = 350
Config.ServerDistanceCheck = true
Config.ServerDistanceTolerance = 2.0

RateLimitMs reduces event spam.

ServerDistanceCheck enables authoritative proximity validation for player interactions.

ServerDistanceTolerance is added to the door's configured distance when validating the player server-side.

Capture

Config.AdminCaptureDistance = 15.0
Config.AdminCaptureRadius = 0.42
Config.AdminCaptureFallbackRadius = 1.35
Config.AdminCaptureScreenRadius = 0.075

The capture system can use a normal object ray, a capsule test and a camera-aligned object fallback.

Duplicate Door Detection

Config.DuplicateDoorTolerance = 0.15

The same physical door object cannot belong to two different door definitions.

Debug

Config.Debug = false

Enable temporarily when diagnosing persistence or synchronization problems.

Bridges & Integrations

Nord Doorlock keeps integrations outside the core logic.

Client Bridges

client/bridge/framework.lua
client/bridge/notify.lua
client/bridge/textui.lua
client/bridge/target.lua

Server Bridges

server/bridge/framework.lua
server/bridge/inventory.lua

This structure allows a server owner or developer to add a custom provider without editing the main door synchronization logic.

Framework Bridge

Responsible for:

Supported:

ESX
QB-Core
QBX
nord-core
standalone

Notification Bridge

Supported automatic providers include:

ox_lib
nord_notify
QB-Core
ESX
standalone chat fallback

The notification type values used internally include:

inform
success
error

Text UI Bridge

Supported:

ox_lib
nord_textui
built-in NUI fallback

The standalone fallback is pure NUI and does not rely on GTA text natives.

Target Bridge

Supported:

ox_target
qb-target
nord_target

When no supported target is active, normal key/NUI interaction remains available.

The current nord_target bridge registers the standard toggle interaction. If your nord_target implementation should expose a separate lockpick option, extend client/bridge/target.lua.

Inventory Bridge

Supported:

nord_inventory
ox_inventory
QB inventory
ESX inventory
standalone fallback

Used primarily for the lockpick item.

Adding a Custom Provider

Prefer editing or extending the corresponding bridge file rather than placing provider-specific code in:

client/main.lua
server/main.lua

This keeps future updates easier to merge.

Storage & Persistence

Nord Doorlock supports persistence without requiring a database.

JSON Mode

Default:

Config.Storage = 'json'

Despite the name, the authoritative store is FiveM Resource KVP.

KVP key:

nord_doorlock:doors:v2

The resource also mirrors data to:

data/doors.json
data/doors.backup.json

This design allows doors to survive resource/server restarts even when the resource directory is not writable.

Source Selection on Load

When using JSON mode, Nord Doorlock can read:

The newest valid source is selected.

Legacy JSON arrays are accepted and migrated to the newer persisted wrapper.

JSON Payload Shape

Current mirror structure:

{
  "version": 2,
  "savedAt": 1700000000,
  "doors": []
}

MySQL Mode

Configure:

Config.Storage = 'mysql'

oxmysql must be started.

The table is auto-created.

Optional SQL:

CREATE TABLE IF NOT EXISTS `nord_doorlock` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `data` LONGTEXT NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Each database row stores the door payload in the data column.

Auto Mode

Config.Storage = 'auto'

If oxmysql is running, MySQL is used.

Otherwise Nord Doorlock falls back to KVP/JSON.

Persistence Safety

For authoritative changes, the server saves before broadcasting success.

If persistence fails, state-changing API operations attempt to roll back the in-memory change rather than pretending the operation succeeded.

Storage Diagnostics

Console or administrator command:

doors_storage

Typical fields:

mode
ready
doors
error

Developer export:

local health = exports.nord_doorlock:GetStorageHealth()

Returned data includes values such as:

{
    mode = 'json',
    configuredMode = 'json',
    lastError = nil,
    kvpKey = 'nord_doorlock:doors:v2',
    ready = true,
    serverError = nil,
    doorCount = 10
}

Reloading From Persistence

Server export:

local ok, count, removedDuplicates =
    exports.nord_doorlock:ReloadDoors()

This reloads definitions, performs duplicate cleanup and broadcasts a full synchronization.

Commands & Diagnostics

/doors

Opens the in-game administrator panel.

Command name:

Config.AdminCommand = 'doors'

Default:

/doors

The server validates administrator permission before opening the panel.

doors_storage

Displays storage health.

Server console:

doors_storage

Authorized administrators can also run it in game.

Example information:

mode=json ready=true doors=12 error=none

Use this command when:

doors_dedupe

Scans the currently loaded door definitions and removes overlapping physical duplicates.

doors_dedupe

This is useful after migrating from an older build where one physical door may have been registered multiple times.

The resource also performs duplicate cleanup while loading persisted doors.

Debug Mode

Enable:

Config.Debug = true

Use it temporarily to get extra storage/persistence logging.

Disable it again after troubleshooting on production servers unless the extra logging is required.