Table of Contents

Class ProgressBar

Namespace
Fallencake.UI
Assembly
Fallencake.UI.dll

A modular progress bar component with support for different fill types, directions, animations, and audio feedback.

[AddComponentMenu("Modular UI/Progress Bar")]
[ExecuteAlways]
public class ProgressBar : UIBehaviour, ISaveable, IProgressBarAudioProvider, IAudioProvider
Inheritance
object
Object
Component
Behaviour
MonoBehaviour
UIBehaviour
ProgressBar
Implements

Fields

MAX_INDICATORS

Maximum number of indicators that can be created automatically. This limit exists to prevent performance issues with too many UI elements.

public const int MAX_INDICATORS = 100

Field Value

int

_backgroundImage 

[SerializeField]
protected Image _backgroundImage

Field Value

Image

_fillContainer 

[SerializeField]
protected RectTransform _fillContainer

Field Value

RectTransform

_fillImage 

[SerializeField]
protected Image _fillImage

Field Value

Image

_fillLabel 

[SerializeField]
protected RectTransform _fillLabel

Field Value

RectTransform

_fillType 

[SerializeField]
protected ProgressBar.FillType _fillType

Field Value

ProgressBar.FillType

_indicatorAmount 

[SerializeField]
protected int _indicatorAmount

Field Value

int

_indicatorPrefab 

[SerializeField]
protected GameObject _indicatorPrefab

Field Value

GameObject

_indicators 

[SerializeField]
protected List<ImageIndicator> _indicators

Field Value

List<ImageIndicator>

_indicatorsContainer 

[SerializeField]
protected Transform _indicatorsContainer

Field Value

Transform

_isDifferentIndicators 

[SerializeField]
protected bool _isDifferentIndicators

Field Value

bool

_isWholeNumbers 

[SerializeField]
protected bool _isWholeNumbers

Field Value

bool

_maxValue 

[SerializeField]
protected float _maxValue

Field Value

float

_minValue 

[SerializeField]
protected float _minValue

Field Value

float

_progressText 

[SerializeField]
protected TMP_Text _progressText

Field Value

TMP_Text

_value 

[SerializeField]
[Range(0, 1)]
protected float _value

Field Value

float

Properties

AnimationDuration 

public float AnimationDuration { get; set; }

Property Value

float

AudioSource

AudioSource used to play sounds.

public AudioSource AudioSource { get; set; }

Property Value

AudioSource

AutoConfigureLayoutGroup

Auto-configure UnityEngine.UI.LayoutGroup settings for indicators container. When enabled, automatically adds and configures UnityEngine.UI.HorizontalLayoutGroup or UnityEngine.UI.VerticalLayoutGroup based on the progress Direction. Also sets spacing, alignment, and force expand settings.

public bool AutoConfigureLayoutGroup { get; set; }

Property Value

bool

BackgroundImage 

public Image BackgroundImage { get; set; }

Property Value

Image

Component

Owning component used by handlers for context and coroutines.

public MonoBehaviour Component { get; }

Property Value

MonoBehaviour

CurrentAnimationType 

public ProgressBar.AnimationType CurrentAnimationType { get; set; }

Property Value

ProgressBar.AnimationType

CurrentFillType 

public virtual ProgressBar.FillType CurrentFillType { get; set; }

Property Value

ProgressBar.FillType

CustomTextFormat 

public string CustomTextFormat { get; set; }

Property Value

string

DeselectSound

Sound played on deselect.

public AudioData DeselectSound { get; }

Property Value

AudioData

Direction 

public ProgressBar.ProgressDirection Direction { get; set; }

Property Value

ProgressBar.ProgressDirection

DisplayMode 

public ProgressBar.TextDisplayMode DisplayMode { get; set; }

Property Value

ProgressBar.TextDisplayMode

EnableSounds

Enables/disables sound playback for this component.

public bool EnableSounds { get; set; }

Property Value

bool

FillImage 

public Image FillImage { get; set; }

Property Value

Image

FillLabel

The RectTransform that is placed at the current value position on the progress bar if IsFillLabelEnabled is true.

public RectTransform FillLabel { get; set; }

Property Value

RectTransform

IndicatorAmount

Number of indicators to create automatically (only used when IsDifferentIndicators is false).

public int IndicatorAmount { get; set; }

Property Value

int

IndicatorPrefab

Prefab GameObject with ImageIndicator component for automatic indicator creation. Used if ProgressBar.FillType is Indicators and IsDifferentIndicators is false.

public GameObject IndicatorPrefab { get; set; }

Property Value

GameObject

IndicatorSpacing

Spacing between indicators in UnityEngine.UI.LayoutGroup. Used if ProgressBar.FillType is Indicators.

public float IndicatorSpacing { get; set; }

Property Value

float

Indicators

List of indicator components. Used if ProgressBar.FillType is Indicators. Filled automatically if IsDifferentIndicators is false, or manually by user if true.

public List<ImageIndicator> Indicators { get; set; }

Property Value

List<ImageIndicator>

IndicatorsContainer

Transform container where indicators will be instantiated. LayoutGroup will be automatically added based on progress Direction.

public Transform IndicatorsContainer { get; set; }

Property Value

Transform

IsAnimating 

public bool IsAnimating { get; }

Property Value

bool

IsBackgroundEnabled 

public bool IsBackgroundEnabled { get; set; }

Property Value

bool

IsChangePitchUpdateSound 

public bool IsChangePitchUpdateSound { get; set; }

Property Value

bool

IsColorizingEnabled

Enables colorizing the progress bar using a gradient or color range. When is true, the bar color is updated in UpdateColors() based on the current value.

public bool IsColorizingEnabled { get; set; }

Property Value

bool

IsDifferentIndicators

If false - indicators for Indicators list are created automatically from prefab. If true - indicators are set manually by user.

public virtual bool IsDifferentIndicators { get; set; }

Property Value

bool

IsFillLabelEnabled 

public bool IsFillLabelEnabled { get; set; }

Property Value

bool

IsIndicatorForceExpand

Enable force expand for indicators in UnityEngine.UI.LayoutGroup. Used if ProgressBar.FillType is Indicators.

public bool IsIndicatorForceExpand { get; set; }

Property Value

bool

IsSavingEnabled

Enables save/load behavior for the component.

public bool IsSavingEnabled { get; set; }

Property Value

bool

IsSecondaryBarEnabled

Secondary bar with custom Triggers And Delay:

The secondary bar can work in two modes:

  1. Proportional mode (Fallencake.UI.ProgressBar._useCustomTriggers = false): Secondary bar value equals primary bar value
  2. Custom triggers mode (Fallencake.UI.ProgressBar._useCustomTriggers = true): Secondary bar value determined by trigger pairs

Example usage with custom triggers:

  • Trigger 1: primaryValue = 25, secondaryValue = 10 (when primary reaches 25, secondary shows 10)
  • Trigger 2: primaryValue = 50, secondaryValue = 30 (when primary reaches 50, secondary shows 30)
  • Trigger 3: primaryValue = 100, secondaryValue = 50 (when primary reaches 100, secondary shows 50)
  • Fallencake.UI.ProgressBar._secondaryBarDelay = 0.3 (primary updates first, then secondary after 0.3 seconds)
public bool IsSecondaryBarEnabled { get; set; }

Property Value

bool

IsTextEnabled 

public bool IsTextEnabled { get; set; }

Property Value

bool

IsWholeNumbers 

public virtual bool IsWholeNumbers { get; set; }

Property Value

bool

MaxValue 

public virtual float MaxValue { get; set; }

Property Value

float

MinValue 

public float MinValue { get; set; }

Property Value

float

NormalizedValue 

public float NormalizedValue { get; set; }

Property Value

float

OnProgressComplete 

public ProgressBar.ProgressEvent OnProgressComplete { get; set; }

Property Value

ProgressBar.ProgressEvent

OnProgressUpdateEnd 

public ProgressBar.ProgressEvent OnProgressUpdateEnd { get; set; }

Property Value

ProgressBar.ProgressEvent

OnProgressUpdateStart 

public ProgressBar.ProgressEvent OnProgressUpdateStart { get; set; }

Property Value

ProgressBar.ProgressEvent

OnSecondaryUpdateEnd 

public ProgressBar.ProgressEvent OnSecondaryUpdateEnd { get; set; }

Property Value

ProgressBar.ProgressEvent

OnSecondaryUpdateStart 

public ProgressBar.ProgressEvent OnSecondaryUpdateStart { get; set; }

Property Value

ProgressBar.ProgressEvent

OnValueChanged 

public ProgressBar.ProgressValueEvent OnValueChanged { get; set; }

Property Value

ProgressBar.ProgressValueEvent

PitchResetTimeSeconds 

public float PitchResetTimeSeconds { get; set; }

Property Value

float

PressSound

Sound played on press/submit.

public AudioData PressSound { get; }

Property Value

AudioData

ProgressCompleteSound

Sound data for completion.

public AudioData ProgressCompleteSound { get; }

Property Value

AudioData

ProgressText 

public TMP_Text ProgressText { get; set; }

Property Value

TMP_Text

ProgressUpdateSound

Sound data for progress update (loop/step).

public AudioData ProgressUpdateSound { get; }

Property Value

AudioData

SaveKey

PlayerPrefs key used to persist the state.

public string SaveKey { get; set; }

Property Value

string

SecondaryBarDelay

Delay in seconds between primary and secondary bar updates.

  • Positive value: primary bar updates first, then secondary bar after delay
  • Negative value: secondary bar updates first, then primary bar after delay
  • Zero: both bars update simultaneously This delay works for both proportional mode and custom triggers mode.
public float SecondaryBarDelay { get; set; }

Property Value

float

SecondaryFillImage

The fill image used for the secondary progress bar (only used when UseCustomSecondaryBar is false).

public Image SecondaryFillImage { get; set; }

Property Value

Image

SecondaryFillType

Specifies the visual representation of the secondary bar. Can be either Filled or Sliced.

public ProgressBar.FillType SecondaryFillType { get; set; }

Property Value

ProgressBar.FillType

SecondaryProgressBar 

public ProgressBar SecondaryProgressBar { get; set; }

Property Value

ProgressBar

SecondaryTriggers

Custom trigger pairs that define secondary bar values for specific primary bar values. Only used when UseCustomTriggers is true.

Example usage with custom triggers:

  • Trigger 1: primaryValue = 25, secondaryValue = 10 (when primary reaches 25, secondary shows 10)
  • Trigger 2: primaryValue = 50, secondaryValue = 30 (when primary reaches 50, secondary shows 30)
  • Trigger 3: primaryValue = 100, secondaryValue = 50 (when primary reaches 100, secondary shows 50)
  • _secondaryBarDelay = 0.3 (primary updates first, then secondary after 0.3 seconds)
public List<SecondaryBarTrigger> SecondaryTriggers { get; set; }

Property Value

List<SecondaryBarTrigger>

SelectSound

Sound played on select/hover.

public AudioData SelectSound { get; }

Property Value

AudioData

Selectable

UI selectable to bind event triggers to.

public Selectable Selectable { get; }

Property Value

Selectable

UseCustomSecondaryBar

When enabled, uses custom trigger pairs to determine secondary bar values. When disabled, secondary bar value equals primary bar value (proportional mode). In custom triggers mode, you define trigger pairs (SecondaryBarTrigger) where:

  • primaryValue: When primary bar reaches this value
  • secondaryValue: Secondary bar should display this value
public bool UseCustomSecondaryBar { get; set; }

Property Value

bool

UseCustomTriggers

When enabled, uses custom trigger pairs to determine secondary bar values. When disabled, secondary bar value equals primary bar value (proportional mode).

public bool UseCustomTriggers { get; set; }

Property Value

bool

Value 

public float Value { get; set; }

Property Value

float

Volume

Per-component volume multiplier.

public float Volume { get; set; }

Property Value

float

Methods

AddValue(float) 

public void AddValue(float amount)

Parameters

amount float

ApplyIndicatorColor(ImageIndicator, float)

Applies dynamic color to indicator based on progress value and settings

protected virtual void ApplyIndicatorColor(ImageIndicator indicator, float alpha)

Parameters

indicator ImageIndicator
alpha float

Awake() 

protected override void Awake()

ClearAutoIndicators() 

protected virtual void ClearAutoIndicators()

CompleteProgress()

Sets the progress bar to the maximum value.

public void CompleteProgress()

ConfigureIndicatorsLayoutGroup() 

protected virtual void ConfigureIndicatorsLayoutGroup()

CreateExampleTriggers()

Creates example trigger configuration for testing purposes

[ContextMenu("Create Example Secondary Bar Triggers")]
public void CreateExampleTriggers()

CreateIndicatorFromPrefab(GameObject) 

protected virtual ImageIndicator CreateIndicatorFromPrefab(GameObject prefab)

Parameters

prefab GameObject

Returns

ImageIndicator

ForceCleanupExcessIndicators()

Force cleanup of excess auto indicators in container. This method ensures the container has exactly _indicatorAmount auto indicators.

[ContextMenu("Force Cleanup Excess Indicators")]
public void ForceCleanupExcessIndicators()

ForceCreateIndicators(int)

Force creates the specified number of indicators immediately. Used in ForceRefreshIndicators to avoid timing issues with delayed destruction in editor.

protected virtual void ForceCreateIndicators(int targetCount)

Parameters

targetCount int

Number of indicators to create

ForceRefreshIndicators()

Force refresh of indicators (useful for debugging). If using auto indicators (IsDifferentIndicators = false), removes all existing indicators and recreates them from the prefab with IndicatorPrefab according to IndicatorAmount.

[ContextMenu("Force Refresh Indicators")]
public void ForceRefreshIndicators()

GetCurrentAutoIndicatorCount() 

protected virtual int GetCurrentAutoIndicatorCount()

Returns

int

GraphicUpdateComplete()

Callback sent when this ICanvasElement has completed Graphic rebuild.

public virtual void GraphicUpdateComplete()

InitializeIndicators() 

protected virtual void InitializeIndicators()

LayoutComplete()

Callback sent when this ICanvasElement has completed layout.

public virtual void LayoutComplete()

LoadState()

Loads component state from persistent storage.

public void LoadState()

OnDestroy() 

protected override void OnDestroy()

PlayProgressCompleteSound() 

public void PlayProgressCompleteSound()

PlayProgressUpdateSound() 

public void PlayProgressUpdateSound()

Rebuild(CanvasUpdate)

Rebuild the element for the given stage.

public virtual void Rebuild(CanvasUpdate executing)

Parameters

executing CanvasUpdate

The current CanvasUpdate stage being rebuild.

ResetProgress()

Resets the progress bar to the minimum value.

public void ResetProgress()

SafeDestroyGameObject(GameObject) 

protected virtual void SafeDestroyGameObject(GameObject obj)

Parameters

obj GameObject

SaveState()

Saves component state to persistent storage.

public void SaveState()

SetBackgroundEnabled(bool) 

public void SetBackgroundEnabled(bool enabled)

Parameters

enabled bool

SetDirection(ProgressDirection) 

public void SetDirection(ProgressBar.ProgressDirection direction)

Parameters

direction ProgressBar.ProgressDirection

SetFillLabelEnabled(bool) 

public void SetFillLabelEnabled(bool enabled)

Parameters

enabled bool

SetTextEnabled(bool) 

public void SetTextEnabled(bool enabled)

Parameters

enabled bool

SetValue(float, bool)

Sets the value of the progress bar, optionally animating the transition. This method validates the input, clamps it within the allowed range, and updates the progress bar's visual state. If the value is changed, it triggers value change events and handles secondary bar logic if enabled.

public void SetValue(float newValue, bool animate = true)

Parameters

newValue float

The new value to assign to the progress bar. This value will be clamped between _minValue and _maxValue.

animate bool

If true, the progress bar will animate smoothly to the new value (if animation is enabled and the application is playing); otherwise, the value will update instantly.

SetValueImmediate(float)

Sets the value of the progress bar without animation. This method is used internally by SetValue(float, bool) when animation is disabled.

protected virtual void SetValueImmediate(float newValue)

Parameters

newValue float

The new value to assign to the progress bar. This value will be clamped between _minValue and _maxValue.

SetValueImmediate(float, bool, bool)

Sets the value of the progress bar without animation. This method is used internally by SetValue(float, bool) when animation is disabled.

public void SetValueImmediate(float newValue, bool updateVisuals = true, bool triggerEvents = true)

Parameters

newValue float

The new value to assign to the progress bar. This value will be clamped between _minValue and _maxValue.

updateVisuals bool

If true, the progress bar will update its visuals.

triggerEvents bool

If true, the progress bar will trigger events.

SetupLayoutGroupSettings(LayoutGroup) 

protected virtual void SetupLayoutGroupSettings(LayoutGroup layoutGroup)

Parameters

layoutGroup LayoutGroup

Start() 

protected override void Start()

SubtractValue(float) 

public void SubtractValue(float amount)

Parameters

amount float

Update() 

protected virtual void Update()

UpdateColors() 

public void UpdateColors()

UpdateIndicators() 

protected virtual void UpdateIndicators()

UpdateVisuals()

Updates the visual representation of the progress bar based on its current fill type. This method handles the visual update for both regular fill types and indicators. It also updates the secondary bar and the fill label position.

protected virtual void UpdateVisuals()

ValidateAndFixIndicatorCount()

Validates and fixes indicator count discrepancies. Call this if you suspect there are issues with indicator count.

[ContextMenu("Validate & Fix Indicator Count")]
public void ValidateAndFixIndicatorCount()

ValidateValue() 

protected virtual void ValidateValue()