TextDraw

From SA-MP Wiki

(Redirected from Textdraw)
Jump to: navigation, search

Image:32px-Ambox_warning_orange.png This article is currently a Work In Progress. It is therefore possible that the content of this article is currently incomplete or incorrect.


Contents

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: http://forum.sa-mp.com/showthread.php?t=290640

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:



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.



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 (as of 0.3e R2) 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;

IMPORTANT NOTE: An array is still needed for the variable, as the ID of the textdraws may differ from player to player, as other players may have more or less textdraws created than the other.

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

Creating the Textdraw

Dimension map.
Enlarge
Dimension map.

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[]))
xX coordinate at which to create the textdraw
yY coordinate at which to create the textdraw
text[]The text in the textdraw.


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:

Image:Textdraw_font_styles.png

ID Info Tips
0 The San Andreas Font. Use for header or titles, not a whole page.
1 Clear font that includes both upper and lower case characters. Can be used for a lot of text.
2 Clear font, but includes only capital letters. Can be used in various instances.
3 GTA font Retains quality when enlarged. Useful for large texts.

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))
playeridThe ID of the player to show the textdraw for
textThe ID of the textdraw to show


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).
Retrieved from "https://sampwiki.blast.hk/wiki/TextDraw"
Personal tools
Navigation
Toolbox