mobius1/rprogress

Customisable radial progress bars for FiveM

rprogress

Customisable radial progress bars for FiveM.

Table of contents

• Demo Videos
• Requirements
• Download & Installation
• Configuration
• Upgrading
• Client Functions
• Scenarios and Animations
• MiniGame
• Sync vs Async
• Static Progress Dials
• Partial Progress Dials
• Pie Progress
• Demo Commands
• Contributing
• To Do

Demo Videos

• Default
• Custom MaxAngle and Rotation
• Animations
• Without Timer
• Demo with esx_doorlock
• Custom Label Position
• Static Progress Dial
• Mini Game

Requirements

• None!

Download & Installation

• Download and extract the package: https://github.com/Mobius1/rprogress/archive/master.zip
• Drop the rprogress-master directory into you resources directory
• Rename the directory from rprogress-master to rprogress
• Add ensure rprogress in your server.cfg
• Edit config.lua to your liking
• Start your server and rejoice!

Configuration

Config.Async        = true  -- Whether to run the progress dial asyncronously

Config.From         = 0     -- Starting progress percentage
Config.To           = 100   -- Ending progress percentage

Config.Duration         = 5000          -- Duration of the progress
Config.Label            = "Loading..."  -- Text shown with the dial
Config.LabelPosition    = "bottom"

Config.Color        = "rgba(255, 255, 255, 1.0)"    -- Progress dial colour
Config.BGColor      = "rgba(0, 0, 0, 0.4)"          -- Progress background colour
Config.ZoneColor    = "rgba(51, 105, 30, 1)"        -- Minigame Zone colour

Config.x            = 0.5 -- Horizontal position
Config.y            = 0.5 -- Vertical position

Config.Rotation     = 0         -- Rotation angle of dial
Config.MaxAngle     = 360       -- Max arc in degrees - 360 will be a full circle, 90 will be a quarter of a circle, etc
Config.Radius       = 60        -- Radius of the radial dial
Config.Stroke       = 10        -- stroke width of the radial dial
Config.Width        = 300       -- Width of the linear bar
Config.Height       = 40        -- Height of the linear bar
Config.Cap          = 'butt'    -- or 'round'
Config.Padding      = 0         -- Background bar padding
Config.CancelKey    = 178       -- Key used for cancelling progress

Config.ShowTimer    = true  -- Shows the timer countdown within the radial dial
Config.ShowProgress = false -- Shows the progress within the radial dial

Config.Easing       = "easeLinear" -- The easing used for the dial animation - see "rprogress/ui/js/easings.js"

Config.DisableControls = {
    Mouse           = false,    -- Disable mouse controls until progress is complete
    Player          = false,    -- Disable player movement until progress is complete
    Vehicle         = false     -- Disable vehicle control until progress is complete    
}

NOTE: Config.Position is based on screen size so setting Config.Position.x = 0.5 will be the center of the screen, Config.Position.x = 1.0 with be right-side of the screen, Config.Position.x = 0.0 will be the left-side of the screen, etc.

Upgrading

Upgrading to v0.6.0

Replace all instances of exports.rprogress:NewStaticProgress with exports.rprogress:Static

Client Functions

NOTE: DO NOT run these in a loop

Available exports:

-- starts the progress dial for the defined duration
-- This runs in sync so any code after this call won't be run until the progress is complete
exports.rprogress:Start(text, duration)

-- stops the progress dial early
exports.rprogress:Stop()

-- Display a custom progress dial by overriding config.lua values
exports.rprogress:Custom(options)

-- Create a static progress dial
exports.rprogress:Static(options)

-- Create a linear progress bar
exports.rprogress:Linear(text, duration)

-- or

exports.rprogress:Custom({
    Type = 'linear'
    Duration = 3000,
    Width = 400,
    Height = 50,
    y = 0.75
})

Display a progress dial with text for set duration

exports.rprogress:Start(text, duration)

Stop the progress dial early

exports.rprogress:Stop()

Create a custom progress instance

exports.rprogress:Custom({
    Async = true,
    canCancel = true,       -- Allow cancelling
    cancelKey = 178,        -- Custom cancel key
    x = 0.5,                -- Position on x-axis
    y = 0.5,                -- Position on y-axis
    From = 0,               -- Percentage to start from
    To = 100,               -- Percentage to end
    Duration = 1000,        -- Duration of the progress
    Radius = 60,            -- Radius of the dial
    Stroke = 10,            -- Thickness of the progress dial
    Cap = 'butt',           -- or 'round'
    Padding = 0,            -- Padding between the progress dial and the background dial
    MaxAngle = 360,         -- Maximum sweep angle of the dial in degrees
    Rotation = 0,           -- 2D rotation of the dial in degrees
    Width = 300,            -- Width of bar in px if Type = 'linear'
    Height = 40,            -- Height of bar in px if Type = 'linear'
    ShowTimer = true,       -- Shows the timer countdown within the radial dial
    ShowProgress = false,   -- Shows the progress % within the radial dial    
    Easing = "easeLinear",
    Label = "My Custom Label",
    LabelPosition = "right",
    Color = "rgba(255, 255, 255, 1.0)",
    BGColor = "rgba(0, 0, 0, 0.4)",
    ZoneColor = "rgba(51, 105, 30, 1)",
    Animation = {
        scenario = "WORLD_HUMAN_AA_SMOKE", -- https://pastebin.com/6mrYTdQv
        animationDictionary = "missheistfbisetup1", -- https://alexguirre.github.io/animations-list/
        animationName = "unlock_loop_janitor",
    },
    DisableControls = {
        Mouse = true,
        Player = true,
        Vehicle = true
    },    
    onStart = function()
        -- do something when progress starts
    end,
    onComplete = function(cancelled)
        -- cancelled: boolean - whether player cancelled the progress

        -- do something when progress is complete
    end
})

Scenarios and Animations

rprogress allows you to run a scenario or play an animation while the progress dial is running.

If you want to run a scenario, then provide the Animation table with the scenario key.

exports.rprogress:Custom({
    Animation = {
        scenario = "WORLD_HUMAN_AA_SMOKE"
    }
}) 

You can find a list of scenarios here

If you want to play an animation, then provide the Animation table with the required animationDictionary and animationName keys. You can also provide the optional flag key (see TaskPlayAnim).

exports.rprogress:Custom({
    Animation = {
        animationDictionary = "missheistfbisetup1",
        animationName = "unlock_loop_janitor",
        flag = 1, -- optional
    }
}) 

You can find a list of animation dictionaries / names here.

If scenario is set as well as animationDictionary and animationName, then the scenario will take priority.

MiniGame

rProgress can be set up to allow a minigame to test player reflexes by utilising the MiniGame() method.

The progress bar will flip back and forth and display a trigger zone for the player to hit the SpaceBar when the progress bar is within it.

As with the Custom() method, you can pass a variety of options. The onComplete callback will return the success parameter to indicate whether the player was successful or not.

exports.rprogress:MiniGame({
    Difficulty = "Easy",
    Timeout = 5000, -- Duration before minigame is cancelled
    onComplete = function(success)
            if success then
                -- Player was successful
            else
                -- Player was unsuccessful
            end    
    end,
    onTimeout = function()
        -- Player took too long to respond
    end
})

You can define the defficulties in the config.lua file:

Config.MiniGameOptions = {
    MaxAngle = 240,
    Rotation = -120,    
    Difficulty = {
        Easy = {
            Zone = 40,
            Duration = 500
        },
        Medium = {
            Zone = 25,
            Duration = 450
        },
        Hard = {
            Zone = 20,
            Duration = 400
        }      
    }      
}

To add you own difficulty you can define it in the Config.MiniGameOptions.Difficulty table and add the Zone and Duration values:

Config.MiniGameOptions = {
    MaxAngle = 240,
    Rotation = -120,    
    Difficulty = {
        Custom = {
            Zone = 40,         -- The percentage of the dial that is the trigger zone (lower = harder)
            Duration = 1000    -- Time in milliseconds for the dial to fill in one direction (lower = harder)
        }
    }
}

Then use it in the MiniGame() method:

exports.rprogress:MiniGame({
    Difficulty = "Custom",
    onComplete = function(success)

    end
})

You can also pass the Zone and Duration values instead of Difficulty for on-the-fly difficulty settings:

exports.rprogress:MiniGame({
    Zone = 40,
    Duration = 750,
    onComplete = function(success)
    
    end
})

Sync vs Async

The Start() method runs in sync so any code after the call to the method won't be run until the progress is complete. If you want a progress dial to run asyncronously, you can use the Custom() method with Async set to true and utilise the onStart and onComplete callbacks.

Async

print("before")

exports.rprogress:Custom({
    Async = true,
    Duration = 3000,
    onStart = function()
        print("start")
    end      
    onComplete = function()
        print("complete")
    end    
})

print("after")

Output

before
after
start
complete

Sync

print("before")

exports.rprogress:Custom({
    Async = false,
    Duration = 3000,
    onStart = function()
        print("start")
    end      
    onComplete = function()
        print("complete")
    end     
})

print("after")

Output

before
start
complete
after

Static Progress Dials

If you don't just want a progress dial that fills automatically, you can create a static one and update it as required.

Demo Video

-- Create new static progress dial
local staticDial = exports.rprogress:Static(options)

-- Show the progress dial
staticDial.Show()

-- Update the progress of the dial (0-100)
staticDial.SetProgress(progress)

-- Hide the progress dial
staticDial.Hide()

-- Destroy the dial (set as no longer needed)
staticDial.Destroy()

Partial Progress Dials

To create a partial progress dial set the maxAngle property to the desired value:

exports.rprogress:Custom({
    maxAngle: 240
})

Result

You can also set rotation property to the desired value:

exports.rprogress:Custom({
    maxAngle: 240,
    rotation: -120
})

Result

Pie Progress

Setting the radius and stroke properties to equal values will produce a pie chart type progress:

exports.rprogress:Custom({
    Radius: 60,
    Stroke: 60
})

Result

Demo Commands

/rprogressStart [text] [duration]
/rprogressCustom [from] [to] [duration] [radius] [stroke] [MaxAngle] [rotation] [padding] [cap]
/rprogressMiniGame [difficulty]
/rprogressSync [duration]
/rprogressAsync [duration]
/rprogressStatic
/rprogressEasing [functionName] [duration]
/rprogressAnimation [animDictionary] [animName] [duration]
/rprogressScenario [scenarioName] [duration]

You can delete the demo.lua file and remove it's entry from fxmanifest.lua if these are not required.

Contributing

Pull requests welcome.

Legal

License

rprogress - Customisable radial progress dials for FiveM.

Copyright (C) 2020 Karl Saunders

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>

rprogress's Issues

Custom option not working

Hi , Custom Create option ("from") is not working , it starts from 0 every time no mater what number i put

exports.rprogress:Custom({
Async = true,
x = 0.5,
y = 0.5,
From = 50, -- this line not working
To = 100,
Duration = 1000,
Radius = 60,
Stroke = 10,
MaxAngle = 360,
Rotation = 0,
Label = "Test",
LabelPosition = "right",
Color = "rgba(255, 255, 255, 1.0)",
BGColor = "rgba(0, 0, 0, 0.4)",
DisableControls = {
Mouse = true,
Player = true,
Vehicle = true
},
onStart = function()
-- do something when progress starts
end,
onComplete = function()
-- do something when progress is complete
end
})

Minigame

You can't really start a minigame one after another, they have to have a Wait between them to work correctly, otherways new minigame will not be shown.

Request: Add ability to cancel progress

Something that allows players to cancel progress midway.

Enhancement Add a timer

For example, the minigame is only shown for 2 seconds, if the minigame hasnt been completed in 2 seconds return false and get rid of the minigame from screen

canCancel error, and do nothing

Enchancement Multi Customs, Static ...

Hey It's me again,

I'm actually working on an enchancement for your script

Actually you can get only one Custom but for some reason, i need to get more custom in same time ^^
When my version will work, do you want a new PR from my version?

Best regards

minigame timeout not working

The timeout is not working for me, maybe am I doing something wrong?

exports.rprogress:MiniGame({
	Difficulty = "Easy",
	Timeout = 5000, -- Duration before minigame is cancelled
	onComplete = function(success)
		if success then
			print('yolo')
		else
			print('Player was unsuccessful')
		end
	end,
	onTimeout = function()
		print('Player took too long to respond')
	end
})

Ability to spam completed callback

Changed code to
RegisterNUICallback('progress_minigame_input', function(data, cb)
if(not MiniGameCompleted) then
if OnComplete ~= nil then
OnComplete(data.success == true)
end
StopAnimation()
MiniGameCompleted = true
end
cb('ok')
end)

Request: Disable keyboard

You can spam and after spam it will be stuck

cant get it to work on a certain script

so usually atleast for every other resource ive been able to get it to work but this one script is being jankey

this is the code

if not unit then
            drug = true
            exports['mythic_progbar']:Progress({
                name = "coke",
                duration = 10000,
                label = 'Coke Started to Form',
                useWhileDead = false,
                canCancel = true,
                 controlDisables = {
                    disableMovement = true,
                    disableCarMovement = true,
                    disableMouse = false,
                    disableCombat = true,
                },
                animation = {
                    animDict = "mp_arresting",
                    anim = "a_uncuff",
                    flags = 49,
                },
            }, function(cancelled)
                if not cancelled then
                    TriggerServerEvent('coke')
                    weed = false
                    
                 else
                
                end
            end)
        end

end)

ive tried making it

  if not unit then
           drug = true
           exports.rprogress:Start({
               name = "coke",
               duration = 10000,
               label = 'Coke Started to Form',

ive also tried

       if not unit then
            drug = true
            exports.rprogress:Start("Coke Started to Form", 10000)

but nothing can get it to work, the closet ive gotten was with my first solution but i get an error No such export ShowNotification in resource FeedM2 any help would be appriciated, i know this isnt an issue necesarilly but if you could point me in the right direction because ive never seen a script run it like this thank you

Enchatement: Be able to easily change the green color of the challange

title

Add option for animations

Add an option to play a ped animation during the progress

add custom props

Hi, can you adding props function?