VRS Bridge

Overview

vrs_bridge is a shared abstraction library for the vrs_ resource ecosystem. Write your gameplay code once against vrs_bridge and it runs on QBox, QBCore, or ESX, with every common inventory, target, UI, and vehicle-key system auto-detected underneath it.

3 frameworks

QBox, QBCore, and ESX, auto-detected on boot.

Inventory & target

ox / qb / qs / codem inventories, ox / qb targets.

UI systems

ox_lib, qb, or framework notify, menu, input, and progress.

10 vehicle-key systems

qbx, qb, Renewed, wasabi, qs, mk, MrNewb, jaksam, t1ger, F_RealCarKeys.

Instead of littering a resource with if QBCore then ... elseif ESX then ..., you call one stable API:

local VRS = exports.vrs_bridge
local money = VRS:GetMoney(src, 'cash')
VRS:AddItem(src, 'lockpick', 2)
VRS:Notify(data)

The bridge figures out what’s installed and routes the call.

Install

Ensure dependencies exist

QBox ships them: a framework, and ideally ox_lib (used for cross-framework notify, menu, input, progress, and callbacks).

Drop vrs_bridge into your resources folder

Place the resource in your server’s resources/ directory.

Start it before any resource that depends on it

server.cfg

ensure ox_lib
ensure oxmysql
ensure qbx_core        # or qb-core / es_extended
ensure vrs_bridge
# ... your vrs_ resources after this line

No SQL and no config required. Detection results print on boot when Config.Debug = true.

Configuration

config.lua is escrow-open. Everything is 'auto' by default, override only if detection guesses wrong:

config.lua

Config.Framework = 'auto'  -- 'qbox' | 'qbcore' | 'esx'
Config.Inventory = 'auto'  -- 'ox'   | 'qb'     | 'qs'   | 'codem'
Config.Target    = 'auto'  -- 'ox'   | 'qb'
Config.Menu      = 'auto'  -- 'ox'   | 'qb'
Config.Input     = 'auto'  -- 'ox'   | 'qb'
Config.Notify    = 'auto'  -- 'ox'   | 'framework'
Config.Progress  = 'auto'  -- 'ox'   | 'qb'

Config.Detection is an ordered list per subsystem. The first started resource wins. Add a row to support a resource we didn’t list, this file, plus shared/detect.lua, stay open after escrow specifically so you can.

API reference

Every export is called with colon syntax: exports.vrs_bridge:Fn(...).

Shared
Server
Client

GetVersion

Returns the current bridge version string (e.g. '1.0.0').

exports.vrs_bridge:GetVersion()

Returns: string

AssertVersion

Dependency check. Errors if the running bridge is older than min.

exports.vrs_bridge:AssertVersion(min)

string

required

Minimum required version, e.g. '1.0.0'.

GetFramework

Returns the detected framework id ('qbox', 'qbcore', or 'esx').

exports.vrs_bridge:GetFramework()

Returns: string

GetDetected

Returns the full detection result table (framework, inventory, target, notify, menu, input, progress, vehiclekeys).

exports.vrs_bridge:GetDetected()

Returns: table

GetPlayer

Returns the framework player object for a source.

exports.vrs_bridge:GetPlayer(src)

number

required

The player server id.

GetIdentifier

Returns the player’s citizenid (QB/QBox) or identifier (ESX).

exports.vrs_bridge:GetIdentifier(src)

number

required

The player server id.

GetLicense

Returns the account-level license:xxxx identifier, which survives character deletes.

exports.vrs_bridge:GetLicense(src)

number

required

The player server id.

GetCharacterName

Returns "First Last" for the current character, falling back to the player’s display name.

exports.vrs_bridge:GetCharacterName(src)

number

required

The player server id.

GetPlayerByIdentifier

Resolves an identifier back to a server id.

exports.vrs_bridge:GetPlayerByIdentifier(id)

string

required

A citizenid or identifier.

OnPlayerLoaded

Fires once per character session on any framework (event + safety-net poller, deduped). Already-loaded players are replayed to new subscribers. Handlers are auto-removed when your resource stops.

exports.vrs_bridge:OnPlayerLoaded(cb)

function

required

Callback function(src, identifier).

OnPlayerUnloaded

Fires on logout, character switch, or disconnect.

exports.vrs_bridge:OnPlayerUnloaded(cb)

function

required

Callback function(src, identifier).

GetJob (server)

Returns a normalised job table: { name, label, grade, gradeName, onDuty, type }.

exports.vrs_bridge:GetJob(src)

number

required

The player server id.

GetPlayersOnJob

Returns count, ids[] of players on the given job.

exports.vrs_bridge:GetPlayersOnJob(jobName, requireOnDuty)

string

required

The job name to match, e.g. "police".

boolean

If true, only count on-duty players.

GetMoney

Returns the balance for a money type.

exports.vrs_bridge:GetMoney(src, type)

number

required

The player server id.

string

required

One of "cash", "bank", "black", "crypto" (mapped per framework in Config.MoneyMap).

AddMoney

Adds money and returns success.

exports.vrs_bridge:AddMoney(src, type, amount, reason)

number

required

The player server id.

string

required

Money type: "cash", "bank", "black", "crypto".

number

required

The amount to add.

string

Optional reason logged by the framework.

RemoveMoney

Removes money and returns success.

exports.vrs_bridge:RemoveMoney(src, type, amount, reason)

number

required

The player server id.

string

required

Money type: "cash", "bank", "black", "crypto".

number

required

The amount to remove.

string

Optional reason logged by the framework.

AddItem

Gives an item to the player.

exports.vrs_bridge:AddItem(src, item, count, metadata, slot)

number

required

The player server id.

string

required

The item name.

number

required

How many to give.

table

Optional item metadata.

number

Optional inventory slot.

RemoveItem

Removes an item from the player.

exports.vrs_bridge:RemoveItem(src, item, count, metadata, slot)

number

required

The player server id.

string

required

The item name.

number

required

How many to remove.

table

Optional metadata match.

number

Optional inventory slot.

HasItem (server)

Returns bool, have: whether the player has at least count of the item, and how many they have.

exports.vrs_bridge:HasItem(src, item, count)

number

required

The player server id.

string

required

The item name.

number

Minimum required amount. Defaults to 1.

GetItemCount (server)

Returns the number of a given item the player carries.

exports.vrs_bridge:GetItemCount(src, item)

number

required

The player server id.

string

required

The item name.

CanCarry

Returns whether the player can carry count more of an item.

exports.vrs_bridge:CanCarry(src, item, count)

number

required

The player server id.

string

required

The item name.

number

required

How many to test.

RegisterCallback

Registers a server-side callback that clients can invoke via Callback.

exports.vrs_bridge:RegisterCallback(name, fn)

string

required

Callback name.

function

required

Handler function(src, ...) returning the response values.

GiveVehicleKeys

Gives keys and unlocks the vehicle via the detected key system.

exports.vrs_bridge:GiveVehicleKeys(src, vehicle)

number

required

The player server id.

number

required

A networked server entity handle.

RemoveVehicleKeys

Removes keys (best effort, not every system exposes a removal API).

exports.vrs_bridge:RemoveVehicleKeys(src, vehicle)

number

required

The player server id.

number

required

A networked server entity handle.

GetPlayerData

Returns the local player’s framework data table.

exports.vrs_bridge:GetPlayerData()

Returns: table

GetJob (client)

Returns the local player’s job table: { name, label, grade, gradeName, onDuty, type }.

exports.vrs_bridge:GetJob()

Returns: table

HasItem (client)

Returns bool, have for the local player.

exports.vrs_bridge:HasItem(item, count)

string

required

The item name.

number

Minimum required amount. Defaults to 1.

GetItemCount (client)

Returns the number of a given item in the local player’s inventory.

exports.vrs_bridge:GetItemCount(item)

string

required

The item name.

Callback

Blocking client-to-server callback.

exports.vrs_bridge:Callback(name, ...)

string

required

Callback name registered with RegisterCallback on the server.

any

Arguments forwarded to the server handler.

Notify

Shows a notification. Accepts a plain string, or an options table.

exports.vrs_bridge:Notify(data)

string | table

required

A message string, or { title, description, type, duration, position, icon }.

OpenMenu

Opens (or registers) a menu. Options support onSelect, event, serverEvent, args, arrow, disabled, readOnly, metadata. registerOnly = true re-registers without opening (refreshes a parent for ox_lib back-nav).

exports.vrs_bridge:OpenMenu(data)

table

required

{ id, title, menu, onBack, onExit, registerOnly, options[] }.

Input

Shows an input dialog using ox_lib row shapes. Returns answers[] or nil if cancelled.

exports.vrs_bridge:Input(title, rows)

string

required

Dialog title.

table

required

Array of ox_lib input row definitions.

Progress

Runs a progress bar. Returns true on completion, false if cancelled.

exports.vrs_bridge:Progress(data)

table

required

{ label, duration, canCancel, useWhileDead, disable, anim, prop }.

AddBoxZone

Adds a targetable box zone. Options are normalised to { name, label, icon, distance, canInteract, onSelect, event, serverEvent, args, items, groups }.

exports.vrs_bridge:AddBoxZone(data)

table

required

{ name, coords, size, rotation, distance, options[] }.

AddEntityZone

Adds a targetable zone bound to an entity.

exports.vrs_bridge:AddEntityZone(entity, options, distance)

number

required

The entity handle to bind to.

table

required

Target options array.

number

Interaction distance.

RemoveZone

Removes a zone by handle.

exports.vrs_bridge:RemoveZone(handle)

any

required

Handle returned from AddBoxZone or AddEntityZone.

RemoveEntityZone

Removes all zones bound to an entity.

exports.vrs_bridge:RemoveEntityZone(entity)

number

required

The entity handle previously registered with AddEntityZone.

Vehicle keys

GiveVehicleKeys(src, vehicle) / RemoveVehicleKeys(src, vehicle), server-side, vehicle must be a networked entity.

The handler maps live in the open files server/vehiclekeys.lua and client/vehiclekeys.lua. Every handler is pcall-guarded, a wrong export logs a warning, never crashes, and adding a new system is one row in Config.Detection.vehiclekeys plus one handler entry. Systems with client-only exports are relayed to the player’s client automatically.

Depending on the bridge

In your fxmanifest.lua:

fxmanifest.lua

dependency 'vrs_bridge'

At runtime, guarantee a compatible version:

CreateThread(function()
    assert(exports.vrs_bridge:GetVersion(), 'vrs_bridge not running')
    -- or hard-assert a minimum:
    -- exports.vrs_bridge:AssertVersion('1.0.0')
end)

Permanent ID

Newspaper Job

Overview

3 frameworks

Inventory & target

UI systems

10 vehicle-key systems

Install

Configuration

API reference

Vehicle keys

Depending on the bridge

​Overview

3 frameworks

Inventory & target

UI systems

10 vehicle-key systems

​Install

​Configuration

​API reference

​Vehicle keys

​Depending on the bridge

Overview

Install

Configuration

API reference

Vehicle keys

Depending on the bridge