Textdraws

What is a Textdraw?

As the name implies, a textdraw is text that is drawn on a player's screen. Unlike client messages or gametext however, textdraws can be shown on a player's screen for an indefinite period of time. Textdraws can be simple text on the screen such as a website address, or complex scripted dynamic textdraws such as progress bars.

This 'textdraw editor' tool can make designing textdraws much easier.

Global Textdraws

Global textdraws can be created, then shown to all players. There is a limit as to how many can be created, though. This means if you have a server with 500 players, creating more than 4 textdraws per-player is not possible. That's where player-textdraws come in. See further down. Here is a list of all the functions related to global textdraws:

• TextDrawCreate: Create a textdraw.
• TextDrawDestroy: Destroy a textdraw.
• TextDrawColor: Set the color of the text in a textdraw.
• TextDrawBoxColor: Set the color of the box in a textdraw.
• TextDrawBackgroundColor: Set the background color of a textdraw.
• TextDrawAlignment: Set the alignment of a textdraw.
• TextDrawFont: Set the font of a textdraw.
• TextDrawLetterSize: Set the letter size of the text in a textdraw.
• TextDrawTextSize: Set the size of a textdraw box.
• TextDrawSetOutline: Choose whether the text has an outline.
• TextDrawSetShadow: Toggle shadows on a textdraw.
• TextDrawSetProportional: Scale the text spacing in a textdraw to a proportional ratio.
• TextDrawUseBox: Toggle if the textdraw has a box or not.
• TextDrawSetString: Set the text in an existing textdraw.
• TextDrawShowForPlayer: Show a textdraw for a certain player.
• TextDrawHideForPlayer: Hide a textdraw for a certain player.
• TextDrawShowForAll: Show a textdraw for all players.
• TextDrawHideForAll: Hide a textdraw for all players.
• IsTextDrawVisibleForPlayer: Checks if a textdraw is shown for the player.
• IsValidTextDraw: Checks if a textdraw is valid.
• TextDrawGetAlignment: Gets the text alignment of a textdraw.
• TextDrawGetBackgroundColour: Gets the background colour of a textdraw.
• TextDrawGetBoxColour: Gets the box colour of a textdraw.
• TextDrawGetColour: Gets the text colour of a textdraw.
• TextDrawGetFont: Gets the text font of a textdraw.
• TextDrawGetLetterSize: Gets the width and height of the letters.
• TextDrawGetOutline: Gets the thickness of a textdraw's text's outline.
• TextDrawGetPos: Gets the position of a textdraw.
• TextDrawGetPreviewModel: Gets the preview model of a 3D preview textdraw.
• TextDrawGetPreviewRot: Gets the rotation and zoom of a 3D model preview textdraw.
• TextDrawGetPreviewVehCol: Gets the preview vehicle colors of a 3D preview textdraw.
• TextDrawGetPreviewVehicleColours: Gets the preview vehicle colours of a 3D preview textdraw.
• TextDrawGetShadow: Gets the size of a textdraw's text's shadow.
• TextDrawGetString: Gets the text of a textdraw.
• TextDrawGetTextSize: Gets the X axis and Y axis of the textdraw.
• TextDrawIsBox: Checks if a textdraw is box.
• TextDrawIsProportional: Checks if a textdraw is proportional.
• TextDrawIsSelectable: Checks if a textdraw is selectable.
• TextDrawSetPos: Sets the position of a textdraw.
• TextDrawSetStringForPlayer: Changes the text on a textdraw for a specific player.

Player-textdraws

Player-textdraws are only created for one specific player. Up to 256 textdraws can be created PER-PLAYER. That's 128,000 on a server with 500 players. A little more than 2048. Player-textdraws should be used for things that are not 'static'. Do not use them to display a website address for example, but for a vehicle health indicator.

• CreatePlayerTextDraw: Create a player-textdraw.
• PlayerTextDrawDestroy: Destroy a player-textdraw.
• PlayerTextDrawColor: Set the color of the text in a player-textdraw.
• PlayerTextDrawBoxColor: Set the color of a player-textdraw's box.
• PlayerTextDrawBackgroundColor: Set the background color of a player-textdraw.
• PlayerTextDrawAlignment: Set the alignment of a player-textdraw.
• PlayerTextDrawFont: Set the font of a player-textdraw.
• PlayerTextDrawLetterSize: Set the letter size of the text in a player-textdraw.
• PlayerTextDrawTextSize: Set the size of a player-textdraw box (or clickable area for PlayerTextDrawSetSelectable).
• PlayerTextDrawSetOutline: Toggle the outline on a player-textdraw.
• PlayerTextDrawSetShadow: Set the shadow on a player-textdraw.
• PlayerTextDrawSetProportional: Scale the text spacing in a player-textdraw to a proportional ratio.
• PlayerTextDrawUseBox: Toggle the box on a player-textdraw.
• PlayerTextDrawSetString: Set the text of a player-textdraw.
• PlayerTextDrawShow: Show a player-textdraw.
• PlayerTextDrawHide: Hide a player-textdraw.
• IsPlayerTextDrawVisible: Checks if a player-textdraw is shown for the player.
• IsValidPlayerTextDraw: Checks if a player-textdraw is valid.
• PlayerTextDrawBackgroundColour: Adjust the background colour of a player-textdraw.
• PlayerTextDrawBoxColour: Sets the colour of a textdraw's box (PlayerTextDrawUseBox ).
• PlayerTextDrawColour: Sets the text colour of a player-textdraw.
• PlayerTextDrawGetAlignment: Gets the text alignment of a player-textdraw.
• PlayerTextDrawGetBackgroundColour: Gets the background colour of a player-textdraw.
• PlayerTextDrawGetBoxColour: Gets the box colour of a player-textdraw.
• PlayerTextDrawGetColour: Gets the text colour of a player-textdraw.
• PlayerTextDrawGetFont: Gets the text font of a player-textdraw.
• PlayerTextDrawGetLetterSize: Gets the width and height of the letters.
• PlayerTextDrawGetOutline: Get the outline size on a player-textdraw.
• PlayerTextDrawGetPos: Gets the position of a player-textdraw.
• PlayerTextDrawGetPreviewModel: Gets the preview model of a 3D preview player-textdraw.
• PlayerTextDrawGetPreviewRot: Gets the rotation and zoom of a 3D model preview player-textdraw.
• PlayerTextDrawGetPreviewVehicleColours: Gets the preview vehicle colors of a 3D preview player-textdraw.
• PlayerTextDrawGetShadow: Get the shadow size on a player-textdraw.
• PlayerTextDrawGetString: Gets the text of a player-textdraw.
• PlayerTextDrawGetTextSize: Gets the X axis and Y axis of the player-textdraw text size.
• PlayerTextDrawIsBox: Checks if a player-textdraw is box.
• PlayerTextDrawIsProportional: Checks if a player-textdraw is proportional.
• PlayerTextDrawIsSelectable: Checks if a player-textdraw is selectable.
• PlayerTextDrawSetPos: Sets the position of a player-textdraw.
• PlayerTextDrawSetPreviewVehicleColours: Set the color of a vehicle in a player-textdraw model preview (if a vehicle is shown).

Variable Declaration

When creating a textdraw, you should always decide if the textdraw you're going to create has to be global (eg. your website address, global annoucement) or if it's going to differ per player (eg. kills, deaths, score).

Global Textdraw

A global textdraw is the easiest to create and requires only one variable. This variable is needed to modify the textdraw and to show it to the players later on. The declaration for such a textdraw needs to be a global variable in most cases. The textdraw variable also needs to be prefixed with the Text: tag and should be initialized with the value Text:INVALID_TEXT_DRAW. If you omit the initialization, the textdraw may conflict with others as you add more textdraws.

new Text:gMyText = Text:INVALID_TEXT_DRAW;

Per-Player Textdraw

A per-player textdraw is exactly the same as a regular 'global' textdraw, but only creates the textdraw for a single player.

This is useful for textdraws that are unique to each player, such as a 'stats' bar showing their kills or score.

This can be used to avoid going over the global-textdraw limit, as you can create 256 textdraws per player.

They are also easier to manage, as they automatically destroy themselves when the player disconnects.

new PlayerText:gMyPlayerText = PlayerText:INVALID_TEXT_DRAW;

The function names only differ slightly, with 'TextDraw' becoming 'PlayerTextDraw', with one exception: CreatePlayerTextDraw ('TextDrawSetString' becomes 'PlayerTextDrawSetString').

Creating the Textdraw

Once you've declared a variable/array to store the ID of your textdraw(s) in, you can proceed to create the textdraw itself. For global textdraws that are always created, the code should be placed under OnGameModeInit. To create the textdraw, the function TextDrawCreate must be used.

Note that this function merely creates the textdraw, other functions are used to modify it and to show it to the player(s).

Parameters:

TextDrawCreate(Float:x, Float:y, text[])

Return Values:

The ID of the created textdraw

Let's proceed to create the textdraw:

public OnGameModeInit()
{
    gMyText = TextDrawCreate(320.0, 240.0, "Hello World!");
    return 1;
}

We have created a textdraw in the center of the screen that says "Hello World!".

Setting the font

There are 4 fonts available for textdraw text:

As of SA-MP 0.3d, a new font (id 4) can be set. This is used in combination with the TextDrawCreate and TextDrawTextSize functions to show a texture 'sprite' on the player's screen. We'll cover this later.

Showing the textdraw

For this example, the textdraw has been created globally under OnGameModeInit and will be shown to player when they join the server.

To show a textdraw for a single player, the function TextDrawShowForPlayer is used.

Parameters:

TextDrawShowForPlayer(playerid, Text:text)

Return Values:

This function does not return any specific values.

The playerid is passed through OnPlayerConnect, and the text-draw ID is stored in the 'gMyText' variable.

public OnGameModeInit()
{
    gMyText = TextDrawCreate(320.0, 320.0, "Hello World!");
    return 1;
}

public OnPlayerConnect(playerid)
{
    TextDrawShowForPlayer(playerid, gMyText);
    return 1;
}

Assorted Tips

• Try to use whole number when specifying positions, this ensures the best compatibility on different resolutions.
• Fonts appear to look the best with an X to Y ratio of 1 to 4 (e.g. if x = 0.5 then y should be 2).