LuaBeans Bridge

LuaBeans Bridge is the core FiveM integration resource that connects your server to LuaBeans - Community Manager. It handles API communication, duty state management, and provides exports for other resources.

Overview

LuaBeans Bridge acts as the communication layer between your FiveM server and the LuaBeans web panel. It:

• Manages player duty state (on/off duty)

• Fetches player departments and ranks from the web panel

• Provides exports for other resources to check duty status

• Caches player data to reduce API calls

• Handles authentication via API token

Installation

Step 1: Copy Resource

Copy the luabeans resource folder into your FiveM server's resources directory:

# From your FiveM server directory
cp -r /path/to/luabeans fivem-server/resources/

Or extract from the distribution ZIP if you downloaded it.

Step 2: Configure Server

Add to your server.cfg:

# LuaBeans Bridge
set LUABEANS_API_BASE "https://hub.yourserver.com"
set LUABEANS_LEO_API_TOKEN "your-api-token-from-web-panel-env"
ensure luabeans

Important: The LUABEANS_LEO_API_TOKEN must match the LEO_API_TOKEN value in your web panel's .env file.

Step 3: Verify Installation

1. Start your FiveM server

2. Check console for LuaBeans Bridge startup messages

3. Join the server and test duty commands

Configuration

Required Convars

Convar	Required	Description	Example
LUABEANS_API_BASE	Yes	Base URL of your LuaBeans web panel	https://hub.yourserver.com
LUABEANS_LEO_API_TOKEN	Yes	API token (must match LEO_API_TOKEN in web panel)	abc123...

Optional Configuration

Edit config.lua to customize behavior:

Config.API = {
  BaseURL = GetConvar('LUABEANS_API_BASE', 'https://hub.example.com'),
  Token = GetConvar('LUABEANS_LEO_API_TOKEN', ''),
  TimeoutMs = 5000,  -- API request timeout
  Enabled = true      -- Enable/disable API calls
}

Config.RefreshIntervalMs = 300000  -- Refresh player data every 5 minutes
Config.Debug = false               -- Enable debug logging

Integrations

rcore_police Integration

Automatically sync duty state with rcore_police:

Config.Integrations.RcorePoliceDutyBridge = true  -- Default: true

When enabled, LuaBeans Bridge will call:

TriggerEvent('rcore_police:server:setPlayerDuty', source, onDuty)

ESX Integration

Automatically sync job assignments with ESX:

Config.ESX = {
  Enabled = true,                          -- Enable ESX integration
  LeoJobType = 'leo',                      -- Job type for LEO departments
  OffDutyFallbackJob = 'unemployed',       -- Job when going off duty
  OffDutyFallbackGrade = 0,                -- Job grade when off duty
  SwitchJobOnDuty = false                  -- Don't overwrite permanent job assignments
}

When on duty, the player's job is set to the department slug. When off duty, it reverts to the fallback job.

Client Exports

LuaBeans Bridge provides several client exports for other resources to use.

IsPlayerOnDuty()

Check if a player is currently on duty.

local isOnDuty = exports['luabeans']:IsPlayerOnDuty()

if isOnDuty then
  print("Player is on duty")
else
  print("Player is off duty")
end

Returns: boolean - true if on duty, false if off duty

GetDutyOptions()

Get all available duty options for the player.

local options = exports['luabeans']:GetDutyOptions()

if options.ok then
  print("Departments available:", #options.departments)
  for i, dept in ipairs(options.departments) do
    print("- " .. dept.name)
  end
  
  -- Set active department
  if #options.departments > 0 then
    options.departments[1].setActive()
  end
else
  print("Error:", options.error)
end

Returns: Table with:

• ok (boolean) - Whether the request succeeded

• departments (table) - Array of available departments

• selectedDeptId (number) - Currently selected department ID

• onDuty (boolean) - Whether player is currently on duty

Each department entry has a setActive() method to set it as the active department.

UpdatePlayerDuty(status)

Go on or off duty.

-- Go on duty with currently selected department
exports['luabeans']:UpdatePlayerDuty(true)

-- Go off duty
exports['luabeans']:UpdatePlayerDuty(false)

Parameters:

• status (boolean) - true to go on duty, false to go off duty

Note: If going on duty, you must first select a department using GetDutyOptions().departments[index].setActive().

Server Events

luabeans:server:playerOnDuty

Fired when a player goes on duty.

RegisterNetEvent('luabeans:server:playerOnDuty', function(source, departmentId, rankId)
  -- Handle player going on duty
  print("Player", source, "went on duty for department", departmentId)
end)

Parameters:

• source (number) - Player server ID

• departmentId (number) - Department ID

• rankId (number) - Player's rank ID in department

luabeans:server:playerOffDuty

Fired when a player goes off duty.

RegisterNetEvent('luabeans:server:playerOffDuty', function(source)
  -- Handle player going off duty
  print("Player", source, "went off duty")
end)

Parameters:

• source (number) - Player server ID

Client Events

These events are emitted by LuaBeans Bridge for UI resources to listen to.

luabeans:client:profile

Fired when player profile data is loaded or refreshed.

RegisterNetEvent('luabeans:client:profile', function(profile)
  -- profile contains player data from web panel
  print("Profile loaded:", json.encode(profile))
end)

Profile Structure:

{
  userId = 123,
  discordId = "123456789012345678",
  username = "PlayerName",
  departments = {
    {
      id = 1,
      name = "Police Department",
      slug = "police",
      rankId = 5,
      rankName = "Officer",
      rankOrder = 3
    }
  }
}

luabeans:client:deptData

Fired when department data is loaded (vehicles, uniforms, etc.).

RegisterNetEvent('luabeans:client:deptData', function(data)
  -- data.dept contains department info
  -- data.assets contains vehicles, uniforms, loadouts, locations
  print("Department data loaded for:", data.dept.name)
end)

luabeans:client:offDuty

Fired when player goes off duty (client-side notification).

RegisterNetEvent('luabeans:client:offDuty', function()
  -- Handle off duty notification
  print("You went off duty")
end)

API Endpoints Used

LuaBeans Bridge makes API calls to these endpoints:

GET /api/leo/user/:discordId/departments

Fetches player's departments and ranks.

Headers:

• Authorization: Bearer <LUABEANS_LEO_API_TOKEN>

Response:

{
  "ok": true,
  "departments": [
    {
      "id": 1,
      "name": "Police Department",
      "slug": "police",
      "rankId": 5,
      "rankName": "Officer",
      "rankOrder": 3,
      "permissions": ["leo.duty", "leo.vehicle"]
    }
  ]
}

POST /api/leo/duty/:action

Updates player duty state.

Actions: on or off

Headers:

• Authorization: Bearer <LUABEANS_LEO_API_TOKEN>

• Content-Type: application/json

Body (for on action):

{
  "departmentId": 1,
  "discordId": "123456789012345678"
}

Troubleshooting

Resource Not Starting

Issue: LuaBeans Bridge won't start

Solutions:

1. Check server.cfg has ensure luabeans

2. Verify resource folder name is exactly luabeans

3. Check console for error messages

4. Verify fxmanifest.lua is present

API Connection Failed

Issue: Cannot connect to web panel API

Solutions:

1. Verify LUABEANS_API_BASE is correct and accessible from server

2. Check LUABEANS_LEO_API_TOKEN matches web panel LEO_API_TOKEN

3. Verify web panel is running and accessible

4. Check firewall rules allow connection from FiveM server

5. Verify SSL certificate is valid (if using HTTPS)

No Departments Showing

Issue: Player sees no departments in duty menu

Solutions:

1. Verify player has discord: identifier

2. Check player is assigned to departments in web panel

3. Verify DISCORD_GUILD_ID matches in web panel

4. Check player has active department memberships

5. Use /dutyrefresh command to refresh player data

Duty State Not Persisting

Issue: Duty state resets on disconnect/reconnect

Solutions:

1. This is expected behavior - duty state is session-based

2. Players must go on duty each time they join

3. Duty state is not saved between sessions

Permission Issues

Issue: Player has incorrect permissions

Solutions:

1. Refresh player data: /dutyrefresh or Refresh roles in web panel

2. Verify rank permissions in web panel

3. Check department assignment in web panel

4. Verify Discord role syncing is working

Performance Considerations

API Rate Limiting

• LuaBeans Bridge caches player data for 5 minutes (configurable)

• API calls are rate-limited to prevent spam

• Consider increasing Config.RefreshIntervalMs if experiencing rate limits

Network Optimization

• Uses connection pooling for HTTP requests

• Implements request timeouts (default 5 seconds)

• Handles network errors gracefully

Resource Dependencies

LuaBeans Bridge has no hard dependencies but integrates with:

• ESX (optional) - For job sync

• rcore_police (optional) - For duty bridge

• Discord identifiers - Required for all players

Advanced Usage

Custom Duty Logic

You can listen to duty events and implement custom logic:

RegisterNetEvent('luabeans:server:playerOnDuty', function(source, departmentId, rankId)
  -- Custom on-duty logic
  local xPlayer = ESX.GetPlayerFromId(source)
  if xPlayer then
    -- Give items, set job, etc.
    xPlayer.addInventoryItem('handcuffs', 1)
  end
end)

RegisterNetEvent('luabeans:server:playerOffDuty', function(source)
  -- Custom off-duty logic
  local xPlayer = ESX.GetPlayerFromId(source)
  if xPlayer then
    -- Remove items, reset job, etc.
    xPlayer.removeInventoryItem('handcuffs', 1)
  end
end)

Integration with Other Resources

Other resources can check duty status:

-- In another resource
local function isPlayerOnDuty(source)
  local isOnDuty = false
  TriggerClientEvent('luabeans:client:checkDuty', source)
  RegisterNetEvent('luabeans:client:dutyStatus', function(status)
    isOnDuty = status
  end)
  -- Note: This is a simplified example - actual implementation may vary
  return isOnDuty
end

Configuration Files

config.lua

Main configuration file for integrations and API settings.

Location: luabeans/config.lua

Note: This file is excluded from escrow by default so you can edit it.

fxmanifest.lua

Resource manifest defining files and dependencies.

Support

For issues with LuaBeans Bridge:

• Check console logs for error messages

• Verify API connectivity

• Review Troubleshooting section

• Check web panel logs for API errors

• Ensure player has proper Discord identifier

Related Documentation

• LuaBeans Duty - UI/menu layer for duty system

• LEO Duty System - Web panel configuration

• FiveM API Documentation - Complete API reference