joaopauloarj/PlayerBar

PlayerBar

A lightweight, fast, and fully directional progress bar include for open.mp with legacy SA-MP compatibility.

PlayerBar provides customizable per-player textdraw progress bars with support for all four fill directions (up, down, left, and right), through a clean API inspired by Progress2.

---

Preview

Features

• Lightweight implementation
• Compatible with open.mp and legacy SA-MP 0.3.7
• Four fill directions
• Per-player bars
• Progress2-inspired API
• Highly customizable

---

Installation

Using sampctl:

sampctl install joaopauloarj/PlayerBar

Or copy PlayerBar.inc into your compiler's include directory (e.g. qawno/include).

Then include it:

#include <PlayerBar>

Note PlayerBar is primarily developed for open.mp, but is also compatible with legacy SA-MP 0.3.7 without requiring any API changes.

---

Usage Example

new PlayerBar:gHealthBar[MAX_PLAYERS];

public OnPlayerConnect(playerid)
{
    gHealthBar[playerid] = PlayerBar_Create(
        playerid,
        320.0,
        224.0,
        100.0,
        2.0,
        DIRECTION_RIGHT,
        0xFF0000FF
    );

    PlayerBar_SetValue(playerid, gHealthBar[playerid], 75.0);
    return 1;
}

public OnPlayerDisconnect(playerid, reason)
{
    PlayerBar_Destroy(playerid, gHealthBar[playerid]);
    return 1;
}

---

Constants

---

API Reference

PlayerBar:PlayerBar_Create(...)

Create a progress bar for the playerid.

PlayerBar:PlayerBar_Create(
    playerid,
    Float:x,
    Float:y,
    Float:width = 50.0,
    Float:height = 1.25,
    E_DIRECTION:direction = DIRECTION_RIGHT,
    colour = 0xFF0000FF,
    Float:maxvalue = 100.0
);

Returns:

• PlayerBar on success.
• INVALID_PLAYER_BAR_ID on failure.

---

PlayerBar_Destroy(...)

Destroy a player bar.

PlayerBar_Destroy(playerid, PlayerBar:barid);

Returns:

• 1 on success
• 0 on failure

---

PlayerBar_DestroyAll(...)

Destroys every bar belonging to a player.

PlayerBar_DestroyAll(playerid);

Returns:

• 1 on success
• 0 on failure

---

PlayerBar_Show(...)

Show bar to a player.

PlayerBar_Show(playerid, PlayerBar:barid);

Returns:

• 1 on success
• 0 on failure

---

PlayerBar_Hide(...)

Hide bar to a player.

PlayerBar_Hide(playerid, PlayerBar:barid);

Returns:

• 1 on success
• 0 on failure

---

PlayerBar_SetPos(...)

Sets the position of a player bar.

PlayerBar_SetPos(
    playerid,
    PlayerBar:barid,
    Float:x,
    Float:y
);

Returns:

• 1 on success.
• 0 on failure.

---

PlayerBar_GetPos(...)

Gets the position of the player's bar.

PlayerBar_GetPos(
    playerid,
    PlayerBar:barid,
    &Float:x,
    &Float:y
);

Returns:

• 1 on success.
• 0 on failure.

Output parameters

• x - Receives the horizontal position.
• y - Receives the vertical position.

---

PlayerBar_SetSize(...)

Sets the size of a player bar.

PlayerBar_SetSize(
    playerid,
    PlayerBar:barid,
    Float:width,
    Float:height
);

Returns:

• 1 on success.
• 0 on failure.

---

PlayerBar_GetSize(...)

Gets the size of a player bar.

PlayerBar_GetSize(
    playerid,
    PlayerBar:barid,
    &Float:width,
    &Float:height
);

Returns:

• 1 on success.
• 0 on failure.

Output parameters

• width - Receives the width of the player bar.
• height - Receives the height of the player bar.

---

PlayerBar_SetDirection(...)

Sets the fill direction of a player bar.

PlayerBar_SetDirection(
    playerid,
    PlayerBar:barid,
    E_DIRECTION:direction
);

Returns:

• 1 on success.
• 0 on failure.

Available directions:

• DIRECTION_UP
• DIRECTION_RIGHT
• DIRECTION_DOWN
• DIRECTION_LEFT

---

E_DIRECTION:PlayerBar_GetDirection(...)

Gets the fill direction of a player bar.

PlayerBar_GetDirection(
    playerid,
    PlayerBar:barid
);

Returns:

• E_DIRECTION on success.
• INVALID_PLAYER_BAR_DIRECTION on failure.

---

PlayerBar_SetValue(...)

Sets the fill value of a player bar.

PlayerBar_SetValue(
    playerid,
    PlayerBar:barid,
    Float:value
);

Returns:

• 1 on success.
• 0 on failure.

---

Float:PlayerBar_GetValue(...)

Gets the fill value of a player bar.

Float:PlayerBar_GetValue(
    playerid,
    PlayerBar:barid
);

Returns:

• The current value on success.
• INVALID_PLAYER_BAR_VALUE on failure.

---

PlayerBar_SetMaxValue(...)

Sets the maximum value of a player bar.

PlayerBar_SetMaxValue(
    playerid,
    PlayerBar:barid,
    Float:maxvalue
);

Returns:

• 1 on success.
• 0 on failure.

---

Float:PlayerBar_GetMaxValue(...)

Gets the maximum value of a player bar.

Float:PlayerBar_GetMaxValue(
    playerid,
    PlayerBar:barid
);

Returns:

• The current maximum value on success.
• INVALID_PLAYER_BAR_VALUE on failure.

---

PlayerBar_SetColour(...)

Sets the fill colour of a player bar.

PlayerBar_SetColour(
    playerid,
    PlayerBar:barid,
    newcolour
);

Returns:

• 1 on success.
• 0 on failure.

---

PlayerBar_GetColour(...)

Gets the fill colour of a player bar.

PlayerBar_GetColour(
    playerid,
    PlayerBar:barid
);

Returns:

• The current fill colour on success.
• INVALID_PLAYER_BAR_COLOUR on failure.

---

PlayerBar_SetBackgroundColour(...)

Sets the background colour of a player bar.

PlayerBar_SetBackgroundColour(
    playerid,
    PlayerBar:barid,
    newcolour
);

Returns:

• 1 on success.
• 0 on failure.

---

PlayerBar_GetBackgroundColour(...)

Gets the background colour of a player bar.

PlayerBar_GetBackgroundColour(
    playerid,
    PlayerBar:barid
);

Returns:

• The current background colour on success.
• INVALID_PLAYER_BAR_COLOUR on failure.

---

bool:PlayerBar_IsVisible(...)

Checks whether a player bar is currently visible.

bool:PlayerBar_IsVisible(
    playerid,
    PlayerBar:barid
);

Returns:

• true if the player bar is visible.
• false otherwise.

---

bool:PlayerBar_IsValid(...)

Checks whether a player bar handle is valid.

bool:PlayerBar_IsValid(
    playerid,
    PlayerBar:barid
);

Returns:

• true if the player bar handle is valid.
• false otherwise.

---

License

PlayerBar is released under the MIT License.

You are free to use, modify, distribute and include it in both open-source and commercial projects, provided that the original copyright and license notice are retained.

See the LICENSE file for the full license text.

Credits

PlayerBar was developed by João Paulo (@joaopauloarj).

The public API was inspired by Southclaws' Progress2.

The implementation, rendering system, mathematical calculations, and cross-runtime compatibility were independently designed and developed for PlayerBar.