FiveM vRP框架开发指南：Lua脚本、API函数与服务器架构详解

fivem-development by proelias7/fivem-skill

72 周安装量

2 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/proelias7/fivem-skill --skill fivem-development

开发系统架构游戏

🇨🇳中文介绍

FiveM 开发 — vRP

框架架构

vRP Creative Network 基于 Lua 5.4，通过 Proxy（服务器到服务器）和 Tunnel（客户端-服务器）进行通信。

FiveM 原生函数 — 官方来源

原生函数的官方来源：

文档：https://docs.fivem.net/natives/
官方仓库（镜像）：https://github.com/proelias7/fivem-natives

对 Creative v5 和 vRPEX（旧版本）的支持

旧版本保持相同的逻辑和最佳实践，但更改了函数和文件名。

Creative v5： 核心使用 camelCase，modules/group.lua，配置文件在 config/*.lua。
vRPEX： 经典核心（getUserId、getUserSource、等）和配置文件在。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

概念	描述
Passport	唯一的角色ID（相当于其他 vRP 中的 `user_id`）
Source	玩家在服务器上的连接ID（每次重连都会改变）
Datatable	包含角色数据（库存、位置、皮肤等）的内存表
Characters	以 `source` 为索引的全局服务器端角色数据表
Sources	用于反向查找的全局表 `Sources[Passport] = source`

主要 API（服务器端）

函数	参数	返回值	描述
`vRP.Passport(source)`	source	Passport	false
`vRP.Source(Passport)`	Passport	source	nil
`vRP.Datatable(Passport)`	Passport	table	false
`vRP.Inventory(Passport)`	Passport	table	角色库存
`vRP.Identity(Passport)`	Passport	table	false
`vRP.FullName(source)`	source	string	false
`vRP.Players()`	—	table	返回 `Sources`（Passport→source）
`vRP.Kick(source, Reason)`	source, string	—	踢出玩家
`vRP.Teleport(source, x, y, z)`	source, 坐标	—	传送玩家
`vRP.GetEntityCoords(source)`	source	vector3	玩家坐标
`vRP.ModelPlayer(source)`	source	string	Ped 模型（mp_m/mp_f）

函数	参数	返回值	描述
`vRP.GetBank(source)`	source	number	银行余额
`vRP.GiveBank(Passport, Amount)`	Passport, number	—	向银行添加金钱
`vRP.RemoveBank(Passport, Amount)`	Passport, number	—	从银行移除金钱
`vRP.PaymentBank(Passport, Amount)`	Passport, number	bool	使用银行支付（检查余额）
`vRP.PaymentMoney(Passport, Amount)`	Passport, number	bool	使用现金支付
`vRP.PaymentFull(Passport, Amount)`	Passport, number	bool	先尝试现金，然后银行
`vRP.PaymentDirty(Passport, Amount)`	Passport, number	bool	使用黑钱支付
`vRP.WithdrawCash(Passport, Amount)`	Passport, number	bool	银行取款
`vRP.PaymentGems(Passport, Amount)`	Passport, number	bool	使用宝石支付
`vRP.GetCoins(Passport)`	Passport	number	获取硬币
`vRP.AddCoins(Passport, Amount)`	Passport, number	bool	添加硬币
`vRP.RemCoins(Passport, Amount)`	Passport, number	bool	移除硬币

函数	参数	返回值	描述
`vRP.GiveItem(Passport, Item, Amount, Notify, Slot)`	...	—	给予物品（无耐久度）
`vRP.GenerateItem(Passport, Item, Amount, Notify, Slot)`	...	—	给予物品（带耐久度/使用次数）
`vRP.TakeItem(Passport, Item, Amount, Notify, Slot)`	...	bool	移除物品（返回成功与否）
`vRP.RemoveItem(Passport, Item, Amount, Notify)`	...	—	移除物品（无返回值）
`vRP.ItemAmount(Passport, Item)`	Passport, string	number	物品数量
`vRP.ConsultItem(Passport, Item, Amount)`	...	bool	检查是否拥有指定数量
`vRP.InventoryWeight(Passport)`	Passport	number	当前重量
`vRP.GetWeight(Passport)`	Passport	number	最大重量
`vRP.SetWeight(Passport, Amount)`	Passport, number	—	增加最大重量
`vRP.MaxItens(Passport, Item, Amount)`	...	bool	检查物品最大限制
`vRP.ClearInventory(Passport)`	Passport	—	清空库存

函数	参数	返回值	描述
`vRP.HasPermission(Passport, Permission, Level)`	...	bool	检查直接权限
`vRP.HasGroup(Passport, Permission, Level)`	...	bool	检查组（包含父组）
`vRP.HasService(Passport, Permission)`	...	bool	检查是否在服务中
`vRP.SetPermission(Passport, Permission, Level, Mode)`	...	—	设置权限
`vRP.RemovePermission(Passport, Permission)`	...	—	移除权限
`vRP.ServiceToggle(Source, Passport, Permission, Silenced)`	...	—	切换服务状态
`vRP.NumPermission(Permission, Level)`	...	table, number	处于服务中的玩家
`vRP.CheckGroup(Passport, Type)`	...	bool	按类型检查组
`vRP.HasAction(Passport)`	Passport	bool	检查警察行动状态
`vRP.SetAction(Passport, Status)`	...	—	设置行动状态

函数	参数	描述
`vRP.UpgradeHunger(Passport, Amount)`	...	增加饥饿值
`vRP.DowngradeHunger(Passport, Amount)`	...	减少饥饿值
`vRP.UpgradeThirst(Passport, Amount)`	...	增加口渴值
`vRP.DowngradeThirst(Passport, Amount)`	...	减少口渴值
`vRP.UpgradeInfection(Passport, Amount)`	...	增加感染值
`vRP.DowngradeInfection(Passport, Amount)`	...	减少感染值
`vRP.Revive(source, Health)`	...	复活玩家

-- 注册预处理查询
vRP.Prepare("name/query", "SELECT * FROM table WHERE id = @id")

-- 执行查询
local result = vRP.Query("name/query", { id = 123 })

内部使用 oxmysql。参数使用 @name 格式。

-- 服务器数据（entitydata — 全局数据）
local data = vRP.GetSrvData("UniqueKey")
vRP.SetSrvData("UniqueKey", { field = "value" })

-- 玩家数据（playerdata — 每个玩家的数据）
local data = vRP.UserData(Passport, "key")
vRP.setUData(Passport, "key", json.encode(data))

函数	描述
`parseInt(value)`	转换为整数（最小为 0）
`parseFormat(value)`	格式化数字，添加千位分隔符
`splitString(str, symbol)`	按分隔符分割字符串
`SplitOne(name)`	分割后的第一个元素
`sanitizeString(str, chars, allow)`	过滤字符
`CompleteTimers(seconds)`	以 HTML 格式格式化完整时间
`MinimalTimers(seconds)`	格式化摘要时间
`CountTable(table)`	计算表中的项目数
`async(func)`	执行异步函数

客户端-服务器通信

-- 服务器端：简单通知
TriggerClientEvent("Notify", source, "success", "消息。", false, 5000)
-- 类型："success", "important", "negado"（拒绝）

-- 服务器端：物品通知
TriggerClientEvent("NotifyItens", source, { "+", "itemIndex", "amount", "物品名称" })
-- "+" 表示获得，"-" 表示失去

事件	端	描述
`"Connect"`	服务器	玩家选择了角色 `(Passport, Source)`
`"Disconnect"`	服务器	玩家断开连接 `(Passport, Source)`
`"CharacterChosen"`	服务器	角色已选择 `(Passport, source)`
`"vRP:Active"`	客户端	玩家已激活 `(source, Passport, Name)`

关键性能规则（摘要）

编写代码时请务必遵循以下规则：

Tunnel 与 Event： 当你不需要返回值时，使用 TriggerServerEvent/TriggerClientEvent。只有当你需要返回值时才使用 Tunnel。
动态休眠： 绝不使用固定的 Wait(0)。根据状态调整（距离 < 20 = 0，距离 < 50 = 500，否则 = 1000+）。
同一环境中的调用： 直接调用函数。绝不使用 TriggerEvent() 在同一端调用。
不在循环中进行远程调用： 不要在小于 5 秒的循环中使用 Tunnel/Events。优先使用批量或增量方式。
小负载： 只发送变更，而不是完整数据。每个事件限制在约 8KB。
缓存： 对于重复的数据库查询，使用 exports.cacheaside:Get()。绝不在循环中查询数据库。
SafeEvent（服务器）： 任何给予金钱/物品/优势的事件必须通过 exports["cerberus"]:SafeEvent(source, "eventName", { time = N })。
SetCooldown（客户端）： 客户端的重复性操作（打开菜单、使用物品）必须使用 exports["cerberus"]:SetCooldown("name", ms)。
表 > if/else： 对于 3 个或更多条件，使用查找表（O(1)）而不是 if/elseif 链。
保护 nil 值： 在连接变量之前始终检查。使用 or "" 作为后备值。

UI 构建（React + Vite）

技术栈：React 18 + TypeScript + Vite + Tailwind CSS + Zustand。

vite.config.ts 中设置 base: "./"（对于 FiveM 强制要求）
所有尺寸使用 rem — 布局绝不使用 px
在 html 字体大小中使用媒体查询，以根据玩家分辨率进行缩放
Tailwind v4 使用 OKLCH，而 FiveM CEF 不支持它。请使用 Tailwind v3.4.17。
禁止使用： backdrop-filter: blur()、filter: blur()、filter: drop-shadow() — 会导致 FPS 下降
禁止使用： framer-motion、GSAP、react-spring — 重量级动画库
使用纯 CSS 过渡/关键帧进行动画
独立模块（Notify、Progress）放在 VisibilityProvider 外部
主界面放在带有 NuiFocus 的 VisibilityProvider 内部
全局设置 overflow: hidden 和 user-select: none
开发时使用 isEnvBrowser() 进行数据模拟
通信：使用 observe() 监听 NUI，使用 Post.create() 发送回调

完整的 UI 指南：ui-guide.md

UI 构建指南（React + Vite + FiveM）：ui-guide.md
详细的最佳实践（性能、安全、缓存）：best-practices.md
完整详细的 API：reference.md
代码示例：examples.md
资源模板：templates.md
模式和约定：patterns.md

外部资源（下载）

当项目提及依赖项时，请使用这些官方仓库：

cacheaside（内存缓存）：git@github.com:proelias7/cacheaside.git
cerberus（反作弊 + 冷却时间）：git@github.com:proelias7/cerberus.git

vRP Creative Network 与经典 vRP 具有兼容性别名：

vRPex（旧）	Creative Network（当前）
`getUserId`	`Passport`
`getUserSource`	`Source`
`getUserIdentity`	`Identity`
`getUserDataTable`	`Datatable`
`hasGroup`	`HasGroup`
`hasPermission`	`HasPermission`
`giveInventoryItem`	`GiveItem`
`tryGetInventoryItem`	`TakeItem`
`getInventoryItemAmount`	`ItemAmount`
`giveMoney`	`GiveBank`
`tryFullPayment`	`PaymentFull`
`getBankMoney`	`GetBank`
`query` / `execute`	`Query`
`prepare`	`Prepare`

请始终使用原生的 Creative Network 名称（右列），而不是别名。

🇺🇸English

FiveM Development — vRP

Framework Architecture

vRP Creative Network is based on Lua 5.4 with communication via Proxy (server-to-server) and Tunnel (client-server).

FiveM Natives — Official Source

Official source for natives:

Docs: https://docs.fivem.net/natives/
Official Repository (mirror): https://github.com/proelias7/fivem-natives

Support for Creative v5 and vRPEX (older variations)

Older versions maintain the same logic and best practices but change function and file names.

Creative v5: core in camelCase, modules/group.lua, configs in config/*.lua.
vRPEX: classic core (getUserId, getUserSource, getUsers, etc.) and configs in cfg/*.lua.

See the full mapping in reference.md.

Key Concepts

Concept	Description
Passport	Unique character ID (equivalent to `user_id` in other vRPs)
Source	Player connection ID on the server (changes on every reconnection)
Datatable	In-memory table with character data (inventory, position, skin, etc.)
Characters	Global server-side table indexed by `source` with character data
Sources	Global table `Sources[Passport] = source` for reverse lookup

Identification Flow

-- Server-side: get Passport from source
local Passport = vRP.Passport(source)

-- Server-side: get source from Passport
local source = vRP.Source(Passport)

-- Server-side: get character Datatable
local Datatable = vRP.Datatable(Passport)

-- Server-side: get inventory
local Inventory = vRP.Inventory(Passport)

Proxy/Tunnel System

-- In any SERVER-SIDE resource, get access to vRP:
local Proxy = module("vrp", "lib/Proxy")
vRP = Proxy.getInterface("vRP")

-- In any CLIENT-SIDE resource:
local Tunnel = module("vrp", "lib/Tunnel")
local Proxy = module("vrp", "lib/Proxy")
vRPS = Tunnel.getInterface("vRP")  -- call server functions

-- Expose your resource functions (server):
myResource = {}
Proxy.addInterface("myResource", myResource)
Tunnel.bindInterface("myResource", myResource)

Fire-and-forget Rule

Prefix Tunnel calls with _ to not wait for a response:

-- Await response (blocking)
local result = vRP.Generateitem(Passport,"water",1)

-- Fire-and-forget (non-blocking)
vRP._Generateitem(Passport,"water",1)

Main API (Server-side)

Player/Identity

Function	Parameters	Return	Description
`vRP.Passport(source)`	source	Passport	false
`vRP.Source(Passport)`	Passport	source	nil
`vRP.Datatable(Passport)`	Passport	table	false
`vRP.Inventory(Passport)`	Passport	table	Character inventory

Money

Function	Parameters	Return	Description
`vRP.GetBank(source)`	source	number	Bank balance
`vRP.GiveBank(Passport, Amount)`	Passport, number	—	Adds money to bank
`vRP.RemoveBank(Passport, Amount)`	Passport, number	—	Removes money from bank
`vRP.PaymentBank(Passport, Amount)`	Passport, number	bool

Inventory

Function	Parameters	Return	Description
`vRP.GiveItem(Passport, Item, Amount, Notify, Slot)`	...	—	Gives item (no durability)
`vRP.GenerateItem(Passport, Item, Amount, Notify, Slot)`	...	—	Gives item (with durability/charges)
`vRP.TakeItem(Passport, Item, Amount, Notify, Slot)`	...	bool	Removes item (returns success)
`vRP.RemoveItem(Passport, Item, Amount, Notify)`

Groups/Permissions

Function	Parameters	Return	Description
`vRP.HasPermission(Passport, Permission, Level)`	...	bool	Checks direct permission
`vRP.HasGroup(Passport, Permission, Level)`	...	bool	Checks group (includes parents)
`vRP.HasService(Passport, Permission)`	...	bool	Checks if in service
`vRP.SetPermission(Passport, Permission, Level, Mode)`	...

Survival

Function	Parameters	Description
`vRP.UpgradeHunger(Passport, Amount)`	...	Increases hunger
`vRP.DowngradeHunger(Passport, Amount)`	...	Decreases hunger
`vRP.UpgradeThirst(Passport, Amount)`	...	Increases thirst
`vRP.DowngradeThirst(Passport, Amount)`	...	Decreases thirst
`vRP.UpgradeInfection(Passport, Amount)`

Database

-- Register prepared query
vRP.Prepare("name/query", "SELECT * FROM table WHERE id = @id")

-- Execute query
local result = vRP.Query("name/query", { id = 123 })

Uses oxmysql internally. Parameters with @name.

Persistent Data

-- Server Data (entitydata — global data)
local data = vRP.GetSrvData("UniqueKey")
vRP.SetSrvData("UniqueKey", { field = "value" })

-- Player Data (playerdata — data per player)
local data = vRP.UserData(Passport, "key")
vRP.setUData(Passport, "key", json.encode(data))

Global Utilities

Function	Description
`parseInt(value)`	Converts to integer (min. 0)
`parseFormat(value)`	Formats number with thousand separator
`splitString(str, symbol)`	Splits string by separator
`SplitOne(name)`	First element of split
`sanitizeString(str, chars, allow)`	Filters characters
`CompleteTimers(seconds)`

Client-Server Communication

Notification Events

-- Server-side: simple notification
TriggerClientEvent("Notify", source, "success", "Message.", false, 5000)
-- Types: "success", "important", "negado" (denied)

-- Server-side: item notification
TriggerClientEvent("NotifyItens", source, { "+", "itemIndex", "amount", "Item Name" })
-- "+" for gain, "-" for loss

Important Events

Event	Side	Description
`"Connect"`	Server	Player chose character `(Passport, Source)`
`"Disconnect"`	Server	Player disconnected `(Passport, Source)`
`"CharacterChosen"`	Server	Character chosen `(Passport, source)`
`"vRP:Active"`

Critical Performance Rules (Summary)

ALWAYS follow these rules when writing code:

Tunnel vs Event: Use TriggerServerEvent/TriggerClientEvent when you do NOT need a return. Use Tunnel only when you NEED a return.
Dynamic Sleep: NEVER fixed Wait(0). Adjust based on state (dist < 20 = 0, dist < 50 = 500, else = 1000+).
Calls in same environment: Call functions directly. NEVER use TriggerEvent() to call on the same side.
No remote calls in loops: Do not use Tunnel/Events in loops < 5 seconds. Prefer batch or delta.
Small Payloads: Send only the change, not full data. Limit of ~8KB per event.
Cache: Use exports.cacheaside:Get() for repeated database queries. Never query the database in a loop.

UI Construction (React + Vite)

Stack: React 18 + TypeScript + Vite + Tailwind CSS + Zustand.

Fundamental Rules:

base: "./" in vite.config.ts (MANDATORY for FiveM)
Use rem for ALL sizes — NEVER px for layout
Media queries in html font-size to scale with player resolution
Tailwind v4 uses OKLCH and FiveM CEF does not support it. Use Tailwind v3.4.17.
FORBIDDEN: backdrop-filter: blur(), filter: blur(), filter: drop-shadow() — cause FPS drop
FORBIDDEN: framer-motion, GSAP, react-spring — heavy animation libs
Use pure CSS transitions/keyframes for animations
Independent modules (Notify, Progress) outside VisibilityProvider
Main interface inside VisibilityProvider with NuiFocus
Global overflow: hidden and

For complete UI guide: ui-guide.md

Additional References

For UI construction guide (React + Vite + FiveM): ui-guide.md
For detailed best practices (performance, security, cache): best-practices.md
For complete and detailed API: reference.md
For code examples: examples.md
For resource templates: templates.md
For patterns and conventions: patterns.md

External Resources (Download)

Use these official repositories when the project mentions dependencies:

cacheaside (in-memory cache): git@github.com:proelias7/cacheaside.git
cerberus (anti-exploit + cooldowns): git@github.com:proelias7/cerberus.git

vRPex Compatibility

The vRP Creative Network has compatibility aliases with classic vRP:

vRPex (old)	Creative Network (current)
`getUserId`	`Passport`
`getUserSource`	`Source`
`getUserIdentity`	`Identity`
`getUserDataTable`	`Datatable`

ALWAYS use the native Creative Network names (right column), not the aliases.

Weekly Installs

Repository

proelias7/fivem-skill

GitHub Stars

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode66

github-copilot66

codex66

gemini-cli65

amp63

kimi-cli63

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

122,000 周安装

SafeEvent (server): Every event that gives money/item/advantage MUST pass through exports["cerberus"]:SafeEvent(source, "eventName", { time = N }).

SetCooldown (client): Repetitive actions on client (open menu, use item) must use exports["cerberus"]:SetCooldown("name", ms).

Tables > if/else: For 3+ conditions, use lookup table (O(1)) instead of if/elseif chains.

Protect nil: Always check variables before concatenating. Use or "" as fallback.

isEnvBrowser() for data mocking in dev

Communication: observe() to listen to NUI, Post.create() to send callbacks