Player

class pysamp.player.Player(playerid: int)

Bases: object

Class to interact with players that are online.

A player is a client controlled character inside the server. The characters that are not controlled by a player are called non-player characters (NPCs), and are found in the Actor class.

allow_teleport(allow: bool) → bool

Enable or disable teleporting when marking the map with the map- marker.

Parameters: allow – A bool to allow or disallow teleport.
Returns: Nothing.

Warning

Deprecated since 0.3d. Please use the callback player.on_click_map instead.

animation_index() → int

Get the current playing animation index of the player.

Returns: The animation index.

apply_animation(animation_library: str, animation_name: str, delta: float, loop: bool, lock_x: bool, lock_y: bool, freeze: bool, time: int, force_sync: bool = False) → bool: Apply a given animation to the player.

attach_camera_to_player_object(player_object: PlayerObject) → bool

Attach the player camera to a player object.

Parameters: player_object (PlayerObject) – The player object you want to attach to.
Returns: No return value.

ban() → bool

Ban the player from the server.

Returns: No value is returned.

This writes their IP to the server samp.ban file, and they will not be able to reconnect using the same IP.

ban_ex(reason: str) → bool

This method does the exact same as ban(), but adds a reason.

Parameters: reason (str) – The reason to write together with the ban.
Returns: No value is returned.

The reason will be written as a comment together with the IP in the samp.ban file.

camera_target_actor() → Optional[Actor]

Get the Actor the current player is looking at.

Returns: A actor.Actor instance representing the actor. If no actor is being targeted by the camera, it will return None.

clear_animations(forcesync: bool = False) → bool

Stop any ongoing animations the player has running.

Parameters: forcesync (optional bool) – Set to True to force the player to sync the animation with other players in streaming radius.
Returns: This method does not have any return values.

Clears all animations for the player (it also cancels all current tasks such as jetpacking, parachuting, entering vehicles, driving, swimming, etc..).

classmethod command(function=<function _NO_FUNCTION>, /, **kwargs)

create_explosion(x: float, y: float, z: float, type: int, radius: float) → bool

Create an explosion only visible to the player.

Parameters

x (float) – The x coordinate to create the explosion at.
y (float) – The y coordinate to create the explosion at.
z (float) – The z coordinate to create the explosion at.
type (int) – Thich type of explosion.
radius (float) – The radious for the explosion.

Returns

No value returned.

Explosion list: https://www.open.mp/docs/scripting/resources/explosionlist

delete_pvar(var_name: str) → bool

Deletes a player variable.

Parameters: var_name – The variable name to delete.
Returns: This method does not return anything.

disable_checkpoint() → bool

Remove the active checkpoint for a player.

Returns: No value is returned by this method.

disable_race_checkpoint() → bool

Removes the active race checkpoint for the player.

Returns: This method does not return anything.

disable_remote_vehicle_collisions(disable: bool) → bool

Disables collisions between occupied vehicles for a player.

Parameters: disable – Bool that disables colissions if set to True.
Returns: No return value for this method.

distance_from_point(x: float, y: float, z: float) → float: Calculate the distance between the player and a map coordinate.

edit_attached_object(index: int) → bool

Enter edit mode for an attached object.

Parameters: index – The slot of the attached object to edit.
Returns: This method does not return anything.

Available slots indexes are 0 through 9.

Clicking save will call on_player_edit_attached_object.

Note

You can move the camera while editing by pressing and holding the spacebar (or W in vehicle) and moving your mouse

Warning

Players will be able to scale objects up to a very large or negative value size. Limits should be put in place using on_player_edit_attached_object to abort the edit.

enable_camera_target(enable: bool) → bool

Toggle camera targeting functions for a player. Disabled by default to save bandwidth.

Parameters: enable (bool) – False to disable, True to enable.
Returns: This method does not return anything.

enable_stunt_bonus(enable: bool) → bool

Toggle stunt bonus when doing jumps and flips for the given player.

Parameters: enable (bool) – Boolean to toggle it on or off. True = enabled.
Returns: This method does not return anything.

force_class_selection() → bool: Forces a player to go back to class selection on next spawn.

Note

You can quickly get the player into class selection by toggling spectating on and then off. Will not perform a state change to PLAYER_STATE_WASTED if the spectate toggle method is used.

game_text(text: str, time: int, style: int) → bool

Send a big text to the player visible on their screen.

Parameters

text (str) – The text to show.
time (int) – The time it should be shown in ms.
style (int) – The style of the text. (0, 1 or 5).

Returns

No value returned.

Warning

Do note that the players may crash because of odd number of tilde (~) symbols used in the game text. Using color codes (e.g. ~r~) beyond the 255th character may crash the client.

Also, a blank space at end of the string may result in faliure. For example: “Headshot ” results in failure. Instead it should be “Headshot” or “Headshot_”.

get_ammo() → int: Get the amount of ammo in the player’s current weapon.

get_armour() → float

Get the player’s armour.

Value is a float between 0.0 and 100.0.

get_camera_aspect_ratio() → float

Get the player’s aspect ratio on the camera.

Returns: 4/3, 5/4 or 16/9. For example, 4/3 = 1.3333333333333.

Note

The return value of this function represents the value of the “widescreen” option in the game’s display settings, not the actual aspect ratio of the player’s display.

get_camera_front_vector() → Tuple[float, float, float]

This function will return the current direction of player’s aiming in 3-D space, the coords are relative to the camera position, see Player.get_camera_pos().

Returns: This function returns a tuple with 3 floats, that represents the forward facing vector in x, y and z direction.

get_camera_mode() → int

Returns the current GTA camera mode for the requested player.

Returns: A number that represents the camera mode the player currently is in.

The camera modes are useful in determining whether a player is aiming, doing a passenger driveby etc.

Please look at the below table for an overview of the available camera modes.

Value	Constant	Description
3	MODE_BEHINDCAR	Train/tram camera
4	MODE_FOLLOWPED	Follow ped (normal behind player camera), several variable distances
7	MODE_SNIPER	Sniper aiming (sniper scope)
8	MODE_ROCKETLAUNCHER	Rocket Launcher aiming (rocket launcher scope)
15	MODE_FIXED	Fixed camera (non-moving) - used for garages, chase camera, entering buildings, buying food etc
16	MODE_1STPERSON	Vehicle front camera, bike side camera
18	MODE_CAM_ON_A_STRING	Normal car (+ skimmer + helicopter + airplane), several variable distances
22	MODE_BEHINDBOAT	Normal boat camera
46	MODE_CAMERA	Weapon aiming (weapon scope)
51	MODE_ROCKETLAUNCHER_HS	Heat-seeking Rocket Launcher aiming
53	MODE_AIMWEAPON	Aiming any other weapon
55	MODE_AIMWEAPON_FROMCAR	Vehicle passenger aiming camera (drive by as a player)
56	MODE_DW_HELI_CHASE	Chase camera: helicopter/bird view
57	MODE_DW_CAM_MAN	Chase camera: ground camera, zooms in quite quickly and pan to the vehicle
58	MODE_DW_BIRDY	Chase camera: horizontal flyby past vehicle
59	MODE_DW_PLANE_SPOTTER	Chase camera (for air vehicles only): ground camera, looking up to the air vehicle
62	MODE_DW_PLANECAM1	Chase camera (for air vehicles only): vertical flyby past air vehicle
63	MODE_DW_PLANECAM2	Chase camera (for air vehicles only): horizontal flyby past air vehicle (similar to 58 and 62)
64	MODE_DW_PLANECAM3	Chase camera (for air vehicles only): camera focused on pilot, similar to pressing LOOK_BEHIND key on foot, but in air vehicle

get_camera_position() → Tuple[float, float, float]

Get the current camera position for the player.

Returns: A tuple with 3 floats, representing x, y and z position.

Note

Player’s camera positions are only updated once a second, unless aiming.

get_camera_target_object() → Optional[Object]

Allows you to retrieve the map object the player is looking at.

Returns: The Object the player is looking at. If None is returned, player isn’t looking at any object.

Note

This function is disabled by default to save bandwidth. Use Player.enable_camera_target() to enable it for each player.

get_camera_target_player() → Optional[Player]

Get the player the current player is looking at.

Returns: A Player instance representing the player. If no player is being targeted by the camera, it will return None.

Note

This function is disabled by default to save bandwidth. Use Player.enable_camera_target() to enable it for each player.

get_camera_target_vehicle() → Optional[Vehicle]

Allows you to retrieve the ID of the vehicle the player is looking at.

Returns: The Vehicle the player is looking at. If None is returned, player isn’t looking at any vehicle.

Note

This function is disabled by default to save bandwidth. Use Player.enable_camera_target() to enable it for each player.

Note

While a player may look at multiple vehicles, this method only returns one ID at a time. By experience, this usually returns the closest vehicle in sight.

get_camera_zoom() → float

Retrieves the game camera zoom level for a given player.

Returns: The zoom level as a float. Useful to check zoom level when using a sniper, etc.

Note

This retrieves the zoom level of the GAME Camera (including Sniper scope), not the camera weapon.

get_color() → int: Get the player’s color.

Note

If you try to read the value before it is set, it will return 0 (Black).

get_drunk_level() → int

Get the player’s drunk level.

0 to 2000 - No visible effect
2001 to 5000 - Visible camera swaying and control issues in vehicles. HUD is visible.
5001 and above - Swaying continues, but HUD becomes invisible.

Note

Drunk level will decrease with player fps. If you have 50 fps, the drunk level will decrease with 50 levels per second. This makes this method very useful to determine user FPS from server side.

More information: https://open.mp/docs/scripting/functions/SetPlayerDrunkLevel

get_facing_angle() → float: Get the player’s facing angle.

get_fighting_style() → int: Get the player’s special fighting style.

get_health() → float: Get the player’s health.

get_id() → int: Get the player’s player id.

get_interior() → int

Get the player’s interior. Normal world is in interior 0.

Returns: A positive integer between 0-65535.

A list of currently known interiors and their positions can be found here: https://open.mp/docs/scripting/resources/interiorids

get_ip() → str: Get the player’s IP Address.

get_keys() → Tuple[int, int, int]

Check which keys a player is pressing.

Returns

A tuple with 3 integers in the following order:

keys: A set of bits containing the player’s key states represented as a bitmask.
up_down: Up/Down state
left_right: left/right state

See all keys here: https://sampwiki.blast.hk/wiki/Keys

Note

Only the FUNCTION of keys can be detected; not the actual keys. For example, it is not possible to detect if a player presses SPACE, but you can detect if they press SPRINT (which can be mapped (assigned/binded) to ANY key (but is space by default)).

Note

As of update 0.3.7, the keys “A” and “D” are not recognized when in a vehicle. However, keys “W” and “S” can be detected with the “keys” return value.

get_last_shot_vectors() → Tuple[float, float, float, float, float, float]

Find out from where a bullet was shot, and where it hit/collided.

The values are returned as a tuple, listed in the following table:

Note

This function will only work when lag compensation is enabled. If the player hit nothing, the hit positions will be 0. This means you can’t currently calculate how far a bullet travels through open air.

The values in the tuple are in the following order:

From X: X coordinate of where the bullet originated from.
From Y: Y coordinate of where the bullet originated from.
From Z: Z coordinate of where the bullet originated from.
Hit X: X coordinate of where the bullet hit.
Hit Y: Y coordinate of where the bullet hit.
Hit Z: Z coordinate of where the bullet hit.

Here is an example of how you can use it:

if "/lastshot" in cmdtext[0:9]:
    # Get the coordinates
    (
        x,
        y,
        z,
        to_x,
        to_y,
        to_y
    ) = player.get_last_shot_vectors()

    # Send them to the player
    player.send_client_message(
        -1,
        "Last shot info: {}, {}, {}. Hit pos: {}, {}, {}".format(
            str(x),
            str(y),
            str(z),
            str(to_x),
            str(to_y),
            str(to_y)
        )
    )

get_money() → int: Get the player’s money.

get_name() → str: Get the player’s name.

get_ping() → int: Get the player latency to server, represented in milliseconds.

get_pos() → Tuple[float, float, float]: Get the position of the player.

get_pvar_float(var_name: str) → float

Get a player variable containing a float.

Parameters: var_name – The variable name you want to get the value for. Case-insensitive, and is set with player.set_pvar_float().
Returns: The value the variable holds. Is 0.0 if not set.

Player variables are reset when the player disconnects.

get_pvar_int(var_name: str) → int

Get a player variable containing an integer.

Parameters: var_name – The variable name you want to get the value for. Case-insensitive, and is set with set_pvar_int.
Returns: The value the variable holds. Is 0 if not set.

Player variables are reset when the player disconnects.

get_pvar_name_at_index(index: int) → str

Find a player variable name at a certain index.

Parameters: index – Which index should be retrieved.
Returns: The name of the variable, if set.

get_pvar_string(var_name: str) → str

Get a player variable containing a string.

Parameters: var_name – The variable name you want to get the value for. Case-insensitive, and is set with player.set_pvar_string().
Returns: The value the variable holds. Is empty if not set.

Player variables are reset when the player disconnects.

get_pvar_type(var_name: str) → int

Gets the type (integer, float or string) of a player variable.

Parameters: var_name – The name of the variable you want to get the type of.
Returns: An ID that represent either of the types. See table below.

Possible values that can be returned:

Type values
ID	Type
0	PLAYER_VARTYPE_NONE
1	PLAYER_VARTYPE_INT
2	PLAYER_VARTYPE_STRING
3	PLAYER_VARTYPE_FLOAT

PLAYER_VARTYPE_NONE is returned when the variable with the given name does not exist.

get_pvars_upper_index() → int

Each PVar (player-variable) has its own unique identification number for lookup, this function returns the highest ID set for a player.

Returns: An integer representing the highest index at which there was found a player variable set.
Example

pvar_upper_index = player.get_pvars_upper_index() + 1
pvar_count: int = 0

for i in range(pvar_upper_index):
    var_name = player.get_pvar_name_at_index(i)
    # If the var is set (type not 0), increment p_var_count.
    if player.get_pvar_type(var_name) is not 0:
        pvar_count = pvar_count + 1

print(f"You have {pvar_count} player-variables set. \
    Upper index (highest ID):\
    {pvar_upper_index - 1}.")

get_score() → int: Get the player’s score.

get_skin() → int

Get the player’s skin.

Returns: Skin ID, valid values are 0-311.

A skin is the character model.

get_special_action() → int

Get the special action the player is performing.

Returns: An ID representing the special action that is being performed.

Check the list with special actions here: https://www.open.mp/docs/scripting/resources/specialactions

get_state() → int

Get the current player state.

https://open.mp/docs/scripting/resources/playerstates for more info.

get_surfing_object() → Optional[Object]

Get the moving object the player is standing on.

Returns: An instance of Object the player is standing on, or None if there’s no moving object found.

get_surfing_vehicle() → Optional[Vehicle]

Get the moving vehicle the player is standing on.

Note

Can return None if there’s no driver in the car.

Returns: A Vehicle instance the player is surfing on, or None if there’s no vehicle being surfed.

get_target_actor() → int: Get which actor that the player is currently aiming at.

get_target_player() → int: Check who the player is aiming at. Returns the player

get_team() → int

Get the player’s team ID.

0-254 are valid teams
255 is defined as NO_TEAM. The player is not on any team (default)
-1 is returned if something went wrong reading the value.

get_time() → Tuple[int, int]

Get the player’s game time.

Value is represented as a tuple with two values: hour, minute

get_vehicle_id() → int

This method gets the ID of the vehicle the player is currently in.

Returns: Vehicle ID of the vehicle.

Note

NOT the model id of the vehicle. See get_vehicle_model(vehicleid) for that.

get_vehicle_seat() → int

Find out which seat a player is in.

Returns: The seat ID. -1 means they are not in a vehicle. 0-4 is normal

get_velocity() → Tuple[float, float, float]

Get the velocity of the player.

Returns: A tuple with 3 floats, representing the velocity in x, y & z direction.

Example:

x, y, z = player.get_velocity()
print(f"Current velocity: {x}, {y}, {z}")
# prints: 'Current velocity: 0.0, 0.0, 0.0'
# given that the player is not moving.

get_virtual_world() → int

Get the player’s current virtual world.

Returns: The current virtual world.

get_wanted_level() → int: Get the player’s wanted level.

get_weapon_data(slot: int) → Tuple[int, int]

Get weapon data on a given slot.

The weapon slot can be 0-13. The tuple returned contains weapon, ammo.

Example:

weapon, ammo = player.get_weapon_data(3)  # Get data in slot 3
print(f"Weapon ID: {weapon} || Ammo: {ammo}")

get_weapon_state() → int

Check the state of the player’s weapon.

- ID - Constant - Description
- -1 - WEAPONSTATE_UNKNOWN - Unknown (Set when in a vehicle)
- 0 - WEAPONSTATE_NO_BULLETS - The weapon has no remaining ammo
- 1 - WEAPONSTATE_LAST_BULLET - The weapon has one remaining bullet
- 2 - WEAPONSTATE_MORE_BULLETS - The weapon has multiple bullets
- 3 - WEAPONSTATE_RELOADING - he player is reloading their weapon

Example:

if player.weapon_state = WEAPONSTATE_LAST_BULLET:
    player.send_client_message(-1, "You only have 1 bullet left!")

give_money(money: int) → bool

Give money or take money from a player.

The amount of money you want to give can be negative to reduce money.

Example

player.give_money(1000)  # Give player $1000

give_weapon(weapon_id: int, ammo: int) → bool

Give the player a weapon with specified amount of ammo.

Parameters

weapon_id – The weapon ID to give the player.
ammo – The amount of ammo the weapon should have.

Returns

This function does not return anything.

See all weapon ID’s here: https://open.mp/docs/scripting/resources/weaponids

Also, notice how you can use the constants as in pawn too, to define the weapon. For example, WEAPON_KATANA.

player.give_weapon(6, 1)  # Give a shovel
player.give_weapon(WEAPON_COLT45, 500)  # Colt45, 500 bullets

gpci() → str

Get a hash that represents the installation directory of SA-MP for the client.

This is linked to their SAMP/GTA path on their computer.

Warning

This hash is NOT Unique, and can be same across multiple players.

print(player.gpci())

interpolate_camera_look_at(from_x: float, from_y: float, from_z: float, to_x: float, to_y: float, to_z: float, time: int, cut: int = 2) → bool

Make the camera change the “focus” from one coordinate to another.

Parameters

from_x – Initial x coordinate to start looking at.
from_y – Initial y coordinate to start looking at.
from_z – Initial z coordinate to start looking at.
to_x – X coordinate to end looking at.
to_y – Y coordinate to end looking at.
to_z – Z coordinate to end looking at.
time – The time in milliseconds for the transition to last.
cut – The camera style you want to use. Check style for the available styles.

Returns

This method does not return anything.

This method is often used in conjunction with interpolate_camera_position() in order to create smooth camera transitions and cutscenes.

interpolate_camera_position(from_x: float, from_y: float, from_z: float, to_x: float, to_y: float, to_z: float, time: int, cut: int = 2) → bool

Smoothly move the camera position from one coordinate to another, using a given time on the transition.

Parameters

from_x – X coordinate to start from.
from_y – Y coordinate to start from.
from_z – Z coordinate to start from.
to_x – X coordinate to end at.
to_y – Y coordinate to end at.
to_z – Z coordinate to end at.
time – The time in milliseconds for the transition to last.
cut –
The camera style you want to use. Check style for the available styles.

Returns

This method does not return anything.

This method only moves the physical position of the camera. If you want to make it rotate or look at something specific, you need to use this method in conjunction with interpolate_camera_look_at().

A tip to make objects load while the camera is moving, is to put the player into spectate mode. This also removes the hud. Reset the player camera back to normal by using set_camera_behind().

is_admin() → bool

Check if player is logged in to RCON.

Returns: True if they are, otherwise False.

is_attached_object_slot_used(index: int) → bool

Check if a player has an object attached in the specified index (slot).

param int index

The index (slot) to check.

return

Will return True if the slot is used, otherwise False.

# Count amount of attached objects currently on player
count = 0
for slot in range(MAX_PLAYER_ATTACHED_OBJECTS):
    if player.is_attached_object_slot_used(slot):
        count +=1
print(count) # then shows the count in the log

is_connected() → bool

Check if the player is connected.

Returns: True if connected, otherwise False

is_in_any_vehicle() → bool

Check if the player is currently in any vehicle.

Returns: True if they are, otherwise False.

is_in_checkpoint() → bool

Check if the player is currently inside a checkpoint.

Returns: True if they are, False if not.

Note

Race checkpoints are not compatible with this method. Please use is_in_race_checkpoint() to check that.

is_in_race_checkpoint() → bool

Check if the given player is inside a race checkpoint.

Returns: True if they are, otherwise False.

Note

non-race checkpoints are not compatible with this method. Please use is_in_checkpoint() to check that.

is_in_range_of_point(range: float, x: float, y: float, z: float) → bool

Checks if the player is in range of a point.

Parameters

range – The radius of the circle around the point.
x,y,z – The coordinate of the point.

Returns

A boolean that represents if the player is in range or not.

is_in_vehicle(vehicle_id: int) → bool

Check if the player is in a specific vehicle ID.

Parameters: vehicle_id (int) – The vehicle ID to check they are in
Returns: True if they are, otherwise False.

In order to check if they are in any vehicle, use is_in_any_vehicle().

is_npc() → bool

Check if the player is an NPC.

Returns: True if yes, otherwise False.

is_streamed_in(player: Player) → bool: Checks if the player is streamed in on another player’s client.

kick() → bool

Kick the player from the server.

Returns: No value is returned.

classmethod on_click_map(playerid: int, x: float, y: float, z: float)

classmethod on_click_player(playerid: int, clickedplayerid: int, source: int)

classmethod on_click_playertextdraw(playerid: int, playertextid: int)

classmethod on_click_textdraw(playerid: int, clickedid: int)

classmethod on_command_text(playerid: int, command_text: str)

classmethod on_connect(playerid: int)

classmethod on_death(playerid: int, killerid: int, reason: int)

classmethod on_disconnect(playerid: int, reason: int)

classmethod on_edit_attached_object(playerid: int, response: int, index: int, modelid: int, boneid: int, offset_x: float, offset_y: float, offset_z: float, rot_x: float, rot_y: float, rot_z: float, scale_x: float, scale_y: float, scale_z: float)

classmethod on_edit_object(playerid: int, is_playerobject: bool, objectid: int, response: int, x: float, y: float, z: float, rot_x: float, rot_y: float, rot_z: float)

classmethod on_enter_checkpoint(playerid: int)

classmethod on_enter_exit_mod_shop(playerid: int, enterexit: int, interiorid: int)

classmethod on_enter_race_checkpoint(playerid: int)

classmethod on_enter_vehicle(playerid: int, vehicleid: int, is_passenger: bool)

classmethod on_exit_vehicle(playerid: int, vehicleid: int)

classmethod on_exited_menu(playerid: int)

classmethod on_give_damage(playerid: int, damagedid: int, amount: float, weaponid: int, bodypart: int)

classmethod on_give_damage_actor(playerid: int, damaged_actorid: int, amount: float, weaponid: int, bodypart: int)

classmethod on_interior_change(playerid: int, newinteriorid: int, oldinteriorid: int)

classmethod on_key_state_change(playerid: int, newkeys: int, oldkeys: int)

classmethod on_leave_checkpoint(playerid: int)

classmethod on_leave_race_checkpoint(playerid: int)

classmethod on_pick_up_pickup(playerid, pickupid: int)

classmethod on_request_class(playerid: int, classid: int)

classmethod on_request_spawn(playerid: int)

classmethod on_select_object(playerid: int, type: int, objectid: int, modelid: int, x: float, y: float, z: float)

classmethod on_selected_menu_row(playerid: int, row: int)

classmethod on_spawn(playerid: int)

classmethod on_state_change(playerid, newstate: int, oldstate: int)

classmethod on_stream_in(playerid: int, forplayerid: int)

classmethod on_stream_out(playerid: int, forplayerid: int)

classmethod on_take_damage(playerid: int, issuerid: int, amount: float, weaponid: int, bodypart: int)

classmethod on_text(playerid: int, text: str)

classmethod on_update(playerid: int)

classmethod on_weapon_shot(playerid: int, weaponid: int, hittype: int, hitid: int, x: float, y: float, z: float)

play_audio_stream(url: str, position_x: float = 0.0, position_y: float = 0.0, position_z: float = 0.0, distance: float = 50.0, usepos: bool = False) → bool

Play an audio stream for a player.

Normal files can also be streamed, such as MP3.

play_crime_report(suspect: Player, crime: int) → bool

Plays a crime report for the player.

You know when the player gets wanted in single player, the dispatch on the radio reads out actions and positions. You can also do this on SA-MP, by calling this method.

Parameters

suspect – The player you want to play the crime report about.
crime – One of the available crime ID’s in below table.

Crime ID’s
Crime id	10-code that is used	Message from dispatcher
3	10-71	Advise nature of fire (size, type, contents of building)
4	10-47	Emergency road repairs needed
5	10-81	Breatherlizer Report
6	10-24	Assignment Completed
7	10-21	Call () by phone
8	10-21	Call () by phone
9	10-21	Call () by phone
10	10-17	Meet Complainant
11	10-81	Breatherlizer Report
12	10-91	Pick up prisoner/subject
13	10-28	Vehicle registration information
14	10-81	Breathalyzer
15	10-28	Vehicle registration information
16	10-91	Pick up prisoner/subject
17	10-34	Riot
18	10-37	(Investigate) suspicious vehicle
19	10-81	Breathalyzer
21	10-7	Out of service
22	10-7	Out of service

play_sound(soundid: int, x: float, y: float, z: float) → bool

Play a game sound for the player.

Parameters

soundid – The sound id you would like to play for the player.
x – x coordinate to play the sound at.
y – y coordinate.
z – z coordinate.

Note

Set the position to 0.0 if you want to ignore the position, and to play it no matter where the player is at.

A list with available sound id’s can be found here: https://sampwiki.blast.hk/wiki/SoundID

put_in_vehicle(vehicle_id: int, seat_id: int) → bool

Put the player inside a vehicle.

Parameters

vehicle_id – The vehicle you want to put the player in.
seat_id – Which seat. (0->)

Available seats

0 - Driver
1 - Front passenger
2 - Back-left passenger
3 - Back-right passenger
4+ - Passenger seats (coach etc.)

Warning

If this function is used on a player that is already in a vehicle, other players will still see them in their previous vehicle. To fix this, first remove the player from the vehicle.

Warning

If the seat is invalid or is taken, will cause a crash when the player exit the vehicle. For example bikes may only have two seats.

remove_attached_object(index: int) → bool

Remove an attached object from a player.

Parameters: index – The index to remove the object from (0-9)
Returns: Returns True on success, otherwise False.

# Remove all player-attached objects
if "/removeall" in cmdtext[0:9]:
    for slot in range(MAX_PLAYER_ATTACHED_OBJECTS):
        if player.is_attached_object_slot_used(slot):
            player.remove_attached_object(slot)

remove_building(model_id: int, x: float, y: float, z: float, radius: float) → bool

Removes a standard San Andreas model for a single player within a specified range.

Parameters
Parameter	Desccription
model_id	The model to remove.
Float:fX	The X coordinate around which the objects will be removed.
Float:fY	The Y coordinate around which the objects will be removed.
Float:fZ	The Z coordinate around which the objects will be removed.
Float:fRadius	The radius around the specified point to remove objects with the specified model.

Warning

There appears to be a limit of around 1000 lines/objects. There is no workaround.
When removing the same object for a player, they will crash.
Commonly, players crash when re-connecting to the server because the server removes buildings on OnPlayerConnect.

Example usage:

# This will remove ALL map objects for the player:
player.remove_building(-1, 0.0, 0.0, 0.0, 6000.0)

remove_from_vehicle() → bool

Remove a player from the current vehicle.

Returns: This method does not return anything.

Note

The exiting animation is not synced for other players.
The player is not removed if they are in a RC Vehicle.

remove_map_icon(icon_id: int) → bool

This removes a map icon that was set with player.set_map_icon.

Parameters: icon_id – The icon slot to remove the icon from (0-99).
Returns: No return value.

reset_money() → bool: Use this method to reset player money to 0`.

reset_weapons() → bool: Removes all weapons from a player.

send_client_message(color: int, message: str) → bool

Send a chat message only visible to the player.

Parameters

color (int) – The color, in 0xRRGGBBAA format.
message (str) – The message to send to the player.

Note

A client message can only contain 128 characters, including embedded color codes.

send_death_message(killer: Player, killee: Player, weapon: int) → bool

Send a death message only to the current player.

Parameters

killer (Player) – The player who killed.
killee (Player) – The player who was killed.
weapon (int) – The weapon that was used.

Returns

No return value.

send_message_to_player(sender: Player, message: str) → bool

Have the player receive a direct message from the sender.

Parameters

sender (Player) – The player that authored the message.
message (str) – The message the sender wrote.

Returns

No return value.

set_ammo(conf: Tuple[int, int]) → bool

Set ammo for a weapon id.

Parameters: conf (tuple) – A tuple containing the weapon id and ammo. Ammo value should be an int between 0-32766.
Returns: No return value.

set_armed_weapon(weapon_id: int) → bool

Sets which weapon the player is holding.

The player needs to have this weapon for it to work. Calling this method will not give the player a new weapon.

set_armour(armour: float) → bool

set_attached_object(index: int, model_id: int, bone: int, offset_x: float = 0.0, offset_y: float = 0.0, offset_z: float = 0.0, rotation_x: float = 0.0, rotation_y: float = 0.0, rotation_z: float = 0.0, scale_x: float = 1.0, scale_y: float = 1.0, scale_z: float = 1.0, material_color_1: int = 0, material_color_2: int = 0) → bool

Attach an object to a specific bone on a player.

Parameters

index (int) – The index (slot) to assign the object to (0-9).
model_id (int) – The model to attach.
bone (int) – The bone to attach the object to. (0-18)
offset_x (optional, float) – X axis offset for the object position.
offset_y (optional, float) – Y axis offset for the object position.
offset_z (optional, float) – Z axis offset for the object position.
rotation_x (optional, float) – X axis rotation of the object.
rotation_y (optional, float) – Y axis rotation of the object.
rotation_z (optional, float) – Z axis rotation of the object.
scale_x (optional, float) – X axis scale of the object.
scale_y (optional, float) – Y axis scale of the object.
scale_z (optional, float) – Z axis scale of the object.
material_color_1 (optional, int) – The first object color.
material_color_2 (optional, int) – The second object color.

Returns

This method does not return anything.

Note

Colors can be set as an integer or hex in ARGB color format.

Available bones:

ID	Bodypart
1	Spine
2	Head
3	Left upper arm
4	Right upper arm
5	Left hand
6	Right hand
7	Left thigh
8	Right thigh
9	Left foot
10	Right foot
11	Right calf
12	Left calf
13	Left forearm
14	Right forearm
15	Left clavicle (shoulder)
16	Right clavicle (shoulder)
17	Neck
18	Jaw

Example:

# Give player a white hat, and paint it green
player.set_attached_object(
    3,
    19487,
    2,
    0.101,
    -0.0,
    0.0,
    5.50,
    84.60,
    83.7,
    1.0,
    1.0,
    1.0,
    0xFF00FF00
)

set_camera_behind() → bool

Restore the camera to a place behind the player, after using ex. Player.set_camera_pos().

Returns: This method does not return anything.

set_camera_look_at(x: float, y: float, z: float, cut: int = 2) → bool

Make the camera look towards a set corrdinate.

Parameters

x (float) – The x coordinate to look at.
y (float) – The y coordinate to look at.
z (float) – The z coordinate to look at.
cut (optional int) –
The style of the change. Can be used to interpolate (change slowly) from old pos to new pos using CAMERA_MOVE.

set_camera_position(pos: Tuple[float, float, float]) → bool

Set the camera position to a given coordinate.

Parameters: pos – A tuple with 3 values, representing the x, y and z coordinate.
Returns: This method does not return anything.

set_chat_bubble(text: str, color: int, draw_distance: float, expiretime: int) → bool

Make text appear above the nametag of a player, that other players can see.

Parameters

text – The text you would like to show.
color – Which color you would like to give the font.
draw_distance – How far you want the text to be visible from.
expiretime – How long in miliseconds the bubble should stay.

Returns

This method does not return anything.

Note

You can not see your own chat bubbles, same applies for 3D textlabels.

set_checkpoint(x: float, y: float, z: float, size: float) → bool

Create a checkpoint for the player. Shows a red blip on the radar.

Parameters

x – The x position for the checkpoint.
y – The y position for the checkpoint.
z – The z position for the checkpoint.
size – The size of the checkpoint.

Note

Checkpoints are asynchronous, meaning only one can be shown at a time.

Checkpoints don’t need to be disabled before setting another one.

set_color(color: int) → bool

Set a player’s color to a given color value.

You can use Hexadecimal numbers to make it easier. The value is expected in the following format 0xRRGGBBAA, where:

RR is red

GG is green

BB is blue

AA is the opacity.

set_drunk_level(level: int) → bool

Set the player’s drunk level.

Parameters

level –

0 to 2000: No visible effect
2001 to 5000: Visible camera swaying and control issues in vehicles. HUD is visible.
5001 and above: Swaying continues, but HUD becomes invisible.

Returns

Does not return anything.

set_facing_angle(angle: float) → bool

Set the player’s facing angle.

Parameters: angle – A float, 0.0 < 360.0
Returns: This method does not return anything.

Directly north is heading 0.0.

set_fighting_style(style: int) → bool

Set the player’s fighting style.

Parameters: style – A fight style ID, shown in below table.
Returns: This method does not return anything.

To use in-game, aim and press the ‘secondary attack’ key (ENTER by default).

Available fight styles
ID	Constant
4	FIGHT_STYLE_NORMAL
5	FIGHT_STYLE_BOXING
6	FIGHT_STYLE_KUNGFU
7	FIGHT_STYLE_KNEEHEAD
15	FIGHT_STYLE_GRABKICK
16	FIGHT_STYLE_ELBOW

set_health(health: float) → bool

set_interior(interior_id: int) → bool: Set the interior the player to be in. Syncs for all players even when the player is desynced

set_map_icon(icon_id: int, x: float, y: float, z: float, marker_type: int, color: int, style: int = 0) → bool

Place an icon/marker on a player’s map. Can be used to mark locations.

Parameters

icon_id – The icon slot you want to use. Maximum 100 icons can be shown (0-99).
x – The world x-coordinate.
y – The world y-coordinate.
z – The world z-coordinate.
marker_type – Which type of icon or marker you want to show. More here: https://www.open.mp/docs/scripting/resources/mapicons
color – The color you want to give the marker, in RGBA format.
style – The icon style: https://www.open.mp/docs/scripting/resources/mapiconstyles

Returns

This method does not return anything.

Note

If you use an invalid marker type, it will create ID 1 (White Square). If you use an icon ID that is already in use, it will replace the current map icon using that ID.

Warning

You can only have 100 icons. Marker type 1, 2, 4 and 56 can make the client crash.

set_marker(showplayer: Player, color: int) → bool

Change the colour of the player’s nametag and radar blip for another player on the server.

Parameters

showplayer – The player that should see the change.
color – The desired color in RGBA format.

Returns

Returns nothing.

# "target" is a player object.
player.set_marker(target, 0xAA3333FF)
# Now, "target" will see the "player" with the given
# color on their map.

set_money(money: int) → bool

Set the money a player should have.

Parameters: money – Set the new amount of money the player should have.
Returns: This method does not return anything.

Note

If the player has negative amount of cash, numbers will be shown as red on the HUD.

Note

Behind the scenes, setting money will first do reset_money and then give_money.

set_name(name: str) → int

Set a new name for the player.

Parameters: name – The name to set. Must be 2-24 characters long and only contain valid characters (0-9, a-z, A-Z, [], (), $ @ . _ and =).
Returns: This method does not return anything.

Warning

Player names can be up to 24 characters when using this function, but when joining the server from the SA-MP server browser, players’ names must be no more than 20 and less than 3 characters (the server will deny entry). This allows for 4 characters extra when using SetPlayerName. Beware that an empty name will cause the server to crash.

set_pos(pos: Tuple[float, float, float]) → bool: Set the player’s position

set_pos_find_z(position: Tuple[float, float, float]) → bool

This sets the players position then adjusts the players z-coordinate to the nearest solid ground under the position.

This function does not work if the new coordinates are far away from where the player currently is. The Z height will then be 0, which will likely put them underground.

set_pvar_float(var_name: str, value: float) → bool

Set a player variable containing a float.

Parameters

var_name – Case insensitive name of the player variable.
value – The string you want to set for it.

Returns

Will return False if the var_name is empty or too long, otherwise it returns True.

You can read this value across all scripts using player.get_pvar_float().

set_pvar_int(var_name: str, value: int) → bool

Set a player variable containing an integer.

Parameters

var_name – Case insensitive name of the player variable.
value – The value you want to set for it.

Returns

Will return False if the var_name is empty or too long, otherwise it returns True.

You can read this value across all scripts using player.get_pvar_int().

set_pvar_string(var_name: str, value: str) → bool

Set a player variable containing a string.

Parameters

var_name – Case insensitive name of the player variable.
value – The string you want to set for it.

Returns

Will return False if the var_name is empty or too long, otherwise it returns True.

You can read this value across all scripts using player.get_pvar_string().

set_race_checkpoint(type: int, x: float, y: float, z: float, next_x: float, next_y: float, next_z: float, size: float) → bool

Race checkpoints are red checkpoints, as used in singleplayer races.

Parameters

type – Can be values 0-8, see table further down for reference.
x – World X coordinate to place the race checkpoint.
y – World Y coordinate to place the race checkpoint.
z – World Z coordinate to place the race checkpoint.
next_x – The X coordinate of the next race checkpoint.
next_y – The Y coordinate of the next race checkpoint.
next_z – The Z coordinate of the next race checkpoint.
size – The radius of the checkpoint. Also acts as the trigger area.

Returns

No value returned.

The available types
ID	Constant name	Description
0	RACE_NORMAL	Normal checkpoint with arrow to the next coordinates.
1	RACE_FINISH	Checkpoint with finish flag on it.
2	RACE_NOTHING	An empty checkpoint with nothing on it.
3	RACE_AIR_NORMAL	A normal air race checkpoint (Circle).
4	RACE_AIR_FINISH	Air checkpoint with finish flag on it.
5	RACE_AIR_ONE	Air race checkpoint that rotates and stops.
6	RACE_AIR_TWO	Air race checkpoint that increases, decreases and disappears.
7	RACE_AIR_THREE	Air race checkpoint, this type swings up and down.
8	RACE_AIR_FOUR	Air race checkpoint, swings up and down.

Note

If you use RACE_FINISH and at the same time use coordinates for the next checkpoint, it will automatically show RACE_NORMAL instead.

Warning

Race checkpoints are asynchronous, that means only one can be shown at a time.

You do not need to disable a checkpoint in order to show a new one.

set_score(score: int) → bool: Set the player’s score to a given value.

set_shop_name(shop_name: str) → bool

Loads or unloads an interior script for a player.

This can for example be the ammunation menu, that belongs to the ammunition interior.

Learn more here: https://sampwiki.blast.hk/wiki/ShopNames

set_skill_level(weapon_skill: int, level: int) → bool

Set the skill level of a certain weapon type for a player.

Parameters

weapon_skill – The weaponskill type (see below table).
level – The level, range 0-999 where 999 is the maximum skill.

Returns

This method does not return anything.

Weapon skills
ID	Constant
0	WEAPONSKILL_PISTOL
1	WEAPONSKILL_PISTOL_SILENCED
2	WEAPONSKILL_DESERT_EAGLE
3	WEAPONSKILL_SHOTGUN
4	WEAPONSKILL_SAWNOFF_SHOTGUN
5	WEAPONSKILL_SPAS12_SHOTGUN
6	WEAPONSKILL_MICRO_UZI
7	WEAPONSKILL_MP5
8	WEAPONSKILL_AK47
9	WEAPONSKILL_M4
10	WEAPONSKILL_SNIPERRIFLE

set_skin(skinid: int) → bool

Change the skin/character of the player.

Parameters: skinid – ID can be between 0 and 311, except for skin ID 74.
Returns: Nothing is returned by this method.

See available skins and the corresponding ID’s here: https://open.mp/docs/scripting/resources/skins

Warning

Known Issues: If a player’s skin is set when they are crouching, in a vehicle, or performing certain animations, they will become frozen or otherwise glitched. This can (in most cases) be fixed by using player.toggle_controllable(True).

Players can be detected as being crouched through player.get_special_action() == SPECIAL_ACTION_DUCK

Warning

Other players around the player may crash if they are in a vehicle or if they are interacting a vehicle when the skin is changed. Setting a player’s skin when the player is dead may crash players around them. Breaks the sitting animation on bikes.

Example:

player.set_skin(45)

set_spawn_info(team: int, skin: int, x: float, y: float, z: float, rotation: float, weapon1: int, weapon1_ammo: int, weapon2: int, weapon2_ammo: int, weapon3: int, weapon3_ammo: int) → bool

This method can be used to change the spawn information of a specific player.

It allows you to automatically set someone’s weapons to spawn with, their team, skin and spawn position, normally used for things like minigames or automatic-spawn systems. This information is used after a player dies, to know where / how to spawn them.

set_special_action(action_id: int) → bool

Set a special action on a player.

Parameters: action_id – The special action the player should perform.
Returns: No return value for this method.

Check the list of special actions here: https://www.open.mp/docs/scripting/resources/specialactions

set_team(teamid: int) → bool

Set the team the player should belong to.

0-254 are valid teams. 255 is defined as NO_TEAM. That means you need to set team to 255 to remove from a team.

set_time(time: Tuple[int, int]) → bool

Set the time for the player.

Parameters: time (tuple) – (Hour, Minute) is how the tuple looks like.

set_velocity(pos: Tuple[float, float, float]) → bool: Set the velocity of a player in X,Y,Z direction.

set_virtual_world(world_id: int) → bool

Set the player to be part of a different virtual world.

Parameters: world_id (int) – The world ID (0-65535).
Returns: This method does not return anything.

set_wanted_level(level: int) → bool: Set the player’s wanted level.

set_weather(weather: int) → bool

Set the player’s weather.

param weather

The weather ID to set between 0 and 20.

return

This method does not return anything.

If player.toggle_clock is on, then the weather will change slowly too.

Available weather IDs
ID	Constant name	Comments
0	EXTRASUNNY_LA
1	SUNNY_LA
2	EXTRASUNNY_SMOG_LA
3	SUNNY_SMOG_LA
4	CLOUDY_LA
5	SUNNY_SF
6	EXTRASUNNY_SF
7	CLOUDY_SF
8	RAINY_SF
9	FOGGY_SF
10	SUNNY_VEGAS
11	EXTRASUNNY_VEGAS	Has heat wave effect
12	CLOUDY_VEGAS
13	EXTRASUNNY_COUNTRYSIDE
14	SUNNY_COUNTRYSIDE
15	CLOUDY_COUNTRYSIDE
16	RAINY_COUNTRYSIDE
17	EXTRASUNNY_DESERT
18	SUNNY_DESERT
19	SANDSTORM_DESERT
20	UNDERWATER	greenish, foggy effect

More information and details: https://dev.prineside.com/en/gtasa_weather_id/

To set weather for everyone, use set_weather(weatherid) which is a global function.

set_world_bounds(x_max: float, x_min: float, y_max: float, y_min: float) → bool

Set the world boundaries for a player. Players can not go out of the boundaries, they will be pushed back in.

Parameters

x_max – The max x coordinate of the bounds.
x_min – The min x coordinate of the bounds.
y_max – The max y coordinate of the bounds.
y_min – The min y coordinate of the bounds.

Returns

This method does not return anything.

Illustration

     MinY
       v
MinX > *-------------
       |            |
       |   Bound    |
       |   center   |
       |            |
       -------------* < MaxX
                   ^
                  MaxY

show_name_tag(showplayer: Player, show: bool) → bool

This method allows you to toggle the drawing of player nametags, healthbars and armor bars which display above their head.

Parameters

showplayer – Player whose name tag will be shown or hidden.
show – False to hide, True to show.

Returns

Returns nothing.

For use of a similar function like this on a global level, check out show_name_tags() function.

spawn() → bool: (Re)Spawns a player.

Note

Kills the player if they are in a vehicle and then they spawn with a bottle in their hand.

spectate_player(target_player: Player, mode: int = 1) → bool

Spectate a specific player.

Parameters

target_player (Player) – The player to spectate.
mode (optional) – The spectate mode to use. Default: SPECTATE_MODE_NORMAL

Returns

No return value.

Spectate modes:

SPECTATE_MODE_NORMAL: Normal spectate mode (third person point of view). Camera can not be changed. This is the default mode.

SPECTATE_MODE_FIXED: Use set_camera_position() after this to position the player’s camera, and it will track the player.

SPECTATE_MODE_SIDE: The camera will be attached to the side of the player (like when you’re in first-person camera on a bike and you do a wheelie)

spectate_vehicle(target_vehicle: Vehicle, mode: int = 1) → bool

Spectate a specific vehicle.

Parameters

target_vehicle (Vehicle) – The vehicle to spectate.
mode (optional int) – The spectate mode to use. Default: SPECTATE_MODE_NORMAL.

Avaialable spectate modes:

SPECTATE_MODE_NORMAL: Normal spectate mode (third person point of view). Camera can not be changed. This is the default mode.

SPECTATE_MODE_FIXED: Use set_camera_position() after this to position the player’s camera, and it will track the vehicle.

SPECTATE_MODE_SIDE: The camera will be attached to the side of the vehicle (like when you’re in first-person camera on a bike and you do a wheelie)

start_recording_data(recordtype: int, recordname: str) → bool: Used to record NPC data.

stop_audio_stream() → bool: Stops the player’s audio stream.

stop_recording_data() → bool: Stop recording NPC data, started with start_recording_data().

toggle_clock(toggle: bool) → bool

Toggle the in-game clock (top-right corner) for a specific player.

Parameters: toggle (bool) – True to toggle clock on, else use False.
Returns: No return value.

When this is enabled, time will progress at 1 minute per second. Weather will also interpolate (slowly change over time) when set using set_weather()

toggle_controllable(toggle: bool) → bool

Freeze or unfreeze a player.

Parameters: toggle – Set to False to freeze, True to unfreeze.
Returns: This method does not return antyhing.

Warning

The player will also be unable to move their camera.

toggle_spectating(toggle: bool) → bool

Toggle the player in and out of spectate mode. When in spectate mode, the HUD is removed.

Parameters: toggle (bool) – Toggle spectate on with True or off with False.
Returns: No return value.

While in spectator mode a the player can spectate (watch) other players and vehicles. After using this method, either spectate_player() or spectate_vehicle() needs to be used.

Note

When spectator mode is disabled, OnPlayerSpawn will automatically be called, if you wish to restore player to state before spectating, you will have to handle that in OnPlayerSpawn. Note also, that player can also go to class selection before if they used F4 during spectate, a player also CAN die in spectate mode due to various glitches.

Warning

If the player is not loaded in before setting the spectate status to False, the connection can be closed unexpectedly.

weapon() → int

Get the weapon id of the currently held weapon.

Returns: The weapon ID of the weapon they are holding.

Note

When the player state is PLAYER_STATE_DRIVER or PLAYER_STATE_PASSENGER, this function returns the weapon held by the player before they entered the vehicle.