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 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 Gets player Passport vRP.Source(Passport) Passport source|nil Gets source from Passport vRP.Datatable(Passport) Passport table|false Character in-memory data vRP.Inventory(Passport) Passport table Character inventory vRP.Identity(Passport) Passport table|false Character data (name, name2, bank, phone, etc.) vRP.FullName(source) source string|false Character full name vRP.Players() — table Returns Sources (Passport→source) vRP.Kick(source, Reason) source, string — Kicks the player vRP.Teleport(source, x, y, z) source, coords — Teleports the player vRP.GetEntityCoords(source) source vector3 Player coordinates vRP.ModelPlayer(source) source string Ped model (mp_m/mp_f) 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 Pays with bank (checks balance) vRP.PaymentMoney(Passport, Amount) Passport, number bool Pays with cash vRP.PaymentFull(Passport, Amount) Passport, number bool Tries cash, then bank vRP.PaymentDirty(Passport, Amount) Passport, number bool Pays with dirty money vRP.WithdrawCash(Passport, Amount) Passport, number bool Bank withdrawal vRP.PaymentGems(Passport, Amount) Passport, number bool Pays with gems vRP.GetCoins(Passport) Passport number Gets coins vRP.AddCoins(Passport, Amount) Passport, number bool Adds coins vRP.RemCoins(Passport, Amount) Passport, number bool Removes coins 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) ... — Removes item (no return) vRP.ItemAmount(Passport, Item) Passport, string number Item amount vRP.ConsultItem(Passport, Item, Amount) ... bool Checks if has amount vRP.InventoryWeight(Passport) Passport number Current weight vRP.GetWeight(Passport) Passport number Max weight vRP.SetWeight(Passport, Amount) Passport, number — Adds to max weight vRP.MaxItens(Passport, Item, Amount) ... bool Checks item max limit vRP.ClearInventory(Passport) Passport — Clears inventory 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) ... — Sets permission vRP.RemovePermission(Passport, Permission) ... — Removes permission vRP.ServiceToggle(Source, Passport, Permission, Silenced) ... — Toggles service vRP.NumPermission(Permission, Level) ... table, number Players in service vRP.CheckGroup(Passport, Type) ... bool Checks group by type vRP.HasAction(Passport) Passport bool Checks police action vRP.SetAction(Passport, Status) ... — Sets action status 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) ... Increases infection vRP.DowngradeInfection(Passport, Amount) ... Decreases infection vRP.Revive(source, Health) ... Revives player 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) Formats full time in HTML MinimalTimers(seconds) Formats summarized time CountTable(table) Counts items in table async(func) Executes asynchronous function 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" Client Player activated (source, Passport, Name) 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. 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. 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: vRPex (old) Creative Network (current) 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 ALWAYS use the native Creative Network names (right column), not the aliases.