SourceMod 1.5.0 API Changes

This page is unfinished, still in progress

These are just the API changes from SourceMod 1.4.7 to SourceMod 1.5.0. Click here for the full SourceMod 1.5.0 Release Notes.

Additions

BaseComm

The BaseComm base plugin now has a new set of global forwards to notify other plugins of its actions.

/**
 * Called when a client is muted or unmuted
 * 
 * @param	client		Client index
 * @param	muteState	True if client was muted, false otherwise
 */
 forward BaseComm_OnClientMute(client, bool:muteState);

/**
 * Called when a client is gagged or ungagged
 * 
 * @param	client		Client index
 * @param	gagState	True if client was gaged, false otherwise
 */
 forward BaseComm_OnClientGag(client, bool:gagState);

Clients

GetClientAuthString by default now is only successful if the client has fully authenticated (if the new ValidateAuthentication feature is enabled in core.cfg).

There is a new bool param, validate, which can be sent as false to bypass this and get a potentially unvalidated auth string.

A new GetSteamAccountID native also has this param with the same purpose. A Steam account ID is the lower 32 bits of the full 64-bit Steam ID (referred to as community id by some) and is unique per account.

/**
 * Returns the client's Steam account ID.
 *
 * @param client		Client Index.
 * @param validate		Check backend validation status.
 * 				DO NOT PASS FALSE UNLESS YOU UNDERSTAND THE CONSEQUENCES,
 *			        You WILL KNOW if you need to use this, MOST WILL NOT.
 * @return				Steam account ID or 0 if not available.
 * @error				If the client is not connected or the index is invalid.
 */
native GetSteamAccountID(client, bool:validate=true);

You can also now return the maximum number of non-bots that a game will allow to join, which can be lower than MaxClients.

These limits can be put into place in games starting with Left 4 Dead. L4D 1 and 2 use it to limit connecting clients to 4 (coop) or 8 (versus) depending on game mode, and Counter-Strike: Global Offensive's new "gametypes" config system will set it based on the current mode's configured MaxPlayers amount.

/**
 * Returns the maximum number of human players allowed on the server.  This is 
 * a game-specific function used on newer games to limit the number of humans
 * that can join a game and can be lower than MaxClients. It is the number often
 * reflected in the server browser or when viewing the output of the status command.
 * On unsupported games or modes without overrides, it will return the same value
 * as MaxClients.
 *
 * You should not globally cache the value to GetMaxHumanPlayers() because it can change across
 * game modes. You may still cache it locally.
 *
 * @return				Maximum number of humans allowed.
 */
native GetMaxHumanPlayers();

Console

New global forwards have been added to specifically catch player chat without having to manually add a command listener for each possible chat command in a given game.

OnClientSayCommand can be used to block chat from occurring, and OnClientSayCommand_Post will only be fired if the chat was allowed, not blocked in the first forward or due to flooding.

/**
 * Global listener for the chat commands.
 *
 * @param client		Client index.
 * @param command		Command name.
 * @param sArgs			Chat argument string.
 * 
 * @return				An Action value. Returning Plugin_Handled bypasses the game function call.
							Returning Plugin_Stop bypasses the post hook as well as the game function.
 */
forward Action:OnClientSayCommand(client, const String:command[], const String:sArgs[]);

/**
 * Global post listener for the chat commands.
 *
 * @param client		Client index.
 * @param command		Command name.
 * @param sArgs			Chat argument string.
 * 
 */
forward OnClientSayCommand_Post(client, const String:command[], const String:sArgs[]);

CStrike

In addition to being updated to have existing functionality work on CS:GO, many new natives have been added to the CStrike extension.

/**
 * Gets a team's score
 * @param team			Team index to get score for.
 * @return				Returns the internal team score.
 *
 * @error				Invalid team index.
 */
native CS_GetTeamScore(team);

/**
 * Sets a team's score
 * @param team			Team index to set score for.
 * @param value			Value to set teams score as.
 * @noreturn
 *
 * @error				Invalid team index.
 * @note				This will update the scoreboard only after the scoreboard update function is called. Use SetTeamScore plus this to update the scoreboard instantly and save values correctly.
 */
native CS_SetTeamScore(team, value);

/**
 * Gets a client's mvp count
 * @param client		Client index to get mvp count of.
 * @return				Returns the client's internal MVP count.
 *
 * @error				Invalid client.
 */
native CS_GetMVPCount(client);

/**
 * Sets a client's mvp count
 * @param client		Client index to set mvp count for.
 * @param value			Value to set client's mvp count as.
 * @noreturn
 *
 * @error				Invalid client.
 */
native CS_SetMVPCount(client, value);

/**
 * Gets a client's contribution score (CS:GO only)
 * @param client		Client index to get score of.
 * @return				Returns the client's score.
 *
 * @error				Invalid client.
 */
native CS_GetClientContributionScore(client);

/**
 * Sets a client's contribution score (CS:GO only)
 * @param client		Client index to set score for.
 * @param value			Value to set client's score as.
 * @noreturn
 *
 * @error				Invalid client.
 */
native CS_SetClientContributionScore(client, value);

/**
 * Gets a client's assists (CS:GO only)
 * @param client		Client index to get assists of.
 * @return				Returns the client's assists.
 *
 * @error				Invalid client.
 */
native CS_GetClientAssists(client);

/**
 * Sets a client's assists (CS:GO only)
 * @param client		Client index to set assists for.
 * @param value			Value to set client's assists as.
 * @noreturn
 *
 * @error				Invalid client.
 */
native CS_SetClientAssists(client, value);

CS Weapon IDs defined in cstrike.inc are now SM-specific and may no longer match the value used internally by the game's own functions and variables, but will continue to work with the CStrike extensions natives and forwards across both CS:S and CS:GO.

/**
 * Gets a weaponID from a alias
 * @param alias			Weapon alias to attempt to get an id for.
 * @return				Returns a weapon id or 0 if failed to find a match.
 *
 * @note For best results use CS_GetTranslatedWeaponAlias on the weapon name before passing it.
 */
native CSWeaponID:CS_AliasToWeaponID(const String:alias[]);

/**
 * Gets a alias from a weaponID
 * @param weaponID		WeaponID to get alias for.
 * @param destination	Destination string to hold the weapon alias.
 * @param len			Length of the destination array.
 * @return				Returns number of cells written.
 */
native CS_WeaponIDToAlias(CSWeaponID:weaponID, String:destination[], len);

/**
 * Returns weather a WeaponID is valid on the current mod (css or csgo)
 * @param weaponID		WeaponID to check
 * @return				Returns true if its a valid WeaponID false otherwise.
 *
 * @note This will return false always for CSWeapon_NONE
 */
native bool:CS_IsValidWeaponID(CSWeaponID:id);

Entity

It is now possible to easily get the address of an entity for use with SourceMod's advanced StoreToAddress and LoadFromAddress natives.

/**
 * Gets the memory address of an entity.
 * 
 * @param entity		Entity index.
 * @return				Address of the entity.
 * @error				Invalid entity.
 */
native Address:GetEntityAddress(entity);

Protobuf

Support and many new natives for protobuf usermessages has been added. These are used in newer games like Counter-Strike: Global Offensive and Dota 2 in place of bitbuf messages.

For more info, see the Protobuf article.

SDKHooks

With it already in use on numerous servers, the SDKHooks extension has been added as officially supported.

For those not already familiar with the api, see the sdkhooks.inc file.

There is also a new ISDKHooks interface for extensions which allows them to add listeners for entity creation and deletion.

SDKTools

GetPlayerResourceEntity has been added as a game-agnostic replacement for TF2_GetResourceEntity

The resource entity typically contains multiple player-indexed arrays to network shared player data from the server to the client. Its data is typically updated internally each frame, making it much easier to read than effectively write. It's commonly used for scoreboard data amount other things. You can find a list of all of the data on it in a game by generating a dump of the game's networked properties (see Entity_Properties#SourceMod_Commands).

/*
 * Returns the entity index of the player resource/manager entity.
 *
 * @return				Index of resource entity or -1 if not found.
 */
native GetPlayerResourceEntity();

UserMessages

The GetUserMessageType native has been added to detect at runtime which usermessage system that the current game uses.

/**
 * UserMsg message serialization formats
 */
enum UserMessageType
{
	UM_BitBuf = 0,
	UM_Protobuf,
};

/**
 * Returns usermessage serialization type used for the current engine
 *
 * @return				The supported usermessage type.
 */
native UserMessageType:GetUserMessageType();