samp.directory
← Scripts e bibliotecas

Walter-Correa/Progress-Bar-Plus

A high-performance, modern progress bar and visual gauge library for SA-MP and Open.MP.

Biblioteca★ 1atualizado anteontemMPL-2.0Pawn
Abrir no GitHub
Testar no compilador Pawn →

Adiciona os arquivos de include dele, com as bibliotecas de que depende, ao compilador Pawn no seu navegador, prontos para incluir num script.

README.md

Progress Bar Plus

Progress Bar Plus is a high-performance, modern, flicker-free progress bar and visual gauge library engineered specifically for San Andreas Multiplayer (SA-MP) and open.mp.

It empowers Pawn developers to build fully customizable, hardware-accelerated HUD meters: Linear Rectangular Bars, Segmented Radial Ring Odometers, and Concentric Circular Gauges, complete with Fluid Value Interpolation (Lerp), Dynamic Multi-Stop Color Gradients, Intelligent Auto-Scaling HUD Text Labels, Cyclic Auto-Fill Animations, and Multi-Phase Blinking Alerts—all operating with zero external dependencies and guaranteed $16:9$ widescreen pixel-perfect border correction.

[!NOTE] This project is conceptually inspired by @Southclaws's progress2. It has been completely rebuilt from the ground up as a standalone, modern visual suite, introducing hardware-accelerated sprite rendering (LD_SPAC:white and LD_BEAT:chit), $16:9$ widescreen aspect-ratio border compensation, zero-flicker TextDraw recycling, open.mp native repositioning, smart bandwidth delta caching, and advanced animated states.



Comparison: progress2 vs. Progress Bar Plus

Feature / Capabilityprogress2 (Southclaws)Progress Bar Plus
Rendering PrimitiveText box padding using character "_" (PlayerTextDrawUseBox)✅ Hardware-accelerated native sprites (LD_SPAC:white & LD_BEAT:chit)
Widescreen ($16:9$) GeometryUncompensated coordinate offsets (borders appear thicker horizontally on $16:9$)✅ Exact $1.25\times$ vertical multiplier (PB_BORDER_Y_RATIO), uniform physical pixel thickness
Supported Visual Styles1 style (linear horizontal/vertical rectangular bar)✅ 3 styles (PB_STYLE_BAR, PB_STYLE_RING segmented radial odometer, PB_STYLE_CIRCLE concentric gauge)
Standard SA-MP Value UpdatesDestroys & recreates textdraw on every update when PlayerTextDrawSetPos is unavailable✅ Zero-flicker dynamic sizing via PlayerTextDrawTextSize; never destroys textdraw on updates
Zero-Value Z-Order PreservationDestroys textdraw on $0.0$; subsequent recreate re-renders bar on top of newer HUD layers✅ Hides element (PlayerTextDrawHide) on $0.0$; strictly preserves creation z-order
External DependenciesRequires YSI-Includes (y_iterate) and sampctl toolchains in modern versions✅ Completely standalone and zero-dependency (only standard <a_samp> or <open.mp>)
Fluid Value Interpolation (Lerp)❌ None (requires external gamemode timers, step loops, and tracking variables)✅ Built-in quadratic ease-out interpolation (InterpolatePlayerProgressBarValue)
Dynamic Color Gradients❌ None (requires manual gamemode color math)✅ Built-in multi-stop color blending (SetPlayerProgressBarGradient)
Visual HUD Text Labels❌ None (requires external TextDraws manually attached to coordinates)✅ Built-in high-contrast HUD labels with token formatting, auto-scaling, and vertical stacking
Dynamic Auto-Fill Animations❌ None (requires external gamemode timers and state machines)✅ Built-in cyclic auto-fill engine (AutoFillPlayerProgressBar) preserving base progress
Pulsing & Critical Alerts❌ None (requires manual gamemode timer and color toggling logic)✅ Built-in multi-phase blinking engine (BlinkPlayerProgressBar) with independent colors
Multi-Element Network CachingNot applicable (only supports basic 3-textdraw rectangular bars)✅ Per-segment delta cache (PB_TDColour), updating only modified dots to prevent packet flooding
Tagging & Type SafetyRequires strict PlayerBar: tag (produces tag mismatch warnings if handled as raw integer)✅ Standard integer IDs with backward compatibility tag/direction macros (zero compiler warnings)
In-Game Visual EditorBasic single-bar scripts (editor-pottus.pwn / editor-emmet.pwn), export-only✅ Full Progress Bar Plus - Editor with clickable 11-button Dock, 20-layer Z-order stack, .pbp projects, .pbt templates, Pawn code importer, 3-format exporter & Undo

Documentation Hub

Comprehensive, modular guides and technical references are available in the docs/ directory:

GuideDescription
📖 Getting StartedStep-by-step setup, zero-dependency installation, and drop-in migration from progress2.
📐 Bar Styles & GeometryLinear bars, radial ring odometers, circular gauges, and $16:9$ widescreen border compensation.
⚡ Animations & Visual FXSmooth lerp (quadratic ease-out), multi-stop gradients, cyclic auto-fill, and blinking alerts.
🏷️ HUD Value & Text LabelsIntelligent auto-scaling, adaptive vertical text stacking (~n~), and dynamic color tracking.
🎨 In-Game Visual EditorInteractive 11-tool dock, real-time keyboard transforms, multi-layer workspace, HUD anchors.
📚 Complete API ReferenceExhaustive technical dictionary with all 62 functions, parameters, return types, and constants.

Quick Start & Installation

1. File Placement

Copy ProgressBar.inc into your server's include directory:

  • SA-MP / Pawno: pawno/include/ProgressBar.inc
  • open.mp / Qawno: qawno/include/ProgressBar.inc

2. Include in Your Script

#include <open.mp> // or <a_samp>
#include <ProgressBar>

[!TIP] Performance Tip (Include Order): If your script uses TextDraw hooking libraries (such as TextDrawFX), place #include <ProgressBar> before them so that high-frequency progress bar updates bind directly to raw native functions and bypass third-party hook loops.

3. Basic Example

Create a modern, auto-scaling health meter with dynamic gradient color tracking in just a few lines:

new PlayerBar:gPlayerHealthBar[MAX_PLAYERS];

public OnPlayerSpawn(playerid)
{
    // Create a 60x10 health bar anchored near the radar
    gPlayerHealthBar[playerid] = CreatePlayerProgressBar(
        playerid,
        548.0, 65.0, 60.5, 9.5,
        0x2ECC71FF, 100.0,
        PB_DIR_RIGHT, 1.25
    );

    // Enable dynamic 3-stop health gradient (Green -> Amber -> Red)
    SetPlayerProgressBarGradient(playerid, gPlayerHealthBar[playerid], true);

    // Attach high-contrast HUD text label tracking the bar's live color
    SetPlayerProgressBarLabel(playerid, gPlayerHealthBar[playerid], true, "{PERCENT}%", 0);

    // Display on screen
    ShowPlayerProgressBar(playerid, gPlayerHealthBar[playerid]);
    return 1;
}

public OnPlayerTakeDamage(playerid, issuerid, Float:amount, weaponid, bodypart)
{
    new Float:hp;
    GetPlayerHealth(playerid, hp);
    
    // Smoothly animate the bar to the new health value over 400ms
    InterpolatePlayerProgressBarValue(playerid, gPlayerHealthBar[playerid], hp, 400);
    return 1;
}

[!TIP] Need to migrate an existing gamemode from progress2? Read the Migration Guide in docs/getting-started.md for instant 1:1 drop-in compatibility.


In-Game Visual HUD Editor

Progress Bar Plus includes a full-featured in-game visual designer filterscript located in Progress Bar Plus - Editor/. Built with Pawn.CMD and an optimized 10-slot Session Pool architecture, it works out-of-the-box on both SA-MP and open.mp.

[ Style ] [ Color ] [ Transform ] [ Animate ] [ Align ] [ Duplicate ] [ Delete ] [ + Layer ] [ Save ] [ Export ] [ Close ]

Highlights

  • Clickable 11-Button Dock: Real-time HUD telemetry, grid snapping, and full-screen preview.
  • Keyboard Transform Engine: Fluid 35ms positioning via W/A/S/D and Arrow keys with SHIFT/CTRL fast and ALT precision speed modifiers.
  • Multi-Layer Stacking: Up to 20 bar layers per project with Z-order sorting and 1-step snapshot Undo.
  • Anti-Kick Rate Limiting: Density-aware rebuild throttling and key-release auto-flush prevent ackslimit packet flooding even with 60-segment radial gauges.
  • Universal Exporter: Generates ready-to-paste Pawn code (.pwn, .inc), project files (.pbp), and reusable layer templates (.pbt).

Type /pbe in-game to launch the editor.

[!TIP] For the complete manual, keybinding tables, and session management, see docs/in-game-editor.md.


Complete API Reference

All 62 functions, macros, style enumerations, and compile-time constants are exhaustively documented with signature parameters, return values, and code snippets in docs/api-reference.md:

  • Lifecycle & Creation: CreatePlayerProgressBar, DestroyPlayerProgressBar, ResetPlayerProgressBar, ShowPlayerProgressBar, HidePlayerProgressBar...
  • Value & Range Control: SetPlayerProgressBarValue, SetPlayerProgressBarRange, SetPlayerProgressBarMinValue, SetPlayerProgressBarMaxValue...
  • Position, Dimensions & Borders: SetPlayerProgressBarPos, SetPlayerProgressBarSize, SetPlayerProgressBarBorder...
  • Colors & Dynamic Gradients: SetPlayerProgressBarColour, SetPlayerProgressBarGradient, SetPlayerProgressBarGradientInverted...
  • Animations & Visual FX: InterpolatePlayerProgressBarValue, AutoFillPlayerProgressBar, BlinkPlayerProgressBar...
  • HUD Value & Text Labels: SetPlayerProgressBarLabel, SetPlayerProgressBarLabelAutoScale, SetPlayerProgressBarLabelFollowColour...
  • Styles, Segments & Rings: SetPlayerProgressBarStyle, SetPlayerProgressBarSegments, SetPlayerProgressBarRingScale...
  • Constants & Enums: PB_STYLE_*, PB_DIR_*, PB_GRAD_*, PROGRESSBAR_VERSION_*...
  • Compile-Time Defines: PB_MAX_BARS, PB_MAX_TDS, PB_TICK_RATE, PB_BORDER_Y_RATIO...

Version History

Show the version history

2.2.0 — 03/11/2026

  • Intelligent Auto-Adaptive Text Stacking:
    • Auto-adaptive label layout (PB_FormatLabel / PB_IsLabelVertical): automatically evaluates whether label text fits horizontally inside the bar's inner width. When narrow vertical bars cannot accommodate horizontal text, characters automatically stack vertically using ~n~ linebreaks while preserving embedded color tags ({RRGGBB}) and geometric center alignment.
    • Wide vertical bars dynamically maintain standard horizontal text layout without unnecessary stacking.
  • Dynamic Gradient Color Label Tracking:
    • Label text can now dynamically inherit and synchronize with the bar's active fill color (followColour = true).
    • Injects dynamic {%06x} native SA-MP color tags, keeping HUD text label colors continuously synchronized across static colors, dynamic multi-stop gradients (SetPlayerProgressBarGradient), auto-fill previews, and lerp transitions.
  • Anti-Kick Rate Limiting & Network Protection:
    • Fixed client exceeded 'ackslimit' kicks when moving or resizing high-density radial rings (45+ segments) by implementing density-aware rebuild throttling (200ms for $\ge 45$ segs, 120ms for $\ge 30$, 70ms for $<30$), continuous coordinate accumulation, and an immediate key-release auto-flush engine (EP_RingPendingRebuild).
    • Expanded radial ring segment scale multiplier bounds: minimum lowered to 0.10 (range: $0.10$ to $3.00$).
  • Dynamic Direction Change Fix:
    • SetPlayerProgressBarDirection now completely re-renders and realigns progress fill sprites and text labels, allowing seamless live direction switching (PB_DIR_RIGHT, PB_DIR_LEFT, PB_DIR_UP, PB_DIR_DOWN) without visual offset distortion.
  • Standardized Include Versioning System:
    • Introduced standard macro definitions in ProgressBar.inc: PROGRESSBAR_VERSION_MAJOR, PROGRESSBAR_VERSION_MINOR, PROGRESSBAR_VERSION_PATCH, and PROGRESSBAR_VERSION_STRING.
    • Updated GitHub Actions CI/CD workflows (build.yml and release.yml) to automatically parse and validate version macros from ProgressBar.inc.
  • Progress Bar Plus - Editor v2.2.0 Upgrades:
    • Streamlined label orientation UI (fully automated auto-adaptive text positioning).
    • Live gradient color synchronization in the editor preview.
    • Segment scale range text updated to 0.10 - 3.00.
  • Comprehensive Documentation Suite (docs/):
    • Created dedicated documentation suite with 7 modular guides covering setup, geometry, animations, labels, editor manual, and exhaustive API reference.

2.1.0 — 02/11/2026

  • Smooth Value Interpolation (InterpolatePlayerProgressBarValue):
    • Added built-in fluid value transition engine with quadratic ease-out curves and 30 FPS timer ticks (PB_TICK_RATE = 33ms).
    • Added StopPlayerProgressBarInterpolation and IsPlayerProgressBarInterpolating for complete runtime control.
    • Implemented mutual exclusion: activating lerp automatically halts auto-fill, and activating auto-fill automatically halts lerp.
  • Dynamic Multi-Stop Color Gradients (SetPlayerProgressBarGradient):
    • Added dynamic color interpolation based on current bar fill ratio (Empty -> Midpoint -> Full, defaulting to Red -> Amber -> Green).
    • Added bidirectional gradient direction and polarity control (SetPlayerProgressBarGradientInverted / SetPlayerProgressBarGradientDirection) supporting Standard (Health: Red -> Green) and Inverted (Heat/Threat/Temperature: Green -> Red) progression modes.
    • Implemented real-time gradient synchronization with cyclic auto-fill preview animations across all bar styles.
    • Added StopPlayerProgressBarGradient and IsPlayerProgressBarGradientEnabled.
  • Intelligent Auto-Scaling HUD Text Labels (SetPlayerProgressBarLabel):
    • Built-in high-contrast HUD text label with dynamic template token formatting ({PERCENT}, {VALUE}, {MAX}, {MIN}).
    • Added SetPlayerProgressBarLabelAutoScale: mathematically bounds font scale within the bar's inner dimensions so text never overflows borders across all resizes and moves.
  • Custom Min-Value Range (SetPlayerProgressBarMinValue, SetPlayerProgressBarRange):
    • Added support for custom minimum thresholds with mathematical fill normalization (part = (val - min) / (max - min)), ensuring zero visual distortion.
  • Progress Bar Plus - Editor v2.1.0:
    • Integrated Text Label designer with font picker, live preview, offset adjustments, and auto-scale toggle.
    • Integrated Dynamic Health Gradient toggle and Direction / Polarity switcher in Color & Themes menu.
    • Integrated Min-Value configuration dialog in Animations & Values menu.
    • Full export generator updated for all v2.1.0 functions across Pawn script, project (.pbp), and template (.pbt) formats.
  • Drop-In Compatibility & Repository Enhancements:
    • 100% backward-compatible drop-in replacement for v1.0.0 and progress2 codebases.
    • Added .gitignore to keep runtime server logs (log.txt, server_log.txt, omp-server.log) out of version control.
    • Added automated GitHub Actions build and release workflows (.github/workflows/build.yml and release.yml).

2.0.0 — 01/11/2026

  • Introduced Progress Bar Plus - Editor (Progress Bar Plus - Editor/filterscripts/FS_ProgressBarEditor.pwn & gamemodes/GM_ProgressBarEditor.pwn):
    • Complete in-game visual HUD editor built with Pawn.CMD, compatible out-of-the-box with SA-MP and open.mp, accompanied by a lightweight sandbox test gamemode.
    • Memory-optimized 10-slot concurrent Session Pool architecture with automatic in-memory Project Lock protection preventing concurrent overwrites across active editors.
    • Interactive 11-button Editor Dock (Bottom / Top / Minimized fullscreen preview) with live telemetry HUD, project save state indicator ([Saved] / [Unsaved]), and alignment crosshair/thirds grid.
    • Multi-bar workspace supporting up to 20 layers per project with Z-order reordering, cloning, renaming, visibility toggling, and 1-step snapshot Undo.
    • Real-time 35ms transform engine supporting Keyboard (W/A/S/D & Arrows) with SHIFT/CTRL fast and ALT fine speed modifiers, grid snapping, and $16:9$ perfect circle aspect-ratio locking for rings and circles with precise 1:1 screen synchronization.
    • Interactive Live Value Scrubber allowing developers to visually test fill thresholds in real time using WASD / Arrow keys.
    • Color & Theme Designer featuring 28 modern curated palette swatches, direct hex RGBA/RGB #HEX entry, 5 opacity presets, automatic border shading, and cross-layer visual theme cloning.
    • Segmented Radial Ring Customizer with real-time segment count adjustment ($4$ to $60$) and independent dot scale multipliers.
    • Dynamic Auto-Fill preview designer and multi-phase blinking alert configurator with interval and duration tuning.
    • Project management system saving binary .pbp workspaces to scriptfiles/ProgressBarPlus/projects/ with automatic directory self-healing.
    • Template preset library saving reusable layer templates (.pbt) to scriptfiles/ProgressBarPlus/templates/.
    • Interactive Pawn code importer parsing CreatePlayerProgressBar code directly into live editable layers.
    • Tri-format code exporter generating modular standalone includes (.inc), standalone test gamemodes (.pwn), or raw code snippets into scriptfiles/ProgressBarPlus/exports/.

1.0.0 — 01/11/2026

  • Initial public release of Progress Bar Plus:
    • Pure sprite rendering engine utilizing native LD_SPAC:white (linear bars) and LD_BEAT:chit (segmented radial rings and expanding concentric circular gauges).
    • Built-in widescreen aspect-ratio border compensation (PB_BORDER_Y_RATIO = 1.25) guaranteeing uniform physical pixel thickness on $16:9$ monitors.
    • Dynamic in-place coordinate resizing (PlayerTextDrawTextSize and open.mp PlayerTextDrawSetPos) eliminating TextDraw destruction flickering.
    • Handle preservation and zero-value hiding (PlayerTextDrawHide) maintaining strict Z-index ordering.
    • Dynamic cyclic auto-fill animation engine (AutoFillPlayerProgressBar).
    • Multi-phase blinking alert system (BlinkPlayerProgressBar) with independent inner and border color overrides.
    • Per-segment delta network caching (PB_TDColour) preventing bandwidth packet flooding on high-frequency ring updates.
    • Zero external dependencies—fully compatible with standard SA-MP (<a_samp>) and open.mp (<open.mp>).

Author & Credits

Ler o resto no GitHub

Esta página é montada com o que o GitHub publica sobre o repositório. O samp.directory não hospeda o código. Avisar de um problema com esta página

Walter-Correa/Progress-Bar-Plus: Biblioteca de SA-MP | samp.directory