Description

# RPS_LIB ## Universal FiveM Bridge Library > Drop-in bridge layer for FiveM scripts. Write your resource once — it works on any supported framework, inventory, notification system, fuel system, target system, and more. No rewrites when you change servers or swap resources. --- ## What It Does RPS_LIB sits between your scripts and the various third-party resources running on your server. Instead of writing `exports['qb-core']:GetCoreObject()` everywhere and having to rewrite everything when someone switches to ESX, you write `Lib.Framework.GetJob()` once and the lib figures out which system is running and talks to it for you. Every module auto-detects the correct resource at startup. You can also pin any module to a specific resource in one config file, or disable modules your server doesn't use. --- ## Supported Frameworks | Resource | Type | |---|---| | `es_extended` | ESX | | `qb-core` | QBCore | | `qbx_core` | QBX Core | | `ox_core` | Overextended Core | | `ND_Core` | ND Framework | --- ## Supported Bridges Per Module | Module | Supported Resources | |---|---| | **Framework** | `es_extended` · `qb-core` · `qbx_core` · `ox_core` · `ND_Core` | | **Inventory** | `ox_inventory` · `qb-inventory` · `qs-inventory` · `ps-inventory` · `codem-inventory` | | **Notifications** | `ox_lib` · `qb-core` · `okokNotify` · `mythic_notify` · `es_extended` · GTA native fallback | | **Fuel** | `ox_fuel` · `LegacyFuel` · `cdn-fuel` · `ps-fuel` · `sna-fuel` · native `SetVehicleFuelLevel` fallback | | **Radial Menu** | `ox_lib` · `qb-radialmenu` | | **Dispatch** | `ps-dispatch` · `cd_dispatch` · `linden_outlawalert` · `core_dispatch` · `qs-dispatch` | | **Target** | `ox_target` · `qb-target` · `bt-target` | | **Door Locks** | `ox_doorlock` · `qb-doorlock` · `nUI_doorlock` · native entity freeze fallback | | **Gang** | `op-crime` · `ps-gangs` · `op-gangs` · `esx_gang` · `qbx_core` · `qb-core` · `ND_Core` | --- ## Module Feature Breakdown --- ### Framework Module Wraps player data, job checks, and money across all supported frameworks. **Client features:** - Get current job name, grade number, and grade label - Get player money by account (`cash`, `bank`, `black_money`) - Get player citizen identifier - Check if player is in a specific job with optional minimum grade - Accepts a single job name or a list of job names for `IsJob` checks - Get raw player data table for advanced usage **Server features:** - All client features but for any player by server id - Add money to a player account - Remove money from a player account (returns `false` if insufficient funds, no deduction made) - Get all currently online players - Get raw framework player object for direct access --- ### Inventory Module Wraps item checks, item management, stash registration, and usable item registration across all inventory systems. **Client features:** - Get item count for any item - Check if player has a minimum quantity of an item - Get all items in player inventory as a normalised list (name, label, count, weight, slot, metadata) - Open a stash inventory by id - Open a vehicle trunk inventory - Trigger item use client-side **Server features:** - Add items to a player's inventory with optional metadata and slot - Remove items from a player's inventory - Check if a player has a minimum quantity of an item - Get item count for a player - Register a server-side usable item callback (fires when player uses the item) - Register a persistent stash (shared or player-owned) so inventory systems know about it before clients open it --- ### Notification Module Wraps all notification and UI systems with a consistent API. **Client features:** - Send a notification with type (`success`, `error`, `info`, `warning`), custom title, duration, and icon - Shorthand helpers: `Success`, `Error`, `Info`, `Warn` - Progress bar with optional animation, disable flags, cancel support, and finish/cancel callbacks - Returns `true` if the bar completed, `false` if cancelled - Input dialog with multiple field types (`input`, `number`, `checkbox`, `select`, `date`) - Falls back to native GTA HUD notification if no system is detected **Server features:** - Send any notification to a specific player - Shorthand helpers for all types - Broadcast a notification to all players on the server - Broadcast a notification to all online players with a specific job --- ### Fuel Module Wraps all fuel systems with get, set, and drain helpers. **Client features:** - Get fuel level for any vehicle (defaults to current vehicle) - Set fuel level (clamped to 0–100) - Add fuel to a vehicle - Remove fuel from a vehicle - Check if fuel is below a threshold - Start a continuous drain thread that respects engine state — returns a stop function so you can end the drain cleanly - Falls back to native `SetVehicleFuelLevel` / `GetVehicleFuelLevel` if no system detected **Server features:** - Set fuel level on any player's vehicle by network id - Add fuel to any player's vehicle by network id --- ### Radial Menu Module Wraps radial wheel systems so items register correctly regardless of which resource is running. **Client features:** - Add a group of items to the radial wheel with id, label, icon, and callback - Remove a group of items by id - Add a sub-menu linked to a parent item (ox_lib only) - Disable or re-enable the radial wheel programmatically (ox_lib only) - Net event callbacks are auto-registered per item so `qb-radialmenu` events are wired correctly without manual effort **Server features:** - Push a radial item group to a specific player - Remove a radial item group from a specific player - Push a radial item group to all online players simultaneously --- ### Dispatch Module Wraps all alert and dispatch systems with a consistent send format. **Client features:** - Send a fully customised alert with title, message, alert code, coords, blip config, vehicle plate, weapon, and priority - Route alert to a specific job using the config job map - Multi-job support for systems that allow it (ps-dispatch) - Shorthand wrappers: `Police`, `EMS`, `Fire` - Falls back to a server relay when no local dispatch system is detected **Server features:** - Same send API as client — broadcasts the alert to all clients - Shorthand wrappers for police, EMS, and fire - Server-to-client dispatch relay for scripts that trigger alerts from server-side logic --- ### Target Module Wraps all target/interaction systems so zones, models, and entities work the same way regardless of which target resource is running. **Client features:** - Add interaction options to a specific entity (NPC, vehicle, object) - Add a box zone at given coords with configurable size, heading, and debug outline - Add a sphere zone at given coords with configurable radius - Add a model-based target that applies to every instance of a prop or ped model - All option entries support: label, icon, distance, job restriction, item restriction, and onSelect callback - `qb-target` net event auto-registration — callbacks wire themselves so no manual event setup needed - Remove entity targets, zone targets, and model targets individually - Zone bridge is tracked per zone so removal uses the correct system **Server features:** - Tell a specific player to add or remove a box zone - Tell all players to add or remove a model target globally --- ### Door Lock Module Wraps door lock systems with persistent server-side state so doors survive player reconnects. **Client features:** - Register one or more doors with name, model hash, coords, heading, interact distance, default lock state, authorised jobs, and minimum grade - Lock, unlock, or toggle any registered door by name - Check lock state of any door - Auto-receives server-pushed state changes and updates local state - Falls back to native entity freeze if no door system is detected **Server features:** - Lock, unlock, toggle, and check state of any registered door - State changes broadcast to all connected clients immediately - Door states persist in memory — newly connecting players receive all current states automatically so they never see desync - QBCore door registration and toggle relay for full compatibility - nUI_doorlock server relay support --- ### Gang Module Wraps all gang systems across frameworks and standalone gang resources. **Detection priority (standalone systems checked before framework built-ins):** `op-crime` → `ps-gangs` → `op-gangs` → `esx_gang` → `qbx_core` → `qb-core` → `ND_Core` This order ensures that if you run `op-crime` alongside QBCore, the dedicated gang system wins and you get the correct data rather than QBCore's built-in gang field. **Client features:** - Get current gang name, grade number, grade label, and gang display label - Check if player is the gang boss - Check if player is in any active gang (not `none` or `civilian`) - Check if player's gang matches one or more gang names with optional minimum grade - Get normalised gang data as a consistent table regardless of which bridge is active (always returns `name`, `label`, `grade`, `gradeLabel`, `isBoss`, `isInGang`, `bridge`) - Listen for gang changes via event — fires on login, gang update, promotion, and server push - Raw data is normalised using flexible key matching so different bridges with different field names all produce the same output **Server features:** - All client read functions available server-side by player source id - Set a player's gang and grade — automatically broadcasts updated data to the player's client - Remove a player from their gang - Get a list of all online players in a specific gang - Get a list of all online gang bosses for a specific gang - Send a notification to all online members of a gang - Send a notification to all online bosses of a gang - Net event for client-side data refresh requests --- ## Core System Features ### Bridge Resolver The bridge resolver is the engine behind every module. Key behaviours: - **Lazy resolution** — bridges are resolved the first time a module function is called, not at declaration time. This guarantees config is always read before any detection runs. - **Config pin** — setting `Bridges.gang = 'op-crime'` forces that exact resource. If it is not started, the module shows `NO BRIDGE` and does not silently fall back to another system. - **Hard pin failure** — if a pinned resource is not running, a clear warning is printed to the server console explaining exactly what to fix. - **Auto-detect** — if set to `'auto'`, the resolver tries each resource in priority order and uses the first one that is started. - **Cached results** — once resolved, the result is cached for the lifetime of the resource. No repeated detection overhead. - **Disabled flag** — setting any bridge to `false` skips the module entirely with no memory or thread overhead. ### Module Registry - Every module self-declares using `Module{}` in its `init.lua` - Completion is tracked via `Lib.done()` at the end of each module file - Status is queryable at runtime: `loaded`, `declared`, `disabled` - No central list to maintain — adding a module never requires editing the registry ### Event Bus - Both client and server have a lightweight internal event bus (`Lib.on`, `Lib.off`, `Lib.emit`) - Used internally for gang updates, door state changes, and dispatch alerts - Available for external use by other scripts via `GetLib()` ### Ready Gate (client) - `Lib.onReady(cb)` fires once the lib has fully initialised after resource start - If called after the lib is already ready, the callback fires immediately - Prevents race conditions when registering targets, doors, or radial items at startup ### Boot Report Printed to the server console once on every resource start. Shows every module in a formatted table with: - Module name - Resolved bridge resource name - Detection mode: `AUTO` (detected automatically) · `PINNED` (forced in config) · `OFF` (disabled) - Status: `ACTIVE` · `NATIVE` (built-in fallback) · `DISABLED` · `NO BRIDGE` (not found or pinned resource not running) - Summary line: total active, pinned, disabled, and failed counts - Inline config hint reminding how to pin or disable --- ## Exports Available to Other Scripts ### Client exports | Export | Description | |---|---| | `GetLib()` | Full `Lib` table with all modules | | `GetFramework()` | `Lib.Framework` module only | | `GetInventory()` | `Lib.Inventory` module only | | `GetNotify()` | `Lib.Notify` module only | | `GetFuel()` | `Lib.Fuel` module only | | `GetRadial()` | `Lib.Radial` module only | | `GetDispatch()` | `Lib.Dispatch` module only | | `GetTarget()` | `Lib.Target` module only | | `GetDoors()` | `Lib.Doors` module only | | `GetGang()` | `Lib.Gang` module only | | `OnReady(cb)` | Register a callback to fire once lib is ready | | `GetBridges()` | Returns a table of resolved bridge names per module | | `GetStatus()` | Returns a table of module load status | ### Server exports | Export | Description | |---|---| | `GetLib()` | Full `Lib` table | | `GetFramework()` | `Lib.Framework` module only | | `GetInventory()` | `Lib.Inventory` module only | | `GetNotify()` | `Lib.Notify` module only | | `GetDoors()` | `Lib.Doors` module only | | `GetDispatch()` | `Lib.Dispatch` module only | | `GetGang()` | `Lib.Gang` module only | | `GetPlayer(src)` | Raw framework player object | | `IsJob(src, jobs, grade)` | Job check shortcut | | `DoTransaction(src, opts)` | Atomic money + item deduction with auto-rollback | | `GetBridges()` | Resolved bridge names per module | | `GetStatus()` | Module load status table | --- ## Plug-and-Play Module System Adding a completely new system requires three files and two lines in the manifest — nothing else. **Files to create:** ``` modules/mymodule/init.lua ← declares name, version, bridge priority list modules/mymodule/client.lua ← client API, ends with Lib.done('mymodule') modules/mymodule/server.lua ← server API, ends with Lib.done('mymodule') ``` **Lines to add in `fxmanifest.lua`:** ```lua -- in client_scripts { } 'modules/mymodule/init.lua', 'modules/mymodule/client.lua', -- in server_scripts { } 'modules/mymodule/init.lua', 'modules/mymodule/server.lua', ``` No changes to config, no changes to shared files, no registry updates, no loader list to edit. The `_template` folder contains a fully commented example to copy from. --- ## File Structure ``` rps_lib/ ├── fxmanifest.lua Resource manifest ├── config/ │ └── config.lua User config – bridges, defaults, job mappings ├── core/ │ ├── shared.lua Lib table, bridge resolver, module registry, utilities │ ├── client.lua Event bus, ready gate, net event receivers │ ├── server.lua Server event bus, notify helpers │ ├── exports_client.lua All client-side exports (loaded last) │ └── exports_server.lua All server-side exports + boot report (loaded last) └── modules/ ├── _template/ Copy this to add a new module │ ├── init.lua │ ├── client.lua │ └── server.lua ├── framework/ ESX · QBCore · QBX · ox_core · ND_Core │ ├── init.lua │ ├── client.lua │ └── server.lua ├── inventory/ ox · qb · qs · ps · codem ├── notify/ ox_lib · qb · okokNotify · mythic · esx · native ├── fuel/ ox_fuel · LegacyFuel · cdn · ps · sna · native ├── radial/ ox_lib · qb-radialmenu ├── dispatch/ ps · cd · linden · core · qs ├── target/ ox_target · qb-target · bt-target ├── doorlock/ ox · qb · nUI · native fallback └── gang/ op-crime · ps-gangs · esx_gang · qbx · qb · ND ``` --- ## Quick Start ``` ensure rps_lib ← in server.cfg, before your scripts ``` ```lua -- fxmanifest.lua of your script dependencies { 'rps_lib' } ``` ```lua -- client.lua local Lib = exports['rps_lib']:GetLib() -- server.lua local Lib = exports['rps_lib']:GetLib() ``` --- ## Version | | | |---|---| | **Name** | rps_lib | | **Version** | 1.0.0 | | **Game** | GTA V / FiveM | | **Lua** | 5.4 | | **Total files** | 37 Lua files | | **Modules** | 9 | | **Supported bridges** | 38 across all modules |

Features

• **Core**
• - ✅ Auto-detects running resources on server start
• - ✅ Pin any module to a specific resource in config
• - ✅ Disable any module with `false` in config
• - ✅ Boot report shows every module status on start
• - ✅ No silent fallback when a pinned resource is not running
• - ✅ Lazy bridge resolution — config always read before detection
• - ✅ Bridge results cached after first call — zero repeated overhead
• - ✅ Internal event bus on both client and server
• - ✅ Client ready gate prevents startup race conditions
• - ✅ 37 Lua files, all syntax-verified
• **Framework**
• - ✅ Get player job name, grade, and label
• - ✅ Get player money by account (cash, bank, black_money)
• - ✅ Get player citizen identifier
• - ✅ Check player job with optional minimum grade
• - ✅ Accept a single job or list of jobs for job checks
• - ✅ Server: add and remove money with insufficient funds check
• **Inventory**
• - ✅ Get item count
• - ✅ Check player has minimum quantity of an item
• - ✅ Get all inventory items as normalised list
• - ✅ Open stash and vehicle trunk
• - ✅ Server: add and remove items with optional metadata
• - ✅ Server: register usable item callback
• - ✅ Server: register persistent stash
• **Notifications**
• - ✅ Success, error, info, and warning notifications
• - ✅ Progress bar with animation and cancel support
• - ✅ Input dialog with multiple field types
• - ✅ Server: send to player, broadcast to all, broadcast to job
• - ✅ Native GTA fallback if no system found
• **Fuel**
• - ✅ Get, set, add, and remove fuel
• - ✅ Low fuel threshold check
• - ✅ Drain thread with custom rate — returns a stop function
• - ✅ Server: set and add fuel by vehicle network id
• - ✅ Native fallback if no system found
• **Radial Menu**
• - ✅ Add and remove item groups
• - ✅ Sub-menu support (ox_lib)
• - ✅ Enable and disable the wheel
• - ✅ Auto-register qb-radialmenu callbacks
• - ✅ Server: push and remove items per player or globally
• **Dispatch**
• - ✅ Send alerts with code, blip, plate, weapon, and priority
• - ✅ Shorthand for police, EMS, and fire
• - ✅ Multi-job alert support
• - ✅ Server relay fallback when no dispatch resource found
• **Target**
• - ✅ Entity, box zone, sphere zone, and model targets
• - ✅ Job and item restrictions per option
• - ✅ Auto-register qb-target callbacks
• - ✅ Remove entity, zone, and model targets
• - ✅ Server: push and remove zones and models per player or globally
• **Door Locks**
• - ✅ Register, lock, unlock, and toggle doors
• - ✅ Authorised job and grade per door
• - ✅ Server: door states synced to all clients
• - ✅ Server: new players receive all door states on join
• - ✅ Native entity freeze fallback if no system found
• **Gang**
• - ✅ Get gang name, grade, grade label, and display label
• - ✅ Check if player is boss, in a gang, or matches specific gangs
• - ✅ Minimum grade check on gang membership
• - ✅ Normalised data table — consistent keys across all bridges
• - ✅ op-crime detected before qb-core (correct op-framework name)
• - ✅ Standalone gang systems always checked before framework built-ins
• - ✅ Listen for gang changes via event
• - ✅ Server: set and remove gang, get online members and bosses
• - ✅ Server: notify all members or bosses of a gang