Configuration

Complete guide to configuring LuaBeans resources for your FiveM server.

Overview

LuaBeans requires two FiveM resources:

• luabeans (Bridge) - Core integration and API communication

• luabeans_duty (Duty) - UI/menu layer for duty system

Both resources must be configured and installed for full functionality.

Installation

Step 1: Copy Resources

Copy both resources to your FiveM server:

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

Step 2: Configure Server

Add to server.cfg:

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

# Start resources (order matters - bridge first)
ensure luabeans
ensure luabeans_duty

Important:

• luabeans must start before luabeans_duty

• API token must match LEO_API_TOKEN in web panel .env

• Base URL must be accessible from FiveM server

Step 3: Verify Installation

1. Start FiveM server

2. Check console for LuaBeans Bridge startup messages

3. Join server and test /duty command

4. Verify menu appears and functions

Configuration Files

luabeans/config.lua

Main configuration file for LuaBeans Bridge:

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

Config.RefreshIntervalMs = 300000  -- 5 minutes
Config.Debug = false

Integration Configuration

rcore_police Integration

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

When enabled, LuaBeans Bridge will automatically sync duty state with rcore_police.

ESX Integration

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

luabeans_duty/config.lua

Configuration file for LuaBeans Duty UI:

-- ACE Permissions on Duty
Config.AcePermsOnDuty = {
  "command.allowed",
  "resource.allowed"
}

-- Department-specific permissions
Config.AcePermsByDepartmentSlug = {
  ["police"] = {
    "command.police",
    "vehicle.police"
  },
  ["sheriff"] = {
    "command.sheriff"
  }
}

Convars Reference

Required Convars

Convar	Required	Description	Example
LUABEANS_API_BASE	Yes	Web panel base URL	https://hub.example.com
LUABEANS_LEO_API_TOKEN	Yes	API token (matches web panel LEO_API_TOKEN)	abc123...

Example Configuration

# LuaBeans Configuration
set LUABEANS_API_BASE "https://hub.yourserver.com"
set LUABEANS_LEO_API_TOKEN "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Resource Dependencies

Required

• Discord Identifiers - All players must have discord: identifier

Optional

• ESX - For job synchronization

• rcore_police - For duty state bridge

• Custom Menu Systems - Replace default menu if desired

Integration Examples

ESX Integration

If using ESX, enable ESX integration in luabeans/config.lua:

Config.ESX.Enabled = true
Config.ESX.LeoJobType = 'leo'
Config.ESX.OffDutyFallbackJob = 'unemployed'

This will:

• Set player job to department slug when on duty

• Revert to fallback job when off duty

• Respect permanent job assignments (if SwitchJobOnDuty = false)

rcore_police Integration

Automatically bridges duty state with rcore_police:

Config.Integrations.RcorePoliceDutyBridge = true

When enabled, LuaBeans Bridge will trigger:

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

Troubleshooting

Resources Not Starting

Issue: Resources won't start

Solutions:

1. Check resource folder names are exactly luabeans and luabeans_duty

2. Verify fxmanifest.lua exists in each resource

3. Check console for syntax errors

4. Verify all dependencies are available

API Connection Failed

Issue: Cannot connect to web panel

Solutions:

1. Verify LUABEANS_API_BASE is correct

2. Check web panel is running and accessible

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

4. Test API endpoint manually: curl https://hub.example.com/api/leo/user/123/departments -H "Authorization: Bearer TOKEN"

5. Check firewall allows connection from FiveM server

Token Authentication Failed

Issue: API returns 401 Unauthorized

Solutions:

1. Verify LUABEANS_LEO_API_TOKEN matches web panel LEO_API_TOKEN

2. Check token is set correctly in server.cfg

3. Verify token format is correct

4. Check token hasn't been changed or expired

No Departments Showing

Issue: Player sees no departments

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. Refresh player data: /dutyrefresh command or web panel "Refresh roles"

5. Check player has active department memberships

Duty State Not Saving

Issue: Duty state resets on disconnect

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 persistent between sessions

4. This is by design for security and accuracy

Performance Tuning

API Rate Limiting

LuaBeans Bridge caches player data to reduce API calls:

• Default cache: 5 minutes (Config.RefreshIntervalMs = 300000)

• Adjustable: Increase for less frequent updates

• Manual refresh: /dutyrefresh command forces refresh

Network Optimization

• Uses connection pooling for HTTP requests

• Implements request timeouts (default 5 seconds)

• Handles network errors gracefully

• Retries failed requests automatically

Security Best Practices

1. Use HTTPS - Always use HTTPS for API communication

2. Secure Token - Keep API token secret and secure

3. Validate Input - Validate Discord IDs and department IDs

4. Rate Limiting - Respect API rate limits

5. Monitor Logs - Check logs for suspicious activity

Related Documentation

• LuaBeans Bridge - Core integration resource

• LuaBeans Duty - Duty system UI

• FiveM API Reference - Complete API documentation

• LEO Duty System - Web panel configuration