Player Textdraw

class pysamp.playertextdraw.PlayerTextDraw(id: int, player: Player)

Bases: object

Textdraws that are per-player. For global textdraws that are shown for all players, check out TextDraw.

Parameters

id – The ID that represents a textdraw.

Players can have up to 256 textdraws shown of this type at once. Exceeding this will cause issues with other textdraws.

To create a new textdraw, use PlayerTextDraw.create().

alignment(alignment: int) → bool

Set the text-alignment of the player-textdraw.

Parameters

alignment (int) – Alignment can be 1: left, 2: center, 3: right.

Returns

This method does not return anything.

Note

For alignment 2 (center) the x and y values of text_size() need to be swapped.

background_color(color: int) → bool

Change the textdraw’s background color.

Parameters

color (int) – The color that the textdraw should be set to.

Returns

This method does not return anything.

Note

• If set_outline() is used with size > 0, the outline color will match the color used in background_color().

• Changing the value of color seems to alter the color used in color()

box_color(color: int) → bool

Sets the text color of a player-textdraw box.

Parameters

color (int) – Color in 0xRRGGBBAA format.

Returns

This method does not return anything.

color(color: int) → bool

Sets the text color of the player-textdraw.

Parameters

color (int) – The color you want to give the textdraw, in a 0xRRGGBBAA format.

You can also use game_text() colors (like ~r~ and ~w~) directly in the text if you want.

Note

The textdraw must be re-shown to the player in order to update the color.

classmethod create(player: Player, x: float, y: float, text: str) → PlayerTextDraw

Create a textdraw for the player.

Parameters

• player (Player) – The Player to create the Textdraw for.

• x (float) – the x-position on the screen.

• y (float) – the y-position on the screen.

• text (str) – The text to show.

Returns

An instance of PlayerTextDraw.

Note

• The (0,0) coordinate is the top left coordinate for the textdraw area based on a 640x448 “canvas” (irrespective of screen resolution). If you plan on using player.text_draw_alignment() with alignment 3 (right), the x,y coordinate is the top right coordinate for the textdraw.

• This function only “creates” the textdraw, you must use player.text_draw_show() to show it to a player.

• It is recommended to use WHOLE numbers instead of decimal positions when creating player textdraws to ensure resolution friendly design.

• Player-textdraws are automatically destroyed when a player disconnects

• Keyboard key mapping codes (such as ~k~~VEHICLE_ENTER_EXIT~) Doesn’t work beyond 255th character.

Warning

• If you choose values for y that are less than 1, the first text row will be invisible and only the shadow is visible.

• text must NOT be empty or the server will crash. Use ” ” (a space) or _ (underscore) instead.

• If the last character in the text is a space (” “), the text will all be blank.

• If part of the text is off-screen, the color of the text will not show, only the shadow (if enabled) will.

destroy() → bool

Destroy the player textdraw.

Returns

Does not return anything.

font(font: int) → bool

Change the font of a textdraw.

Parameters

font (int) – A font ID to give the textdraw (0-3).

Returns

No value is returned.

See all fonts here: https://sampwiki.blast.hk/wiki/PlayerTextDrawFont

Warning

Setting the font above 3 may crash the client.

hide() → bool

Use this method to hide the player-textdraw for the player.

Returns

This method does not return anything.

letter_size(x: float, y: float) → bool

Sets the width and height of the letters in a player-textdraw.

Parameters

• x (float) – Width of a character.

• y (float) – Height of a character.

Returns

Does not return anything.

Note

• Fonts appear to look the best with an X to Y ratio of 1 to 4. (E.g. if x is 0.5 then y should be 2).

• When using this function purely for the benefit of affecting the textdraw box, multiply Y by 0.135 to convert to text_size-like measurements

set_outline(size: int) → bool

Set the outline of a player-textdraw. The outline colour cannot be changed unless background_color() is used.

Parameters

size (int) – The thickness of the outline.

Returns

This method does not return anything.

set_preview_model(model_index: int) → bool

Sets a player textdraw 2D preview sprite of a specified model ID.

Parameters

model_index (int) – The model to show.

Returns

This method does not return anything.

set_preview_rotation(rotation_x: float, rotation_y: float, rotation_z: float, zoom: float = 1.0) → bool

Sets the rotation and zoom of a 3D model preview player-textdraw.

Parameters

• rotation_x (float) – The X rotation value.

• rotation_y (float) – The Y rotation value.

• rotation_z (float) – The Z rotation value.

• zoom (optional float) – The zoom value, default value 1.0, smaller values make the camera closer and larger values make the camera further away.

Returns

This method does not return anything.

set_preview_vehicle_color(color1: int, color2: int) → bool

Set the color of a vehicle in a player-textdraw model preview (if a vehicle is shown).

Parameters

• color1 (int) – The color to set the vehicle’s primary color to.

• color2 (int) – The color to set the vehicle’s secondary color to.

Returns

This method does not return anything.

The textdraw must use the font TEXT_DRAW_FONT_MODEL_PREVIEW and be showing a vehicle, in order for this method to have an effect.

set_proportional(set: bool) → bool

Appears to scale text spacing to a proportional ratio. Useful when using letter_size() to ensure the text has an even character spacing.

Parameters

set (bool) – True to enable proportionality, False to disable.

Returns

Does not return anything.

set_selectable(set: bool) → bool

Set the textdraw selectable.

Parameters

set (bool) – Toggle the textdraw selectable or not.

Returns

No return value.

Warning

This method _must_ be used before the textdraw is shown to the player.

text_size() defines the clickable area.

set_shadow(size: int) → bool

Adds a shadow to the bottom-right side of the text in a player-textdraw. The shadow font matches the text font.

Parameters

size (int) – The size of the shadow. 0 will hide the shadow.

Returns

No value is returned.

Note

The shadow can be cut by the box area if the size is set too big for the area.

set_string(string: str) → bool

Update the shown text in the player-textdraw.

Parameters

string (str) – The new string for the textdraw. Max length: 1024 characters.

Returns

This method does not return anything.

You don’t have to show the textdraw again in order to apply the changes

show() → bool

Use this method to show the player-textdraw for the player.

Returns

This method does not return anything.

text_size(x: float, y: float) → bool

Change the size of the player-textdraw (box if use_box() is enabled and/or clickable area for use with set_selectable()).

Parameters

• x (float) – The size on the X axis (left/right) following the same 640x480 grid as create().

• y (float) – The size on the Y axis (up/down) following the same 640x480 grid as create().

Returns

Does not return any value.

Note

The x and y have different meanings with different alignment() values:

1. (left): they are the right-most corner of the box, absolute coordinates.

2. (center): they need to inverted (switch the two) and the x value is the overall width of the box.

3. (right): the x and y are the coordinates of the left-most corner of the box

Using font type 4 (sprite) and 5 (model preview) converts X and Y of this function from corner coordinates to WIDTH and HEIGHT (offsets).

The TextDraw box starts 10.0 units up and 5.0 to the left as the origin (create()).

This function defines the clickable area for use with set_selectable(), whether a box is shown or not.

use_box(use: bool) → bool

Toggle the box on the textdraw.

Parameters

use (bool) – True to use a box, False to hide the box.

Returns

This method does not return anything.