Exports reference

Everything vns-core does is available to your own resources as exports. This page lists every client and server export in vns-core 1.0.0 with its parameters and return values.

Calling vns-core

You can call exports directly:

local job = exports['vns-core']:GetPlayerJob(source)

Or import the bridge file, which gives you the same functions on a VNS table:

-- fxmanifest.lua
shared_scripts {
    '@vns-core/shared/bridge.lua',
}

-- anywhere in your resource
local job = VNS.GetPlayerJob(source)

Every VNS.<Name>(...) call forwards to exports['vns-core']:<Name>(...), so the names, parameters and return values below apply to both styles. Your resource must start after vns-core.

Note

When vns-core found no framework, inventory or target system, the exports in that group return a safe default instead of erroring: nil, 0, false or an empty table, as noted per export.

Shared data shapes

Player data (returned by GetPlayerData):

{
    source     = 1,                -- server id
    identifier = 'ABC12345',       -- citizenid (QBCore/QBox) or identifier (ESX)
    name       = 'John Doe',       -- character name
    job = {
        name       = 'police',
        label      = 'Police',
        grade      = 2,            -- grade level number
        gradeLabel = 'Sergeant',
        isboss     = false,        -- ESX: true when grade_name == 'boss'
        onduty     = true,         -- ESX: always true
    },
}

Money types: 'cash' and 'bank'. On QBCore/QBox the value is used as the money key, so other types your framework has (for example 'crypto') work too. On ESX, 'cash' is the player's money and any other value is the bank account.

Identity

Side	Export	Parameters	Returns
Client	`GetPlayerData()`	none	Player data table, or `nil` until the character is loaded
Server	`GetPlayerData(source)`	server id	Player data table, or `nil`
Client	`GetIdentifier()`	none	This player's identifier, or `nil` until loaded
Server	`GetIdentifier(source)`	server id	Identifier, or `nil`
Server	`GetPlayerName(source)`	server id	Character name, or `nil`
Server	`GetSourceFromIdentifier(identifier)`	identifier	Server id of the online player with that identifier, or `nil`
Server	`GetDisplayName(identifier)`	identifier	Character name for online or offline players (offline names are read from the framework's database and cached). Returns the identifier itself if no name was found
Server	`GetMetadata(source, key)`	server id, metadata key	The metadata value, or `nil`. ESX needs Legacy 1.9+ (`xPlayer.getMeta`)
Server	`IsAdmin(source)`	server id	`true` if the player has the ace in `Config.AdminAce`

Jobs

Side	Export	Parameters	Returns
Client	`GetPlayerJob()`	none	The `job` table from player data, or `nil`
Server	`GetPlayerJob(source)`	server id	The `job` table, or `nil`
Client	`IsPlayerBoss()`	none	boolean
Server	`IsPlayerBoss(source)`	server id	boolean
Server	`CreateJob(name, label, grades)`	job name, job label, grades array	`true`, or `false, reason`
Server	`UpdateJob(name, label, grades)`	same as `CreateJob`	same as `CreateJob`
Server	`DeleteJob(name)`	job name	`true`, or `false, reason`
Server	`SetPlayerJob(source, jobName, grade)`	server id, job name, grade number	Framework result (`true`/`false`)
Server	`SetDuty(source, onDuty)`	server id, boolean	`true`, or `false` if the player isn't found

grades is an array in display order, where the first entry becomes grade 0:

{
    { label = 'Trainee', payment = 50 },
    { label = 'Worker',  payment = 100 },
    { label = 'Owner',   payment = 200, isboss = true },
}

QBCore / QBox: the job is added at runtime through the framework's AddJob / RemoveJob functions (or its shared jobs table as a fallback). It is not written to your jobs file.
ESX: the job is written to the jobs and job_grades tables and added to ESX.Jobs so it works without a restart. The first grade flagged isboss gets the grade name boss; other grade names are derived from the label. DeleteJob removes the rows again.

Money

Side	Export	Parameters	Returns
Client	`GetMoney(moneyType)`	money type	number (`0` if unknown)
Server	`GetMoney(source, moneyType)`	server id, money type	number (`0` if unknown)
Server	`AddMoney(source, moneyType, amount)`	server id, money type, amount	`true` on success
Server	`RemoveMoney(source, moneyType, amount)`	server id, money type, amount	QBCore/QBox: the framework's result (`false` if the player can't afford it). ESX: `true`

Warning

On ESX, RemoveMoney does not check the balance first. Check GetMoney yourself before charging a player.

Items

Side	Export	Parameters	Returns
Server	`AddItem(source, item, count, metadata)`	server id, item name, amount, optional metadata table	Inventory result (truthy on success)
Server	`RemoveItem(source, item, count, metadata)`	server id, item name, amount, optional metadata	Inventory result (truthy on success)
Client	`GetItemCount(item)`	item name	number
Server	`GetItemCount(source, item)`	server id, item name	number
Client	`HasItem(item, count)`	item name, amount (default 1)	boolean
Server	`HasItem(source, item, count)`	server id, item name, amount (default 1)	boolean
Server	`CanCarryItem(source, item, count)`	server id, item name, amount	boolean. `true` when the inventory has no carry check
Server	`GetItemLabel(item)`	item name	Label string, or the item name if the inventory doesn't provide labels
Server	`GetItems()`	none	`{ [name] = { name, label } }` for every item definition (from the inventory, or the framework's shared items)
Server	`GetPlayerItems(source)`	server id	`{ [name] = { name, label, count } }`, counts summed across slots
Server	`RegisterUsableItem(item, callback)`	item name, `function(source, itemName, itemData)`	`true`, or `false, reason`. `itemData` is only passed on QBCore/QBox
Both	`GetItemImagePath()`	none	Base path for item icons (see `Config.ItemImagePath`)

Items whose name starts with weapon_ are handled as weapons on ESX's built-in inventory.

Stashes

Side	Export	Parameters	Returns
Server	`RegisterStash(stashId, label, slots, weight)`	id, label, slots (default 50), max weight (default 100000)	nothing
Client	`OpenStash(stashId, opts)`	id, `{ label, slots, weight }`	nothing
Server	`OpenStash(source, stashId, opts)`	server id, id, `{ label, slots, weight }`	nothing
Server	`StashHasItems(stashId)`	id	boolean

Opening a stash registers it first where the inventory needs that, so you normally don't need to call RegisterStash yourself. ESX's built-in inventory has no stashes: opening one shows the player an error notification.

Vehicles

Side	Export	Parameters	Returns
Client	`SpawnVehicle(model, coords, heading, cb)`	model name or hash, `vector3`, heading, optional `function(vehicle)`	Networked vehicle handle. Waits for the model to load, so call it from a thread
Client	`DeleteVehicle(vehicle)`	vehicle handle	nothing
Server	`GiveVehicle(source, model, plate)`	server id, model name, optional plate	The plate on success, `nil` on failure. A free unique plate is generated when `plate` is `nil`
Server	`GetOwnedVehicles(source)`	server id	`{ { plate, model }, ... }`
Server	`IsVehicleOwner(source, plate)`	server id, plate	boolean (trailing spaces ignored)
Server	`IsVehicleOwned(plate)`	plate	`true` if any player, online or offline, owns that plate
Server	`GeneratePlate()`	none	A plate like `ABC 1234` that no owned vehicle uses

GiveVehicle writes to player_vehicles (QBCore/QBox) or owned_vehicles (ESX).

Targeting

All target exports are client-side.

Export	Parameters	Returns
`AddSphereZone(opts)`	`{ coords, radius, debug, options }`	Zone id, or `nil` if no target system
`AddBoxZone(opts)`	`{ coords, size, rotation, debug, options }` (`size` is a `vector3`)	Zone id, or `nil`
`RemoveZone(zoneId)`	zone id	nothing
`AddEntityTarget(entity, options)`	entity handle, options array	nothing
`RemoveEntityTarget(entity)`	entity handle	nothing

Each entry in options:

Field	Description
`icon`	Font Awesome icon, e.g. `'fas fa-box'`
`label`	Text shown in the target menu
`distance`	Interaction distance. On qb-target/qtarget one distance applies to the whole zone or entity (default 2.5)
`canInteract`	Optional function returning a boolean
`onSelect`	Function called when the option is chosen
`job`	Optional job restriction, passed to the target system (`groups` on ox_target)

local zone = VNS.AddSphereZone({
    coords = vec3(100.0, 200.0, 30.0),
    radius = 1.5,
    options = {
        {
            icon = 'fas fa-box',
            label = 'Open locker',
            distance = 2.0,
            onSelect = function() VNS.OpenStash('my_locker', { slots = 20, weight = 50000 }) end,
        },
    },
})

Note

The arguments onSelect receives differ between target systems. If you need the entity or coordinates, capture them in the surrounding code instead of reading them from the callback arguments.

Notifications / UI

Side	Export	Parameters	Returns
Client	`Notify(opts)`	`{ title, description, type, duration }`	nothing
Server	`Notify(source, opts)`	server id, same `opts`	nothing
Client	`Progressbar(opts)`	see below	`true` if completed, `false` if cancelled

Notify options: description (or message), optional title, type ('inform' by default; 'success' and 'error' are the common others) and duration in ms (default 5000). Where the notification appears follows Config.NotifySystem. QBCore/QBox notifications don't show the title; ESX shows it as Title: description.

Progressbar options (uses ox_lib's progress bar):

Field	Default	Description
`duration`	`3000`	Length in ms
`label`	`'Please wait...'`	Text
`canCancel`	`true`	Whether the player can cancel
`disable`	move, car and combat disabled; mouse enabled	Table with `move`, `car`, `combat`, `mouse` booleans
`anim`	none	ox_lib animation table
`prop`	none	ox_lib prop table

Misc

Side	Export	Parameters	Returns
Both	`GetFrameworkName()`	none	`'qbcore'`, `'qbox'`, `'esx'` or `nil`
Both	`GetInventoryName()`	none	Inventory name as used in `Config.Inventory`, or `nil`
Both	`GetTargetName()`	none	`'ox_target'`, `'qb-target'`, `'qtarget'` or `nil`
Client	`GetNearbyPlayers(distance)`	radius (default 5.0)	`{ { serverId, name, dist }, ... }`, excluding yourself
Server	`GetNearbyPlayers(source, distance)`	server id, radius (default 5.0)	`{ { source, name, dist }, ... }`, excluding the source player

name in GetNearbyPlayers is the FiveM player name, not the character name.

Event: `vns-core:playerLoaded`

A server-side event fired once a player's character has loaded, whatever framework you run. Use it for initial syncs:

AddEventHandler('vns-core:playerLoaded', function(src)
    local identifier = VNS.GetIdentifier(src)
    -- send this player their data
end)

The client announces itself as soon as its framework player data has an identifier, and again on QBCore:Client:OnPlayerLoaded / esx:playerLoaded (for example after a character switch). Repeats within 5 seconds are ignored, but your handler can still run more than once per session, so keep it safe to repeat.