SourceMod 1.4.0 API Changes

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

Additions

BaseComm

The BaseComm base plugin now has a brand new API to fully interact with it, without conflict.

/**
 * Returns whether or not a client is gagged
 *
 * @param client		Client index.
 * @return			True if client is gagged, false otherwise.
 */
native bool:BaseComm_IsClientGagged(client);

/**
 * Returns whether or not a client is muted
 *
 * @param client		Client index.
 * @return			True if client is muted, false otherwise.
 */
native bool:BaseComm_IsClientMuted(client);

/**
 * Sets a client's gag state
 *
 * @param client		Client index.
 * @param gagState		True to gag client, false to ungag.
 * @return			True if this caused a change in gag state, false otherwise.
 */
native bool:BaseComm_SetClientGag(client, bool:gagState);

/**
 * Sets a client's mute state
 *
 * @param client		Client index.
 * @param muteState		True to mute client, false to unmute.
 * @return			True if this caused a change in mute state, false otherwise.
 */
native bool:BaseComm_SetClientMute(client, bool:muteState);

ClientPrefs

ClientPrefs now allows altering cookie values for clients that are not presently in-game.

/**
 * Sets the value of a Client preference cookie based on an authID string.
 *
 * @param authID		String Auth/STEAM ID of player to set.
 * @param cookie		Client preference cookie handle.
 * @param value			String value to set.
 * @noreturn
 * @error			Invalid cookie handle.
 */
native SetAuthIdCookie(const String:authID[], Handle:cookie, const String:value[]);

Core

Clients

Clients can now be easily identified as being the SourceTV or replay bot, regardless of when they are checked, what they were renamed to, or when they were enabled.

/**
 * Returns if a certain player is the SourceTV bot.
 *
 * @param client		Player index.
 * @return			True if player is the SourceTV bot, false otherwise.
 */
native bool:IsClientSourceTV(client);

/**
 * Returns if a certain player is the Replay bot.
 *
 * @param client		Player index.
 * @return			True if player is the Replay bot, false otherwise.
 */
native bool:IsClientReplay(client);

CommandFilters

Command filters are no longer limited to extensions. Multi-target filters can now be dynamically created, evaluated, and removed natively in Sourcepawn.

/**
 * Adds clients to a multi-target filter.
 *
 * @param pattern       Pattern name.
 * @param clients       Array to fill with unique, valid client indexes.
 * @return              True if pattern was recognized, false otherwise.
 */
functag public bool:MultiTargetFilter(const String:pattern[], Handle:clients);

/**
 * Adds a multi-target filter function for ProcessTargetString().
 *
 * @param pattern       Pattern to match (case sensitive).
 * @param filter        Filter function.
 * @param phrase        Descriptive phrase to display on successful match.
 * @param phraseIsML    True if phrase is multi-lingual, false otherwise.
 * @noreturn
 */
native AddMultiTargetFilter(const String:pattern[], MultiTargetFilter:filter,
                            const String:phrase[], bool:phraseIsML);

/**
 * Removes a multi-target filter function from ProcessTargetString().
 *
 * @param pattern       Pattern to match (case sensitive).
 * @param filter        Filter function.
 * @noreturn
 */
native RemoveMultiTargetFilter(const String:pattern[], MultiTargetFilter:filter);

See plugins/testsuite/ptstest.sp for example usage.

Console

Server command output is now retrievable with the new ServerCommandEx native..

/**
 * Executes a server command as if it were on the server console (or RCON) 
 * and stores the printed text into buffer.
 *
 * Warning: This calls ServerExecute internally and may have issues if
 * certain commands are in the buffer, only use when you really need
 * the response.
 * Also, on L4D2 this will not print the command output to the server console.
 *
 * @param buffer		String to store command result into.
 * @param maxlen		Length of buffer.
 * @param format		Formatting rules.
 * @param ...			Variable number of format parameters.
 * @noreturn
 */
native ServerCommandEx(String:buffer[], maxlen, const String:format[], any:...);

Command and ability access can now be checked directly with an AdminId, rather than requiring an in-game client. This can be useful in checking permissions while still obeying overrides in custom authentication systems such as might be used in IRC relay plugins or custom "RCon" solutions.

/**
 * Returns whether an admin has access to a given command string.  The string 
 * can be any override string, as overrides can be independent of 
 * commands.  This feature essentially allows you to create custom flags
 * using the override system.
 *
 * @param id			AdminId of the admin.
 * @param command		Command name.  If the command is not found, the default 
 *				flags are used.
 * @param flags			Flag string to use as a default, if the command or override 
 *				is not found.
 * @param override_only	If true, SourceMod will not attempt to find a matching 
 *				command, and it will only use the default flags specified.
 *				Otherwise, SourceMod will ignore the default flags if 
 *				there is a matching admin command.
 * @return			True if the admin has access, false otherwise.
 */
native bool:CheckAccess(AdminId:id, 
				const String:command[],
				flags,
				bool:override_only=false);

SourceMod

Game config files now support looking up addresses calculated from other gamedata.

For more information, see SDKTools_(SourceMod_Scripting)#Raw_address_lookups

/*
 * Finds an address calculation in a GameConfig file,
 * performs LoadFromAddress on it as appropriate, then returns the final address.
 *
 * @param gameconf      GameConfig Handle, or INVALID_HANDLE to use sdktools.games.txt.
 * @param name          Name of the property to find.
 * @return              An address calculated on success, or 0 on failure.
 */
native Address:GameConfGetAddress(Handle:gameconf, const String:name[]);

From pawn, you can now directly read and write values at these raw addresses. SDKTools also now supports calls using a raw address as a |this| pointer (see SourceMod_1.4.0_API_Changes#SDKTools).

/**
 * Load up to 4 bytes from a memory address.
 *
 * @param addr          Address to a memory location.
 * @param size          How many bytes should be read.
 * @return              The value that is stored at that address.
 */
native LoadFromAddress(Address:addr, NumberType:size);

/**
 * Store up to 4 bytes to a memory address.
 *
 * @param addr          Address to a memory location.
 * @param data          Value to store at the address.
 * @param size          How many bytes should be written.
 * @noreturn
 */
native StoreToAddress(Address:addr, data, NumberType:size);

CStrike

Allows the ability to view buy commands issued by client and block the command.

/**
 * Called when a player attempts to purchase an item.
 * Return Plugin_Continue to allow the purchase or return a
 * higher action to deny.
 *
 * @param client	Client index
 * @param weapon	User input for weapon name
 */
forward Action:CS_OnBuyCommand(client, const String:weapon[]);

Allows the ability to block weapon drop called by CSWeaponDrop

/**
 * Called when CSWeaponDrop is called
 * Return Plugin_Continue to allow the call or return a
 * higher action to deny.
 *
 * @param client	Client index
 * @param weapon	Weapon index
 */
forward Action:CS_OnCSWeaponDrop(client, weaponIndex);

Adds the ability to change weapon price on a per player basis.

/**
 * Called when game retrieves a weapon's price for a player.
 * Return Plugin_Continue to use default value or return a higher
 * action to use a newly-set price.
 * 
 * @note This can be called multiple times per weapon purchase
 * 
 * @param client	Client index
 * @param weapon	Weapon classname
 * @param price		Buffer param for the price of the weapon
 *
 * @note		Not all "weapons" call GetWeaponPrice. Example: c4, knife, vest, vest helmet, night vision.
 */
forward Action:CS_OnGetWeaponPrice(client, const String:weapon[], &price);

Adds the ability to block round ending.

/**
 * Called when TerminateRound is called.
 * Return Plugin_Continue to ignore, return Plugin_Changed to continue,
 * using the given delay and reason, or return Plugin_Handled or a higher
 * action to block TerminateRound from firing.
 *
 * @param delay		Time (in seconds) until new round starts
 * @param reason	Reason for round end
 */
forward Action:CS_OnTerminateRound(&Float:delay, &CSRoundEndReason:reason);

Adds the commonly used CSWeaponDrop SDKCall as a new native.

/**
 * Forces a player to drop or toss their weapon
 *
 * @param client	Player's index.
 * @param weaponIndex	Index of weapon to drop.
 * @param toss		True to toss weapon (with velocity) or false to just drop weapon
 * @param blockhook	Set to true to stop the corresponding CS_OnCSWeaponDrop
 * 
 * @noreturn
 * @error		Invalid client index, client not in game, or invalid weapon index.
 */
native CS_DropWeapon(client, weaponIndex, bool:toss, bool:blockhook = false);

Allows the ability to end a round with a specific reason.

/**
 * Forces round to end with a reason
 *
 * @param delay		Time (in seconds) to delay before new round starts
 * @param reason	Reason for the round ending
 * @param blockhook	Set to true to stop the corresponding CS_OnTerminateRound
 *			forward from being called.
 * @noreturn
 */
 native CS_TerminateRound(Float:delay, CSRoundEndReason:reason, bool:blockhook = false);

Allows passing buy aliases and retrieving the actual name for the weapon.

/** 
 * Gets a weapon name from a weapon alias
 *
 * @param alias		Weapons alias to get weapon name for.
 * @param weapon	Buffer to store weapons name
 * @param size		Size of buffer to store the weapons name.
 * @noreturn
 *
 * @note		Will set the buffer to the original alias if it is not an alias to a weapon.
 */
 native CS_GetTranslatedWeaponAlias(const String:alias[], String:weapon[], size);

Allows getting a weapons price, while still obeying the forward call to get price if modified.

/**
 * Gets a weapon's price
 *
 * @param client	Client to check weapon price for.
 * @param id		Weapon id for the weapon to check
 * @param defaultprice	Set to true to get defaultprice.
 * @return		Returns price of the weapon (even if modified)
 *
 * @error		Invalid client, failing to get weapon info, or failing to get price offset.
 * @note		c4, knife and shield will always return 0. vest, vest helmet and night vision will always return default price.
 */
 native CS_GetWeaponPrice(client, CSWeaponID:id, bool:defaultprice = false);

Adds the ability to get a clients clan tag.

/**
 * Gets a clients clan tag
 * @param client	Client index to get clan tag for.
 * @param buffer	Buffer to store clients clan tag in.
 * @param size		Size of the buffer.
 * @return		Number of non-null bytes written.
 *
 * @error			Invalid client.
 */
 native CS_GetClientClanTag(client, String:buffer[], size);

Adds the ability to set a clients clan tag.

/**
 * Sets a clients clan tag
 * @param client	Client index to set clan tag for.
 * @param tag		Tag to set clients clan tag as.
 * @noreturn
 *
 * @error		Invalid client.
 */
 native CS_SetClientClanTag(client, const String:tag[]);

MapChooser

/**
 * Called when mapchooser starts a Map Vote.
 */
forward OnMapVoteStarted();

Nominations

/**
 * Attempt to remove a map from the mapchooser map list.
 *
 * @param map		Map to remove.
 * @return			True if the nomination was found and removed, or false if the nomination was not found.
 */
native bool:RemoveNominationByMap(const String:map[]);

/**
 * Attempt to remove a map from the mapchooser map list.
 *
 * @param owner		Client index of the nominater.
 * @return			True if the nomination was found and removed, or false if the nomination was not found.
 */
native bool:RemoveNominationByOwner(owner);

/**
 * Gets the current list of nominated maps.
 *
 * @param maparray		An ADT array handle to add the map strings to.
 * @param ownerarray	An optional ADT array handle to add the nominator client indexes to.
 * @noreturn
 */
native GetNominatedMapList(Handle:maparray, Handle:ownerarray = INVALID_HANDLE);

SDKTools

A new SDKCallType, SDKCall_Raw has been added. This is to be used with the new Address variables to make calls with custom |this| pointers.

Client

It is now possible to directly control some aspects of a client's netchannel in a way that, among other things, you can cause them to reconnect to the current server like at a map change.

/**
 * Sets the client to an inactive state waiting for a new map
 *
 * @param client	The client index
 * @noreturn
 */
native InactivateClient(client);

/**
 * Reconnect a client without dropping the netchannel
 *
 * @param client	The client index
 * @noreturn
 */
native ReconnectClient(client);

GameRules

Property values networked on the GameRulesProxy entity can now be looked up and set directly on the GameRules class. On the proxy, values read could be stale, and attempting to change values only resulted in them being changed on the client or not at all.

The functions work very similarly to their GetEntProp equivalents.

• GameRules_GetProp
• GameRules_SetProp
• GameRules_GetPropFloat
• GameRules_SetPropFloat
• GameRules_GetPropEnt
• GameRules_SetPropEnt
• GameRules_GetPropVector
• GameRules_SetPropVector
• GameRules_GetPropString
• GameRules_SetPropString

For more info on things that can be done with these, see http://forums.alliedmods.net/showthread.php?t=154217.

Sound

You can now use the engine's function for sound gain calculation based on sound level and distance from listener.

/**
 *Calculates gain of sound on given distance with given sound level in decibel
 *
 * @param soundlevel	decibel of sound, like SNDLEVEL_NORMAL or integer value
 * @param distance	distance of sound to calculate, not meter or feet, but Source Engine`s normal Coordinate unit
 * @return		gain of sound. you can multiply this with original sound`s volume to calculate volume on given distance
 */
native Float:GetDistGainFromSoundLevel(soundlevel, Float:distance);

TF2

Notification is now available when "WaitingForPlayers" both begins and ends (or current state can be queried as any time with the new GameRules natives).

/**
 * Called when the server enters the Waiting for Players round state
 *
 * @noreturn
 */
forward TF2_OnWaitingForPlayersStart();

/**
 * Called when the server exits the Waiting for Players round state
 *
 * @noreturn
 */
forward TF2_OnWaitingForPlayersEnd();

Condition addition and removal to and from players can now be detected. Due to various issues, these cannot be blocked, but conditions can be re-removed or re-added in the add and remove callbacks, leaving only a frame of difference.

/**
 * Called after a condition is added to a player
 *
 * @param client		Index of the client to which the conditon is being added.
 * @param condition     Condition that is being added.
 * @noreturn
 */
forward TF2_OnConditionAdded(client, TFCond:condition);

/**
 * Called after a condition is removed from a player
 *
 * @param client		Index of the client to which the condition is being removed.
 * @param condition		Condition that is being removed.
 * @noreturn
 */
forward TF2_OnConditionRemoved(client, TFCond:condition);

Other Changes

Core

Entities

The following functions now have an optional last parameter of element to be used with props that are arrays (ie. m_iAmmo, m_hMyWeapons)

• GetEntProp
• SetEntProp
• GetEntPropFloat
• SetEntPropFloat
• GetEntPropEnt
• SetEntPropEnt
• GetEntPropVector
• SetEntPropVector
• GetEntPropString

Previously, the only way to access anything but the first array member was using the GetEntData and SetEntData funcs with manual offset calculations. Now you can just specify the 0-based index and keep the type-checking and offset-caching benefits of the GetEntProp and SetEntProp functions.

A GetEntPropArraySize native has also been added to retrieve the number of available indexes.

Lang

GetClientLanguage and SetClientLanguage now only require a client to be connected, rather than in-game.

Menus

The MENUFLAG_BUTTON_NOVOTE menu option flag has been added to allow creation of an automatic "No Vote" option at the start of the menu.

String

ExplodeString behavior has changed slightly to fix a long-standing bug with the return value in some cases and to allow more flexibility and more defined behavior.

A new copyRemainder boolean has been added as part of this change.

/**
 * Breaks a string into pieces and stores each piece into an array of buffers.
 *
 * @param text				The string to split.
 * @param split				The string to use as a split delimiter.
 * @param buffers			An array of string buffers (2D array).
 * @param maxStrings		Number of string buffers (first dimension size).
 * @param maxStringLength	Maximum length of each string buffer.
 * @param copyRemainder		False (default) discard excess pieces, true to ignore
 *							delimiters after last piece.
 * @return					Number of strings retrieved.
 */
stock ExplodeString(const String:text[], const String:split[], String:buffers[][], maxStrings,
                    maxStringLength, bool:copyRemainder = false)

Key points in change:

• Return value now always matches the actual number of strings written
• If the string being exploded ends with one or more of the delimiter, the string will be split at all delimiters, even resulting in empty strings at the end
• If all allocated strings buffers have been copied to and there is another delimiter remaining, you can opt in (with the copyRemainder bool) to have the remaining text appended to the last string written.

DBI

SQL_GetAffectedRows now works properly with threaded query handles.

The handle passed to both SQL_GetInsertId and SQL_GetError can now be a query handle.

SDKTools

Functions

The ForceEdictIndex parameter in CreateEntityByName is now always ignored on ep2 (orangebox) and later (resulting in the same behavior as keeping its default value of -1).

This change was made because 1) forcing edict indexes can be unsafe ("crashy") if misused, and 2) it allows CreateEntityByName to now be automatically supported by all ep2 and later games and mods, without requiring gamedata.

TF2

The TF2 holiday functions have changed, breaking our former TF2_OnGetHoliday forward that was able to be used for altering the active TF2 holiday.

While that forward is now deprecated, a new one, TF2_OnIsHolidayActive has emerged in its place. As a bonus, this effectively let's you have effects for multiple holidays active at once (now that the game supports it).

/**
 * Called at various times when the game checks to see if the given holiday is active.
 * Return Plugin_Continue to let the original calculation or return a higher
 * action to override the decision with the value of 'result'
 *
 * @param holiday		Holiday being checked.
 * @param result		Buffer param for the result of the decision.
 * @return				Plugin_Continue for original calculation, higher value to use 'result'.
 */
forward Action:TF2_OnIsHolidayActive(TFHoliday:holiday, &bool:result);