fivem-development（五方发展）

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

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

Money

Inventory

Groups/Permissions

Survival

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

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

Critical Performance Rules (Summary)

ALWAYS follow these rules when writing code:

1. Tunnel vs Event: Use TriggerServerEvent/TriggerClientEvent when you do NOT need a return. Use Tunnel only when you NEED a return.
2. Dynamic Sleep: NEVER fixed Wait(0). Adjust based on state (dist < 20 = 0, dist < 50 = 500, else = 1000+).
3. Calls in same environment: Call functions directly. NEVER use TriggerEvent() to call on the same side.
4. No remote calls in loops: Do not use Tunnel/Events in loops < 5 seconds. Prefer batch or delta.
5. Small Payloads: Send only the change, not full data. Limit of ~8KB per event.
6. Cache: Use exports.cacheaside:Get() for repeated database queries. Never query the database in a loop.
7. SafeEvent (server): Every event that gives money/item/advantage MUST pass through exports["cerberus"]:SafeEvent(source, "eventName", {time = N}).
8. SetCooldown (client): Repetitive actions on client (open menu, use item) must use exports["cerberus"]:SetCooldown("name", ms).
9. Tables > if/else: For 3+ conditions, use lookup table (O(1)) instead of if/elseif chains.
10. Protect nil: Always check variables before concatenating. Use or "" as fallback.

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 user-select: none
• isEnvBrowser() for data mocking in dev
• Communication: observe() to listen to NUI, Post.create() to send callbacks

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:

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