VORP Progressbar System Documentation

VORP Progressbar allows you to create visual progress indicators in your scripts with multiple theme options and customizable duration.

Table of Contents

1. Getting Started
2. Initialization
3. Starting Progressbars
4. Theme Options
5. Examples
6. Best Practices

Getting Started

The VORP Progressbar system provides a visual way to show progress for long-running operations like crafting, loading, or any timed activity.

Getting Started > Basic Usage Flow

1. Initialize the progressbar at the top of your script
2. Call the start function when you need to show progress
3. Handle completion in the callback function

Initialization > Initialize Progressbar

Initialize the progressbar system at the top of your script:

progressbar = exports.vorp_progressbar:initiate()

Returns: Progressbar object with methods for controlling progress display

Note: This should be called once at the beginning of your script, not every time you want to show a progressbar.

Starting Progressbars > Start Function

Display a progressbar with specified parameters:

progressbar.start(message, duration, callback, theme)

Parameters:

• message (string) - The message displayed in the progressbar
• duration (number) - Duration in milliseconds
• callback (function) - Function called when progressbar completes
• theme (string) - Visual theme: "linear", "circle", or "innercircle"

Starting Progressbars > Basic Example

progressbar.start("Loading Example", 20000, function()
  print('DONE!!!!')
end, 'linear')

Theme Options

The progressbar system supports three different visual themes:

Theme Options > Linear Theme

A horizontal progress bar that fills from left to right.

progressbar.start("Processing...", 5000, function()
  print("Linear progress complete!")
end, 'linear')

Best for:

• File operations
• Data processing
• Loading screens
• General progress indication

Theme Options > Circle Theme

A circular progress indicator that fills clockwise.

progressbar.start("Crafting Item...", 10000, function()
  print("Crafting complete!")
end, 'circle')

Best for:

• Crafting systems
• Skill training
• Circular timers
• Compact progress display

Theme Options > Inner Circle Theme

A circular progress indicator with inner circle design.

progressbar.start("Healing...", 8000, function()
  print("Healing complete!")
end, 'innercircle')

Best for:

• Health/mana regeneration
• Meditation/resting
• Special abilities
• Aesthetic variety

Examples > Basic Loading Operation

-- Initialize at script start
progressbar = exports.vorp_progressbar:initiate()

-- Function to show loading
function ShowLoadingProgress()
  progressbar.start("Loading player data...", 3000, function()
    print("Player data loaded successfully!")
    -- Continue with loaded data
    TriggerEvent("playerDataReady")
  end, 'linear')
end

-- Usage
RegisterCommand("load", function()
  ShowLoadingProgress()
end)

Examples > Crafting System

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function StartCrafting(itemName, craftTime)
  local message = "Crafting " .. itemName .. "..."
  
  progressbar.start(message, craftTime, function()
    print("Crafted " .. itemName .. " successfully!")
    -- Add item to inventory
    TriggerServerEvent("addCraftedItem", itemName)
  end, 'circle')
end

-- Usage
RegisterNetEvent("startCraftingClient")
AddEventHandler("startCraftingClient", function(itemName, duration)
  StartCrafting(itemName, duration)
end)

Examples > Healing System

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function StartHealing(healAmount)
  progressbar.start("Healing wounds...", 5000, function()
    print("Healing complete!")
    -- Restore health
    TriggerServerEvent("restoreHealth", healAmount)
  end, 'innercircle')
end

-- Usage with item
RegisterNetEvent("useHealthItem")
AddEventHandler("useHealthItem", function(healAmount)
  StartHealing(healAmount)
end)

Examples > Mining/Gathering System

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function StartMining(rockType)
  local miningTime = GetMiningTime(rockType) -- Custom function
  local message = "Mining " .. rockType .. "..."
  
  progressbar.start(message, miningTime, function()
    print("Mining complete!")
    -- Give mined resources
    TriggerServerEvent("giveMiningRewards", rockType)
  end, 'linear')
end

function GetMiningTime(rockType)
  local times = {
    iron = 8000,
    gold = 12000,
    diamond = 20000
  }
  return times[rockType] or 5000
end

Examples > Skill Training

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function TrainSkill(skillName, trainingTime)
  progressbar.start("Training " .. skillName .. "...", trainingTime, function()
    print("Skill training complete!")
    TriggerServerEvent("addSkillExp", skillName, 100)
  end, 'circle')
end

-- Usage
RegisterCommand("train", function(source, args)
  local skill = args[1] or "strength"
  TrainSkill(skill, 10000)
end)

Examples > Bank Transaction

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function ProcessBankTransaction(transactionType, amount)
  local message = transactionType == "deposit" and "Depositing $" .. amount or "Withdrawing $" .. amount
  
  progressbar.start(message, 3000, function()
    print("Bank transaction complete!")
    TriggerServerEvent("processBankTransaction", transactionType, amount)
  end, 'linear')
end

-- Usage
RegisterNetEvent("startBankTransaction")
AddEventHandler("startBankTransaction", function(type, amount)
  ProcessBankTransaction(type, amount)
end)

Examples > Advanced Example with Interruption

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

local currentProgress = nil

function StartInterruptibleProgress(message, duration, onComplete, onInterrupt)
  currentProgress = {
    active = true,
    onInterrupt = onInterrupt
  }
  
  progressbar.start(message, duration, function()
    if currentProgress and currentProgress.active then
      currentProgress = nil
      if onComplete then
        onComplete()
      end
    end
  end, 'circle')
end

function InterruptProgress()
  if currentProgress and currentProgress.active then
    currentProgress.active = false
    if currentProgress.onInterrupt then
      currentProgress.onInterrupt()
    end
    currentProgress = nil
    print("Progress interrupted!")
  end
end

-- Usage
RegisterCommand("longaction", function()
  StartInterruptibleProgress(
    "Performing long action...", 
    15000,
    function()
      print("Long action completed!")
    end,
    function()
      print("Long action was interrupted!")
    end
  )
end)

RegisterCommand("interrupt", function()
  InterruptProgress()
end)

Examples > Dynamic Progress Messages

-- Initialize progressbar
progressbar = exports.vorp_progressbar:initiate()

function ShowDynamicProgress(stages)
  local currentStage = 1
  local totalStages = #stages
  
  local function nextStage()
    if currentStage <= totalStages then
      local stage = stages[currentStage]
      local message = stage.message .. " (" .. currentStage .. "/" .. totalStages .. ")"
      
      progressbar.start(message, stage.duration, function()
        currentStage = currentStage + 1
        if currentStage <= totalStages then
          nextStage()
        else
          print("All stages complete!")
        end
      end, stage.theme or 'linear')
    end
  end
  
  nextStage()
end

-- Usage
RegisterCommand("multistage", function()
  local stages = {
    {message = "Preparing materials", duration = 3000, theme = "linear"},
    {message = "Mixing ingredients", duration = 5000, theme = "circle"},
    {message = "Finalizing product", duration = 2000, theme = "innercircle"}
  }
  
  ShowDynamicProgress(stages)
end)

Best Practices > Initialization

1. Initialize once at the top of your script
2. Don't re-initialize for each progressbar
3. Store reference globally if needed across multiple functions

-- Good: Initialize once at script start
progressbar = exports.vorp_progressbar:initiate()

-- Bad: Don't do this repeatedly
function badExample()
  local progressbar = exports.vorp_progressbar:initiate() -- Don't repeat this
  progressbar.start("Bad example", 1000, function() end, 'linear')
end

Best Practices > Duration Selection

1. Match duration to action - longer actions need longer progress
2. Consider user experience - avoid extremely long progressbars
3. Use realistic timing - 30 seconds for complex crafting, 3 seconds for simple actions

-- Good duration examples
progressbar.start("Quick action", 2000, callback, 'linear')     -- 2 seconds
progressbar.start("Medium task", 8000, callback, 'circle')      -- 8 seconds  
progressbar.start("Complex craft", 15000, callback, 'circle')   -- 15 seconds

Best Practices > Theme Selection

1. Linear - General purpose, loading, file operations
2. Circle - Crafting, skills, circular timers
3. Inner Circle - Special actions, healing, meditation

Best Practices > Message Guidelines

1. Be descriptive - tell users what's happening
2. Use present tense - "Crafting..." not "Will craft..."
3. Include context - item names, quantities when relevant
4. Keep it concise - avoid overly long messages

-- Good messages
"Crafting Iron Sword..."
"Healing wounds..."
"Processing bank transaction..."
"Mining gold ore..."

-- Avoid
"Please wait..."
"Loading..."
"Working..."

Best Practices > Error Handling

function SafeProgressbar(message, duration, callback, theme)
  if not progressbar then
    print("Progressbar not initialized!")
    return
  end
  
  if not message or not duration or not callback then
    print("Invalid progressbar parameters!")
    return
  end
  
  progressbar.start(message, duration, function()
    -- Wrap callback in pcall for safety
    local success, error = pcall(callback)
    if not success then
      print("Progressbar callback error: " .. tostring(error))
    end
  end, theme or 'linear')
end

Best Practices > Performance Considerations

1. Don't overlap progressbars - finish one before starting another
2. Clean up properly - ensure callbacks complete
3. Avoid very short durations - under 1 second may feel jarring

Notes

• Progressbar system is client-side only
• Must be initialized before use
• Only one progressbar can be active at a time
• Duration is specified in milliseconds
• Callback function is executed when progress completes
• Theme parameter is optional, defaults to 'linear' if not specified
• Messages should be clear and descriptive for better user experience
• Consider the visual context when choosing themes