Configuration

B2Lib provides extensive configuration options to customize the appearance, behavior, and functionality of all UI components. This guide covers every aspect of the configuration system, from basic settings to advanced customization.

Overview

The B2Lib configuration system is centralized in the Config.lua file, which contains all settings for:

  • Theme System - Colors, typography, spacing, and visual styles

  • Component Settings - Individual UI component configurations

  • Performance Options - Optimization settings for better performance

  • Feature Toggles - Enable/disable specific components

  • Styling Configurations - Detailed appearance customization

Quick Start

Basic Configuration

-- 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
}

-- Set default theme
Config.Theme.mode = 'dark' -- 'light', 'dark', 'transparent'

-- Configure notifications
Config.Notifications = {
    defaultDuration = 5000,
    defaultPosition = 'top-right',
    maxVisible = 5,
    showIcon = true,
    playSound = true
}

Performance Optimization

Config.Performance = {
    maxNotifications = 5,        -- Limit simultaneous notifications
    updateInterval = 16,         -- 60 FPS update rate
    fadeAnimations = true,       -- Enable smooth animations
    maxCacheSize = 1000,        -- UI element cache limit
    raycastDistance = 10.0,     -- Interaction detection range
    entityCheckDistance = 50.0   -- Entity scanning range
}

Position System

B2Lib uses a comprehensive 9-position grid system for consistent UI placement across all screen resolutions.

Grid Layout

┌─────────────────────────────────────┐
│ top-left    top-center    top-right │
│                                     │
│ center-left   center   center-right │
│                                     │
│ bottom-left bottom-center bottom-right │
└─────────────────────────────────────┘

Valid Positions

Primary Positions:

  • top-left, top-center, top-right

  • center-left, center, center-right

  • bottom-left, bottom-center, bottom-right

Legacy Aliases:

  • left (center-left)

  • right (center-right)

  • center-top, center-bottom, bottom

Best Practices

Position
Best Use Case
Reason

top-right

Notifications

Non-intrusive, natural reading flow

bottom-center

Interaction prompts

Natural eye focus area

center

Important dialogs

Maximum attention

center-left

Menus

Easy access, doesn't block gameplay

Avoid: top-left and bottom-left due to potential conflicts with other UI elements.

Usage Examples

-- Notification in top-right corner
exports.b2lib:notify({
    message = "Welcome to the server!",
    position = "top-right"
})

-- Progress bar in center
exports.b2lib:progress({
    label = "Loading...",
    position = "center",
    duration = 5000
})

-- Text UI at bottom center
exports.b2lib:textUI({
    text = "[E] Interact",
    position = "bottom-center"
})

Theme System

The theme system provides comprehensive visual customization with three built-in themes and extensive customization options.

Theme Modes

Dark Theme (Default)

Professional dark theme optimized for low-light environments.

Config.Theme.mode = 'dark'

Features:

  • Dark backgrounds with light text

  • High contrast for readability

  • Reduced eye strain in low-light conditions

  • Professional appearance

Light Theme

Clean, bright theme optimized for well-lit environments.

Config.Theme.mode = 'light'

Features:

  • Light backgrounds with dark text

  • Clean, modern appearance

  • Excellent readability in bright conditions

  • Familiar interface patterns

Transparent Theme

Semi-transparent theme for immersive gameplay.

Config.Theme.mode = 'transparent'

Features:

  • Transparent backgrounds

  • High contrast text for readability

  • Minimal visual interference

  • Immersive gaming experience

Color System

The color system is based on TailwindCSS neutral palette for consistency and accessibility.

Semantic Colors

Config.Theme.colors.dark = {
    primary = '#3b82f6',      -- Primary actions, links
    secondary = '#6b7280',    -- Secondary actions, muted elements
    success = '#22c55e',      -- Success states, confirmations
    warning = '#f59e0b',      -- Warnings, cautions
    error = '#ef4444',        -- Errors, destructive actions
    info = '#06b6d4',         -- Informational messages
}

Background Hierarchy

background = {
    primary = '#111827',      -- Main background
    secondary = '#1f2937',    -- Elevated surfaces
    tertiary = '#374151',     -- Subtle elevation
    overlay = 'rgba(0, 0, 0, 0.7)' -- Modal overlays
}

Text Hierarchy

text = {
    primary = '#f9fafb',      -- Headings, important text
    secondary = '#e5e7eb',    -- Body text
    tertiary = '#9ca3af',     -- Muted text, labels
    inverse = '#111827'       -- Dark text for light backgrounds
}

Border Colors

border = {
    primary = '#4b5563',      -- Visible borders
    secondary = '#374151',    -- Subtle borders
    accent = '#3b82f6'        -- Focus states, active elements
}

Typography System

Consistent typography scale based on modern design principles.

Config.Theme.typography = {
    fontFamily = 'Inter, system-ui, sans-serif',
    
    fontSize = {
        xs = '0.75rem',    -- 12px - Small labels, captions
        sm = '0.875rem',   -- 14px - Body text, form inputs
        base = '1rem',     -- 16px - Default body text
        lg = '1.125rem',   -- 18px - Subheadings
        xl = '1.25rem',    -- 20px - Headings
    },
    
    fontWeight = {
        normal = '400',    -- Regular text
        medium = '500',    -- Emphasized text
        semibold = '600',  -- Subheadings
        bold = '700'       -- Headings, important text
    },
    
    lineHeight = {
        tight = '1.25',    -- Headings, compact text
        normal = '1.5',    -- Body text
        relaxed = '1.75'   -- Long-form content
    }
}

Spacing System

Consistent spacing scale based on 4px base unit for pixel-perfect alignment.

Config.Theme.spacing = {
    xs = '0.25rem',   -- 4px - Tight spacing
    sm = '0.5rem',    -- 8px - Small spacing
    md = '1rem',      -- 16px - Default spacing
    lg = '1.5rem',    -- 24px - Large spacing
    xl = '2rem',      -- 32px - Extra large spacing
}

Border Radius System

Config.Theme.borderRadius = {
    none = '0',           -- Sharp corners
    sm = '0.125rem',      -- 2px - Subtle rounding
    md = '0.375rem',      -- 6px - Default rounding
    lg = '0.5rem',        -- 8px - Noticeable rounding
    xl = '0.75rem',       -- 12px - Strong rounding
    full = '9999px'       -- Fully rounded (pills, circles)
}

Shadow System

Layered shadow system for depth and elevation.

Config.Theme.shadows = {
    none = 'none',
    sm = '0 1px 2px 0 rgba(0, 0, 0, 0.05)',     -- Subtle depth
    md = '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)', -- Default elevation
    lg = '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)', -- High elevation
    xl = '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)', -- Maximum elevation
    inner = 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)' -- Inset shadows
}

Animation System

Consistent animation timing and easing for smooth interactions.

Config.Theme.animations = {
    enabled = true,        -- Global animation toggle
    
    duration = {
        fast = '150ms',    -- Quick interactions (hover, focus)
        normal = '300ms',  -- Default transitions
        slow = '500ms'     -- Complex animations
    },
    
    easing = {
        linear = 'linear',                           -- Constant speed
        easeIn = 'cubic-bezier(0.4, 0, 1, 1)',      -- Slow start
        easeOut = 'cubic-bezier(0, 0, 0.2, 1)',     -- Slow end
        easeInOut = 'cubic-bezier(0.4, 0, 0.2, 1)'  -- Slow start and end
    },
    
    reducedMotion = false  -- Respect user's motion preferences
}

Component Configuration

Feature Toggles

Enable or disable specific UI components for performance optimization or to prevent conflicts.

Config.EnabledComponents = {
    notifications = true,    -- Toast-style notification system
    progress = true,         -- Progress bars and loading indicators
    menus = true,           -- Hierarchical navigation menus
    textui = true,          -- Contextual text displays with keybinds
    input = true,           -- Input dialogs and forms
    alert = true,           -- Alert and confirmation dialogs
    contextMenu = true,     -- Right-click context menus
    skillcheck = true,      -- Timing-based skillcheck minigame
    lockpicking = true,     -- Tension-based lockpicking minigame
    hacking = true          -- Memory-based hacking minigame
}

Notifications

Configure the toast-style notification system.

Config.Notifications = {
    defaultDuration = 5000,      -- Default display duration in milliseconds
    defaultPosition = 'top-right', -- Default position for notifications
    maxVisible = 5,              -- Maximum notifications shown simultaneously
    showIcon = true,             -- Show type-specific icons
    playSound = true             -- Play notification sounds
}

Usage Example:

exports.b2lib:notify({
    type = 'success',
    message = 'Action completed successfully!',
    duration = 3000
})

Progress Bars

Configure progress bars for loading states and timed actions.

Config.Progress = {
    position = 'center',         -- Default position for progress bars
    showPercentage = true,       -- Display percentage text
    defaultColor = 'primary',    -- Default progress bar color
    defaultType = 'circular'     -- Default type: 'circular' or 'linear'
}

Usage Example:

exports.b2lib:progress({
    label = 'Processing...',
    duration = 5000,
    type = 'circular',
    color = 'success'
})

Text UI

Configure contextual text displays with optional keybind hints.

Config.TextUI = {
    position = 'bottom-center',  -- Default position for text UI
    showBackground = true,       -- Show background for better readability
    fadeTime = 400              -- Fade animation duration in milliseconds
}

Usage Example:

exports.b2lib:textUI({
    text = 'Press E to interact',
    keybind = 'E',
    icon = 'hand'
})

Menu System

Configure hierarchical navigation menus with search and dynamic content.

Config.Menu = {
    position = 'center-left',    -- Default position for menus
    width = 400,                 -- Default menu width in pixels
    enableSearch = true,         -- Enable search functionality
    closeOnClick = true,         -- Close menu when clicking outside
    maxItems = 10               -- Maximum items per menu page
}

Input Dialogs

Configure input dialogs for collecting user data.

Config.Input = {
    position = 'center',         -- Default position for input dialogs
    showBackground = true,       -- Show dialog background
    enableValidation = true      -- Enable input validation
}

Alert Dialogs

Configure alert and confirmation dialogs.

Config.Alert = {
    position = 'center-left',    -- Default position for alert dialogs
    showBackground = true,       -- Show dialog background
    enableConfirm = true         -- Enable confirmation dialogs
}

Context Menus

Configure position-based context menus for right-click interactions.

Config.ContextMenu = {
    enableTouch = true,          -- Enable touch/mobile support
    closeOnOutsideClick = true,  -- Close when clicking outside menu
    showIcons = true             -- Show icons in menu items
}

Skillcheck Minigame

Configure the timing-based skillcheck minigame system with single-zone design.

Config.Skillcheck = {
    position = 'center',         -- Default position for skillcheck
    defaultDifficulty = 'medium', -- Default difficulty level
    
    difficulties = {
        easy = {
            speed = 1.0,         -- Slow indicator movement
            targetSize = 45,     -- Target zone size (not used in single-zone)
            perfectSize = 25,    -- Large perfect zone
            maxAttempts = 5,     -- Multiple attempts
            pattern = 'continuous', -- Movement pattern
            direction = 1        -- Clockwise movement
        },
        medium = {
            speed = 2.0,         -- Medium indicator movement
            targetSize = 45,     -- Target zone size (not used in single-zone)
            perfectSize = 15,    -- Medium perfect zone
            maxAttempts = 3,     -- Three attempts
            pattern = 'continuous', -- Movement pattern
            direction = 1        -- Clockwise movement
        },
        hard = {
            speed = 3.0,         -- Fast indicator movement
            targetSize = 45,     -- Target zone size (not used in single-zone)
            perfectSize = 10,    -- Small perfect zone
            maxAttempts = 2,     -- Two attempts
            pattern = 'bounce', -- Bounce pattern for difficulty
            direction = 1        -- Clockwise movement
        },
        expert = {
            speed = 4.0,         -- Very fast indicator movement
            targetSize = 45,     -- Target zone size (not used in single-zone)
            perfectSize = 8,     -- Tiny perfect zone
            maxAttempts = 1,     -- Single attempt only
            pattern = 'bounce', -- Bounce pattern
            direction = -1       -- Counter-clockwise for confusion
        }
    }
}

Component Styling

Detailed styling configurations for each UI component. These settings control the visual appearance and layout.

Notification Styling

Config.ComponentStyles.notifications = {
    width = '320px',             -- Fixed notification width
    padding = '16px',            -- Internal padding
    borderRadius = 'lg',         -- Corner rounding (from theme)
    shadow = 'lg',               -- Drop shadow (from theme)
    iconSize = '18px',           -- Notification icon size
    titleFontSize = 'sm',        -- Title text size (from theme)
    titleFontWeight = 'semibold', -- Title font weight (from theme)
    messageFontSize = 'sm',      -- Message text size (from theme)
    messageLineHeight = 'relaxed', -- Message line height (from theme)
    closeButtonSize = '14px',    -- Close button size
    spacing = '12px',            -- Spacing between notifications
    borderWidth = '1px',         -- Border thickness
    animationType = 'slide',     -- Animation type
    animationDuration = 'normal' -- Animation duration (from theme)
}

Progress Bar Styling

Config.ComponentStyles.progress = {
    -- Circular progress bar styling
    circular = {
        size = '80px',               -- Circle diameter
        strokeWidth = '8px',         -- Progress stroke width
        backgroundColor = 'transparent', -- Background color
        borderRadius = 'full',       -- Fully rounded
        shadow = 'md',               -- Drop shadow
        labelFontSize = 'sm',        -- Label text size
        labelFontWeight = 'medium',  -- Label font weight
        percentageFontSize = 'xs',   -- Percentage text size
        animationDuration = 'normal' -- Animation duration
    },
    
    -- Linear progress bar styling
    linear = {
        width = '300px',             -- Bar width
        height = '8px',              -- Bar height
        borderRadius = 'full',       -- Fully rounded ends
        backgroundColor = 'rgba(0, 0, 0, 0.1)', -- Background color
        shadow = 'sm',               -- Subtle shadow
        labelFontSize = 'sm',        -- Label text size
        labelFontWeight = 'medium',  -- Label font weight
        animationDuration = 'normal' -- Animation duration
    }
}

Menu Styling

Config.ComponentStyles.menu = {
    width = '400px',             -- Menu width
    maxHeight = '500px',         -- Maximum menu height
    padding = '16px',            -- Internal padding
    borderRadius = 'xl',         -- Large corner rounding
    shadow = 'xl',               -- Large drop shadow
    borderWidth = '1px',         -- Border thickness
    
    -- Menu header styling
    header = {
        padding = '12px 16px',       -- Header padding
        borderRadius = 'lg',         -- Header corner rounding
        titleFontSize = 'lg',        -- Title text size
        titleFontWeight = 'semibold', -- Title font weight
        subtitleFontSize = 'sm',     -- Subtitle text size
        subtitleFontWeight = 'normal' -- Subtitle font weight
    },
    
    -- Menu item styling
    item = {
        padding = '12px 16px',       -- Item padding
        borderRadius = 'md',         -- Item corner rounding
        fontSize = 'sm',             -- Item text size
        fontWeight = 'medium',       -- Item font weight
        iconSize = '16px',           -- Item icon size
        spacing = '12px',            -- Spacing between items
        hoverTransition = 'fast'     -- Hover animation duration
    },
    
    -- Search input styling
    search = {
        padding = '8px 12px',        -- Search input padding
        borderRadius = 'md',         -- Search corner rounding
        fontSize = 'sm',             -- Search text size
        borderWidth = '1px',         -- Search border thickness
        focusRingWidth = '2px'       -- Focus ring thickness
    }
}

Skillcheck Styling

Config.ComponentStyles.skillcheck = {
    -- Basic visual settings
    size = '200px',                  -- Circle diameter
    strokeWidth = 8,                 -- Ring thickness
    centerSize = '48px',             -- Center button size
    textSize = '1rem',               -- Text size
    shadow = 'lg',                   -- Drop shadow level
    
    -- Zone styling
    targetOpacity = 0.8,             -- Target zone opacity
    perfectOpacity = 0.9,            -- Perfect zone opacity
    indicatorOpacity = 1.0,          -- Moving indicator opacity
    
    -- Animation settings
    animationDuration = 300,         -- Animation duration in ms
    easing = 'ease-out',             -- Animation easing
    
    -- Attempts indicator
    showAttempts = true,             -- Show attempts remaining
    attemptSize = '12px',            -- Attempt indicator size
    attemptSpacing = '4px',          -- Spacing between indicators
    
    -- Advanced settings
    glowIntensity = 0.3,             -- Glow effect intensity
    pulseEffect = true,              -- Enable pulse animation
    rotationSmoothing = 0.1          -- Rotation smoothing factor
}

Lockpicking Styling

Config.ComponentStyles.lockpicking = {
    -- Container settings
    width = '300px',                 -- Interface width
    padding = '20px',                -- Internal padding
    borderRadius = '16px',           -- Corner rounding
    shadow = 'xl',                   -- Drop shadow
    
    -- Lock mechanism styling
    lockSize = '192px',              -- Lock circle size
    outerRingWidth = '4px',          -- Outer ring thickness
    innerRingWidth = '2px',          -- Inner ring thickness
    handleWidth = '4px',             -- Handle arm thickness
    handleLength = '64px',           -- Handle arm length
    centerSize = '24px',             -- Center hub size
    
    -- Sweet spot indicator
    sweetSpotWidth = '3px',          -- Sweet spot indicator width
    sweetSpotLength = '20px',        -- Sweet spot indicator length
    sweetSpotGlow = '8px',           -- Glow effect size
    
    -- Feedback system
    feedbackBarWidth = '12px',       -- Feedback bar width
    feedbackBarHeight = '48px',      -- Feedback bar height
    feedbackBarSpacing = '2px',      -- Spacing between bars
    
    -- Time remaining bar
    timeBarWidth = '200px',          -- Time bar width
    timeBarHeight = '8px',           -- Time bar height
    timeBarRadius = 'full',          -- Time bar corner rounding
    
    -- Animation settings
    transitionDuration = 300,        -- Transition duration in ms
    glowTransition = 'ease-out',     -- Glow animation easing
    pulseIntensity = 0.2             -- Pulse effect intensity
}

Radial Menu Configuration

Comprehensive configuration for the radial menu system.

Basic Settings

Config.RadialMenu = {
    -- Keybind settings
    keybind = 20,                    -- Control ID for Z key
    holdToActivate = true,           -- Hold key to show, release to hide
    
    -- Visual settings
    defaultRadius = 100,             -- Distance from center to items
    minRadius = 80,                  -- Minimum radius for small menus
    maxRadius = 150,                 -- Maximum radius for large menus
    centerSize = 50,                 -- Size of center circle
    itemSize = 45,                   -- Size of individual items
    
    -- Dynamic expansion
    enableDynamicRadius = true,      -- Expand radius based on item count
    radiusPerItem = 6,               -- Additional radius per item beyond 6 items
    animationDuration = 250,         -- Animation duration in milliseconds
    expansionDelay = 40,             -- Delay between item appearances
    
    -- Interaction settings
    selectionDeadzone = 30,          -- Minimum distance from center to select
    autoSelectOnHover = false,       -- Auto-select items on hover
    hapticFeedback = true,           -- Enable controller vibration
    allowMovementDuringMenu = true,  -- Allow player movement while menu is open
    
    -- Visual styles
    defaultStyle = 'default',        -- Style preset: 'default', 'minimal', 'gaming'
    showLabels = true,               -- Show item labels
    showCenter = true,               -- Show center circle
    showConnectors = false,          -- Show lines connecting items to center
}

Menu Structure

The radial menu uses a hierarchical structure with nested items:

Config.RadialMenu.mainMenu = {
    id = 'main',
    title = 'Main Menu',
    centerIcon = '⭐',
    items = {
        {
            id = 'citizen',
            title = 'Citizen',
            icon = '👤',
            items = {
                {
                    id = 'givecontact',
                    title = 'Give Contact',
                    icon = '📞',
                    type = 'client',
                    event = 'b2lib:contact:give',
                    shouldClose = true
                },
                -- More items...
            }
        },
        -- More categories...
    }
}

Menu Item Properties:

  • id - Unique identifier for the menu item

  • title - Display text for the item

  • icon - Icon to display (emoji or icon name)

  • items - Submenu items (for nested menus)

  • type - Event type ('client' or 'server')

  • event - Event name to trigger

  • shouldClose - Whether to close menu after selection

  • data - Additional data to pass with the event

Performance Configuration

Optimize B2Lib performance based on your server's requirements.

Config.Performance = {
    maxNotifications = 5,        -- Maximum simultaneous notifications
    updateInterval = 16,         -- UI update interval in milliseconds (60 FPS)
    fadeAnimations = true,       -- Enable fade in/out animations
    maxCacheSize = 1000,        -- Maximum cached UI elements
    raycastDistance = 10.0,     -- Maximum distance for interaction raycasting
    entityCheckDistance = 50.0   -- Maximum distance for entity detection
}

Performance Tips

  1. Reduce maxNotifications for lower-end clients

  2. Increase updateInterval to 33ms (30 FPS) for better performance

  3. Disable fadeAnimations on servers with many players

  4. Lower raycastDistance to reduce CPU usage

  5. Adjust maxCacheSize based on available memory

Debug Configuration

Configure debugging and logging options for development and troubleshooting.

Config.Debug = {
    enabled = true,                  -- Enable debug logging
    logLevel = 'debug',              -- Logging level: 'error', 'warn', 'info', 'debug'
    showPerformanceMetrics = false   -- Show performance metrics in console
}

Log Levels

Level
Description

error

Only critical errors

warn

Warnings and errors

info

General information, warnings, and errors

debug

All messages including detailed debugging information

Custom Themes

Create custom themes by modifying the color palette:

-- Custom theme example
Config.Theme.colors.custom = {
    primary = '#8b5cf6',      -- Purple primary
    secondary = '#64748b',    -- Slate secondary
    success = '#10b981',      -- Emerald success
    warning = '#f59e0b',      -- Amber warning
    error = '#ef4444',        -- Red error
    info = '#06b6d4',         -- Cyan info
    
    background = {
        primary = '#0f172a',      -- Slate 900
        secondary = '#1e293b',    -- Slate 800
        tertiary = '#334155',     -- Slate 700
        overlay = 'rgba(15, 23, 42, 0.8)'
    },
    
    text = {
        primary = '#f8fafc',      -- Slate 50
        secondary = '#e2e8f0',    -- Slate 200
        tertiary = '#94a3b8',     -- Slate 400
        inverse = '#0f172a'       -- Slate 900
    },
    
    border = {
        primary = '#475569',      -- Slate 600
        secondary = '#334155',    -- Slate 700
        accent = '#8b5cf6'        -- Purple 500
    }
}

-- Apply custom theme
Config.Theme.mode = 'custom'

Best Practices

Configuration Management

  1. Backup Configuration - Always backup Config.lua before making changes

  2. Test Changes - Test configuration changes on a development server first

  3. Document Modifications - Keep track of custom changes for future updates

  4. Use Version Control - Store configuration in version control for team collaboration

Performance Optimization

  1. Monitor Performance - Enable performance metrics during testing

  2. Optimize for Your Server - Adjust settings based on player count and hardware

  3. Disable Unused Components - Turn off components you don't use

  4. Regular Maintenance - Review and optimize settings periodically

Theme Customization

  1. Maintain Contrast - Ensure sufficient contrast for accessibility

  2. Test All Components - Verify theme changes work across all UI components

  3. Consider Use Cases - Different themes for different times of day or events

  4. User Preferences - Allow players to choose their preferred theme

Troubleshooting

Common Issues

UI Components Not Showing:

  1. Check Config.EnabledComponents settings

  2. Verify position values are valid

  3. Check console for error messages

  4. Ensure resource is properly started

Performance Issues:

  1. Reduce maxNotifications and maxCacheSize

  2. Increase updateInterval to 33ms

  3. Disable fadeAnimations

  4. Lower raycastDistance and entityCheckDistance

Theme Issues:

  1. Verify color values are valid CSS colors

  2. Check theme mode is set correctly

  3. Ensure all required color properties are defined

  4. Test with default theme first

Styling Problems:

  1. Check CSS unit values (px, rem, %)

  2. Verify theme references are correct

  3. Test with default styling first

  4. Check browser developer tools for CSS errors

PreviousInstallationNextInterface

Last updated