vRP

https://vrp-framework.github.io/vRP
Admin
vRP is a framework designed for building custom servers, offering extensive configuration options,...
Tokens:20,600
Snippets:115
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Transformer Processor - Item Consumption Example

Source: https://vrp-framework.github.io/vRP/dev/index

Example configuration for the Transformer processor, specifying items to be consumed.

```lua
...
items = {
  ["edible|peach"] = 1
}
```

--------------------------------

### VRP DBDriver API: Database Operations

Source: https://vrp-framework.github.io/vRP/dev/index

Outlines the methods for implementing a database driver within VRP. Key methods include `onInit` for connection setup, `onPrepare` for query preparation, and `onQuery` for executing queries with different modes (query, execute, scalar).

```lua
-- Initialize the database connection
-- DBDriver:onInit(db_config_table)

-- Prepare a SQL query with parameter placeholders
-- DBDriver:onPrepare(query_name, sql_query_string)

-- Execute a prepared query
-- DBDriver:onQuery(query_name, parameters_map, execution_mode)
-- Modes: "query", "execute", "scalar"

```

--------------------------------

### Proxy and Tunnel Setup in VRP Extensions

Source: https://vrp-framework.github.io/vRP/dev/index

Defines how extensions can expose and access functions using the proxy and tunnel systems. Proxy is for general interface exposure, while tunnel is for direct client-server or server-client communication. Proxy interfaces are accessed via `Proxy.getInterface`, and tunnel interfaces via `self.remote` or `Tunnel.getInterface`.

```lua
-- server-side or client-side extension setup
MyExt.proxy = {}
function MyExt.proxy:getInfo()
  -- implementation
end

-- client-side specific tunnel setup
MyExt.tunnel = {}
function MyExt.tunnel:test()
  -- implementation
end

-- Accessing proxy interface from another resource
local my_ext = Proxy.getInterface("vRP.EXT.MyExt")
local info = my_ext.getInfo()

-- Accessing tunnel interface from server-side extension
function MyExt.event:playerSpawn(user, first_spawn)
  self.remote._test(user.source) -- Calls client-side tunnel function
end

-- Accessing tunnel interface from client-side extension
function MyExt.event:playerDeath()
  self.remote._test() -- Calls server-side tunnel function
end
```

--------------------------------

### User Aptitude Management

Source: https://vrp-framework.github.io/vRP/dev/index

Functions to manage user aptitudes, including getting aptitudes, varying experience, leveling up/down, and setting experience.

```lua
self.cdata.aptitudes

-- return user aptitudes table
User:getAptitudes()

-- vary experience of an aptitude
User:varyExp(group, aptitude, amount)

-- level up an aptitude
User:levelUp(group, aptitude)

-- level down an aptitude
User:levelDown(group, aptitude)

User:getExp(group, aptitude)

-- set aptitude experience
User:setExp(group, aptitude, amount)
```

--------------------------------

### User Mission System Functions

Source: https://vrp-framework.github.io/vRP/dev/index

Implements functions for the mission system, allowing users to start, progress through, and stop missions. Missions consist of steps with text, positions, areas, and optional map entities. It provides methods to start, advance, stop, and check for active missions.

```lua
self.mission
self.mission_step

-- start a mission for a player
--- mission:
----
----- name: mission name
-----
----- steps: ordered list of
-----
-----
----- text: (html)
-----
----- position: {x,y,z}
-----
----- radius: (optional) area radius (affect default PoI)
-----
----- height: (optional) area height (affect default PoI)
-----
----- onenter: see Map.User:setArea
-----
----- onleave: (optional) see Map.User:setArea
-----
----- map_entity: (optional) a simple PoI by default
User:startMission(mission)

-- end the current player mission step
User:nextMissionStep()

-- stop the player mission
User:stopMission()

-- check if the player has a mission
User:hasMission()
```

--------------------------------

### VRP Money Module User Extensions

Source: https://vrp-framework.github.io/vRP/dev/index

Provides functions for managing a user's in-game currency, including wallet and bank balances. Supports getting, setting, transferring, and attempting various financial transactions like payments, withdrawals, and deposits.

```lua
-- Accessing currency data
self.cdata.wallet
self.cdata.bank

-- Getters
User:getWallet()
User:getBank()

-- Setters
User:setWallet(amount)
User:setBank(amount)

-- Transfers
User:giveBank(amount)
User:giveWallet(amount)

-- Transaction attempts
User:tryPayment(amount, dry)
User:tryWithdraw(amount, dry)
User:tryDeposit(amount, dry)
User:tryFullPayment(amount, dry)
```

--------------------------------

### vRP Server API Functions (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side vRP functions for database interaction, user management, and data storage. It includes functions for preparing and executing SQL queries, setting and getting user, character, server, and global data, and kicking players. Database drivers can be registered.

```lua
self.cfg -- cfg/base config
self.lang -- loaded lang (https://github.com/ImagicTheCat/Luang)
self.users -- map of id => User
self.pending_users -- pending user source update (first spawn), map of ids key => user
self.users_by_source -- map of source => user
self.users_by_cid -- map of character id => user

-- db/SQL API
self.db_drivers
self.db_driver
self.db_initialized

vRP.DBDriver

-- return identification string for a specific source
vRP.getSourceIdKey(source)

vRP.getPlayerEndpoint(player)

vRP.getPlayerName(player)

-- register a DB driver
-- db_driver: DBDriver class
vRP:registerDBDriver(db_driver)

-- prepare a query
--- name: unique name for the query
--- query: SQL string with @params notation
vRP:prepare(name, query)

-- execute a query
--- name: unique name of the query
--- params: map of parameters
--- mode: default is "query"
---- "query": should return rows (list of map of parameter => value), affected
---- "execute": should return affected
---- "scalar": should return a scalar
vRP:query(name, params, mode)

-- shortcut for vRP.query with "execute"
vRP:execute(name, params)

-- shortcut for vRP.query with "scalar"
vRP:scalar(name, params)

-- user data
-- value: binary string
vRP:setUData(user_id,key,value)

vRP:getUData(user_id,key)

-- character data
-- value: binary string
vRP:setCData(character_id,key,value)

vRP:getCData(character_id,key)

-- server data
-- value: binary string
vRP:setSData(key,value,id)

vRP:getSData(key,id)

-- global data
-- value: binary string
vRP:setGData(key,value)

vRP:getGData(key)

-- reason: (optional)
vRP:kick(user, reason)

vRP:save()
```

--------------------------------

### VRP Mission Events

Source: https://vrp-framework.github.io/vRP/dev/index

Handles events related to player missions, including when a player starts, steps through, or stops a mission. These events provide access to mission data attached to the user.

```lua
playerMissionStart(user)
playerMissionStep(user)
playerMissionStop(user)
```

--------------------------------

### Player State Management: Weapons, Health, and Customization (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side functions for managing player's weapons, ammunition, armor, health, and visual customization. Includes functions to get, set, and replace weapons and their ammo, adjust armor and health levels, and modify player's appearance through drawables, textures, and overlays.

```Lua
self.state_ready

-- WEAPONS

-- get player weapons
-- return map of name => {.ammo}
PlayerState:getWeapons()

-- replace weapons (combination of getWeapons and giveWeapons)
-- weapons: map of name => {.ammo}
--- ammo: (optional)
-- return previous weapons
PlayerState:replaceWeapons(weapons)

-- weapons: map of name => {.ammo}
--- ammo: (optional)
PlayerState:giveWeapons(weapons, clear_before)

-- set player armour (0-100)
PlayerState:setArmour(amount)

PlayerState:getArmour()

-- amount: 100-200 ?
PlayerState:setHealth(amount)

PlayerState:getHealth()

-- PLAYER CUSTOMIZATION

-- get number of drawables for a specific part
PlayerState:getDrawables(part)

-- get number of textures for a specific part and drawable
PlayerState:getDrawableTextures(part,drawable)

-- get player skin customization
-- return custom parts
PlayerState:getCustomization()

-- set partial customization (only what is set is changed)
-- custom: indexed customization parts ("foo:arg1:arg2...")
--- "modelhash": number, model hash
--- or "model": string, model name
--- "drawable:<index>": {drawable,texture,palette} ped components
--- "prop:<index>": {prop_index, prop_texture}
--- "hair_color": {primary, secondary}
--- "overlay:<index>": {overlay_index, primary color, secondary color, opacity}
PlayerState:setCustomization(custom)

-- TUNNEL

PlayerState.tunnel.getWeapons = PlayerState.getWeapons
PlayerState.tunnel.replaceWeapons = PlayerState.replaceWeapons
PlayerState.tunnel.giveWeapons = PlayerState.giveWeapons
PlayerState.tunnel.setArmour = PlayerState.setArmour
PlayerState.tunnel.getArmour = PlayerState.getArmour
PlayerState.tunnel.setHealth = PlayerState.setHealth
PlayerState.tunnel.getHealth = PlayerState.getHealth
PlayerState.tunnel.getDrawables = PlayerState.getDrawables
PlayerState.tunnel.getDrawableTextures = PlayerState.getDrawableTextures
PlayerState.tunnel.getCustomization = PlayerState.getCustomization
PlayerState.tunnel.setCustomization = PlayerState.setCustomization
```

--------------------------------

### Group Management and Permissions (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side functions for managing groups and permissions. This includes retrieving users by group or permission, getting group titles, and registering custom permission checks. It interacts with the VRP server-side configuration and permission system.

```lua
self.cfg

-- return users list
Group:getUsersByGroup(name)

-- return users list
Group:getUsersByPermission(perm)

-- return title or nil
Group:getGroupTitle(group_name)

-- register a special permission function
-- name: name of the permission -> "!name.[...]"
-- callback(user, params)
--- params: params (strings) of the permissions, ex "!name.param1.param2" -> ["name", "param1", "param2"]
--- should return true or false/nil
Group:registerPermissionFunction(name, callback)
```

--------------------------------

### Home Server Properties (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Lists server-side properties for the VRP home system, including configuration, components, and available slots.

```lua
self.cfg
self.components
self.slots -- map of type => map of slot id => slot instance
```

--------------------------------

### Home Server Methods (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Provides server-side methods for managing homes, including address lookups, finding free slots, and registering components. Supports online and offline character access.

```lua
-- address access (online and offline characters)
-- return address or nil
Home:getAddress(cid)

-- return character id or nil
Home:getByAddress(home,number)

-- find a free address number to buy
-- return number or nil if no numbers availables
Home:findFreeNumber(home,max)

-- register home component
-- id: unique component identifier (string)
-- component: Home.Component derived class
Home:registerComponent(component)

-- SLOTS

-- get slot instance
-- return slot or nil
Home:getSlot(stype, sid)

-- get slot instance by address
-- return slot or nil
Home:getSlotByAddress(home, number)

-- return sid or nil
Home:findFreeSlot(stype)
```

--------------------------------

### Handle vRP Events

Source: https://vrp-framework.github.io/vRP/dev/index

Demonstrates how to listen to global vRP events by defining methods within the 'event' table of an extension. Synchronous events may require listeners to return promptly.

```lua
MyExt.event = {}

function MyExt.event:playerSpawn(user, first_spawn)
end
```

--------------------------------

### vRP Client API

Source: https://vrp-framework.github.io/vRP/dev/index

Documentation for the client-side vRP API, including configuration and events related to player actions.

```APIDOC
## vRP Client API

### Properties
- **cfg** (table) - Client configuration.

### Events
- `playerSpawn()` - Called when the player spawns.
- `playerDeath()` - Called when the player dies.
```

--------------------------------

### CSS Loading for GUI Customization (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Demonstrates how to load custom CSS files for GUI customization on the client-side using `GUI:setDiv`. This allows for detailed styling overrides and the integration of custom design files.

```lua
-- client-side
function MyExt.event:NUIready()
  vRP.EXT.GUI:addDiv("my_ext_css", LoadResourceFile("my_ext", "design.css"), "")
end
```

--------------------------------

### Audio: Playing and Managing Sound Sources (Client)

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side functions for playing one-time or looping audio sources. Supports spatialization based on 3D coordinates and optional player parentage. Also includes functions for managing named audio sources.

```lua
self.voice_channels = {} -- map of channel => map of player => state (0-1)

-- play audio source (once)
--- url: valid audio HTML url (ex: .ogg/.wav/direct ogg-stream url)
--- volume: 0-1
--- x,y,z: position (omit for unspatialized)
--- max_dist  (omit for unspatialized)
--- player: (optional) player source id, if passed the spatialized source will be relative to the player (parented)
Audio:playAudioSource(url, volume, x, y, z, max_dist, player)

-- set named audio source (looping)
--- name: source name
--- url: valid audio HTML url (ex: .ogg/.wav/direct ogg-stream url)
--- volume: 0-1
--- x,y,z: position (omit for unspatialized)
--- max_dist  (omit for unspatialized)
--- player: (optional) player source id, if passed the spatialized source will be relative to the player (parented)
Audio:setAudioSource(name, url, volume, x, y, z, max_dist, player)

-- remove named audio source
Audio:removeAudioSource(name)
```

--------------------------------

### Server Aptitude Definitions

Source: https://vrp-framework.github.io/vRP/dev/index

Functions for defining and managing aptitude groups and individual aptitudes on the server. Includes setting initial and maximum experience, and utility functions for converting experience to levels and vice versa.

```lua
self.cfg
self.exp_step
self.groups

-- define aptitude group
Aptitude:defineGroup(group, title)

-- define aptitude
-- max_exp: -1 => infinite
Aptitude:defineAptitude(group, aptitude, title, init_exp, max_exp)

-- get aptitude definition
Aptitude:getAptitude(group, aptitude)

-- get aptitude group title
-- return string
Aptitude:getGroupTitle(group)

-- convert experience to level
-- return float
Aptitude:expToLevel(exp)

-- convert level to experience
-- return integer
Aptitude:levelToExp(lvl)
```

--------------------------------

### vRP Server API

Source: https://vrp-framework.github.io/vRP/dev/index

Documentation for the server-side vRP API, including configuration, database operations, data management, and player management.

```APIDOC
## vRP Server API

### Properties
- **cfg** (table) - Base configuration.
- **lang** (table) - Loaded language configuration.
- **users** (map) - Map of user IDs to User objects.
- **pending_users** (map) - Pending user source updates.
- **users_by_source** (map) - Map of player sources to User objects.
- **users_by_cid** (map) - Map of character IDs to User objects.
- **db_drivers**
- **db_driver**
- **db_initialized** (boolean)

### Database API
- **vRP.DBDriver**
- **getSourceIdKey(source)** (string) - Returns the identification string for a specific source.
- **getPlayerEndpoint(player)**
- **getPlayerName(player)**
- **registerDBDriver(db_driver)** - Registers a database driver.
- **prepare(name, query)** - Prepares a SQL query.
- **query(name, params, mode)** - Executes a query. Modes: `query`, `execute`, `scalar`.
- **execute(name, params)** - Shortcut for `vRP.query` with `execute` mode.
- **scalar(name, params)** - Shortcut for `vRP.query` with `scalar` mode.

### Data Management
- **setUData(user_id, key, value)** - Sets user data.
- **getUData(user_id, key)** - Gets user data.
- **setCData(character_id, key, value)** - Sets character data.
- **getCData(character_id, key)** - Gets character data.
- **setSData(key, value, id)** - Sets server data.
- **getSData(key, id)** - Gets server data.
- **setGData(key, value)** - Sets global data.
- **getGData(key)** - Gets global data.

### Player Management
- **kick(user, reason)** - Kicks a user.
- **save()**

### Events
- `characterLoad(user)` (sync) - Called right after character loading.
- `characterUnload(user)` (sync) - Called before character unloading.
- `playerJoin(user)` - Called when a player joins.
- `playerRejoin(user)` - Called when a player rejoins.
- `playerDelay(user, state)` - Called when the player tunnel delay changes.
- `playerSpawn(user, first_spawn)` - Called when the player spawns.
- `playerDeath(user)` - Called when the player dies.
- `playerLeave(user)` (sync) - Called before user removal.
- `save` - Called when vRP performs a save.
```

--------------------------------

### Home Component Methods (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Defines methods for a Home component, managing its lifecycle and player interactions. Includes loading, unloading, entering, and leaving the component's slot.

```lua
-- called when the component is loaded for a specific slot
Component:load()

-- called when the component is unloaded from a specific slot
Component:unload()

-- called when a player enters the slot
Component:enter(user)

-- called when a player leaves the slot
Component:leave(user)
```

--------------------------------

### Load vRP Script

Source: https://vrp-framework.github.io/vRP/dev/index

Demonstrates how to load a script into the vRP resource context using Proxy and vRP.loadScript. This allows the script to access the vRP API. Ensure utils.lua is included in the resource manifest.

```lua
-- include @vrp/lib/utils.lua in __resource.lua (for the targeted side)

local Proxy = module("vrp", "lib/Proxy")
local vRP = Proxy.getInterface("vRP")

vRP.loadScript("my_resource", "vrp") -- load "my_resource/vrp.lua"
```

--------------------------------

### General API - Utilities

Source: https://vrp-framework.github.io/vRP/dev/index

Utility functions provided by `lib/utils.lua`, including side detection, module loading, and string manipulation.

```APIDOC
## General API - Utilities (`lib/utils.lua`)

This library defines several useful global functions.

*   **`SERVER`** (boolean): Indicates if the current environment is the server-side.
*   **`CLIENT`** (boolean): Indicates if the current environment is the client-side.
*   **`module(rsc, path)`**: Loads a Lua resource file as a module for a specific side.
    *   `rsc` (string): The resource name.
    *   `path` (string): The Lua file path without the extension.
*   **`class`**: Represents the Luaoop class system.
*   **`async(func)`**: Creates an async returner or a thread (Citizen.CreateThreadNow).
    *   `func` (function, optional): If passed, creates a thread; otherwise, returns an async returner.
*   **`tohex(str)`**: Converts a Lua string to its hexadecimal representation.
*   **`clone(t)`**: Performs a basic deep clone of a table (does not handle circular references).
*   **`parseInt(v)`**: Parses a value into an integer.
*   **`sanitizeString(str, strchars, allow_policy)`**: Removes characters not allowed or disabled by `strchars`.
    *   `str` (string): The input string.
    *   `strchars` (string): Characters to consider for policy.
    *   `allow_policy` (boolean): If true, allows all `strchars`; if false, allows everything except `strchars`.
*   **`splitString(str, sep)`**: Splits a string by a separator.
    *   `str` (string): The string to split.
    *   `sep` (string): The separator character.
```

--------------------------------

### VRP PedBlacklist Client Configuration

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side configuration for the PedBlacklist module, managing the mapping of ped model hashes and the interval for checking/applying the blacklist.

```lua
self.ped_models -- map of model hash
self.interval
```

--------------------------------

### Home Slot Methods (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Provides methods for interacting with a home slot. Includes checking if the slot is empty.

```lua
Slot:isEmpty()
```

--------------------------------

### Define vRP Extension

Source: https://vrp-framework.github.io/vRP/dev/index

Shows how to define a vRP extension by creating a class that extends vRP.Extension. Loaded extensions are accessible via the vRP instance, enabling direct method calls.

```lua
local MyExt = class("MyExt", vRP.Extension)

-- Loaded extensions are accessibles through the vRP instance:
vRP.EXT.MyExt:test()
```

--------------------------------

### VRP General API: Utility Functions (lib/utils.lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Provides a collection of essential global utility functions available in the VRP framework via `lib/utils.lua`. These include side detection (SERVER, CLIENT), module loading, class creation, asynchronous function execution, string manipulation, and data cloning.

```lua
-- Side detection
-- SERVER -- boolean
-- CLIENT -- boolean

-- Load Lua resource file as module
-- module(resource_name, file_path_without_extension)

-- Class definition and instantiation
-- class -- Luaoop class

-- Create async returner or thread
-- async(function_to_run)

-- String manipulation and conversion
-- tohex(str)
-- sanitizeString(str, strchars, allow_policy)
-- splitString(str, separator)

-- Data manipulation
-- clone(table) -- basic deep clone
-- parseInt(value)

```

--------------------------------

### User Object API

Source: https://vrp-framework.github.io/vRP/dev/index

Documentation for the User object, its properties, and associated methods for managing characters and user state.

```APIDOC
## User Object API

### Properties
- **source**
- **name** (string) - FiveM name (may be steam name)
- **id**
- **cid** (string) - character id
- **endpoint** (string) - FiveM endpoint
- **data** - user data
- **cdata** - character data
- **loading_character** (boolean) - flag
- **use_character_action** (number) - action delay
- **spawns** (number) - spawn count

### Methods
- **isReady()** (boolean) - Returns true if the user character is ready (loaded, not loading).
- **save()**
- **getCharacters()** (table) - Returns a list of character IDs.
- **createCharacter()** (string or nil) - Returns the created character ID or nil if failed.
- **useCharacter(id)** (boolean, number) - Attempts to use a character. Returns true or false, and an error code.
  - **Error Codes:**
    - 1: delay error, too soon
    - 2: already loading
    - 3: invalid character
- **deleteCharacter(id)** (boolean) - Deletes a character. Returns true or false on failure.
```

--------------------------------

### VRP Interface Function Call Conventions

Source: https://vrp-framework.github.io/vRP/dev/index

Describes how to call functions through VRP interfaces, differentiating between synchronous and asynchronous calls, and highlighting conventions for tunnel server-side calls. Underscore prefixes denote asynchronous calls or ignoring return values.

```lua
-- PROXY: Any side, TUNNEL: Client-side calls to Server or Server-side calls to Client

-- Synchronous call (waits for return values)
-- interface.function_name(arguments...)

-- Asynchronous call (does not wait for return values)
-- interface._function_name(arguments...)

-- TUNNEL Server-side specific call (requires player source)
-- interface.function_name(player_source, arguments...)
-- interface._function_name(player_source, arguments...) -- ignores return values

```

--------------------------------

### Home User Methods (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Defines methods for user interactions within the VRP home system. Allows users to access and leave homes.

```lua
-- access a home by address
-- return true on success
User:accessHome(home, number)

User:leaveHome()

-- check if inside a home
User:inHome()
```

--------------------------------

### Aptitude Module API

Source: https://vrp-framework.github.io/vRP/dev/index

API documentation for the Aptitude module, which adds aptitudes and experience (skill/education) system.

```APIDOC
## Aptitude Module API

### Extension
This module adds aptitudes and experience (skill/education).
```

--------------------------------

### vRP Shared API

Source: https://vrp-framework.github.io/vRP/dev/index

Documentation for the shared vRP API, including extension management, event triggering, and logging functions available on both client and server.

```APIDOC
## vRP Shared API

### Properties
- **EXT** (map) - Map of extension names to extension instances.
- **modules** (table) - Configuration for modules.

### Methods
- **vRP.Extension**
- **registerExtension(extension)** - Registers an extension class.
- **triggerEvent(name, ...)** - Triggers an event asynchronously for each listener.
- **triggerEventSync(name, ...)** - Triggers an event and waits for all listeners to complete.
- **log(msg, suffix, level)** - Logs a message. `suffix` is optional, `level` defaults to 0.
- **error(msg, suffix)** - Logs an error message. `suffix` is optional.

### Events
- `extensionLoad(extension)`: Called when an extension is loaded, passing the extension instance.
```

--------------------------------

### Server Configuration Properties (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Common server-side configuration property found in multiple VRP modules, such as home_components and general extensions.

```lua
self.cfg
```

--------------------------------

### Admin Module API

Source: https://vrp-framework.github.io/vRP/dev/index

API documentation for the Admin module, providing functionalities for administration menus and actions.

```APIDOC
## Admin Module API

### Extension
#### Client
- **Admin:toggleNoclip()**
- **Admin:teleportToMarker()**

**Tunnel Mappings:**
- `Admin.tunnel.toggleNoclip = Admin.toggleNoclip`
- `Admin.tunnel.teleportToMarker = Admin.teleportToMarker`

### Menu
- **admin**: Administration menu.
- **admin.users**: Administration sub-menu for user list.
- **admin.users.user**: Administration sub-menu for user details.

#### Data
- **id** (number) - User ID (offline or online).
```

--------------------------------

### User GUI Interaction (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Functions for user-specific GUI interactions, including menu management and input prompts. Allows opening, closing, and updating menus, as well as prompting the user for text input or simple yes/no confirmation. Requires the VRP framework.

```lua
self.menu_stack -- stack of menus
self.request_ids
self.requests

-- return current menu or nil
User:getMenu()

-- open menu (build and open menu)
-- data: (optional) menu build data
-- return menu
User:openMenu(name, data)

-- close menu
-- menu: (optional) menu to close, if nil, will close the current menu
User:closeMenu(menu)

-- close and rebuild current menu (no remove)
-- menu is rebuilt, listeners are kept
User:actualizeMenu()

-- close all menus
User:closeMenus()

-- prompt textual (and multiline) information from player
-- return entered text
User:prompt(title, default_text)

-- REQUEST

-- ask something to a player with a limited amount of time to answer (yes|no request)
-- time: request duration in seconds
-- return true (yes) or false (no)
User:request(text, time)
```

--------------------------------

### PoI Map Entity Configuration and Commands

Source: https://vrp-framework.github.io/vRP/dev/index

Describes the configuration options and commands for the PoI (Point of Interest) map entity. PoI entities are generic blips/markers with various customization options for appearance and behavior, inheriting from Map.PosEntity.

```lua
config
blip_id, blip_color  |  (optional) blip id/color (ex: https://wiki.gtanet.work/index.php?title=Blips)
---
blip_scale  |  (optional) float
blip_flashes  |  (optional) mode number `1` or `2` (flashes or flashes alternate)
title  |  (optional) title (used for the blip)
marker_id  |  (optional) marker id (ex: https://wiki.gtanet.work/index.php?title=Marker)
scale  |  (optional) `{sx,sy,sz}` marker scale
color  |  (optional) `{r,g,b,a}` marker color
height  |  (optional) marker height
rotate_speed  |  (optional) number of z-axis rotations per second

commands
`setBlipRoute()` |  set player blip route to `PoI` blip
```

--------------------------------

### PlayerState API

Source: https://vrp-framework.github.io/vRP/dev/index

API endpoints for managing the player's state, including customization, weapons, health, and armor.

```APIDOC
## PlayerState API

### Description
This module handles the overall state of the player character, encompassing aspects such as customization, inventory (weapons), health, and armor. It also provides events for tracking the loading and updating of the player's state.

### Events

- **`playerStateLoaded(user)`**: Called when the player's state loading process is complete.
- **`playerStateUpdate(user, state)`**: Called when the player's state is updated. The `state` parameter is read-only and may represent a partial update of properties.
```

--------------------------------

### Proxy and Tunnel Interfaces

Source: https://vrp-framework.github.io/vRP/dev/index

Defines how extensions can listen to proxy/tunnel calls and how to access these interfaces from other resources.

```APIDOC
## Proxy and Tunnel

### Proxy

Extensions can define methods in the `proxy` table to listen to proxy calls.

```lua
MyExt.proxy = {}
function MyExt.proxy:getInfo()
end
```

The generated proxy interface can be accessed from other resources using `Proxy.getInterface`.

```lua
local my_ext = Proxy.getInterface("vRP.EXT.MyExt")
local info = my_ext.getInfo()
```

**Note:** Extensions should not use proxy between themselves.

### Tunnel

Extensions can define methods in the `tunnel` table to listen to tunnel calls.

```lua
-- client-side
MyExt.tunnel = {}
function MyExt.tunnel:test()
end
```

The tunnel interface is accessible from the client-side or server-side extension through the `remote` table.

```lua
-- server-side
function MyExt.event:playerSpawn(user, first_spawn)
  self.remote._test(user.source)
end

-- client-side
function MyExt.event:playerDeath()
  self.remote._test()
end
```

### Proxy and Tunnel API

#### Proxy API

*   **`Proxy.addInterface(name, itable)`**: Adds an event handler to call interface functions.
    *   `name` (string): The interface name.
    *   `itable` (table): The table containing functions.
*   **`Proxy.getInterface(name, identifier)`**: Gets a proxy interface.
    *   `name` (string): The interface name.
    *   `identifier` (string, optional): A unique string to identify this proxy interface access; defaults to the resource name if nil.

#### Tunnel API

*   **`Tunnel.setDestDelay(dest, delay)`**: Sets the base delay between Triggers for a destination.
    *   `dest` (player source): The destination player.
    *   `delay` (number): Delay in milliseconds (0 for instant trigger).
*   **`Tunnel.bindInterface(name, interface)`**: Binds an interface to listen to network requests.
    *   `name` (string): The interface name.
    *   `interface` (table): The table containing functions.
*   **`Tunnel.getInterface(name, identifier)`**: Gets a tunnel interface to send requests.
    *   `name` (string): The interface name.
    *   `identifier` (string, optional): A unique string to identify this tunnel interface access; defaults to the resource name if nil.

### Interface Usage

*   Interface defined function names should not start with an underscore (`_`).
*   Server-side tunnel calls require the player source as the first parameter.
*   The global `source` can be used in server-side called functions to get the remote player source.
*   Using an underscore (`_`) to call a remote function interface ignores returned values.

```lua
-- PROXY any side, TUNNEL client-side

-- Call and wait for returned values
-- ...: arguments
-- return values
interface.func(...)

-- Call without waiting
-- ...: arguments
interface._func(...)

-- TUNNEL server-side

-- Call and wait for returned values
-- ...: arguments
-- return values
interface.func(player, ...) -- or _func to ignore returned values
```
```

--------------------------------

### User Class Methods (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Provides methods for managing user sessions, characters, and checking readiness. Includes functions for saving, retrieving character lists, creating, using, and deleting characters. User data and character data are accessed via `self.data` and `self.cdata` respectively.

```lua
self.source
self.name -- FiveM name (may be steam name)
self.id
self.cid -- character id
self.endpoint -- FiveM endpoint
self.data -- user data
self.cdata -- character data
self.loading_character -- flag
self.use_character_action -- action delay
self.spawns -- spawn count

-- return true if the user character is ready (loaded, not loading)
User:isReady()

User:save()

-- return characters id list
User:getCharacters()

-- return created character id or nil if failed
User:createCharacter()

-- use character
-- return true or false, err_code
-- err_code:
--- 1: delay error, too soon
--- 2: already loading
--- 3: invalid character
User:useCharacter(id)

-- delete character
-- return true or false on failure
User:deleteCharacter(id)
```

--------------------------------

### Permission System - Item Amount Comparison

Source: https://vrp-framework.github.io/vRP/dev/index

Defines a permission format for comparing item amounts in a player's inventory.

```plaintext
`!item.<fullid>.<op>`
fullid  |  item fullid  
---
op  |  >x, <x, x (equal) amount  
Examples
`!item.edible|tacos.>0` |  one or more tacos  
---
`!item.dirty_money.0` |  no dirty money  
```

--------------------------------

### Audio: VoIP Client Functions

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side functions for managing Voice over IP connections. Includes connecting/disconnecting to other players within specific channels and controlling the speaking state.

```lua
-- VoIP

-- create connection to another player for a specific channel
Audio:connectVoice(channel, player)

-- delete connection to another player for a specific channel
-- player: nil to disconnect from all players
Audio:disconnectVoice(channel, player)

-- enable/disable speaking for a specific channel
--- active: true/false
Audio:setVoiceState(channel, active)

Audio:isSpeaking()
```

--------------------------------

### vRP Garage Module: Client Functions (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Comprehensive client-side functions for managing owned vehicles. This includes spawning, despawning, retrieving vehicle information, checking proximity, and controlling vehicle states and customizations. Also includes vehicle command functions for actions like opening doors and toggling engines.

```lua
self.vehicles -- map of vehicle model => veh id (owned vehicles)
self.hash_models -- map of hash => model

-- veh: vehicle game id
-- return owner character id and model or nil if not managed by vRP
Garage:getVehicleInfo(veh)

-- spawn vehicle (will despawn first)
-- will be placed on ground properly
-- one vehicle per model allowed at the same time
--
-- state: (optional) vehicle state (client)
-- position: (optional) {x,y,z}, if not passed the vehicle will be spawned on the player (and will be put inside the vehicle)
-- rotation: (optional) quaternion {x,y,z,w}, if passed with the position, will be applied to the vehicle entity
Garage:spawnVehicle(model, state, position, rotation)

-- return true if despawned
Garage:despawnVehicle(model)

Garage:despawnVehicles()

-- get all game vehicles
-- return list of veh
Garage:getAllVehicles()

-- return map of veh => distance
Garage:getNearestVehicles(radius)

-- return veh
Garage:getNearestVehicle(radius)

Garage:trySpawnOutVehicles()

-- try re-own vehicles
Garage:tryOwnVehicles()

-- cleanup invalid owned vehicles
Garage:cleanupVehicles()

Garage:fixNearestVehicle(radius)

Garage:replaceNearestVehicle(radius)

-- return model or nil
Garage:getNearestOwnedVehicle(radius)

-- return ok,x,y,z
Garage:getAnyOwnedVehiclePosition()

-- return x,y,z or nil
Garage:getOwnedVehiclePosition(model)

Garage:putInOwnedVehicle(model)

-- eject the ped from the vehicle
Garage:ejectVehicle()

Garage:isInVehicle()

-- return model or nil if not in owned vehicle
Garage:getInOwnedVehicleModel()

-- VEHICLE STATE

Garage:getVehicleCustomization(veh)

-- partial update per property
Garage:setVehicleCustomization(veh, custom)

Garage:getVehicleState(veh)

-- partial update per property
Garage:setVehicleState(veh, state)

-- VEHICLE COMMANDS

Garage:vc_openDoor(model, door_index)

Garage:vc_closeDoor(model, door_index)

Garage:vc_detachTrailer(model)

Garage:vc_detachTowTruck(model)

Garage:vc_detachCargobob(model)

Garage:vc_toggleEngine(model)

-- return true if locked, false if unlocked
Garage:vc_toggleLock(model)
```

--------------------------------

### Inventory Module - Server-Side Functions

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side functions for defining, computing, and managing items and chests within the inventory system.

```lua
self.cfg
self.items -- item definitions
self.computed_items -- computed item definitions
self.chests -- loaded chests

-- define an inventory item (parametric or plain text data)
-- id: unique item identifier (string, no "." or "|")
-- name: display name, value or genfunction(args)
-- description: value or genfunction(args) (html)
-- menu_builder: (optional) genfunction(args, menu)
-- weight: (optional) value or genfunction(args)
--
-- genfunction are functions returning a correct value as: function(args, ...)
-- where args is a list of {base_idname,args...}
Inventory:defineItem(id,name,description,menu_builder,weight)

-- compute item definition (cached)
-- return computed item or nil
-- computed item {}
--- name
--- description
--- weight
--- menu_builder: can be nil
--- args: parametric args
Inventory:computeItem(fullid)

-- compute weight of a list of items (in inventory/chest format)
Inventory:computeItemsWeight(items)

-- load global chest
-- id: identifier (string)
-- return chest (as inventory, map of fullid => amount)
Inventory:loadChest(id)

-- unload global chest
-- id: identifier (string)
Inventory:unloadChest(id)
```

--------------------------------

### VRP Phone Module Server Function

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side function to broadcast service alerts to all listening services. It includes parameters for the sender, service name, location coordinates, and a message.

```lua
-- Send a service alert to all service listeners
-- sender: user or nil (optional, if not nil, it is a call request alert)
-- service_name: service name
-- x,y,z: coordinates
-- msg: alert message
Phone:sendServiceAlert(sender,service_name,x,y,z,msg)
```

--------------------------------

### Inventory Module - User (Client) Functions

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side functions for interacting with the player's inventory, including checking, giving, taking, and opening chests.

```lua
self.cdata.inventory

-- return map of fullid => amount
User:getInventory()

-- try to give an item
-- dry: if passed/true, will not affect
-- return true on success or false
User:tryGiveItem(fullid,amount,dry,no_notify)

-- try to take an item from inventory
-- dry: if passed/true, will not affect
-- return true on success or false
User:tryTakeItem(fullid,amount,dry,no_notify)

-- get item amount in the inventory
User:getItemAmount(fullid)

-- return inventory total weight
User:getInventoryWeight()

-- return maximum weight of inventory
User:getInventoryMaxWeight()

User:clearInventory()

-- open a chest by identifier (GData)
-- cb_close(id): called when the chest is closed (optional)
-- cb_in(chest_id, fullid, amount): called when an item is added (optional)
-- cb_out(chest_id, fullid, amount): called when an item is taken (optional)
-- return chest menu or nil
User:openChest(id, max_weight, cb_close, cb_in, cb_out)
```

--------------------------------

### Audio: Registering Voice Channels (Server)

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side function to register voice channels for VoIP communication. Allows configuration of effects like spatialization and biquad filters.

```lua
self.cfg
self.channels -- map of id => {index, config} (available after the first player connection)

-- register VoIP channel
-- all channels should be registered before any player joins the server
--
-- id: channel name/id (string)
-- config:
--- effects: map of name => true/options
---- spatialization => { max_dist: ..., rolloff: ..., dist_model: ..., ref_dist: ...} (per peer effect)
---- biquad => { frequency: ..., Q: ..., type: ..., detune: ..., gain: ...} see WebAudioAPI BiquadFilter
----- freq = 1700, Q = 3, type = "bandpass" (idea for radio effect)
---- gain => { gain: ... }
Audio:registerVoiceChannel(id, config)
```

--------------------------------

### vRP Core Shared Functions (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Core vRP shared functionalities including extension management, event triggering, and logging. Extensions can be registered using `vRP:registerExtension`, and events can be triggered synchronously or asynchronously. Logging functions like `vRP:log` and `vRP:error` are available.

```lua
self.EXT -- map of name => ext
self.modules -- cfg/modules

vRP.Extension

-- register an extension
-- extension: Extension class
vRP:registerExtension(extension)

-- trigger event (with async call for each listener)
vRP:triggerEvent(name, ...)

-- trigger event and wait for all listeners to complete
vRP:triggerEventSync(name, ...)

-- msg: log message
-- suffix: (optional) category, string
-- level: (optional) level, 0 by default
vRP:log(msg, suffix, level)

-- msg: error message
-- suffix: optional category, string
vRP:error(msg, suffix)
```

--------------------------------

### Server-Side Survival Configuration and Events

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side configuration and event handling for the Survival module. 'self.cfg' holds general configuration, and 'self.vitals' registers the vitals. Events 'playerVitalChange' and 'playerVitalOverflow' are emitted when player vitals change or overflow.

```lua
self.cfg
self.vitals -- registered vitals, map of name => {default_value}

Events
`playerVitalChange(user, name)` |  called when a player vital value changes  
`playerVitalOverflow(user, name, overflow)` |  called when a player vital overflows (overflow can be negative or positive)
```

--------------------------------

### Transformer Module Server-Side API

Source: https://vrp-framework.github.io/vRP/dev/index

Server-side interface for the Transformer module. Allows registration of processors ('registerProcessor') with display, check, and process callbacks. Transformers can be added ('set') or removed ('remove') with detailed configurations including recipes, units, and event callbacks.

```lua
self.cfg
self.transformers -- map of id => transformer
self.processors -- registered processors, map of id => {on_display, on_check, on_process}

-- register a transformer processor
-- on_display(user, reagents, products): should return r_info, p_info (two html strings to display info about the reagents and products)
-- on_check(user, reagents, products): should return true if the processing can occur
-- on_process(user, reagents, products): should process the transformation
-- for the three callbacks:
--- reagents: reagents data, can be nil
--- products: products data, can be nil
Transformer:registerProcessor(id, on_display, on_check, on_process)

-- add a transformer
-- id: transformer identitifer (string)
-- cfg: transformer config
--- title
--- color {r,g,b} (255)
--- max_units
--- units_per_minute
--- pos {x,y,z}
--- radius,height (area properties)
--- permissions: (optional)
--- recipes: map of recipe name => recipe {}
---- description (html)
---- reagents: map of processor id => data, see modules transformer processors
---- products: map of processor id => data, see modules transformer processors
---- permissions: (optional) recipe permissions
---- onstart(transformer, user, recipe_name): (optional) called when the recipe starts
---- onstep(transformer, user, recipe_name): (optional) called at each recipe step
---- onstop(transformer, user, recipe_name): (optional) called when the recipe stops
Transformer:set(id, cfg)

-- remove a transformer
Transformer:remove(id)
```

--------------------------------

### GUI Menu Extension (Lua)

Source: https://vrp-framework.github.io/vRP/dev/index

Client-side and server-side functions for managing GUI menus. Client-side allows adding and updating menu options, while server-side enables registering menu builders and controlling menu display through tunnels. Requires the VRP GUI module.

```lua
self.user
self.name
self.data
self.title
self.options
self.css
self.closed

-- dispatcher events:
--- close(menu)
--- remove(menu)
--- select(menu, id)
Menu:listen(name, callback)

-- add option
-- title: option title (html)
-- action(menu, value, mod, index): (optional) select callback
--- value: option value
--- mod: action modulation
---- -1: left
---- 0: valid
---- 1: right
-- description: (optional) option description (html)
--- callback(menu, value): should return a string or nil
-- value: (optional) option value, can be anything, option index by default
-- index: (optional) by default the option is added at the end, but an index can be used to insert the option
Menu:addOption(title, action, description, value, index)

-- update menu option
-- title: (optional) as Menu:addOption
-- description: (optional) as Menu:addOption
-- will trigger client update if current menu
Menu:updateOption(id, title, description)
```

```lua
self.cfg
self.menu_builders -- map of name => callbacks list

-- register a menu builder function
-- name: menu type name
-- builder(menu): callback to modify the menu
GUI:registerMenuBuilder(name, builder)

-- TUNNEL

-- open the general player menu
GUI.tunnel:openMainMenu()

-- can be used to implement a custom menu

GUI.tunnel:closeMenu()
GUI.tunnel:triggerMenuOption(id, mod)
GUI.tunnel:triggerMenuSelect(id)
```
Tokens:
Raw