sourcemod.clients — Client manipulation.

The sourcemod.clients module contains functions and objects having to do with clients. There may be different functions available in this module than SourceMod’s clients.inc, because they fit in better here.

Constants

These flags will be used in the clients.Client.ban() function, which is yet to be implemented.

Flag	Description
BANFLAG_AUTO	Auto-detects whether to ban by steamid or IP
BANFLAG_IP	Always ban by IP
BANFLAG_AUTHID	Always ban by authstring (Steam ID) if possible
BANFLAG_NOKICK	Does not kick the client

Use COMMAND_FILTER flags with process_target_string to filter the players that will be chosen.

Flag	Description
COMMAND_FILTER_ALIVE	Only allow alive players
COMMAND_FILTER_DEAD	Only filter dead players
COMMAND_FILTER_CONNECTED	Allow players not fully in-game
COMMAND_FILTER_NO_IMMUNITY	Ignore immunity rules
COMMAND_FILTER_NO_MULTI	Do not allow multiple target patterns
COMMAND_FILTER_NO_BOTS	Do not allow bots to be targetted

The tuple process_target_string returns contains a reason field, which will be one of the constants below. These describe the reason why process_target_string failed or succeeded. For implementation purposes, reason values larger than 0 succeeded, a value of 0 means no player was matched, and anything below 0 means players were found, but they didn’t meet the COMMAND_FILTER flags passed.

Flag	Description
COMMAND_TARGET_VALID	Client passed the filter. The value of this flag is 1.
COMMAND_TARGET_NONE	No target was found. The value of this flag is 0. The rest of the flags’ values continue to decline by 1.
COMMAND_TARGET_NOT_ALIVE	Single client is not alive
COMMAND_TARGET_NOT_DEAD	Single client is not dead
COMMAND_TARGET_NOT_IN_GAME	Single client is not in game
COMMAND_TARGET_IMMUNE	Single client is immune
COMMAND_TARGET_EMPTY_FILTER	A multi-filter (such as @all) had no targets
COMMAND_TARGET_NOT_HUMAN	Target was not human
COMMAND_TARGET_AMBIGUOUS	Partial name had too many targets

Functions

create_fake_client(name)

Creates a fake client.

Parameters:

• name (str) – The name to assign to the fake client

Return type:

clients.Client

Returns:

A valid clients.Client object on success, None otherwise.

get_client(index)

Retrieves the clients.Client object with that client index.

Parameters:

• index (int) – The client index

Return type:

clients.Client

Returns:

A valid clients.Client object on success, None if an invalid client index.

get_client_count([in_game_only=True])

Returns the number of clients put in the server.

Parameters:

• in_game_only (bool) – If False, players currently connecting are also counted.

Return type:

int

get_client_from_serial(serial)

Retrieves a clients.Client object by their serial number.

Parameters:

• serial (int) – The Client‘s serial number

Return type:

clients.Client

Returns:

A valid clients.Client object on success, None if an invalid client serial.

get_client_from_userid(userid)

Translates a userid index into a clients.Client object

Parameters:

• userid (int) – Userid value

Return type:

clients.Client

Returns:

A valid clients.Client object on success, None if an invalid userid.

get_max_clients()

Returns the maximum number of clients allowed on the server. This may return 0 if called before the global forward on_map_start.

process_target_string(pattern, admin[, flags=0])

Processes a generic target string and resolves it to a list of clients, or one client, based on filtering rules.

This function returns a tuple containing all the useful data: (targets, target_name, target_name_is_multilingual, reason)

• targets is a list of all the clients matched. This will always be a list, even when only one client is matched.
• target_name is a string containing a description of the targets matched. For instance, if one client is matched, target_name will be that client’s name; if all the bots that are alive are matched, target_name will be “all alive bots”.
• target_name_is_multilingual is a boolean that is True if target_name is multilingual. That is, if it’s a translated phrase. For single client matches, where target_name is the client matched, this will be False.
• reason is an int containing a COMMAND_TARGET constant, describing the reason why no players were matched.

Returning a tuple allows easier handling of the data:

targets,target_name,tn_is_ml,reason = process_target_string("@all", 2, COMMAND_FILTER_ALIVE|COMMAND_FILTER_CONNECTED)

Parameters:

• pattern (str) – Target pattern to process.
• admin (clients.Client or int) – The clients.Client object or client index of the client to process the target string from.
• flags (int) – COMMAND_FILTER flags to filter the search.

class Client

Client Objects

Client objects cannot be instantiated by themselves. Instead, use get_client(index) to retrieve a client object.

ban(time, flags, reason[, kickmsg="Kicked", cmd=None, source=0])

Bans the client. time is the time, in minutes, to ban the client (0 = permanent).

flags is a bitstring of BANFLAG flags that will control the banning mechanism. If BANFLAG_AUTHID is set and no auth ID is available, the ban will fail, unless BANFLAG_AUTO is also set.

reason is a string containing the reason for banning the client. kickmsg is the message to display to the player when they’re kicked.

cmd is a string containing the command used to initiate the ban in order to identify the source. If this is left empty, then the ban_client forward will not be called. source is a value that could be interpreted as the identity of the player whom was the source of the banning (not actually checked by Core).

This returns True if the player was successfully banned, and False otherwise (the only case False is returned is mentioned above in the explanation of flags).

fake_command(cmd)

Executes a client command on the server without being networked.

Parameters:

• cmd (str) – The command string to execute.

is_connected()

Returns whether the client is connected.

is_timing_out()

Returns whether the client is timing out.

kick([msg=""[, delay=True]])

Disconnects a player from the server.

Parameters:

• msg (str) – A message to show the user as a disconnect reason. Note that a period is automatically appended to the message by the engine.
• delay (bool) – If True, the client is kicked in the next game frame. If False, the client is kicked immediately. The delay exists to prevent accidental engine crashes.

Return type:

bool

Returns:

True on successful kick, False if the player is already in the kick queue.

notify_post_admin_check()

Signals that a player has completed post-connection admin checks. Has no effect if the player has already had this event signalled. Note: This must be sent even if no admin id was assigned.

print_center(message)

Prints a message to this client in the center of the screen.

Parameters:

• message (str) – The message to print.

print_chat(message)

Prints a message to this client’s chat area.

Parameters:

• message (str) – The message to print.

print_console(message)

Prints a message to this client’s console.

Parameters:

• message (str) – The message to print.

print_hint(message)

Prints a message to this client inside a hint box.

Parameters:

• message (str) – The message to print.

set_fake_client_convar(convar, value)

Sets a convar value on a fake client.

Parameters:

• convar (str) – The ConVar’s name
• value (str) – The value to set the ConVar to.

show_vgui_panel(name[, kv=None[, show=True]])

Show a VGUI panel to the client.

Parameters:

• name (str) – Panel type name (see viewport_panel_names.h for a list of panel names)
• kv (KeyValues) – A KeyValues with all the data for the panel setup. The data inside the KeyValues depends on the panel type.
• show (bool) – True to show the panel, or False to remove it from the client’s screen.

Attributes

index

A number containing the index of the client. This is what SourcePawn uses for handling clients.

abs_angles

The client’s angles vector.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

abs_origin

The client’s origin vector.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

alive

Whether the client is alive or dead.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

avg_choke

The client’s average packet choke. Value is a percentage ranging from 0.0 to 1.0

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_choke_in

The client’s average incoming packet choke. Value is a percentage ranging from 0.0 to 1.0.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_choke_out

The client’s average outgoing packet choke. Value is a percentage ranging from 0.0 to 1.0.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_data

The client’s data flow, incoming and outgoing, in bytes per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

avg_data_in

The client’s incoming data flow in bytes per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

avg_data_out

The client’s outgoing data flow in bytes per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

avg_latency

The client’s average packet latency, both incoming and outgoing, in seconds.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_latency_in

The client’s average incoming packet latency in seconds.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_latency_out

The client’s average outgoing packet latency in seconds.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_loss

The client’s average packet loss. Value is a percentage ranging from 0.0 to 1.0.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_loss_in

The client’s average incoming packet loss. Value is a percentage ranging from 0.0 to 1.0.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_loss_out

The client’s average outgoing packet loss. Value is a percentage ranging from 0.0 to 1.0.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_packets

The client’s average packet frequency, incoming and outgoing, in packets per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_packets_in

The client’s average incoming packet frequency, in packets per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

avg_packets_out

The client’s average outgoing packet frequency, in packets per second.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

data_rate

The client’s send date rate in bytes per second

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

deaths

The player’s death count.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

entity

The Entity of the Client.

fake

Whether the client is fake or not.

Raises sourcemod.ViperError:  Invalid client or client not connected.

frags

The player’s frag count.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

health

The health of the player.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

ip

The IP address of this client.

Raises sourcemod.ViperError:  Invalid client or client not connected.

lang_id

The client’s language ID as an int.

Raises sourcemod.ViperError:  Invalid client or client not connected.

latency

The client’s packet latency (RTT), both incoming and outgoing, in seconds. This is more accurate than the average latency, but jittery.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

latency_in

The client’s incoming packet latency (RTT) in seconds. This is more accurate than the average latency, but jittery.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

latency_out

The client’s outgoing packet latency (RTT) in seconds. This is more accurate than the average latency, but jittery.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

maxs

The client’s max size vector.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

mins

The client’s min size vector.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

model

The client’s model name.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.

name

The name of this client.

Raises sourcemod.ViperError:  Invalid client or client not connected.

serial

The client’s unique serial identifier.

steamid

The Steam ID of this client. This is None when the client is not authorized, yet.

Raises sourcemod.ViperError:  Invalid client or client not connected.

team

The player’s team.

Raises sourcemod.ViperError:  Invalid client, client not in-game, no mod support, or client not in-game.

time_connected

The amount of time the client has been connected in seconds.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or client is a fake client.

userid

The userid of this client.

Raises sourcemod.ViperError:  Invalid client or client not connected.

weapon

The player’s weapon name.

Raises sourcemod.ViperError:  Invalid client, client not in-game, or no mod support.