View source for Sourcemod 1.5.0 API Changes

''These are just the API changes from SourceMod 1.4.7 to SourceMod 1.5.0. Click here for the full [http://wiki.alliedmods.net/SourceMod_1.5.0_Release_Notes SourceMod 1.5.0 Release Notes].''
__FORCETOC__

=Plugins=

==BaseComm==

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

<pawn>/**
 * 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);</pawn>
 
<pawn>/**
 * 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);</pawn>

==Clients==

<tt>GetClientAuthString</tt> 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.

<pawn>/**
 * 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);</pawn>

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

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.

<pawn>/**
 * 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();</pawn>

==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.

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

<pawn>/**
 * 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[]);</pawn>

<pawn>/**
 * 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[]);</pawn>

==CStrike==

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

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

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.

<pawn>/**
 * 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[]);</pawn>

<pawn>/**
 * 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);</pawn>

<pawn>/**
 * 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);</pawn>

==Entity==

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

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

==HalfLife==

<tt>GuessSDKVersion</tt> is now deprecated. Engine version chronology is no longer constant for many variants due to similar branches receiving updates at different times or older variants receiving features that newer ones lack. This breaks an API guarantee of the native.

It has been replaced with the new, typed GetEngineVersion, which uses the new EngineVersion enum constants in halflife.inc.

<pawn>/**
 * Gets the engine version that the currently-loaded SM core was compiled against.
 *
 * The engine version values are not guaranteed to be in any particular order,
 * and should only be compared by (in)equality.
 *
 * @return				An EngineVersion value.
 */
native EngineVersion:GetEngineVersion();</pawn>

==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|SDKHooks]] extension has been added as officially supported.

For those not already familiar with the api, see the [http://hg.alliedmods.net/releases/sourcemod-1.5/file/tip/plugins/include/sdkhooks.inc sdkhooks.inc] file.

==SDKTools==

<tt>GetPlayerResourceEntity</tt> has been added as a game-agnostic replacement for <tt>TF2_GetResourceEntity</tt>

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]]).

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

The <tt>OnPlayerRunCmd</tt> forward has been overloaded with much more information from the internal usercmd becoming available to plugins, including weapon subtype, command number, client tick count, random seed, and mouse coords.

To check at runtime to confirm that the new parameters are filled in (which they will be if the server is running SourceMod 1.5.0 final or later), you can use the <tt>GetFeatureStatus</tt> or <tt>RequireFeature</tt> natives with a feature name of <tt>FEATURECAP_PLAYERRUNCMD_11PARAMS</tt>.

<pawn>/**
 * @brief Called when a clients movement buttons are being processed
 *
 * @param client	Index of the client.
 * @param buttons	Copyback buffer containing the current commands (as bitflags - see entity_prop_stocks.inc).
 * @param impulse	Copyback buffer containing the current impulse command.
 * @param vel		Players desired velocity.
 * @param angles	Players desired view angles.
 * @param weapon	Entity index of the new weapon if player switches weapon, 0 otherwise.
 * @param subtype	Weapon subtype when selected from a menu.
 * @param cmdnum	Command number. Increments from the first command sent.
 * @param tickcount	Tick count. A client's prediction based on the server's GetGameTickCount value.
 * @param seed		Random seed. Used to determine weapon recoil, spread, and other predicted elements.
 * @param mouse		Mouse direction (x, y).
 * @return 			Plugin_Handled to block the commands from being processed, Plugin_Continue otherwise.
 *
 * @note			To see if all 11 params are avaliable, use FeatureType_Capability and
 *					FEATURECAP_PLAYERRUNCMD_11PARAMS.
 */
forward Action:OnPlayerRunCmd(client, &buttons, &impulse, Float:vel[3], Float:angles[3], &weapon, &subtype, &cmdnum, &tickcount, &seed, mouse[2]);</pawn>

==TF2==

<tt>TF2_AddCondition</tt> now allows you to specify an inflictor entity for conditions that support it.

<pawn>/**
 * Adds a condition to a player
 *
 * @param client		Player's index.
 * @param condition		Integer identifier of condition to apply.
 * @param duration		Duration of condition (does not apply to all conditions).
 * @param inflictor		Condition inflictor's index (0 for no inflictor).
 * @noreturn
 * @error				Invalid client index, client not in game, or no mod support.
 */
native TF2_AddCondition(client, TFCond:condition, Float:duration, inflictor=0);</pawn>

A new forward, <tt>TF2_OnPlayerTeleport</tt> has been added for when the game checks to see if the given player is allowed to use the given teleporter.

<pawn>/**
 * Called when a player attempts to use a teleporter to decide if the player should be allowed to teleport.
 * Return Plugin_Continue to let the original calculation or return a higher
 * action to override the decision with the value of 'result'
 *
 * @param client		Client index.
 * @param teleporter	Teleporter entity index.
 * @param result		Buffer param for the result of the decision.
 *						This is prepopulated with the game's original decision to let a player teleport.
 * @return				Plugin_Continue for original calculation, higher value to use 'result'.
 */
forward Action:TF2_OnPlayerTeleport(client, teleporter, &bool:result);</pawn>

<tt>TF2_IsPlayerInCondition</tt> now returns a correct answer for conditions greater than 64.

<tt>TF2_GetResourceEntity</tt> is now deprecated. Usages of it can be replaced by the new, game-agnostic <tt>GetPlayerResourceEntity</tt> in SDKTools.

<tt>TF2_GetPlayerResourceData</tt> and <tt>TF2_SetPlayerResourceData</tt> are now deprecated in favor of using <tt>GetPlayerResourceEntity</tt> and the GetEntProp* or SetEntProp* natives.

==UserMessages==

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

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

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

=Extensions=

==IGameHelpers==

The following new functions were added.

<cpp>/**
 * @brief Gets a Classname from an edict_t pointer.
 *
 * @param pEdict		edict_t pointer.
 * @return				Pointer to the string, or NULL if bad pointer.
 */
virtual const char *GetEntityClassname(edict_t *pEdict) =0;</cpp>

<cpp>/**
 * @brief Gets a Classname from an CBaseEntity pointer.
 *
 * @param pEntity		CBaseEntity pointer.
 * @return				Pointer to the string, or NULL if bad pointer.
 */
virtual const char *GetEntityClassname(CBaseEntity *pEntity) =0;</cpp>

<cpp>/**
 * @brief Returns whether or not a map name is valid to use with the
 * engine's Changelevel functionality. It need not be an exact filename on
 * some engines. For a check on the exact name, use IVEngineServer::IsMapValid.
 *
 * @param map			Map name.
 * @return				True if valid, otherwise false.
 */
virtual bool IsMapValid(const char *map) =0;</cpp>

==IPlayerHelpers==

<tt>IPlayerHelpers::GetAuthString</tt> and the new <tt>IPlayerHelpers::GetSetamAccountID</tt> both have a new bool param added for whether or not to allow values not yet validated by the Steam backend to be returned on applicable games.

<cpp>/**
 * @brief Returns the player's authentication string.
 *
 * @param		validated	Check backend validation status.
 * @return		String containing the player's auth string.
 *				May be NULL if unavailable.
 */
virtual const char *GetAuthString(bool validated = true) =0;</cpp>

<cpp>/**
 * @brief Returns the client's Steam account ID.
 *
 * @param validated		Check backend validation status.
 * 
 * @return			Steam account ID or 0 if not available.
 */
virtual unsigned int GetSteamAccountID(bool validated = true) =0;</cpp>

==IThreader==

The following new functions were added.

<cpp>/**
 * @brief Sets the number of threads to run per frame.
 * Default value is 1 thread per frame.
 *
 * @param threads	Number of threads to run per frame.
 */
virtual void SetMaxThreadsPerFrame(unsigned int threads) =0;</cpp>

<cpp>/**
 * @brief For threaded workers, the think time of a frame.
 * Has no effect for non-threaded workers.
 * Default value is 50ms.
 *
 * @param thinktime	Number of ms to sleep between frame execution.
 */
virtual void SetThinkTimePerFrame(unsigned int thinktime) =0;</cpp>

==ITranslator==

The following new function was added.

<cpp>/**
 * @brief Retrieves info about a given language number.
 *
 * @param number            Language number.
 * @param code              Pointer to store the language code.
 * @param name              Pointer to store language name.
 * @return                  True if language number is valid, false otherwise.
 */
virtual bool GetLanguageInfo(unsigned int number, const char **code, const char **name) =0;</cpp>

==IUserMessages==

IUserMessages has been reworked to add support newer games that use Google Protocol Buffers (Protobuf) for usermessages.

<tt>IUserMessageListener</tt> has been trimmed and is now just a base class for the new <tt>IBitBufUserMessageListener</tt> and <tt>IProtobufUserMessageListener</tt>

<tt>StartMessage</tt> has been removed and replaced with both <tt>StartBitBufMessage</tt> and <tt>StartProtobufMessage</tt>.

Additionally, a new <tt>GetUserMessageType</tt> has been added to return which one of the two usermessage systems that the running game supports.

See [http://hg.alliedmods.net/releases/sourcemod-1.5/file/tip/public/IUserMessages.h IUserMessages.h] for more details.

==ISDKHooks==

SDKHooks now has a public interface for other extensions to add themselves as a listener to be notified about entity creation and deletion.

See [http://hg.alliedmods.net/releases/sourcemod-1.5/file/tip/public/extensions/ISDKHooks.h ISDKHooks.h] for more details.

==IWebternet==

Support for POSTing files has been added with the new <tt>AddFile</tt> function.

<cpp>/**
 * @brief Adds a file to the form.
 *
 * All data is copied locally and may go out of scope.
 *
 * @param name				Field name (null terminated).
 * @param path				Local file path (null terminated).
 * @return					True on success, false on failure.
 */
virtual bool AddFile(const char *name, const char *path) = 0;</cpp>