Walter-Correa/Progress-Bar-Plus
A high-performance, modern progress bar and visual gauge library for SA-MP and Open.MP.
Dodaje jej pliki include, razem z bibliotekami, od których zależy, do kompilatora Pawn w twojej przeglądarce, gotowe do dołączenia w skrypcie.
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:whiteandLD_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 / Capability | progress2 (Southclaws) | Progress Bar Plus |
|---|---|---|
| Rendering Primitive | Text box padding using character "_" (PlayerTextDrawUseBox) | ✅ Hardware-accelerated native sprites (LD_SPAC:white & LD_BEAT:chit) |
| Widescreen ($16:9$) Geometry | Uncompensated 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 Styles | 1 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 Updates | Destroys & recreates textdraw on every update when PlayerTextDrawSetPos is unavailable | ✅ Zero-flicker dynamic sizing via PlayerTextDrawTextSize; never destroys textdraw on updates |
| Zero-Value Z-Order Preservation | Destroys 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 Dependencies | Requires 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 Caching | Not applicable (only supports basic 3-textdraw rectangular bars) | ✅ Per-segment delta cache (PB_TDColour), updating only modified dots to prevent packet flooding |
| Tagging & Type Safety | Requires 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 Editor | Basic 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:
| Guide | Description |
|---|---|
| 📖 Getting Started | Step-by-step setup, zero-dependency installation, and drop-in migration from progress2. |
| 📐 Bar Styles & Geometry | Linear bars, radial ring odometers, circular gauges, and $16:9$ widescreen border compensation. |
| ⚡ Animations & Visual FX | Smooth lerp (quadratic ease-out), multi-stop gradients, cyclic auto-fill, and blinking alerts. |
| 🏷️ HUD Value & Text Labels | Intelligent auto-scaling, adaptive vertical text stacking (~n~), and dynamic color tracking. |
| 🎨 In-Game Visual Editor | Interactive 11-tool dock, real-time keyboard transforms, multi-layer workspace, HUD anchors. |
| 📚 Complete API Reference | Exhaustive 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/Dand Arrow keys withSHIFT/CTRLfast andALTprecision 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
ackslimitpacket 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.
- Auto-adaptive label layout (
- 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.
- Label text can now dynamically inherit and synchronize with the bar's active fill color (
- 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$).
- Fixed
- Dynamic Direction Change Fix:
SetPlayerProgressBarDirectionnow 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, andPROGRESSBAR_VERSION_STRING. - Updated GitHub Actions CI/CD workflows (
build.ymlandrelease.yml) to automatically parse and validate version macros fromProgressBar.inc.
- Introduced standard macro definitions in
- 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
StopPlayerProgressBarInterpolationandIsPlayerProgressBarInterpolatingfor complete runtime control. - Implemented mutual exclusion: activating lerp automatically halts auto-fill, and activating auto-fill automatically halts lerp.
- Added built-in fluid value transition engine with quadratic ease-out curves and 30 FPS timer ticks (
- 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
StopPlayerProgressBarGradientandIsPlayerProgressBarGradientEnabled.
- 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.
- Built-in high-contrast HUD text label with dynamic template token formatting (
- 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.
- Added support for custom minimum thresholds with mathematical fill normalization (
- 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
progress2codebases. - Added
.gitignoreto 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.ymlandrelease.yml).
- 100% backward-compatible drop-in replacement for v1.0.0 and
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
35mstransform engine supporting Keyboard (W/A/S/D& Arrows) withSHIFT/CTRLfast andALTfine 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
#HEXentry, 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
.pbpworkspaces toscriptfiles/ProgressBarPlus/projects/with automatic directory self-healing. - Template preset library saving reusable layer templates (
.pbt) toscriptfiles/ProgressBarPlus/templates/. - Interactive Pawn code importer parsing
CreatePlayerProgressBarcode directly into live editable layers. - Tri-format code exporter generating modular standalone includes (
.inc), standalone test gamemodes (.pwn), or raw code snippets intoscriptfiles/ProgressBarPlus/exports/.
- Complete in-game visual HUD editor built with
1.0.0 — 01/11/2026
- Initial public release of Progress Bar Plus:
- Pure sprite rendering engine utilizing native
LD_SPAC:white(linear bars) andLD_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 (
PlayerTextDrawTextSizeand open.mpPlayerTextDrawSetPos) 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>).
- Pure sprite rendering engine utilizing native
Author & Credits
Ta strona jest zbudowana z tego, co GitHub publikuje o repozytorium. samp.directory nie hostuje kodu. Zgłoś problem z tym wpisem