🔌Bridge Overview

What is the Bridge System?

The Bridge System is a framework-agnostic layer that allows the Billing System to work with any FiveM framework. It provides a unified API for all core functions, regardless of which framework you're using.

Supported Frameworks

Out of the box, the bridge supports:

Framework	Status	Auto-Detect
QBox (qbx_core)	✅ Fully Supported	✅ Yes
QBCore (qb-core)	✅ Fully Supported	✅ Yes
ESX (es_extended)	✅ Fully Supported	✅ Yes
Custom	🔧 Easy to Add	⚙️ Manual

How It Works

graph LR
    A[Billing System] --> B[Bridge Layer]
    B --> C[QBox]
    B --> D[QBCore]
    B --> E[ESX]
    B --> F[Custom Framework]

The bridge automatically detects your framework and routes all function calls to the correct implementation.

File Structure

bridge/
├── shared.lua    # Framework detection & initialization
├── client.lua    # Client-side bridge functions
├── server.lua    # Server-side bridge functions
└── README.md     # Detailed documentation

Key Features

✅ Automatic Detection

The bridge automatically detects your framework:

-- In config.lua
Config.Framework = 'auto'  -- Automatically detects QBox, QBCore, or ESX

✅ Manual Override

Force a specific framework if needed:

Config.Framework = 'qbox'  -- or 'qb', 'esx', 'custom'

✅ Easy to Extend

Adding support for a custom framework is straightforward:

-- Just implement the required functions
function Bridge.GetPlayer(source)
    if GetFW() == 'custom' then
        return exports['your-core']:GetPlayer(source)
    end
end

Bridge Functions

Client-Side Functions

Function	Purpose	Returns
GetPlayerData()	Get player data	table
GetPlayerJob()	Get player's job	table
GetPlayerName()	Get character name	string
GetPlayerIdentifier()	Get unique ID	string
HasAllowedJob()	Check if job allowed	boolean
GetNearbyPlayers()	Get nearby players	table
Notify(msg, type)	Show notification	void

Server-Side Functions

Function	Purpose	Returns
GetPlayer(source)	Get player object	table
GetIdentifier(source)	Get player ID	string
GetPlayerNameServer(source)	Get name	string
GetPlayerJobServer(source)	Get job	table
GetPlayerBank(source)	Get bank balance	number
GetPlayerCash(source)	Get cash balance	number
RemoveMoney(source, amount, type)	Remove money	boolean
AddMoney(source, amount, type)	Add money	boolean
GetAllPlayers()	Get all players	table
IsJobBossServer(source, job)	Check if boss	boolean

Quick Start

Using the Bridge

-- Client-side example
local playerData = Bridge.GetPlayerData()
local job = Bridge.GetPlayerJob()
Bridge.Notify('Invoice sent!', 'success')

-- Server-side example
local Player = Bridge.GetPlayer(source)
local bank = Bridge.GetPlayerBank(source)
local success = Bridge.RemoveMoney(source, 100, 'bank')

Adding Custom Framework

See the detailed guides:

https://github.com/dollar-src/docs/blob/main/billing/gitbook-custom-framework.md

Critical Functions

⚠️ Money Handling

The money functions are CRITICAL and must be implemented correctly:

-- Remove money (MUST validate and return boolean)
Bridge.RemoveMoney(source, amount, 'bank')

-- Add money (MUST be transaction-safe)
Bridge.AddMoney(source, amount, 'cash')

IMPORTANT: Incorrect money handling can lead to:

• Money duplication exploits

• Money loss bugs

• Transaction failures

Always test money functions thoroughly!

Testing Your Bridge

Basic Test

-- In-game console (F8)
/invoice  -- Should open if you have allowed job

Money Test

1. Create invoice for $100

2. Pay with cash

3. Verify money was removed

4. Pay with bank

5. Verify money was removed

Full Test Checklist

• Framework detected correctly

• Player data retrieved

• Job checks working

• Nearby players detected

• Notifications showing

• Money removal working

• Money addition working

• No console errors

Troubleshooting

Framework Not Detected

-- Check current framework
print(Bridge.GetFramework())

-- Manually set
Config.Framework = 'qbox'

Money Functions Not Working

1. Verify player object is valid

2. Check money type ('cash' or 'bank')

3. Add debug prints

4. Check framework documentation

Next Steps

https://github.com/dollar-src/docs/blob/main/billing/gitbook-client-functions.mdhttps://github.com/dollar-src/docs/blob/main/billing/gitbook-server-functions.mdhttps://github.com/dollar-src/docs/blob/main/billing/gitbook-custom-framework.md