Installation

Installation Guide

This guide will walk you through installing and setting up B2Lib in your FiveM server.

Requirements

Before installing B2Lib, ensure your server meets these requirements:

• FiveM Server: Latest recommended version

• Operating System: Windows or Linux

• Node.js: Version 16 or higher (for building the web interface)

• Framework: Any FiveM framework (ESX, QBCore, etc.) or standalone

Installation Methods

Method 1: Download Release (Recommended)

1. Download the latest release from the B2Lib releases page

2. Extract the archive to your server's resources folder

3. Rename the folder to b2lib (if not already named correctly)

4. Add to server.cfg:

   ensure b2lib

Method 2: Git Clone

1. Navigate to your resources folder:

   cd /path/to/your/server/resources

2. Clone the repository:

   git clone https://github.com/your-repo/b2lib.git

3. Navigate to the B2Lib folder:

   cd b2lib

4. Install dependencies and build:

   npm install
   npm run build

5. Add to server.cfg:

   ensure b2lib

Quick Setup

1. Basic Configuration

The default configuration should work out of the box, but you can customize it:

1. Open config.lua in the B2Lib folder

2. Review the settings and adjust as needed:

-- Basic configuration
Config.Debug = false                    -- Enable debug mode
Config.DefaultTheme = 'dark'           -- Default UI theme
Config.Language = 'en'                 -- Language (en, es, fr, de, etc.)

-- Enable/disable components
Config.EnabledComponents = {
    notifications = true,
    progress = true,
    menus = true,
    textui = true,
    input = true,
    alert = true,
    contextMenu = true,
    skillcheck = true,
    lockpicking = true,
    hacking = true
}

2. Start Your Server

1. Start your FiveM server

2. Check the console for any errors

3. Join your server to test the installation

3. Test the Installation

Run these commands in-game to test B2Lib:

/b2demo:notification
/b2demo:progress
/b2demo:skillcheck
/b2demo:lockpicking
/themesettings

Verification

Console Output

When B2Lib starts successfully, you should see:

[B2Lib] Starting B2Lib v1.0.0
[B2Lib] Loading configuration...
[B2Lib] Initializing UI components...
[B2Lib] B2Lib started successfully!

In-Game Test

1. Open the theme settings with /themesettings or F7 (if bound)

2. Try a notification:

   exports.b2lib:notify({
       type = 'success',
       title = 'Installation Test',
       message = 'B2Lib is working correctly!'
   })

Framework Integration

ESX Integration

B2Lib works seamlessly with ESX. No additional configuration required.

-- Example: ESX job notification
AddEventHandler('esx:setJob', function(job)
    exports.b2lib:notify({
        type = 'info',
        title = 'Job Changed',
        message = string.format('You are now a %s', job.label),
        duration = 5000
    })
end)

QBCore Integration

B2Lib works with QBCore out of the box.

-- Example: QBCore notification
RegisterNetEvent('QBCore:Notify', function(text, type, length)
    exports.b2lib:notify({
        type = type or 'info',
        message = text,
        duration = length or 5000
    })
end)

Standalone Usage

B2Lib can be used without any framework:

-- Example: Standalone usage
RegisterCommand('test', function()
    exports.b2lib:notify({
        type = 'success',
        title = 'Test',
        message = 'Hello from B2Lib!'
    })
end)

Troubleshooting

Common Issues

1. Resource Not Starting

Problem: B2Lib doesn't start or shows errors in console.

Solutions:

• Check that the folder is named exactly b2lib

• Ensure ensure b2lib is in your server.cfg

• Verify all files are present and not corrupted

• Check server console for specific error messages

2. UI Not Showing

Problem: UI components don't appear in-game.

Solutions:

• Check if NUI is enabled on your server

• Verify the web/dist folder exists and contains built files

• Try rebuilding the web interface: npm run build

• Check browser console (F12) for JavaScript errors

3. Theme Settings Not Opening

Problem: Theme settings don't open when called.

Solutions:

• Ensure the player has appropriate permissions

• Check if another UI is blocking NUI focus

• Verify the theme settings component is enabled in config

• Try restarting the resource: /restart b2lib

4. Build Errors

Problem: npm run build fails with errors.

Solutions:

• Ensure Node.js version 16+ is installed

• Delete node_modules and run npm install again

• Check for any missing dependencies

• Ensure you have write permissions in the folder

Debug Mode

Enable debug mode for detailed logging:

Config.Debug = true

This will show detailed information in the console about:

• Component initialization

• Function calls and parameters

• Event triggers

• Error details

Getting Help

If you're still having issues:

1. Check the console for error messages

2. Enable debug mode for more information

3. Review the documentation for proper usage

4. Check GitHub issues for known problems

5. Create a new issue with detailed information

Performance Optimization

Server Performance

• Disable unused components in Config.EnabledComponents

• Adjust notification limits in Config.Notifications.maxVisible

• Use appropriate update intervals for dynamic content

Client Performance

• Limit concurrent UI elements (notifications, progress bars, etc.)

• Use efficient positioning (avoid frequent position changes)

• Test on lower-end hardware to ensure compatibility

Security Considerations

Server Security

• Review permissions for theme settings access

• Validate user inputs in custom implementations

• Monitor resource usage to prevent abuse

Client Security

• Keep NUI secure by validating all data

• Avoid exposing sensitive information in UI components

• Use proper event validation for client-server communication

Next Steps

After successful installation:

1. Read the UI Components Guide to learn about available components

2. Explore Configuration Options for customization

3. Check out Examples for implementation ideas

4. Review Best Practices for optimal usage

Updates

Updating B2Lib

1. Backup your configuration (config.lua and any custom settings)

2. Download the latest release or pull from Git

3. Replace the old files (keeping your config backup)

4. Restore your configuration settings

5. Restart the resource: /restart b2lib

6. Test functionality to ensure everything works

Version Compatibility

• Check release notes for breaking changes

• Test in development before updating production

• Keep backups of working versions

---