> For the complete documentation index, see [llms.txt](https://docs.sourcedev.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sourcedev.pro/src-billing/bridge-overview.md).

# 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

```mermaid
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:

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

### ✅ Manual Override

Force a specific framework if needed:

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

### ✅ Easy to Extend

Adding support for a custom framework is straightforward:

```lua
-- 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

```lua
-- 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:

{% content-ref url="<https://github.com/dollar-src/docs/tree/main/billing/gitbook-custom-framework.md>" %}
<https://github.com/dollar-src/docs/tree/main/billing/gitbook-custom-framework.md>
{% endcontent-ref %}

## Critical Functions

### ⚠️ Money Handling

The money functions are **CRITICAL** and must be implemented correctly:

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

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

{% hint style="danger" %}
**IMPORTANT:** Incorrect money handling can lead to:

* Money duplication exploits
* Money loss bugs
* Transaction failures

Always test money functions thoroughly!
{% endhint %}

## Testing Your Bridge

### Basic Test

```lua
-- 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

```lua
-- 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

{% content-ref url="<https://github.com/dollar-src/docs/tree/main/billing/gitbook-client-functions.md>" %}
<https://github.com/dollar-src/docs/tree/main/billing/gitbook-client-functions.md>
{% endcontent-ref %}

{% content-ref url="<https://github.com/dollar-src/docs/tree/main/billing/gitbook-server-functions.md>" %}
<https://github.com/dollar-src/docs/tree/main/billing/gitbook-server-functions.md>
{% endcontent-ref %}

{% content-ref url="<https://github.com/dollar-src/docs/tree/main/billing/gitbook-custom-framework.md>" %}
<https://github.com/dollar-src/docs/tree/main/billing/gitbook-custom-framework.md>
{% endcontent-ref %}