vRP

https://vrp-framework.github.io/vRP/dev/
Admin
vRP is a developer framework providing an API and structure for creating extensions and modules,...
Tokens:22,105
Snippets:112
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### vRP Extension Proxy and Tunnel Setup

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

Defines how extensions can listen to proxy/tunnel calls by implementing methods in the `proxy` or `tunnel` tables. The generated proxy interface is accessible via `Proxy.getInterface`.

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

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

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

### Mission System for Players (VRP Client)

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

Provides client-side functions for managing player missions, including starting missions with steps, progressing through steps, and stopping missions. Supports defining mission text, positions, and areas.

```lua
self.mission
self.mission_step

User:startMission(mission)

User:nextMissionStep()

User:stopMission()

User:hasMission()
```

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

### GUI CSS Customization (Lua)

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

Example of how to add custom CSS to the GUI using `GUI:setDiv`. This allows for overriding default styles or loading external CSS files like `design.css`.

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

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

### Transformer Processor - Item Definition Example (Lua)

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

Illustrates the configuration format for items consumed and produced by the transformer component. It shows a Lua table representing items and their amounts, using a string key for the item's full ID.

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

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

### VRP Money Module Example (Lua)

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

Illustrates how to define and use money amounts within the VRP framework. Typically used for transactions or defining values.

```lua
...
money = 200
...
```

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

### Player State Management - VRP Client

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

Manages player weapons, armor, health, and customization. Includes functions to get and set these states, as well as synchronize them via a tunnel object.

```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
```

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

### Server Group Management (Lua)

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

Server-side functions for group management, including retrieving users by group or permission, getting group titles, and registering custom permission functions.

```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)
```

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

### User Group Management (Lua)

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

Provides functions to manage user groups and permissions. Includes methods to get, add, and remove groups, check permissions, and retrieve group information.

```lua
self.cdata.groups

-- return map of groups
User:getGroups()

User:hasGroup(name)

User:addGroup(name)

User:removeGroup(name)

-- get user group by type
-- return group name or nil
User:getGroupByType(gtype)

-- check if the user has a specific permission
User:hasPermission(perm)

-- check if the user has a specific list of permissions (all of them)
User:hasPermissions(perms)
```

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

### Load vRP Script Context

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

Loads a script into the vRP resource context on a specific side (server or client). This makes the vRP API available within the loaded script. It requires including utility functions and getting the vRP interface via a proxy.

```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"

```

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

### VRP User Money Management (Lua)

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

Provides functions to manage a user's in-game money, including wallet and bank balances. Supports getting, setting, and transferring funds, as well as attempting payments and withdrawals.

```lua
self.cdata.wallet
self.cdata.bank

-- get wallet amount
User:getWallet()

-- get bank amount
User:getBank()

-- set wallet amount
User:setWallet(amount)

-- set bank amount
User:setBank(amount)

-- give money to bank
User:giveBank(amount)

-- give money to wallet
User:giveWallet(amount)

-- try a payment (with wallet)
-- dry: if passed/true, will not affect
-- return true if debited or false
User:tryPayment(amount, dry)

-- try a withdraw (from bank)
-- dry: if passed/true, will not affect
-- return true if withdrawn or false
User:tryWithdraw(amount, dry)

-- try a deposit
-- dry: if passed/true, will not affect
-- return true if deposited or false
User:tryDeposit(amount, dry)

-- try full payment (wallet + bank to complete payment)
-- dry: if passed/true, will not affect
-- return true if debited or false
User:tryFullPayment(amount, dry)
```

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

### DBDriver API

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

Documentation for the DBDriver interface, outlining methods for database initialization, query preparation, and execution.

```APIDOC
### DBDriver

This interface is used for database interactions.

- **DBDriver:onInit(db_cfg)**: Called when the driver is initialized (connection established). Should return `true` on success.
  - `db_cfg`: Configuration from `cfg/base.lua`'s `.db` section.
- **DBDriver:onPrepare(name, query)**: Should prepare the query using `@param` notation.
  - `name`: Name of the query.
  - `query`: The SQL query string.
- **DBDriver:onQuery(name, params, mode)**: Executes the prepared query.
  - `name`: The name of the prepared query.
  - `params`: A map of parameters for the query.
  - `mode`: The execution mode:
    - `"query"`: Should return rows and affected count.
    - `"execute"`: Should return the affected count.
    - `"scalar"`: Should return a scalar value.
```

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

### vRP DBDriver Interface

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

Defines the interface for database drivers. The `DBDriver` class has methods for initialization (`onInit`), preparing queries (`onPrepare`), and executing queries (`onQuery`) with different modes.

```lua
-- called when the driver is initialized (connection), should return true on success
-- db_cfg: cfg/base.lua .db config
DBDriver:onInit(db_cfg)

-- should prepare the query (@param notation)
DBDriver:onPrepare(name, query)

-- should execute the prepared query
-- params: map of parameters
-- mode:
--- "query": should return rows, affected
--- "execute": should return affected
--- "scalar": should return a scalar
DBDriver:onQuery(name, params, mode)
```

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

### Aptitude Module API

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

Documentation for the Aptitude module, which handles skills and experience.

```APIDOC
## Aptitude Module

Adds aptitudes and experience (skills/education) to the framework.

### Extension

(No specific methods documented for the Extension part in the provided text.)
```

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

### Business Module

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

Manages a simple business system including dirty money and capital.

```APIDOC
## Business Module

### Description
This module adds a simple business system, managing aspects like dirty money and capital for characters.

### Server-Side Extensions
- `self.cfg` - Configuration for the business module.
- `Business:getBusiness(character_id)` - Returns the business data for a character, or `nil`.
- `Business:closeBusiness(character_id)` - Closes the business of a character.

### Item: dirty_money
- Represents dirty money that can be converted to regular money through laundering.

### Menus
- `commerce_chamber` - The main commerce chamber menu.
- `commerce_chamber.directory` - Accesses the business directory.
```

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

### vRP utils.lua Globals

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

Provides a list of global utility functions defined in `lib/utils.lua`. These include side detection constants (SERVER, CLIENT), module loading, class creation, string manipulation, and asynchronous function execution.

```lua
-- side detection
SERVER -- boolean
CLIENT -- boolean

-- load a lua resource file as module (for a specific side)
-- rsc: resource name
-- path: lua file path without extension
module(rsc, path)

class -- Luaoop class

-- create an async returner or a thread (Citizen.CreateThreadNow)
-- func: if passed, will create a thread, otherwise will return an async returner
async(func)

-- convert Lua string to hexadecimal
tohex(str)

-- basic deep clone function (doesn't handle circular references)
clone(t)

parseInt(v)

-- will remove chars not allowed/disabled by strchars
-- allow_policy: if true, will allow all strchars, if false, will allow everything except the strchars
sanitizeString(str, strchars, allow_policy)

splitString(str, sep)
```

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

### User Vital Management (Lua)

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

Handles user vitals (e.g., food, water) on the client. It provides functions to get, set, and vary vital values, and tracks coma states. It interacts with server-side vitals and provides client-side functions for survival mechanics.

```Lua
self.cdata.vitals -- map of name => value

-- return vital value (0-1) or nil
User:getVital(name)

-- set vital
-- value: 0-1
User:setVital(name, value)

User:varyVital(name, value)
```

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

### General API Utilities

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

Provides details on global utility functions defined in `lib/utils.lua`, including side detection, module loading, and string manipulation.

```APIDOC
## General API

### utils (`lib/utils.lua`)
This file defines several useful global variables and functions:

- **SERVER**: Boolean, true if running on the server.
- **CLIENT**: Boolean, true if running on the client.
- **module(rsc, path)**: Loads a Lua resource file as a module for a specific side.
  - `rsc`: Resource name.
  - `path`: Lua file path without extension.
- **class**: Constructor for Luaoop classes.
- **async(func)**: Creates an async returner or a thread (Citizen.CreateThreadNow).
- **tohex(str)**: Converts a Lua string to its hexadecimal representation.
- **clone(t)**: Basic deep clone function (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`. `allow_policy` determines whether to allow or disallow characters based on `strchars`.
- **splitString(str, sep)**: Splits a string by a separator.
```

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

### Map Navigation and Door Control (VRP Client)

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

Client-side functions for setting GPS destinations and controlling the state of the closest door. Includes setting marker coordinates and door lock status.

```lua
Map:setGPS(x,y)

Map:setStateOfClosestDoor(doordef, locked, doorswing)
```

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

### Client Audio Source Playback (Lua)

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

Handles client-side audio playback, including playing single audio sources (spatialized or unspatialized) and setting looping named audio sources. It also manages removal of named 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)
```

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

### vRP Interface Function Calls

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

Demonstrates how to call interface functions for both proxy and tunnel communication. Proxies can call functions directly, while tunnels require specifying the player for server-side calls. Underscore prefixes denote fire-and-forget calls.

```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 Interaction and Menus (Lua)

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

Functions for user interaction, including menu management, prompting for text input, and requesting yes/no answers. Allows opening, closing, and actualizing menus.

```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)
```

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

### VRP User Home Interaction Methods

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

Methods for a VRP user to interact with their home. This includes accessing a home by its address, leaving a home, and checking if the user is currently inside a home.

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

User:leaveHome()

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

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

### VRP Home Components Server Properties

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

Server-side properties for the 'home_components' module in VRP. This primarily provides access to the configuration settings for home components.

```lua
self.cfg
```

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

### vRP Server-Side Database and User Management in Lua

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

Server-side vRP functions for database interaction (drivers, queries, prepare), user data management (set/get UData, CData, SData, GData), player actions (kick), and saving. Includes various event listeners for game events.

```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()
```

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

### Login API

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

Provides base login functionalities including whitelist and ban management.

```APIDOC
## Login API

### Description
This module serves as the base for the login system, incorporating features such as whitelisting and banning players.

### Extension

*   **User**: Access to user-specific login data or functions (details not provided in the source text).

### Features

*   **Whitelist**: Functionality to manage a list of allowed player identifiers.
*   **Ban**: Functionality to manage a list of banned player identifiers.

*Note: Specific functions or properties for the Login API were not detailed in the provided text beyond its general purpose and features.*
```

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

### Audio Channel Registration (Lua)

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

Allows server-side registration of voice channels with specific configurations for audio effects, such as spatialization and biquad filters. All channels must be registered before player connections.

```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)
```

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

### Listen to Global Events in vRP Extension

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

Allows an extension to listen to global vRP events by defining methods within an `event` table. Synchronous events, marked with '(sync)', require listeners to return promptly to avoid blocking execution.

```lua
MyExt.event = {}

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

```

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

### VRP Home Server Management

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

Server-side functions for managing homes in VRP. This includes retrieving home addresses, finding characters by address, locating free slot numbers, registering components, and accessing/finding slots.

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

-- 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)
```

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

### Server Aptitude Definition and Conversion (Lua)

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

Defines aptitude groups and individual aptitudes on the server, including their titles, initial experience, and maximum experience. Also includes functions for converting experience to levels and vice versa. 'max_exp: -1' indicates infinite experience.

```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)
```

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

### Proxy and Tunnel Communication

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

Details on how extensions can listen to proxy/tunnel calls and how to access these interfaces for inter-resource communication.

```APIDOC
## Proxy and Tunnel

### Proxy Interface
Extensions can define functions in the `proxy` table to expose them. These interfaces can be accessed by other resources using `Proxy.getInterface()`.

**Example:**
```lua
MyExt.proxy = {}
function MyExt.proxy:getInfo() 
  -- implementation
end

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

### Tunnel Interface
Extensions can define functions in the `tunnel` table to be called remotely. These are typically used for client-server or server-client communication.

**Example:**
```lua
-- Client-side tunnel definition:
MyExt.tunnel = {}
function MyExt.tunnel:test() 
  -- implementation
end

-- Server-side calling the client tunnel:
function MyExt.event:playerSpawn(user, first_spawn)
  self.remote._test(user.source) -- Using _ signifies fire-and-forget
end

-- Client-side calling the server tunnel:
function MyExt.event:playerDeath()
  self.remote._test() -- Calls the server-side tunnel function
end
```

**Note:** Extensions should not use proxy for communication between themselves. Use tunnels for this purpose.
```

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

### Login Management Functions (VRP Server)

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

Provides server-side functions for managing user bans and whitelist status. Includes checking ban status, setting ban durations and reasons, and managing whitelist entries.

```lua
Login:checkBanned(user_id)

Login:setBanned(user_id, end_timestamp, reason)

Login:isWhitelisted(user_id)

Login:setWhitelisted(user_id, whitelisted)

Login:ban(user, duration, reason)
```

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

### Client API

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

Client-side functions for interacting with the game world, player, and UI elements.

```APIDOC
## Client API Functions

### Description
Provides access to client-side functionalities such as player information, world interaction, notifications, screen effects, and animations.

### Methods

#### Player Information
- `self.id` (number) - The user's ID.
- `self.cid` (number) - The character's ID.
- `self.players` (map) - A map of player IDs to server IDs, tracking connected players.
- `self.ragdoll` (boolean) - Flag indicating if the player is ragdolled.

#### World Interaction
- `Base:triggerRespawn()` - Triggers the player's respawn.
- `Base:teleport(x, y, z, heading)` - Teleports the player to specified coordinates. `heading` is optional.
- `Base:vehicleTeleport(x, y, z, heading)` - Teleports the player's vehicle to specified coordinates. `heading` is optional.
- `Base:getPosition()` - Returns the player's current coordinates (x, y, z).
- `Base:isInside()` - Returns `true` if the player is inside a building, `false` otherwise.
- `Base:getSpeed()` - Returns the player's current speed.
- `Base:getCamDirection()` - Returns the camera's direction vector (dx, dy, dz).
- `Base:getNearestPlayers(radius)` - Returns a map of player IDs to their distances within a given radius.
- `Base:getNearestPlayer(radius)` - Returns the ID of the nearest player within a given radius, or `nil`.

#### Notifications
- `Base:notify(msg)` - Displays a GTA 5 style text notification.
- `Base:notifyPicture(icon, type, sender, title, text)` - Displays a GTA 5 style picture notification.

#### Screen Effects
- `Base:playScreenEffect(name, duration)` - Plays a screen effect. `duration` is in seconds; -1 plays until stopped.
- `Base:stopScreenEffect(name)` - Stops a screen effect.

#### Animations
- `Base:playAnim(upper, seq, looping)` - Plays an animation. `upper` (boolean) for upper body only. `seq` is a list of animations `{dict, anim_name, loops}` or a task definition. `looping` (boolean) for infinite looping.
- `Base:stopAnim(upper)` - Stops an animation. `upper` (boolean) for upper body only.

#### Ragdoll
- `Base:setRagdoll(flag)` - Sets the player's ragdoll state (true or false).

#### Sound
- `Base:playSpatializedSound(dict, name, x, y, z, range)` - Plays a sound at a specific position.
- `Base:playSound(dict, name)` - Plays a sound.

### Tunnel Functions
These functions are available via `Base.tunnel` for remote execution.

### Events
- `playerTeleport()` - Called when the player is teleported.
```

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

### Transformer Module Server-Side Registration (Lua)

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

Server-side logic for registering and managing transformer processors and transformers. It defines how to register processors with display, check, and process callbacks, and how to add/remove transformers with their recipes and configurations.

```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)
```

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

### Inventory System - Server Functions (Lua)

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

Provides server-side Lua functions for managing the game's inventory system. This includes defining new items, computing item definitions and weights, loading and unloading global chests, and accessing configuration and item data.

```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)
```

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

### Client-Side Player Functions (Lua)

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

Provides client-side functions for interacting with the player character and the game world. Includes functionalities for movement, communication, effects, animations, and ragdoll physics.

```Lua
self.id -- user id
self.cid -- character id
self.players -- map of player id, keeps track of connected players (server id)
self.ragdoll -- flag

-- trigger vRP respawn
Base:triggerRespawn()

-- heading: (optional) entity heading
Base:teleport(x,y,z,heading)

-- teleport vehicle when inside one (placed on ground)
-- heading: (optional) entity heading
Base:vehicleTeleport(x,y,z,heading)

-- return x,y,z
Base:getPosition()

-- return false if in exterior, true if inside a building
Base:isInside()

-- return ped speed (based on velocity)
Base:getSpeed()

-- return dx,dy,dz
Base:getCamDirection()

-- return map of player id => distance
Base:getNearestPlayers(radius)

-- return player id or nil
Base:getNearestPlayer(radius)

-- GTA 5 text notification
Base:notify(msg)

-- GTA 5 picture notification
Base:notifyPicture(icon, type, sender, title, text)

-- SCREEN

-- play a screen effect
-- name, see https://wiki.fivem.net/wiki/Screen_Effects
-- duration: in seconds, if -1, will play until stopScreenEffect is called
Base:playScreenEffect(name, duration)

-- stop a screen effect
-- name, see https://wiki.fivem.net/wiki/Screen_Effects
Base:stopScreenEffect(name)

-- ANIM

-- animations dict and names: http://docs.ragepluginhook.net/html/62951c37-a440-478c-b389-c471230ddfc5.htm

-- play animation (new version)
-- upper: true, only upper body, false, full animation
-- seq: list of animations as {dict,anim_name,loops} (loops is the number of loops, default 1) or a task def (properties: task, play_exit)
-- looping: if true, will infinitely loop the first element of the sequence until stopAnim is called
Base:playAnim(upper, seq, looping)

-- stop animation (new version)
-- upper: true, stop the upper animation, false, stop full animations
Base:stopAnim(upper)

-- RAGDOLL

-- set player ragdoll flag (true or false)
Base:setRagdoll(flag)

-- SOUND
-- some lists:
-- pastebin.com/A8Ny8AHZ
-- https://wiki.gtanet.work/index.php?title=FrontEndSoundlist

-- play sound at a specific position
Base:playSpatializedSound(dict,name,x,y,z,range)

-- play sound
Base:playSound(dict,name)

-- TUNNEL

Base.tunnel.triggerRespawn = Base.triggerRespawn
Base.tunnel.teleport = Base.teleport
Base.tunnel.vehicleTeleport = Base.vehicleTeleport
Base.tunnel.getPosition = Base.getPosition
Base.tunnel.isInside = Base.isInside
Base.tunnel.getSpeed = Base.getSpeed
Base.tunnel.getNearestPlayers = Base.getNearestPlayers
Base.tunnel.getNearestPlayer = Base.getNearestPlayer
Base.tunnel.notify = Base.notify
Base.tunnel.notifyPicture = Base.notifyPicture
Base.tunnel.playScreenEffect = Base.playScreenEffect
Base.tunnel.stopScreenEffect = Base.stopScreenEffect
Base.tunnel.playAnim = Base.playAnim
Base.tunnel.stopAnim = Base.stopAnim
Base.tunnel.setRagdoll = Base.setRagdoll
Base.tunnel.playSpatializedSound = Base.playSpatializedSound
Base.tunnel.playSound = Base.playSound

```

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

### Map Entity Lifecycle and Behavior (VRP Client)

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

Defines the client-side Map.Entity class, outlining its lifecycle methods (load, unload, active, frame) and properties (id, cfg). Entities can also have custom commands defined.

```lua
self.id
self.cfg

Entity:load()

Entity:unload()

Entity:active(px, py, pz)

Entity:frame(time)
```

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

### VRP Ped Blacklist Client Configuration (Lua)

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

Configures the client-side ped blacklist module in VRP. Includes settings for ped models and the update interval.

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

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

### Cloak Module

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

Manages character cloaks, including uniforms and customization.

```APIDOC
## Cloak Module

### Description
This module handles character cloaks, such as uniforms and other wearable items, allowing for customization.

### User-Side Extensions
- `self.cdata.pre_cloak` - Data related to the player's cloak.
- `User:setCloak(cloak)` - Sets a cloak for the user.
- `User:removeCloak()` - Removes the user's cloak.
- `User:hasCloak()` - Checks if the user has a cloak equipped.

### Server-Side Extensions
- `self.cfg` - Configuration for the cloak module.

### Menu
- `cloakroom` - The cloakroom menu, allowing access to different cloak types.
```

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

### Profiler Utility

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

Information on how to enable and use the embedded ELProfiler for profiling Lua code within vRP resources.

```APIDOC
## Profiler

vRP integrates ELProfiler for profiling Lua code. Resources that load `@vrp/lib/utils.lua` are automatically set up for profiling. To use the profiler, it must be enabled in `cfg/modules.lua`. This tracks coroutines for profiling. The overhead is generally low, making it suitable for live servers.

Two options are available in the main and admin menus to profile client-side or server-side code, respectively. Profiling uses a statistical/sampling method, so long profiling periods have low memory usage, but there is an overhead due to the Lua debug hook.
```

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

### VRP Home Permission Check

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

Defines the permission syntax for checking home ownership or access using the `!home` command. It allows specifying a home name and number for more precise checks.

```lua
`!home[.<name>[.<number>]]`
name  |  (optional) home name, all `.` characters should be removed  
---
number  |  (optional) home number  
Example
`!home` |  has a home  
---
`!home.HLM Vinewood` |  lives at `HLM Vinewood`  
`!home.HLM Vinewood.5` |  lives at `5, HLM Vinewood`
```

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

### vRP Proxy API

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

Functions for managing proxy interfaces. `Proxy.addInterface` registers a table of functions as an interface, and `Proxy.getInterface` retrieves an existing interface, optionally with a specific identifier.

```lua
-- add event handler to call interface functions
-- name: interface name
-- itable: table containing functions
Proxy.addInterface(name, itable)

-- get a proxy interface
-- name: interface name
-- identifier: (optional) unique string to identify this proxy interface access; if nil, will be the name of the resource
Proxy.getInterface(name, identifier)
```

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

### vRP Extension Proxy Interface Access

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

Demonstrates how to access a proxy interface generated by vRP extensions. The `Proxy.getInterface` function retrieves the specified interface, allowing calls to its methods.

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

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

### VRP Player State Configuration (Lua)

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

Manages player state data, including customization, weapons, health, and armor. Accesses user state through `self.cdata.state` on the server.

```lua
self.cdata.state
```

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

### Permission Check: !inside

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

A permission check to verify if a player is inside a building.

```APIDOC
## Permission: !inside

### Description
Checks if the player is currently inside a building (interior). This check performs a tunnel call.

### Usage
- `!inside`
```

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

### Extension API

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

Details on the base API available to vRP extensions, including logging and accessing network interfaces.

```APIDOC
### Extension

Extensions have access to several base functionalities.

- **self.remote**: A tunnel interface to communicate with the network side (client/server).
- **Extension:log(msg, level)**: Logs a message. `level` is optional (defaults to 0).
- **Extension:error(msg)**: Logs an error message.
```

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

### Server-Side Business Management (Lua)

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

Server-side functions for managing business-related data for characters. Includes retrieving and closing businesses.

```Lua
self.cfg

-- return character business data or nil
Business:getBusiness(character_id)

-- close the business of a character
Business:closeBusiness(character_id)

```
Tokens:
Raw